Ubuntu 上使用 Docker 部署 GitLab 的完整实践
一 环境准备与资源建议
- 操作系统：Ubuntu 20.04/22.04/24.04 LTS
- 容器运行时：Docker CE 与（可选）Docker Compose
- 资源基线：建议至少 4 GB 内存（生产环境建议 8 GB+），磁盘 50 GB+，并预留充足的 IOPS 与备份空间
- 端口规划：HTTP 80、HTTPS 443、SSH 22（如冲突，可将宿主机端口改为 8080/8443/2222 等）
- 目录规划：持久化挂载 /srv/gitlab/{config,logs,data}，便于升级与备份
二 安装 Docker 与 Docker Compose
- 安装 Docker（Ubuntu 推荐方式）
- 更新索引并安装依赖
- 添加 Docker 官方 GPG 与 APT 源
- 安装 Docker CE 并启动服务
- 安装 Docker Compose（示例为 v2.29.2，可按需调整版本）
- 验证
- 运行 docker version、docker-compose version 确认安装成功
示例命令：
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository “deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable”
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker && sudo systemctl enable docker
sudo curl -L “https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-$(uname -s)-$(uname -m)” -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker version
docker-compose version
三 使用 Docker 运行 GitLab
- 准备持久化目录
- mkdir -p /srv/gitlab/{config,logs,data}
- 启动容器（示例映射 80/443/22；如端口冲突，将宿主机端口改为 8080/8443/2222）
- docker run --detach
–hostname gitlab.example.com
–publish 443:443 --publish 80:80 --publish 22:22
–name gitlab
–restart always
–volume /srv/gitlab/config:/etc/gitlab
–volume /srv/gitlab/logs:/var/log/gitlab
–volume /srv/gitlab/data:/var/opt/gitlab
gitlab/gitlab-ce:latest
- 首次访问与初始化
- 浏览器访问 http://服务器IP或域名，设置管理员 root 密码
- 如需查看初始 root 密码（容器首次启动后生成）：
- docker exec -it gitlab grep ‘Password:’ /etc/gitlab/initial_root_password
- 常用运维命令（容器内执行）
- gitlab-ctl reconfigure（使配置生效）
- gitlab-ctl start|stop|restart|status|tail（启停与日志查看）
四 关键配置与 HTTPS 实践
- 修改外部访问地址（容器内编辑 /etc/gitlab/gitlab.rb）
- external_url ‘http://gitlab.example.com’（或 https://…）
- 修改后执行：gitlab-ctl reconfigure
- 自定义 SSH 端口（当宿主机 22 被占用时）
- 启动容器时将宿主机端口改为 2222:22
- 在 gitlab.rb 中设置：
- gitlab_rails[‘gitlab_ssh_host’] = ‘gitlab.example.com’
- gitlab_rails[‘gitlab_shell_ssh_port’] = 2222
- 重新配置并重启：gitlab-ctl reconfigure && gitlab-ctl restart
- 客户端克隆示例：git clone ssh://git@gitlab.example.com:2222/group/project.git
- 启用 HTTPS（两种方式）
- 手动证书
- 将证书与私钥挂载至容器内（如 /etc/gitlab/ssl/）
- gitlab.rb 中配置：
- nginx[‘ssl_certificate’] = “/etc/gitlab/ssl/gitlab.example.com.crt”
- nginx[‘ssl_certificate_key’] = “/etc/gitlab/ssl/gitlab.example.com.key”
- external_url ‘https://gitlab.example.com’
- 执行 reconfigure 生效
- Let’s Encrypt 自动证书
- 开启：letsencrypt[‘enable’] = true
- 配置联系邮箱：letsencrypt[‘contact_emails’] = [‘admin@example.com’]
- 设置域名与证书后执行 reconfigure 生效
五 备份恢复与常见问题
- 备份与恢复
- 备份（宿主机执行，容器内工具会读取 /etc/gitlab/gitlab.rb 中的配置）
- docker exec -it gitlab gitlab-backup create
- 备份产物默认位于 /srv/gitlab/data/backups/（按日期命名）
- 恢复（先停写，再恢复，最后重启）
- docker stop gitlab
- docker cp /path/备份.tar gitlab:/var/opt/gitlab/backups/
- docker exec -it gitlab gitlab-backup restore BACKUP=TIMESTAMP
- docker start gitlab
- 常见问题速查
- 502/504 错误：多为初始化未完成或资源不足，确认内存 ≥4 GB、稍候片刻再刷新；检查日志：docker-compose logs -f 或 gitlab-ctl tail
- SSH 端口冲突：将宿主机端口改为 2222:22，并在 gitlab.rb 同步设置 gitlab_shell_ssh_port
- 首次登录密码：查看 /etc/gitlab/initial_root_password 或使用首次访问页面设置
- 升级与迁移：保持 /srv/gitlab 三目录不动，仅替换镜像标签后执行 reconfigure 完成升级
