如何在Linux上使用GitLab的容器注册表

在 Linux 上使用 GitLab Container Registry 的完整指南

一 前置准备

• 准备可访问的 GitLab 实例（域名或 IP），并开放相应端口（如 80/443/5000/5050）。
• 在客户端安装 Docker，并准备用于登录的 GitLab 个人访问令牌（read_registry + write_registry 权限）。
• 规划 Registry 访问方式：生产环境强烈建议使用 HTTPS；若仅在内网测试，可临时使用 HTTP。
• 若使用自托管 GitLab（非 SaaS），确保服务器时间与 NTP 同步，避免令牌校验异常。

二 在 GitLab 中启用并配置 Registry

• 管理员启用
  • 路径：Admin Area > Settings > General > Container Registry，勾选 Enable Container Registry。
  • 如使用 Omnibus 安装，可在 /etc/gitlab/gitlab.rb 中设置：
    • 启用 Registry：
      • registry_external_url ‘https://registry.example.com’
      • gitlab_rails[‘registry_enabled’] = true
    • 指定存储（示例为本地）：
      • registry[‘storage’] = { ‘filesystem’ => { ‘rootdirectory’ => ‘/var/opt/gitlab/registry’ } }
      • registry[‘storage_delete_enabled’] = true
    • 重新加载：执行 gitlab-ctl reconfigure。
• 端口与域名规划
  • 可复用 GitLab 域名的不同端口（如 https://gitlab.example.com:4443），避免与 GitLab 主服务端口冲突。
  • 若使用独立域名（如 registry.example.com），为该域名配置 TLS 证书（推荐 Let’s Encrypt）。
• 防火墙与网络
  • 开放对应端口（如 443/5000/5050），并确保反向代理或 Ingress 正确转发至 Registry。

三 客户端登录与镜像操作

• 登录 Registry
  • 使用个人访问令牌登录（用户名任意，密码填令牌）：
    • docker login registry.example.com:5050
    • 或：docker login registry.example.com:5050 --username=<your_username> --password=<your_token>
• 命名规范
  • 镜像名称格式：///:
  • 示例：registry.example.com:5050/mygroup/myproject/myapp:v1
• 构建与推送
  • docker build -t registry.example.com:5050/mygroup/myproject/myapp:v1 .
  • docker push registry.example.com:5050/mygroup/myproject/myapp:v1
• 拉取
  • docker pull registry.example.com:5050/mygroup/myproject/myapp:v1
• 常见问题速解
  • 出现 “http: server gave HTTP response to HTTPS client”：说明客户端以 HTTPS 访问了 HTTP 端点，需改为 http:// 或正确配置 HTTPS。
  • 登录失败或 404：核对 域名/端口、项目路径、以及是否启用 Registry。

四 在 GitLab CI 中使用 Registry

• 内置变量（推荐方式）
  • CI 中可直接使用：
    • CI_REGISTRY：Registry 地址
    • CI_REGISTRY_USER：固定值 gitlab-ci-token
    • CI_REGISTRY_PASSWORD：CI_JOB_TOKEN
    • CI_REGISTRY_IMAGE：项目镜像地址（含命名空间与项目）
• 示例 .gitlab-ci.yml
  • stages:
    • build
    • push
  • build:
    • stage: build
    • image: docker:latest
    • services:
      • docker:dind
    • script:
      • docker build --pull -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
  • push:
    • stage: push
    • image: docker:latest
    • services:
      • docker:dind
    • script:
      • docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY
      • docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
• 说明
  • 无需在 CI 中保存明文密码；CI_JOB_TOKEN 自动授权当前项目对 Registry 的推送。

五 安全与运维最佳实践

• 安全加固
  • 强制 HTTPS（Let’s Encrypt 或企业 CA），禁用明文 HTTP；必要时配置 IP 白名单 与 速率限制。
  • 启用 镜像签名（如 cosign）与 漏洞扫描，在 GitLab 15.0+ 可在界面查看签名状态与扫描结果。
• 存储与清理
  • 生产环境优先使用 对象存储（如 S3/MinIO）作 Registry 后端；本地存储需监控磁盘使用。
  • 配置 镜像保留策略 与 自动清理（按标签数量或时间保留最近 N 个版本），避免存储膨胀。
• 监控与日志
  • 结合 Prometheus/Grafana 监控 Registry 吞吐与延迟；集中收集 Nginx/Registry 日志，便于审计与排障。
• 备份与升级
  • 定期备份 /var/opt/gitlab/registry 与 GitLab 配置/数据卷；升级前在测试环境验证，遵循官方升级路径。