处理极狐GitLab Runner 故障

以下内容可以帮助您处理极狐GitLab Runner 故障。

一般故障处理提示

查看日志

  • tail -100 /var/log/syslog (Debian)
  • tail -100 /var/log/messages (RHEL)

重启服务：

  • service gitlab-runner restart

查看 Docker Machine：

  • sudo docker-machine ls
  • sudo su - && docker-machine ls

删除所有 Docker Machine:

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

更改完 config.toml 之后：

  • service gitlab-runner restart
  • docker-machine rm $(docker-machine ls -q)
  • tail -f /var/log/syslog (Debian)
  • tail -f /var/log/messages (RHEL)

确认您的极狐 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 模式

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

命令行中

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

gitlab-runner stop
gitlab-runner --debug run

极狐GitLab Runner config.toml 中

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

log_level = "debug"

Helm Chart 中

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

## 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 提供的服务。这个配置可能会导致以下信息： 

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 服务器。 

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.

如果发生了 Unable to query docker version: Cannot connect to the docker engine endpoint 错误，可能与 TLS 错误有关。如果安装了 docker-machine，会导致一些证书无法正常使用。

为解决这个问题，您需要清除这些证书并重启 Runner。重启之后，Runner 会发现证书为空，随即重新创建证书。 

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

在弹性伸缩 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 到新版本。

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

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

$ 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 在启动时会崩溃，并出现类似于以下的错误： 

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 系统，可以通过以下方式完成： 

# on Debian/Ubuntu based systems
sudo apt-get install tzdata

# on RPM based systems
sudo yum install tzdata

# on Linux Alpine
sudo 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，那么您可以这样做： 

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

    或使用 Windows： 

    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 审计日志进行确定： 

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 错误： 

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 文档。