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 可以避免密码直接出现在命令历史和进程参数中。

bash
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"

预期输出

text
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 入口。

bash
: "${REGISTRY_HOST:?REGISTRY_HOST is required}"

curl -sS -o /dev/null -w '%{http_code}\n' "https://${REGISTRY_HOST}/v2/"

预期输出

text
200

如果仓库强制认证,返回 401 也说明网络和 TLS 已经连通;如果出现 DNS 解析失败、连接超时或证书校验错误,则应先修复网络、代理或 CA 配置,再重复登录和推送。

推送后做远端验收

仅看到 docker push 退出码为 0 还不够。流水线至少应记录目标标签、远端 digest 和本次提交哈希,并在部署前确认目标镜像仍能被仓库解析。若仓库支持 OCI Distribution API 或提供专用 CLI,也可以在这一阶段读取 manifest 验证。

最关键的验收条件是:推送成功、远端 digest 已记录、该 digest 与后续部署使用的制品一致。这样即使 prod 或 latest 之后移动,发布记录仍能准确指向当时真正推送并部署的镜像。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

推送镜像到仓库

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通