CI/CD / 系统课时
推送镜像到仓库
推送镜像到仓库
把镜像推到仓库看似只有一条 docker push,实际失败通常来自认证、命名空间权限或网络链路。本课用一套适合 CI 的登录与推送流程完成发布,并给出按错误类型定位问题的顺序。
学习目标
- 使用
--password-stdin安全登录镜像仓库并推送指定标签。 - 判断仓库地址、命名空间和推送权限是否匹配。
- 根据认证、授权和网络错误快速定位失败层级,并完成推送后验收。
推送前确认完整镜像名
完整镜像引用形如 registry.example.com/platform/demo-app:1.8.0-abc1234def56-prod。其中 registry.example.com 是仓库入口,platform 是命名空间或项目,demo-app 是仓库名,最后一段是镜像标签。任何一段不匹配服务端配置,都可能导致推送失败。
CI 使用的账号至少需要目标仓库的 push 权限。不要为了省事给机器人账号管理员权限;更推荐使用项目级、短时有效的 token,并把用户名和密码放在 CI 的 Secret 管理中,而不是写进仓库脚本或命令参数。
安全登录并推送
下面是片段示例:依赖 CI 已构建并打好目标标签,同时通过环境变量注入 REGISTRY_HOST、REGISTRY_USER 和 REGISTRY_PASSWORD。--password-stdin 可以避免密码直接出现在命令历史和进程参数中。
set -euo pipefail
: "${REGISTRY_HOST:?REGISTRY_HOST is required}"
: "${REGISTRY_USER:?REGISTRY_USER is required}"
: "${REGISTRY_PASSWORD:?REGISTRY_PASSWORD is required}"
REGISTRY="$REGISTRY_HOST"
IMAGE="${REGISTRY}/platform/demo-app:1.8.0-abc1234def56-prod"
# 先确认本地标签存在,避免把“镜像不存在”误判成仓库故障。
docker image inspect "$IMAGE" >/dev/null
printf '%s' "$REGISTRY_PASSWORD" | \
docker login "$REGISTRY" --username "$REGISTRY_USER" --password-stdin
docker push "$IMAGE"预期输出
Login Succeeded
<ID>: Pushed
<ID>: Pushed
1.8.0-abc1234def56-prod: digest: sha256:<ID> size: <VALUE>实际 layer 数量、digest 和 size 会随镜像内容变化。流水线应保存最后得到的 digest,因为 仓库/镜像:标签@sha256:<ID> 才能唯一标识远端制品。
按失败层级排查
如果错误发生在登录阶段,优先检查用户名、token 是否过期,以及凭据是否发给了正确的 registry 主机。出现 unauthorized 往往属于认证问题;登录成功但 push 返回 denied 或 insufficient_scope,更可能是命名空间不存在或账号只有 pull 权限。
网络问题应先确认 registry 的 /v2/ 端点是否可达。下面仍是片段示例,依赖前述 REGISTRY_HOST 指向实际镜像仓库;它不会上传任何镜像,只验证 DNS、TCP、TLS 和 HTTP 入口。
: "${REGISTRY_HOST:?REGISTRY_HOST is required}"
curl -sS -o /dev/null -w '%{http_code}\n' "https://${REGISTRY_HOST}/v2/"预期输出
200如果仓库强制认证,返回 401 也说明网络和 TLS 已经连通;如果出现 DNS 解析失败、连接超时或证书校验错误,则应先修复网络、代理或 CA 配置,再重复登录和推送。
推送后做远端验收
仅看到 docker push 退出码为 0 还不够。流水线至少应记录目标标签、远端 digest 和本次提交哈希,并在部署前确认目标镜像仍能被仓库解析。若仓库支持 OCI Distribution API 或提供专用 CLI,也可以在这一阶段读取 manifest 验证。
最关键的验收条件是:推送成功、远端 digest 已记录、该 digest 与后续部署使用的制品一致。这样即使 prod 或 latest 之后移动,发布记录仍能准确指向当时真正推送并部署的镜像。