极狐 GitLab Logo

极狐GitLab Runner

  1. Tier: 基础版，专业版，旗舰版
  2. 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 是一个孤立的代理，通过极狐GitLab API 从 coordinator（极狐GitLab 安装）请求作业。

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

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

启用调试日志模式#

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

在命令行中#

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

这不应在使用 [Shell executor](../executors/shell.md) 的 runners 上执行，因为它重新定义了 `systemd` 服务并以 root 身份运行所有作业。这带来了安全风险，并更改了文件所有权，使得很难恢复到非特权帐户。
shell
gitlab-runner stop
gitlab-runner --debug run

在极狐GitLab Runner config.toml 中#

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

toml
log_level = "debug"

在 Helm Chart 中#

如果极狐GitLab Runner 是使用 极狐GitLab Runner Helm Chart 安装在 Kubernetes 集群中，要启用调试日志记录，请在 values.yaml customization 中设置 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

配置 Docker executor runner 的 DNS#

当您使用 Docker executor 配置极狐GitLab Runner 时，即使主机 Runner 守护进程具有访问权限，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 executor，并且您正在连接到安装在服务器上的 Docker Engine。您可能会看到 Permission Denied 错误。最可能的原因是您的系统使用 SELinux（在 CentOS、Fedora 和 RHEL 上默认启用）。检查系统上 SELinux 策略是否可能被拒绝。

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

此错误与机器供应有关，可能是由于以下原因：

  1. 存在 TLS 失败。当安装 docker-machine 时，某些证书可能无效。为了解决此问题，请删除证书并重新启动 runner：
shell
sudo su -
rm -r /root/.docker/machine/certs/*
service gitlab-runner restart

runner 重新启动后，会注册证书为空并重新创建它们。

  1. 主机名长于在提供的机器中支持的长度。例如，Ubuntu 机器对 HOST_NAME_MAX 有 64 个字符的限制。主机名由 docker-machine ls 报告。检查 runner 配置中的 MachineName 并在需要时减少主机名长度。
此错误可能在机器上安装 Docker 之前发生。

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

当 Docker autoscaler 无法通过 SSH 通道连接到目标系统上的 Docker 守护进程时，会发生此错误。确保您可以 SSH 到目标系统并成功运行 Docker 命令，例如 docker info。

为您的自动扩展 runners 添加 AWS 实例配置文件#

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

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

构建 Java 项目时，Docker executor 超时#

这很可能是由于损坏的 aufs 存储驱动程序：Java 进程卡顿在内部容器。最佳解决方案是将 storage driver 更改为 OverlayFS（更快）或 DeviceMapper（较慢）。

查看关于配置和运行 Docker或使用 systemd 控制和配置的文章。

上传产物时出现 411#

这是由于极狐GitLab Runner 使用 Transfer-Encoding: chunked，而这在 NGINX 的早期版本中是损坏的。

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

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

  1. 使用 Docker executor，上传是从 Docker 容器中发生的
  2. 使用 Kubernetes executor，上传是从构建 pod 中的构建容器中发生的

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

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

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

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

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

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

当极狐GitLab Runner 帮助程序接收到无效的 URL 或没有任何预签名的 URL 来访问远程缓存时，会发生此错误。查看每个与缓存相关的 config.toml 条目和提供者特定的键和值。无效的 URL 可能是由不符合 URL 语法要求的任何项目构建的。

此外，请确保您的帮助程序 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-server。

在极狐GitLab Recipes 存储库中，有适用于 Apache 和 NGINX 的web-server 配置示例。

如果您使用的是从源代码安装的极狐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，则在 C:\gitlab-runner\zoneinfo.zip 中保存 zoneinfo.zip。

  3. 设置包含 zoneinfo.zip 文件完整路径的 ZONEINFO 环境变量。如果您正在使用 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 文件。

Job failed (system failure): preparing environment:#

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

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

  1. .bash_logout
  2. .condarc
  3. .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 卸载或升级使用 Helm 部署的 runners 之前，请在极狐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, increase to at least [262144]#

Elasticsearch 有一个 vm.max_map_count 要求，必须在运行 Elasticsearch 的实例上设置。

Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1 Will be retried in 3s#

当 Docker 机器无法成功创建 executor 虚拟机时，可能会出现此错误。要获取有关错误的更多信息，请使用在 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 任务。