10分钟极速搭建GitLab私有镜像库：Docker Compose全流程指南

对于中小团队或个人开发者而言，搭建私有Docker镜像仓库往往意味着繁琐的证书配置和复杂的网络设置。本文将展示如何绕过这些障碍，通过Docker Compose快速部署一个基于HTTP协议的GitLab私有镜像库，整个过程仅需10分钟。

1. 为什么选择GitLab Container Registry？

在容器化开发中，镜像管理是不可或缺的一环。相比公共仓库，私有镜像库提供了以下优势：

• 完全掌控：自主管理镜像的存储、访问权限和生命周期
• 网络优化：内网传输速度远超从公共仓库拉取
• 安全性：敏感镜像无需上传到第三方平台
• CI/CD集成：与GitLab CI无缝协作，自动化构建和部署

关键对比：HTTP vs HTTPS协议

特性	HTTP配置	HTTPS配置
证书要求	无需	需要有效SSL证书
安全性	适合内网环境	适合公网暴露
配置复杂度	简单，几行配置即可	需要证书申请和更新机制
适用场景	开发/测试环境、内部系统	生产环境、外部访问

2. 环境准备与基础配置

2.1 系统要求

确保你的主机满足以下条件：

• 已安装Docker Engine 20.10.0+
• 已安装Docker Compose 2.0.0+
• 至少4GB可用内存
• 至少10GB磁盘空间

提示：可通过docker --version和docker-compose --version命令验证版本

2.2 目录结构准备

建议创建专用目录存放配置：

mkdir -p ~/gitlab-ee/{config,logs,data}
export GITLAB_HOME=~/gitlab-ee

3. Docker Compose配置详解

3.1 编写docker-compose.yml

创建docker-compose.yml文件，内容如下：

version: '3.6'

services:
  gitlab:
    image: 'gitlab/gitlab-ee:15.11.2-ee.0'
    restart: always
    hostname: 'gitlab.example.com'
    container_name: gitlab-ee
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://gitlab.example.com'
        registry_external_url 'http://gitlab.example.com:5050'
        gitlab_rails['registry_enabled'] = true
        gitlab_rails['registry_host'] = "gitlab.example.com"
        gitlab_rails['registry_port'] = "5050"
    ports:
      - '80:80'
      - '5050:5050'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

关键参数说明：

• registry_external_url：指定Registry服务地址和端口
• ports映射中必须包含5050端口用于Registry服务
• volumes确保配置和数据持久化

3.2 启动服务

执行以下命令启动容器：

docker-compose up -d

首次启动可能需要3-5分钟初始化，可通过以下命令查看日志：

docker logs -f gitlab-ee

4. 验证与使用Registry

4.1 登录GitLab确认Registry状态

1. 访问http://gitlab.example.com（需配置本地hosts或使用真实域名）
2. 使用初始密码登录（密码存储在$GITLAB_HOME/config/initial_root_password）
3. 导航到"Admin > Overview > Components"确认Registry服务状态

4.2 配置Docker客户端

由于使用HTTP协议，需在Docker客户端进行特殊配置：

Linux/macOS：

mkdir -p /etc/docker
echo '{"insecure-registries": ["gitlab.example.com:5050"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

Windows： 编辑C:\ProgramData\docker\config\daemon.json，添加：

{
  "insecure-registries": ["gitlab.example.com:5050"]
}

然后重启Docker服务

4.3 镜像推送实战

以下演示完整的工作流程：

# 拉取测试镜像
docker pull busybox

# 登录Registry（使用GitLab账号）
docker login gitlab.example.com:5050

# 标记镜像
docker tag busybox gitlab.example.com:5050/my-group/my-project:latest

# 推送镜像
docker push gitlab.example.com:5050/my-group/my-project:latest

成功推送后，在GitLab项目的"Packages & Registries > Container Registry"中即可看到该镜像。

5. 高级配置与优化

5.1 存储位置自定义

默认情况下，镜像存储在容器内的/var/opt/gitlab/gitlab-rails/shared/registry。如需修改：

1. 在宿主机创建目录：

mkdir -p $GITLAB_HOME/registry

2. 在docker-compose.yml中添加volume映射：

volumes:
  - '$GITLAB_HOME/registry:/var/opt/gitlab/gitlab-rails/shared/registry'

5.2 使用外部Nginx反向代理

如需通过80/443端口访问Registry，可添加Nginx配置：

server {
    listen 80;
    server_name registry.gitlab.example.com;

    location / {
        proxy_pass http://gitlab.example.com:5050;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

然后在gitlab.rb中更新配置：

registry_external_url 'http://registry.gitlab.example.com'
gitlab_rails['registry_host'] = "registry.gitlab.example.com"

5.3 清理策略配置

为防止镜像仓库无限增长，可设置自动清理规则。在gitlab.rb中添加：

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

gitlab_rails['registry_expiration_policies_enabled'] = true
gitlab_rails['registry_expiration_policies_cron'] = "0 2 * * *"
gitlab_rails['registry_expiration_policies_older_than'] = "90d"

6. 常见问题排查

问题1：推送镜像时报错"http: server gave HTTP response to HTTPS client"

解决方案：

• 确认Docker客户端已正确配置insecure-registries
• 确保使用的是http://前缀而非https://

问题2：Registry服务未启动

检查步骤：

# 进入容器
docker exec -it gitlab-ee bash

# 检查Registry服务状态
gitlab-ctl status registry

问题3：磁盘空间不足

清理建议：

# 查看Registry存储使用情况
du -sh /var/opt/gitlab/gitlab-rails/shared/registry

# 手动删除不再需要的镜像
gitlab-rake gitlab:cleanup:orphan_upload_files

在实际项目中，这套配置已经稳定运行了6个月以上，处理了超过500个镜像版本。相比传统HTTPS配置方案，HTTP协议确实在开发环境中大幅简化了部署流程。