GitLab容器镜像仓库故障排查指南

GitLab容器镜像仓库故障排查指南

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq

前言

作为GitLab的核心组件之一，容器镜像仓库(Container Registry)在使用过程中可能会遇到各种问题。本文将系统性地介绍常见问题的排查方法和解决方案，帮助管理员快速定位和解决问题。

基础排查步骤

在深入具体问题前，建议先执行以下基础检查：

1. 时间同步检查：确保Docker客户端和GitLab服务器的时间通过NTP服务保持同步，时间不同步会导致认证失败。

2. S3存储验证：对于使用S3存储后端的仓库，确认：

   • IAM权限配置正确
   • S3凭证有效
   • 区域设置匹配

3. 日志分析：检查关键日志文件：

   • 仓库日志：/var/log/gitlab/registry/current
   • GitLab生产日志：/var/log/gitlab/gitlab-rails/production.log

4. 网络配置验证：

   • 检查NGINX配置文件：/var/opt/gitlab/nginx/conf/gitlab-registry.conf
   • 确认请求转发端口正确

5. 端点连通性测试：

   curl --verbose --noproxy "*" https://<主机名>:<端口>/v2/_catalog
   

   正常响应应包含Www-Authenticate: Bearer头部，其中service="container_registry"。

常见问题及解决方案

自签名证书问题

使用自签名证书时，CI作业中可能出现：

Error response from daemon: Get registry.example.com/v1/users/: x509: certificate signed by unknown authority

解决方案：

1. 配置Docker守护进程信任自签名证书
2. 修改GitLab Runner配置文件config.toml：

   [runners.docker]
     privileged = false
     volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
   

认证失败："token signed by untrusted key"

错误表现为：

level=info msg="token signed by untrusted key with ID:..."

排查步骤：

1. 确认证书密钥对路径：

   grep -A6 'auth:' /var/opt/gitlab/registry/config.yml
   grep -A9 'Container Registry' /var/opt/gitlab/gitlab-rails/etc/gitlab.yml
   

2. 验证证书密钥对匹配：

   openssl x509 -noout -modulus -in 证书路径 | openssl sha256
   openssl rsa -noout -modulus -in 密钥路径 | openssl sha256
   

3. 若不匹配：

   • 删除相关文件
   • 执行gitlab-ctl reconfigure重新生成
   • 如需全新生成，先删除/etc/gitlab/gitlab-secrets.json中的registry部分

大镜像推送失败

AWS S3存储后端推送大镜像时可能出现：

level=error msg="response completed with error" err.detail="unexpected EOF"

解决方案：

1. 在配置中增加chunksize参数(25-50MB之间)：

   registry['storage'] = {
     's3' => {
       'chunksize' => 25000000
     }
   }
   

旧版Docker客户端兼容问题

默认禁用schema1清单，旧客户端(1.9或更早)可能推送失败。

启用兼容模式：

registry['compatibility_schema1_enabled'] = true

特殊字符导致的连接错误

组/项目/分支名中包含特殊字符时可能出错，如：

• 前导下划线
• 尾部连字符
• 双连字符

解决方案：

1. 修改路径/名称
2. 或设置推送规则限制

镜像推送重试循环

即使docker login成功，推送仍陷入重试循环。

解决方案：

registry['env'] = {
  "REGISTRY_HTTP_RELATIVEURLS" => true
}

高级调试技巧

调试服务器启用

1. 配置调试地址：

   registry['debug_addr'] = "localhost:5001"
   

2. 访问调试端点：

   curl "localhost:5001/debug/health"
   curl "localhost:5001/debug/vars"
   

Prometheus监控指标

启用调试服务器后，可添加Prometheus支持：

registry['debug'] = {
  'prometheus' => {
    'enabled' => true,
    'path' => '/metrics'
  }
}

调试日志启用

临时启用详细日志：

level: debug

注意：调试日志可能包含敏感信息，排查后应及时关闭。

清理策略调试

通过Rails控制台逐步执行清理策略，验证策略逻辑：

repo = ContainerRepository.find(<仓库ID>)
policy = repo.project.container_expiration_policy
# 逐步执行策略条件过滤

网络问题深度排查

对于复杂的网络问题(如403错误)，建议：

1. 使用mitmproxy进行中间人抓包分析
2. 或临时启用不安全Registry进行本地测试(仅限测试环境)

结语

本文涵盖了GitLab容器镜像仓库的常见问题排查方法和高级调试技巧。通过系统性的排查步骤，管理员可以快速定位和解决大多数运行问题。对于更复杂的问题，建议结合日志分析和网络抓包等高级技术进行深入诊断。

gitlabhq GitLab CE Mirror | Please open new issues in our issue tracker on GitLab.com 项目地址: https://gitcode.com/gh_mirrors/gi/gitlabhq