极狐 GitLab Logo

极狐GitLab Runner 故障排查
所有级别

以下内容可以帮助您处理极狐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 Machine：#

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

删除所有 Docker Machine:#

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 进行安装）请求作业。

当日志在 Windows 上以服务的形式运行时存储在哪里？#

  • 如果极狐GitLab Runner 在 Windows 上以服务的形式运行，系统事件日志会增加。如果您想查看日志，打开事件查看器（在运行菜单中，输入 eventvwr.msc 或搜索"事件查看器"）。然后单击 Windows 日志 > 应用。Runner 日志的源是 gitlab-runner。如果您使用的是 Windows Server Core，请运行 get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto PowerShell 命令获取最近 20 个日志条目。

启用调试 Logging 模式#

WARNING: 调试 Logging 是很严重的安全风险。输出包含作业可用的所有变量和其他密钥的内容。

命令行中#

以根用户的身份从终端登录，运行：

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

极狐GitLab Runner config.toml 中#

您可以将 log_level 设置为 debug，在 config.toml 的全局部分启用调试 Logging。在您的 config.toml 的最上面以及并发行的前/后添加以下行：

toml
log_level = "debug"

Helm Chart 中#

如果使用极狐GitLab Runner Helm Chart 将极狐GitLab Runner 安装在 Kubernetes 集群中，您可以通过设置 values.yaml 自定义中的 logLevel 选项启用调试 Logging：

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

为 Docker 执行器 Runner 配置 DNS#

当使用 Docker 执行器配置极狐GitLab Runner 时，可能会遇到这样的问题：主机上的 Runner Daemon 可以访问极狐GitLab，但是构建容器却无法访问。这是因为主机上配置了 DNS，但是这些配置却没有传递到容器中。

示例：

极狐GitLab 服务和极狐GitLab Runner 存在于以两种方式桥接的不同的网络中（例如，通过 Internet 或 VPN)。如果 Runner 用来查找极狐GitLab 服务所使用的路由机制查询了 DNS，容器的 DNS 配置不知道通过 VPN 使用 DNS 服务，可能会默认使用通过 Internet 提供的服务。这个配置可能会导致以下信息：

shell
Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 15.11.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/'

在这种情况下，Internet 和极狐GitLab 服务之间的服务会导致鉴权失败。这个服务使用单独的证书，如果它们通过 VPN 使用 DNS 服务，Runner 会进行规避。

您可以通过使用 Runner 的 config.toml 文件中的 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 安装时，一些证书可能无效。

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

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

  • 主机名称长度超过了创建机器所支持的最大长度。比如，Ubuntu 机器有 64 个字符的 HOST_NAME_MAX 限制。可通过 docker-machine ls 检查机器名称。检查 runner 配置中的 MachineName 并在需要时减少主机名长度。

NOTE: 在 Docker 安装到机器之前，此错误可能已经发生。

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

当 Docker autoscaler 不能连接到目标系统的 Docker 守护进程时就会出现此错误，当连接是通过 SSH 隧道时。确保您可以 SSH 到目标系统并成功运行 Docker 命令，例如 docker info。

在弹性伸缩 Runner 上添加 AWS 实例配置文件#

创建 AWS IAM 角色之后，在您的 IAM 控制台中，角色会拥有角色 ARN 和实例配置文件 ARN。您必须使用实例配置文件名称，而不是角色名称。

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

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

AUFS 存储驱动损坏很可能会导致这件事情的发生。

最好的解决方法是将存储驱动 更改为 OverlayFS（更快）或 DeviceMapper（更慢）。

请参阅配置和运行 Docker 或 用 Systemd 进行控制和配置。

上传产物时出现 411#

这是因为极狐GitLab Runner 使用了早期 NGINX (https://serverfault.com/questions/164220/is-there-a-way-to-avoid-nginx-411-content-length-required-errors) 版本上损坏的 Transfer-Encoding: chunked。

升级 NGINX 到新版本。

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

当为作业配置环境时可能会遇到此问题，但是极狐GitLab Runner 帮助器没有任何预签名的 URL 来访问远端缓存，或者说是无效的 URL。审核每一个缓存相关的 config.toml 条目并确定提供了对应的键和值。无效的 URL 可能是由任何不遵循 URL 语法要求的条目构造的。

此外，请确保您的极狐GitLab Runner 帮助器 image 和 helper_image_flavor 是匹配且为最新版本。

如果遇到了与凭据配置相关的问题，诊断的错误信息会被天骄到极狐GitLab Runner 的进程日志中。

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

当使用 HTTP（通过极狐GitLab Runner 或手动测试）运行 git clone， 您会看见如下输出：

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 请求被代理到极狐GitLab Workhorse Socket，而不是 极狐GitLab Unicorn Socket。

极狐GitLab Workhorse 解决了通过 HTTP 的 Git 协议 ，所以它是极狐GitLab 的主要入口点。

如果您使用的是极狐 Omnibus GitLab，并且不想使用捆绑的 NGINX 服务器，请阅读使用非捆绑网页服务器。

极狐GitLab Recipes 仓库中有 Apache 和 NGINX 的网页服务器配置示例。

如果您使用从源安装的极狐GitLab，您也需要阅读以上文档和示例，并确保所有 HTTP 流量都流经极狐GitLab Workhorse。

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

可以配置描述 [[docker.machine.autoscaling]] 周期的时区，此功能应该可以在大多数 Unix 系统上开箱即用。然而在一些 Unix 系统及大多数非 Unix 系统上（包括我们提供极狐GitLab Runner 二进制文件的 Windows）使用这个功能的时候，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

如果您的系统没有以 native 的方式提供此数据库，那么您可以按照以下步骤使 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.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 系统）或通过将 ZONEINFO 变量添加到极狐GitLab Runner 用户通过系统设置可以使用的环境变量列表中（Windows 系统）来更新/覆盖服务配置。

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

您可以这样做，但是不能共享同一个 config.toml 文件。

使用同一个配置文件运行多个极狐GitLab Runner 实例会导致不可预测和难以调试的行为。

Job failed (system failure): preparing environment:#

这个错误通常由您的 Shell 加载配置文件而导致，并且是由一个脚本引发的失败。

已知能引发失败的 Dotfile 示例为：

  • .bash_logout
  • .condarc
  • .rvmrc

SELinux 也是引发这个错误的一个原因。您可以查看 SELinux 审计日志进行确定：

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

Cleaning up 阶段后 Runner 突然停止#

当启用“容器漂移检测”设置时，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, increase to at least [262144]#

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

关于如何基于平台正确设置此值，请参见 Elasticsearch 文档。

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

当 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 错误。

此问题可能会影响经历过多次主版升级且长时间运行的实例。

要解决此问题：

  1. 在Rails 控制台中，通过运行 dedupe.rb 脚本，合并表中可能存在的任何重复标签。

  2. 为 tags 表创建唯一的索引：

    sql
    DROP INDEX IF EXISTS index_tags_on_name; -- Drop a potentially invalid index
CREATE UNIQUE INDEX index_tags_on_name ON tags USING btree (name);