对于许多团队来说，使用 Docker 部署的 GitLab 是代码托管和 DevOps 的核心。保持 GitLab 的版本更新至关重要，这不仅能获取最新的功能，还能及时修复安全漏洞。然而，升级过程，尤其是当服务器网络环境不佳时，常常会遇到挑战。
本文将为您提供一份详尽的 GitLab (Docker 版) 升级指南。我们将从标准的在线升级流程开始，然后重点讲解当您遇到 context deadline exceeded 等网络问题时，如何通过手动离线导入镜像的方式完成升级。
场景示例：
- 当前版本:
gitlab/gitlab-ce:17.11.4-ce.0 - 目标版本:
gitlab/gitlab-ce:17.11.7-ce.0 - 核心命令:
sudo docker run -d -p 443:443 -p 80:80 -p 222:22 --name gitlab --restart always -v /home/gitlab/config:/etc/gitlab -v /home/gitlab/logs:/var/log/gitlab -v /home/gitlab/data:/var/opt/gitlab gitlab/gitlab-ce:TAG
Part 1: 标准在线升级流程
在网络通畅的情况下，升级 GitLab 非常直接。核心原理是：停止并删除旧容器，然后使用新版镜像和完全相同的挂载路径启动新容器。 您的所有数据都安全地保存在挂载到主机的卷 (/home/gitlab) 中，因此删除容器本身是无损的。
第 1 步：备份（重中之重！）
在进行任何操作前，永远要先创建一个完整备份。
sudo docker exec -t gitlab gitlab-backup create此命令会在您的数据卷目录 (/home/gitlab/data/backups) 下生成一个 .tar 格式的备份文件。这是您最可靠的“后悔药”。
第 2 步：停止并移除旧容器
sudo docker stop gitlab
sudo docker rm gitlab请放心，只要您的 -v 挂载路径是正确的，此操作不会删除您的任何配置、代码或数据库。
第 3 步：拉取新版镜像
sudo docker pull gitlab/gitlab-ce:17.11.7-ce.0第 4 步：启动新容器
这是最关键的一步。使用您最初的 docker run 命令，只需将末尾的镜像标签更改为新的版本号。
sudo docker run -d \
-p 443:443 -p 80:80 -p 222:22 \
--name gitlab \
--restart always \
-v /home/gitlab/config:/etc/gitlab \
-v /home/gitlab/logs:/var/log/gitlab \
-v /home/gitlab/data:/var/opt/gitlab \
gitlab/gitlab-ce:17.11.7-ce.0第 5 步：监控与验证
新容器启动后，GitLab 会在后台自动执行升级脚本（如数据库迁移）。这个过程可能需要几分钟。您可以通过以下命令实时查看日志：
sudo docker logs -f gitlab当日志输出稳定，并出现服务正常运行的提示时，尝试通过浏览器访问您的 GitLab 实例，确认一切功能正常。
Part 2: 解决网络难题 - 离线升级流程
如果您在执行 docker pull 时遇到以下错误，说明您的服务器无法顺畅连接到 Docker Hub。
Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded
别担心，我们可以“曲线救国”，手动将镜像文件传输到服务器。
方案 A：手动导入镜像（一次性解决）
这个方案分为三步：下载 -> 传输 -> 加载。
1. 在网络好的机器上下载并打包镜像
您需要一台可以正常访问网络的电脑（Windows, macOS, Linux 均可），并安装了 Docker。
首先，启动 Docker Desktop (Windows/macOS 用户)。这是新手最容易忘记的一步，请确保 Docker 引擎正在后台运行。
然后，打开终端 (PowerShell, CMD, Terminal) 执行：
# 1. 拉取你需要的镜像
docker pull gitlab/gitlab-ce:17.11.7-ce.0
# 2. 将镜像保存为 tar 文件
docker save -o gitlab-ce-17.11.7.tar gitlab/gitlab-ce:17.11.7-ce.0命令执行完毕后，当前目录下会生成一个几 GB 大小的 gitlab-ce-17.11.7.tar 文件。
2. 将镜像文件传输到 GitLab 服务器
使用 scp 命令或 WinSCP、MobaXterm 等图形化 SFTP 工具，将 .tar 文件上传到您的服务器，例如上传到 /root/ 目录。
# 在您的本地电脑上执行
# 将 <服务器IP> 替换为您的实际 IP
scp ./gitlab-ce-17.11.7.tar root@<服务器IP>:/root/3. 在 GitLab 服务器上加载镜像
登录到您的 GitLab 服务器，执行 docker load 命令。
sudo docker load -i /root/gitlab-ce-17.11.7.tar加载完成后，可以执行 sudo docker images 进行验证，您会看到 gitlab/gitlab-ce:17.11.7-ce.0 已经存在于本地镜像列表中。
最后，回到 Part 1 的第 4 步，执行 docker run 命令启动新容器即可！
方案 B：配置镜像加速器（一劳永逸）
如果您需要频繁拉取镜像，配置一个国内的镜像加速器是更高效的解决方案。
编辑 Docker 配置文件
sudo nano /etc/docker/daemon.json填入加速器地址并保存
{ "registry-mirrors": [ "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ] }重启 Docker 服务
sudo systemctl daemon-reload sudo systemctl restart docker
配置完成后，再执行 docker pull 命令，速度将会有质的飞跃。
Part 3: 后续步骤
无论您使用哪种方式升级成功，都别忘了做最后的检查和清理工作。
- 全面验证：登录 GitLab，检查项目、仓库、CI/CD 流水线和用户权限是否都正常。
清理旧镜像（可选）：待新版本稳定运行一段时间后，可以删除旧的镜像以释放磁盘空间。
# 列出所有镜像 sudo docker images # 删除旧版本镜像 sudo docker rmi gitlab/gitlab-ce:17.11.4-ce.0
总结
升级 Docker 版的 GitLab 本质上是一个简单而安全的过程，其关键在于理解 Docker 的卷挂载机制。即使面对不理想的网络环境，我们也可以通过离线导入镜像的方式轻松应对。
希望这篇指南能帮助您顺利完成升级，让您的 GitLab 实例永远保持在最佳状态！🚀
版权属于：soarli
本文链接：https://blog.soarli.top/archives/762.html
转载时须注明出处及本声明。
