GitLab 进阶：集成 Docker Registry 的两种方案对比
两种方案概述
GitLab 可以与容器镜像仓库对接，实现 Docker 镜像的构建、推送和管理。主要有两种方案：
| 方案 | 说明 | 推荐度 |
|---|---|---|
| GitLab 内置 Container Registry | 基于 Docker Distribution，与 GitLab 深度集成 | 一般 |
| Harbor Registry | 专业的容器镜像仓库，通过 GitLab 集成对接 | 推荐 |
方案详细对比
功能对比
| 特性 | GitLab 内置 Registry | Harbor Registry |
|---|---|---|
| 部署难度 | 较高（需域名 + SSL + 配置 GitLab） | 低（docker-compose 一键启动） |
| CI/CD 集成度 | 高（内置变量自动注入） | 高（通过集成配置获取变量） |
| 镜像管理 | 基础功能 | 丰富（镜像扫描、签名、复制） |
| 权限控制 | 依赖 GitLab 权限体系 | 独立 RBAC，更精细 |
| 域名要求 | 必须有独立域名 | 无要求，IP 可访问 |
| SSL 证书 | 必须配置 | 可选 |
| Web UI | GitLab 内嵌页面 | 独立管理界面，功能丰富 |
| 垃圾回收 | 需手动执行 | 自动化策略 |
| 漏洞扫描 | 不支持 | 内置 Trivy/Clair 扫描 |
| 镜像复制 | 不支持 | 支持跨仓库复制 |
| 维护成本 | 需修改 GitLab 配置 | 独立维护，不影响 GitLab |
部署复杂度对比
方案一：GitLab 内置 Registry
├── 1. 配置独立域名
├── 2. 生成 SSL 证书
├── 3. 修改 gitlab.rb 配置文件
├── 4. 放置证书到指定目录（名称固定）
├── 5. 重启 GitLab 服务
└── 6. 使用 openssl 验证证书
方案二：Harbor Registry
├── 1. docker-compose up -d
└── 完成
text
方案一：GitLab 内置 Container Registry
配置要求
- 域名：需要为 Registry 配置独立的域名（如
registry.example.com） - SSL 证书：必须配置 HTTPS，确保证书放置在正确位置
- GitLab 配置：修改
gitlab.rb文件启用 Registry
配置步骤
1. 修改 gitlab.rb
# /etc/gitlab/gitlab.rb
# 启用 Container Registry
registry_external_url 'https://registry.example.com'
# 证书配置（路径和文件名固定，不能随意更改）
registry_nginx['ssl_certificate'] = '/etc/gitlab/ssl/registry.example.com.crt'
registry_nginx['ssl_certificate_key'] = '/etc/gitlab/ssl/registry.example.com.key'
ruby
2. 放置证书
# 证书必须放置在容器内的指定目录
# 文件名必须与域名一致
sudo mkdir -p /etc/gitlab/ssl/
sudo cp registry.example.com.crt /etc/gitlab/ssl/
sudo cp registry.example.com.key /etc/gitlab/ssl/
sudo chmod 600 /etc/gitlab/ssl/registry.example.com.key
bash
3. 重启 GitLab
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
bash
4. 验证证书
openssl s_client -connect registry.example.com:443 -showcerts
bash
CI/CD 使用内置 Registry
# .gitlab-ci.yml
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
build-and-push:
stage: build
image: docker:24-cli
services:
- docker:24-dind
before_script:
# 使用内置变量登录 Registry
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
# 设置镜像标签
- |
if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then
export TAG="latest"
else
export TAG="$CI_COMMIT_REF_SLUG"
fi
- docker build -t $CI_REGISTRY_IMAGE:$TAG .
- docker push $CI_REGISTRY_IMAGE:$TAG
rules:
# 仅在包含 Dockerfile 的提交触发
- changes:
- Dockerfile
yaml
内置变量（自动注入，无需配置）：
| 变量 | 说明 |
|---|---|
$CI_REGISTRY | Registry 地址 |
$CI_REGISTRY_USER | 登录用户名 |
$CI_REGISTRY_PASSWORD | 登录密码 |
$CI_REGISTRY_IMAGE | 当前项目的镜像路径 |
坑点总结
- 证书文件名必须固定：不能随意命名，必须与域名一致
- 证书目录必须正确：容器内路径为
/etc/gitlab/ssl/ - 必须使用 HTTPS：Docker 拉取镜像时需要安全连接
- GitLab 配置修改风险：修改
gitlab.rb可能影响整个 GitLab 服务
方案二：Harbor Registry（推荐）
Harbor 优势
- 部署简单：一个
docker-compose up命令即可启动 - 专业管理：提供独立的 Web 管理界面
- 安全扫描：内置镜像漏洞扫描
- 不影响 GitLab：独立运行，不依赖 GitLab 配置
- 企业级功能：RBAC、镜像复制、审计日志
Harbor 部署
# 下载 Harbor 安装包
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-online-installer-v2.10.0.tgz
# 解压
tar xvf harbor-online-installer-v2.10.0.tgz
cd harbor
# 配置 harbor.yml
cp harbor.yml.tmpl harbor.yml
bash
# harbor.yml（关键配置）
hostname: 192.168.3.177
http:
port: 8088
harbor_admin_password: Harbor12345
database:
password: root123
data_volume: /data/harbor
yaml
# 安装并启动
./install.sh
docker-compose up -d
bash
GitLab 集成 Harbor
- 进入 GitLab -> Admin Area > Applications > Integrations
- 搜索并点击 Harbor
- 填写配置：
| 配置项 | 说明 | 示例 |
|---|---|---|
| Harbor URL | Harbor 服务地址 | http://192.168.3.177:8088 |
| Project name | Harbor 项目名称 | my-project |
| Username | Harbor 用户名 | admin |
| Password | Harbor 密码 | Harbor12345 |
- 点击 Save changes
CI/CD 使用 Harbor
集成完成后，GitLab 会自动创建 CI/CD 变量，可在流水线中直接使用：
# .gitlab-ci.yml
build-and-push:
stage: build
image: docker:24-cli
services:
- docker:24-dind
script:
# 登录 Harbor（使用集成变量）
- docker login -u $HARBOR_USERNAME -p $HARBOR_PASSWORD $HARBOR_URL
# 构建并推送
- docker build -t $HARBOR_URL/$HARBOR_PROJECT/my-app:$CI_COMMIT_SHA .
- docker push $HARBOR_URL/$HARBOR_PROJECT/my-app:$CI_COMMIT_SHA
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
yaml
方案选择建议
推荐使用 Harbor 的场景
- 团队规模较大，需要精细的权限管理
- 需要镜像漏洞扫描
- 不想修改 GitLab 核心配置
- 需要独立的镜像管理界面
- 多环境镜像分发（开发/测试/生产）
使用内置 Registry 的场景
- 小型团队，项目数量少
- 已有域名和 SSL 证书基础设施
- 不需要高级镜像管理功能
- 希望减少独立服务维护
CI/CD 变量参考
无论使用哪种方案，GitLab CI/CD 都提供了丰富的预定义变量：
| 变量类别 | 示例变量 | 说明 |
|---|---|---|
| 提交相关 | $CI_COMMIT_SHA, $CI_COMMIT_BRANCH | 当前提交信息 |
| 项目相关 | $CI_PROJECT_ID, $CI_PROJECT_DIR | 项目信息 |
| 流水线相关 | $CI_PIPELINE_ID, $CI_JOB_ID | 流水线/任务 ID |
| Registry 相关 | $CI_REGISTRY, $CI_REGISTRY_USER | 镜像仓库信息 |
注意：部分变量有最低 GitLab 版本要求。使用前请查阅 Predefined Variables Reference，确认版本兼容性。
总结
- Harbor 更推荐：部署简单、功能丰富、不影响 GitLab
- 内置 Registry 适合：小团队快速上手，CI/CD 集成度更高
- 核心原则：专业的工具做专业的事情，让 CI/CD 专注流程编排，镜像管理交给专业平台
↑