极狐 GitLab

故障排除极狐GitLab Runner

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

本部分可在排查极狐GitLab Runner 问题时提供帮助。

常规故障排除提示#

查看日志#

极狐GitLab Runner 服务会将日志发送到 syslog。要查看日志，请参阅您的发行版文档。如果您的发行版包含 journalctl 命令，您可以使用该命令查看日志：

shell
journalctl --unit=gitlab-runner.service -n 100 --no-pager
docker logs gitlab-runner-container # Docker
kubectl logs gitlab-runner-pod # Kubernetes

重启服务#

shell
systemctl restart gitlab-runner.service

查看 Docker 机器#

shell
sudo docker-machine ls
sudo su - && docker-machine ls

删除所有 Docker 机器#

shell
docker-machine rm $(docker-machine ls -q)

将更改应用到 config.toml#

shell
systemctl restart gitlab-runner.service
docker-machine rm $(docker-machine ls -q) # Docker machine
journalctl --unit=gitlab-runner.service -f # Tail the logs to check for potential errors

确认您的极狐GitLab 和极狐GitLab Runner 版本#

极狐GitLab 致力于保证向后兼容性。不过，作为首要的故障排除步骤，您应确保您的 极狐GitLab Runner 版本与您的极狐GitLab 版本相同。

coordinator 是什么意思？#

coordinator 是请求作业的极狐GitLab 安装实例。

换句话说，runner 是一个独立的代理，它从 coordinator（通过极狐GitLab API 访问的极狐GitLab 安装实例）请求作业。

在 Windows 上作为服务运行时，日志存储在哪里？#

  • 如果极狐GitLab Runner 在 Windows 上作为服务运行，它会创建系统事件日志。要查看这些日志，请打开事件查看器（从“运行”菜单中，输入 eventvwr.msc 或搜索“Event Viewer”）。然后转到 Windows 日志 > 应用程序。Runner 日志的 Source 为 gitlab-runner。如果您使用的是 Windows Server Core，请运行以下 PowerShell 命令以获取最后 20 条日志条目：get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto。

启用调试日志记录模式#

调试日志记录可能存在严重的安全风险。其输出包含作业可用的所有变量和其他密钥的内容。您应禁用任何可能将密钥传输给第三方的日志聚合。使用屏蔽变量可以在作业日志输出中保护密钥，但在容器日志中无法保护。

在命令行中#

在终端中，以 root 身份登录，运行以下命令。

不应在使用 Shell 执行器的 runner 上执行此操作，因为它会重新定义 systemd 服务 并以 root 身份运行所有作业。这会带来安全风险，并更改文件所有权，导致难以恢复到非特权账户。

shell
gitlab-runner stop
gitlab-runner --debug run

在极狐GitLab Runner 的 config.toml中#

可以通过将 log_level 设置设为 debug，在 config.toml的全局部分中启用调试日志记录。在 config.toml的最顶部、concurrent 行之前或之后添加以下行：

toml
log_level = "debug"

在 Helm Chart 中#

如果极狐GitLab Runner 是使用极狐GitLab Runner Helm Chart 安装在 Kubernetes 集群中的，要启用调试日志记录，请在 values.yaml 自定义配置中设置 logLevel 选项：

yaml
## Configure the GitLab Runner logging level. Available values are: debug, info, warn, error, fatal, panic
## ref: https://gitlab.cn/docs/runner/configuration/advanced-configuration/#the-global-section
##
logLevel: debug

极狐GitLab Runner 日志中的关联 ID#

极狐GitLab Runner 会为每个 API 请求生成一个关联 ID，以追踪与极狐GitLab 的交互。

当来自极狐GitLab 的 API 响应在 X-Request-Id 响应头中包含关联 ID 时，日志中会使用该值（通常为 ULID 格式）。如果响应中不包含关联 ID，极狐GitLab Runner 会使用它为请求生成的 UUID（不带连字符的小写十六进制格式）。 回退关联 ID 表示该请求未到达 GitLab Workhorse。 问题很可能发生在中间跳转环节（例如 WAF、CDN、负载均衡器或代理）。

您可以使用关联 ID 来匹配各组件之间的日志条目并追踪请求流。在极狐GitLab Runner 日志中搜索 correlation_id 字段，并在极狐GitLab 服务器日志中搜索对应的 ID，以关联事件。

日志条目示例：

plaintext
# Valid correlation ID (ULID format from GitLab API response)
Appending trace to coordinator...ok correlation_id=01KKDQ7P6TRW7Z6P2PWG5808EK job=101162491 status=202 Accepted

# Fallback correlation ID (lowercase hex UUID without dashes, generated by runner)
WARNING: Appending trace to coordinator... job failed correlation_id=21fe32aee0e146c194640b075c95ec7c job=101162868 status=403 Forbidden

为 Docker 执行器 runner 配置 DNS#

当您使用 Docker 执行器配置极狐GitLab Runner 时，即使主机上的 Runner 守护进程可以访问极狐GitLab，Docker 容器也可能无法访问极狐GitLab。 当 DNS 在主机上配置了，但这些配置未传递给容器时，就可能发生这种情况。

示例：

极狐GitLab 服务和极狐GitLab Runner 位于两个不同的网络中，这两个网络以两种方式桥接（例如，通过互联网和通过 VPN）。runner 的路由机制可能通过默认的互联网服务查询 DNS，而不是通过 VPN 上的 DNS 服务。这种配置会导致以下消息：

shell
Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 16.5.0 linux/amd64' fetch origin +da39a3ee5e6b4b0d3255bfef95601890afd80709:refs/pipelines/435345 +refs/heads/master:refs/remotes/origin/master --depth 50 --prune --quiet
fatal: Authentication failed for 'https://gitlab.example.com/group/example-project.git/'

在这种情况下，身份验证失败是由互联网和极狐GitLab 服务之间的某个服务引起的。该服务使用单独的凭据，如果 runner 使用 VPN 上的 DNS 服务，就可以绕过该服务。

您可以通过在 Runner 的 config.toml 文件的 [runners.docker] 部分中使用 dns 配置，来告诉 Docker 使用哪个 DNS 服务器。

toml
dns = ["192.168.xxx.xxx","192.168.xxx.xxx"]

我看到 x509: certificate signed by unknown authority#

有关更多信息，请参阅自签名证书。

访问 /var/run/docker.sock 时出现 Permission Denied#

如果您想使用 Docker 执行器，并且您连接的是安装在服务器上的 Docker Engine。您可能会看到 Permission Denied 错误。 最可能的原因是您的系统使用了 SELinux（在 CentOS、Fedora 和 RHEL 上默认启用）。 检查您系统上的 SELinux 策略，查看是否存在可能的拒绝。

Docker-machine 错误：Unable to query docker version: Cannot connect to the docker engine endpoint.#

此错误与机器预配有关，可能由以下原因导致：

  • 存在 TLS 故障。安装 docker-machine 时，某些证书可能无效。 要解决此问题，请删除这些证书并重启 runner：

    shell
    sudo su -
rm -r /root/.docker/machine/certs/*
service gitlab-runner restart

    runner 重启后，会检测到证书为空并重新创建它们。

  • 主机名长于所预配机器支持的长度。例如，Ubuntu 机器对 HOST_NAME_MAX 有 64 个字符的限制。主机名由 docker-machine ls 报告。检查 runner 配置中的 MachineName， 并在需要时缩短主机名长度。

此错误可能在机器中安装 Docker 之前就已发生。

dialing environment connection: ssh: rejected: connect failed (open failed)#

当连接通过 SSH 隧道传输时，如果 Docker 自动扩缩器无法访问目标系统上的 Docker 守护进程，就会发生此错误。请确保您可以通过 SSH 连接到目标系统并成功运行 Docker 命令，例如 docker info。

为自动扩缩的 runner 添加 AWS 实例配置文件#

创建 AWS IAM 角色后，在 IAM 控制台中，该角色有一个 Role ARN 和一个 Instance Profile ARNs。您必须使用 Instance Profile 名称，而不是 Role Name。

将以下值添加到您的 [runners.machine] 部分： "amazonec2-iam-instance-profile=<instance-profile-name>",

Docker 执行器在构建 Java 项目时超时#

这很可能是因为损坏的 aufs 存储驱动导致的：Java 进程在容器内挂起。最好的解决方案是将存储驱动 更改为 OverlayFS（更快）或 DeviceMapper（更慢）。

请参阅这篇关于配置和运行 Docker的文章，或这篇关于使用 systemd 控制和配置的文章。

上传产物时出现 411#

发生这种情况是因为极狐GitLab Runner 使用了 Transfer-Encoding: chunked，而该特性在早期版本的 NGINX 中是损坏的（https://serverfault.com/questions/164220/is-there-a-way-to-avoid-nginx-411-content-length-required-errors）。

请将您的 NGINX 升级到较新版本。有关更多信息，请参阅此议题：https://gitlab.com/gitlab-org/gitlab-runner/-/issues/1031

我看到其他产物上传错误，如何进一步调试？#

产物直接从构建环境上传到极狐GitLab 实例， 绕过极狐GitLab Runner 进程。 例如：

  • 使用 Docker 执行器时，上传从 Docker 容器进行
  • 使用 Kubernetes 执行器时，上传从构建 Pod 中的构建容器进行

从构建环境到极狐GitLab 实例的网络路由可能与 从极狐GitLab Runner 到极狐GitLab 实例的路由不同。

要启用产物上传，请确保上传路径中的所有组件都允许从构建环境向极狐GitLab 实例发送 POST 请求。

默认情况下，产物上传器会记录上传 URL 和上传响应的 HTTP 状态码。这些信息不足以了解是哪个系统导致了错误或阻止了产物上传。要排查产物上传问题，请为上传尝试启用调试日志记录，以查看上传响应的响应头和正文。

产物上传调试日志记录的响应正文长度上限为 512 字节。 仅在调试时启用日志记录，因为日志中可能会暴露敏感数据。

如果上传到达极狐GitLab 但以错误状态码失败（例如，产生非成功的响应状态码），请调查极狐GitLab 实例本身。有关常见的产物上传问题，请参阅 极狐GitLab 文档。

No URL provided, cache will not be download/uploaded#

当极狐GitLab Runner helper 收到无效 URL，或没有任何 用于访问远程缓存的预签名 URL 时，就会发生此错误。请检查每个与缓存相关的 config.toml 条目以及特定于提供程序的键和值。无效 URL 可能由任何不符合 URL 语法要求的项构造而成。

此外，请确保您的 helper image 和 helper_image_flavor 匹配且为最新版本。

如果凭据配置存在问题，极狐GitLab Runner 进程日志中会添加一条诊断错误消息。

错误：warning: You appear to have cloned an empty repository.#

当使用 HTTP(s) 运行 git clone（使用极狐GitLab Runner 或为测试手动运行）时，如果您看到以下输出：

shell
$ git clone https://git.example.com/user/repo.git

Cloning into 'repo'...
warning: You appear to have cloned an empty repository.

请确保您的极狐GitLab 服务器安装中的 HTTP 代理配置正确无误。使用带有自身配置的 HTTP 代理时，请确保请求被代理到 GitLab Workhorse socket，而不是 GitLab Unicorn socket。

通过 HTTP(S) 的 Git 协议由 GitLab Workhorse 解析，因此它是极狐GitLab 的 主要入口点。

如果您使用的是 Linux 软件包安装，但不想使用内置的 NGINX 服务器，请参阅使用非内置 Web 服务器。

在 GitLab Recipes 代码仓库中，有 适用于 Apache 和 NGINX 的 Web 服务器配置示例。

如果您使用的是从源代码安装的极狐GitLab，请参阅上述文档和示例。确保所有 HTTP(S) 流量都经过 GitLab Workhorse。

请参阅一个用户议题示例。

错误：使用 Timezone 或 OffPeakTimezone 时出现 zoneinfo.zip: no such file or directory 错误#

可以配置描述 [[docker.machine.autoscaling]] 时段所使用的时区。此功能在大多数 Unix 系统上开箱即用。但是，在某些 Unix 系统和大多数非 Unix 系统上（例如 Windows，极狐GitLab Runner 二进制文件可在其上使用）， runner 可能在启动时崩溃并报错：

plaintext
Failed to load config Invalid OffPeakPeriods value: open /usr/local/go/lib/time/zoneinfo.zip: no such file or directory

该错误由 Go 中的 time 包引起。Go 使用 IANA 时区数据库来加载指定时区的配置。在大多数 Unix 系统上，该数据库已存在于某个众所周知的路径中（/usr/share/zoneinfo、/usr/share/lib/zoneinfo、/usr/lib/locale/TZ/）。Go 的 time 包会在所有这三个路径中查找时区数据库。如果它没有找到其中任何一个，但机器配置了 Go 开发环境，则会回退到 $GOROOT/lib/time/zoneinfo.zip 文件。

如果这些路径都不存在（例如在生产 Windows 主机上），则会抛出上述错误。

如果您的系统支持 IANA 时区数据库，但默认不可用，您可以尝试安装它。对于 Linux 系统，可以例如通过以下方式完成：

shell
1# on Debian/Ubuntu based systems
2sudo apt-get install tzdata
3
4# on RPM based systems
5sudo yum install tzdata
6
7# on Linux Alpine
8sudo apk add -U tzdata

如果您的系统不以原生方式提供此数据库，那么您可以按照以下步骤使 OffPeakTimezone 正常工作：

  1. 下载 zoneinfo.zip。从 v9.1.0 版本开始，您可以从带标记的路径下载 该文件。在这种情况下，您应将 zoneinfo.zip 下载 URL 中的 latest 替换为标签名称（例如 v9.1.0）。

  2. 将此文件存储在一个众所周知的目录中。建议使用与 config.toml 文件所在的同一目录。例如，如果您在 Windows 机器上托管 Runner， 并且您的配置文件存储在 C:\gitlab-runner\config.toml，则将 zoneinfo.zip 保存到 C:\gitlab-runner\zoneinfo.zip。

  3. 设置 ZONEINFO 环境变量，其中包含 zoneinfo.zip 文件的完整路径。如果您 使用 run 命令启动 Runner，则可以通过以下方式完成：

    shell
    ZONEINFO=/etc/gitlab-runner/zoneinfo.zip gitlab-runner run <other options ...>

    或者如果使用 Windows：

    powershell
    C:\gitlab-runner> set ZONEINFO=C:\gitlab-runner\zoneinfo.zip
C:\gitlab-runner> gitlab-runner run <other options ...>

    如果您将极狐GitLab Runner 作为系统服务启动，则必须更新或覆盖 服务配置：

    • 在 Unix 系统上，通过您的服务管理器软件修改设置。
    • 在 Windows 上，通过系统设置将 ZONEINFO 变量添加到极狐GitLab Runner 用户可用的环境变量列表中。

为什么我不能运行多个极狐GitLab Runner 实例？#

您可以运行多个实例，但不能共享同一个 config.toml 文件。

使用同一配置文件运行多个极狐GitLab Runner 实例可能会导致意外且难以调试的行为。同一时间只能有一个极狐GitLab Runner 实例使用特定的 config.toml 文件。

作业在开始前出现延迟#

如果某些项目的作业在开始前出现显著延迟，而其他项目的作业立即运行，您可能遇到了长轮询问题。

症状：

  • 作业已排队，但启动执行所需时间异常长（通常与您的极狐GitLab 实例长轮询超时时间一致）。
  • 某些 runner 似乎卡住了，而其他 runner 正常处理作业。
  • 极狐GitLab Runner 日志显示 CONFIGURATION: Long polling issues detected。

原因：

当极狐GitLab Runner 工作进程卡在对极狐GitLab 的长轮询请求中时，就会发生此问题，这会阻止其他作业被及时处理。根据配置的不同，这些问题从性能瓶颈到完全死锁不等。该问题与 由 GitLab Workhorse 的 apiCiLongPollingDuration 设置（默认值：50 秒）控制的极狐GitLab CI/CD 长轮询功能有关。

解决方案：

这些问题可能在多种配置场景中发生。有关原因、配置示例和解决方案的全面信息，请参阅高级配置文档中的长轮询问题部分。

Job failed (system failure): preparing environment:#

此错误通常是由于您的 shell 加载您的配置文件，并且其中一个脚本导致了失败。

已知会导致失败的 dotfiles 示例：

  • .bash_logout
  • .condarc
  • .rvmrc

SELinux 也可能是此错误的罪魁祸首。您可以通过查看 SELinux 审计日志来确认：

shell
sealert -a /var/log/audit/audit.log

Runner 在 Cleaning up 阶段后突然终止#

据报告，当启用“container drift detection（容器漂移检测）”设置时，CrowdStrike Falcon Sensor 会在作业的 Cleaning up files 阶段后终止 Pod。为确保作业能够完成，您必须禁用此设置。

作业失败并显示 remote error: tls: bad certificate (exec.go:71:0s)#

当系统时间在创建产物的作业期间发生显著变化时，可能会发生此错误。由于系统时间的变化，SSL 证书会过期，从而导致 runner 尝试上传产物时出错。

为确保产物上传期间 SSL 验证能够成功，请在作业结束时将系统时间更改为有效的日期和时间。由于产物文件的创建时间也已更改，它们会被自动归档。

Helm Chart：ERROR .. Unauthorized#

在卸载或升级使用 Helm 部署的 runner 之前，请在极狐GitLab 中暂停它们，并等待任何作业完成。

如果您在作业运行期间使用 helm uninstall 或 helm upgrade 移除 runner Pod，则作业完成时可能会出现如下所示的 Unauthorized 错误：

plaintext
ERROR: Error cleaning up pod: Unauthorized
ERROR: Error cleaning up secrets: Unauthorized
ERROR: Job failed (system failure): Unauthorized

这可能是因为移除 runner 时，角色绑定也被移除了。runner Pod 会继续运行直到作业完成，然后 runner 尝试删除它。没有角色绑定，runner Pod 就不再具有访问权限。

有关详细信息，请参阅此议题。

Elasticsearch 服务启动错误 max virtual memory areas vm.max_map_count [65530] is too low#

在 Elasticsearch 服务容器启动时，您可能会收到类似以下的错误：

  • max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Elasticsearch 有一个 vm.max_map_count 要求，必须在运行 Elasticsearch 的实例上设置。 有关如何根据平台正确设置此值，请参阅 Elasticsearch 文档。

错误：Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1#

当 Docker 机器无法成功创建执行器虚拟机时，可能会发生此错误。要获取有关该错误的更多信息，请使用您在 config.toml中定义的相同 MachineOptions 手动创建虚拟机。

例如：docker-machine create --driver=google --google-project=GOOGLE-PROJECT-ID --google-zone=GOOGLE-ZONE ...。

错误：No unique index found for name#

当您创建或更新 runner，而数据库没有为 tags 表建立唯一索引时，可能会发生此错误。在极狐GitLab UI 中，您可能会收到 Response not successful: Received status code 500 错误。

此问题可能会影响在较长时间内经历过多次主要升级的实例。要解决此问题，请使用 gitlab:db:deduplicate_tags Rake 任务合并表中的任何重复标签。有关更多信息，请参阅 Rake 任务。

错误：Not authorized to perform sts:AssumeRoleWithWebIdentity#

如果您为 runner 的 Kubernetes ServiceAccount 资源配置了 IAM 角色， 但 runner 日志显示它无法执行 sts:AssumeRoleWithWebIdentity，您可能会收到如下错误：

plaintext
{"error":"Not authorized to perform sts:AssumeRoleWithWebIdentity","level":"error","msg":"error while generating S3 pre-signed URL","time":"2025-10-15T18:07:20Z"}

当您在 IAM 角色可信实体配置的 StringLike 或 StringEquals 条件中包含 https:// 时，就会发生此问题。

要解决此问题，请从 OIDC URL 中移除 https://：

json
1"Action": "sts:AssumeRoleWithWebIdentity",
2"Condition": {
3  "StringLike": {
4    "oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>"
5  }
6}