GitLab CE 14.2.4域名方式启用容器仓库及镜像推送、CI集成问题

一、独立域名启用Container Registry的完整步骤 #

GitLab 14.2.4版本仅配置registry_external_url无法生效，需完成以下完整配置流程：

1. 编辑GitLab主配置文件
   打开/etc/gitlab/gitlab.rb，添加或修改以下配置项（替换为你的实际域名和证书路径）：

   # 配置仓库独立域名
   registry_external_url 'https://registry.gitlab.example.com'
   
   # 启用Registry核心服务
   registry['enable'] = true
   registry['registry_http_addr'] = "0.0.0.0:5000"
   
   # 启用Registry专属Nginx反向代理
   registry_nginx['enable'] = true
   registry_nginx['listen_port'] = 443
   registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/registry.gitlab.example.com.crt"
   registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/registry.gitlab.example.com.key"
   
   # 配置GitLab Rails端关联参数
   gitlab_rails['registry_enabled'] = true
   gitlab_rails['registry_host'] = "registry.gitlab.example.com"
   gitlab_rails['registry_port'] = 443
   gitlab_rails['registry_api_url'] = "https://registry.gitlab.example.com/v2/"
   
   # （可选）如果使用自签证书，配置Registry信任根证书
   registry['rootcertbundle'] = "/etc/gitlab/ssl/registry.gitlab.example.com.crt"
   

2. 应用配置并重启服务
   执行命令让配置生效：

   gitlab-ctl reconfigure
   gitlab-ctl restart
   

3. 验证基础服务

   • 确认DNS解析已将registry.gitlab.example.com指向GitLab服务器IP
   • 检查防火墙开放443（HTTPS）和5000（Registry内部端口）端口
   • 访问https://registry.gitlab.example.com/v2/，返回空JSON即表示服务正常

二、向仓库推送Docker镜像 #

1. 获取GitLab个人访问令牌
   在GitLab个人设置中生成令牌，需勾选read_registry和write_registry权限。

2. 登录Registry仓库
   在本地Docker环境执行登录命令：

   docker login registry.gitlab.example.com
   # 输入用户名（GitLab账号）和刚才生成的令牌作为密码
   

3. 镜像打标与推送

   • 给本地镜像打标（替换为你的项目路径、镜像名和版本）：

     docker tag local-image:v1 registry.gitlab.example.com/your-group/your-project/my-image:v1
     

   • 推送镜像到仓库：

     docker push registry.gitlab.example.com/your-group/your-project/my-image:v1
     

三、GitLab CI与容器仓库集成 #

通过.gitlab-ci.yml实现自动构建并推送镜像，示例配置如下：

stages:
  - build

build-and-push:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
    # 使用GitLab预定义变量动态生成镜像名
    IMAGE_TAG: registry.gitlab.example.com/$CI_PROJECT_PATH/app:$CI_COMMIT_SHORT_SHA
  before_script:
    # 用预定义变量自动登录仓库，无需手动输入凭据
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $IMAGE_TAG .
    - docker push $IMAGE_TAG

说明：

• $CI_REGISTRY、$CI_REGISTRY_USER、$CI_REGISTRY_PASSWORD是GitLab预定义变量，自动关联当前项目的容器仓库
• docker:dind服务用于在CI环境中启动Docker守护进程，支持镜像构建

四、解决仅配置registry_external_url不生效的问题 #

GitLab 14.2.4版本中，registry_external_url仅用于设置对外访问地址，必须配合以下关键配置才能启用服务：

1. 启用Registry核心服务：registry['enable'] = true
2. 开启Registry专属Nginx代理：registry_nginx['enable'] = true
3. 配置GitLab Rails端的仓库关联参数（gitlab_rails下的registry相关项）
4. 确保证书路径正确且权限合规（证书文件需被GitLab进程读取）

完成上述配置后，重新执行gitlab-ctl reconfigure和gitlab-ctl restart即可生效。

内容的提问来源于stack exchange，提问作者Dmitry