Docker Compose无法拉取推送到GitHub的更新镜像问题排查

一、先确认CI环节是否成功推送最新镜像 #

• 登录GitHub容器注册表（GHCR），进入ghcr.io/user/repo/backend页面，查看镜像的最后推送时间，是否和你触发流水线的时间匹配。如果时间对不上，说明CI环节的镜像推送失败，先检查流水线日志里的构建推送步骤是否有报错。
• 在CI流水线的镜像推送步骤后，添加打印镜像唯一标识（digest）的命令，方便后续对比：

- name: Print image digest
  run: docker inspect ghcr.io/user/repo/backend:latest --format='{{.Id}}'

记录这个digest值，后续在CD环境执行同样命令，看两者是否一致——不一致说明CD环境没拉取到最新镜像。

二、修复CD环节的镜像拉取逻辑 #

默认情况下，docker compose up -d只会复用本地已有的镜像，不会主动拉取GHCR上的新版本，必须强制拉取：

• 修改CD环节的命令为：

docker compose pull backend && docker compose up -d backend

或者一步到位，强制拉取并启动：

docker compose up -d --pull always backend

如果改了自定义标签还是无效，说明CD环境本地已缓存该标签的旧镜像，先删除再拉取：

docker rmi ghcr.io/user/repo/backend:你的自定义标签
docker compose pull backend
docker compose up -d backend

三、排查缓存与旧容器残留问题 #

• 检查CD环境的容器状态：执行docker ps -a | grep backend，查看容器的创建时间。如果创建时间远早于流水线触发时间，说明旧容器没被替换，需要强制重建：

docker compose up -d --force-recreate backend

这个命令会直接删除旧容器，用新镜像创建全新的容器。

• 检查本地镜像缓存：执行docker images ghcr.io/user/repo/backend，看本地镜像的创建时间是否和GHCR上的一致。如果本地时间更早，说明没拉取到新镜像，手动拉取验证：

docker pull ghcr.io/user/repo/backend:latest

四、验证变更是否生效的实用方法 #

• 在后端代码中添加版本标识（比如在接口返回version: "v1.0.1"，或者启动日志打印当前版本），部署后调用接口或查看容器日志确认版本更新：

docker logs backend

• 进入容器内部检查代码文件：

docker exec -it backend cat /app/package.json # 假设Node.js项目，查看版本号
# 或者检查文件修改时间
docker exec -it backend ls -l /app/main.py

内容的提问来源于stack exchange，提问作者Felipe