Debian下GitLab容器化部署方案

Debian下GitLab容器化部署方案

一 环境准备与规划

• 操作系统建议使用Debian 12/11，已安装并运行Docker Engine（非 Docker Desktop for Windows）。GitLab 容器需要可对外访问的有效主机名（不要使用 localhost），并准备一个可用的MTA（如 Postfix/Sendmail）用于邮件投递。生产环境建议将镜像版本固定，避免意外升级。若需使用 SSH 克隆，请规划好 SSH 端口策略（详见下文）。

二 使用 Docker Compose 快速部署

• 1）准备目录与环境变量
  • 建议将持久化目录统一到 /srv/gitlab（也可自定义），并设置环境变量：
    • sudo mkdir -p /srv/gitlab
    • echo ‘export GITLAB_HOME=/srv/gitlab’ | sudo tee -a /etc/profile.d/gitlab.sh
    • source /etc/profile.d/gitlab.sh
• 2）创建 docker-compose.yml（示例）
  • 将域名与端口按实际环境替换（示例域名：gitlab.example.com；宿主机 HTTP/HTTPS 使用 80/443；容器内 SSH 仍为 22，宿主机为避免冲突映射到 2222）：

    version: "3.8"
    services:
      gitlab:
        image: gitlab/gitlab-ce:17.4.6-ce.0   # 建议固定版本
        container_name: gitlab
        restart: always
        hostname: 'gitlab.example.com'
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            external_url 'https://gitlab.example.com'
            gitlab_rails['gitlab_shell_ssh_port'] = 2222
            nginx['redirect_http_to_https'] = true
        ports:
          - "80:80"
          - "443:443"
          - "2222:22"
        volumes:
          - "$GITLAB_HOME/config:/etc/gitlab"
          - "$GITLAB_HOME/logs:/var/log/gitlab"
          - "$GITLAB_HOME/data:/var/opt/gitlab"
        shm_size: "256m"
    

• 3）启动与初始化
  • docker-compose up -d
  • 首次启动需等待组件初始化，随后访问 https://gitlab.example.com 完成管理员设置。
• 4）防火墙放行（如使用 ufw）
  • sudo ufw allow 80/tcp,443/tcp,2222/tcp && sudo ufw reload
• 说明
  • 若宿主机 SSH 已占用 22，推荐将宿主机 SSH 改为其他端口（如 2424），然后保持容器内 22 不变，这样克隆地址无需带端口；否则需将容器内 GitLab Shell 的 SSH 端口改为与宿主机一致，并在克隆时显式指定端口。

三 关键配置与运维要点

• HTTPS 与证书
  • 方案A（推荐）：在 GitLab 容器内使用 Let’s Encrypt 自动申请与续期证书（需将域名解析指向本机，并开放 80/443）。示例思路：
    • 在宿主机准备 Webroot 目录：sudo mkdir -p /var/www/certbot
    • 临时启动 Nginx/HTTP 入口以完成 ACME 验证，获取证书后写入 /srv/gitlab/config/ssl 并在 gitlab.rb 中配置 external_url 与重定向，执行 gitlab-ctl reconfigure 生效。
  • 方案B：使用外部反向代理（如独立 Nginx/Ingress）终止 TLS，容器内仅暴露 HTTP。
• SSH 克隆地址
  • 若宿主机 SSH 端口已改为 2424：保持容器内 22，克隆地址为 ssh://git@gitlab.example.com/user/project.git（无需端口）。
  • 若宿主机 SSH 仍为 22：将容器内端口改为 2222，克隆地址为 ssh://git@gitlab.example.com:2222/user/project.git。
• 邮件与通知
  • GitLab 镜像不含 MTA。可在宿主机安装 Postfix，或单独运行 MTA 容器并与 GitLab 容器通过 Docker 网络通信。
• 资源与性能
  • 建议为容器设置合适的 shm_size（如上 256MB），并依据实例规模调整工作进程、数据库与缓存参数（在 gitlab.rb 中配置）。

四 备份与恢复

• 备份
  • 在宿主机执行（确保挂载了数据卷）：
    • docker-compose exec -T gitlab gitlab-backup create
  • 备份归档默认位于 $GITLAB_HOME/data/backups。建议定期将备份文件拷贝到异地存储，并保留多份历史。
• 恢复
  • 将备份归档放置到 $GITLAB_HOME/data/backups（文件名形如 _gitlab_backup.tar），然后执行：
    • docker-compose exec -T gitlab gitlab-backup restore BACKUP=
  • 完成后执行 gitlab-ctl reconfigure 并重启服务。恢复前确保实例版本与备份版本一致或兼容。

五 升级与常见问题

• 升级步骤
  • 1）在 Compose 文件中将镜像版本升级到目标版本（如从 17.4.6-ce.0 升到新版本）；2）执行 docker-compose pull；3）docker-compose up -d 让 GitLab 自动执行迁移；4）观察日志与页面提示，必要时执行 gitlab-ctl reconfigure。只要卷挂载路径不变，配置与数据不会丢失。
• 常见问题
  • 502/页面无法访问：常见于端口冲突或资源不足。检查宿主机 80/443/2222 是否被占用，必要时调整端口映射；查看容器日志（docker-compose logs -f gitlab）。
  • 首次登录与初始密码：首次访问 Web 界面设置管理员密码；若需临时查看，可在容器内查看 /etc/gitlab/initial_root_password（通常在首次启动后 24 小时内有效）。