容器与云原生 / 系统课时

推送镜像

推送镜像

本课完成从本地镜像到远程仓库的完整推送流程:检查源镜像、登录仓库、补全镜像地址、推送指定版本,并根据各镜像层的状态判断上传是否成功。

学习目标

  • 理解远程镜像名称的组成规则
  • 使用安全方式登录并推送指定标签
  • 根据层状态和摘要验证推送结果

镜像地址必须包含仓库命名空间

远程镜像通常使用 仓库地址/命名空间/镜像名:标签。例如 docker.io/alice/anystack-demo:1.0 中,docker.io 是仓库地址,alice 是账户或组织命名空间,anystack-demo 是仓库名,1.0 是本次发布版本。

本地已有的 anystack-demo:1.0 不会因为执行推送而自动改变名称。必须先用 docker image tag 增加一个指向同一镜像 ID 的完整远程标签,再推送这个新标签。打标签不会复制镜像层,因此几乎不会额外占用磁盘空间。

登录、标记并推送指定版本

下面以 Docker Hub 为例。执行前应确保本地存在 anystack-demo:1.0,并把 <DOCKER_ID> 替换为自己的账户名。令牌通过隐藏输入读取,避免直接写入脚本或命令历史。

bash
set -e

REGISTRY_HOST="docker.io"
NAMESPACE="<DOCKER_ID>"
SOURCE_IMAGE="anystack-demo:1.0"
TARGET_IMAGE="${REGISTRY_HOST}/${NAMESPACE}/anystack-demo:1.0"

read -rsp "Registry access token: " REGISTRY_TOKEN
printf '\n'
printf '%s' "${REGISTRY_TOKEN}" | docker login "${REGISTRY_HOST}" \
  --username "${NAMESPACE}" \
  --password-stdin
unset REGISTRY_TOKEN

docker image inspect "${SOURCE_IMAGE}" --format '{{index .RepoTags 0}}'
docker image tag "${SOURCE_IMAGE}" "${TARGET_IMAGE}"
docker image push "${TARGET_IMAGE}"
docker image pull "${TARGET_IMAGE}"

预期输出

text
Login Succeeded
anystack-demo:1.0
<IMAGE_LAYER>: Pushed
<IMAGE_LAYER>: Layer already exists
1.0: digest: sha256:<DIGEST> size: <SIZE>
Status: Image is up to date for docker.io/<DOCKER_ID>/anystack-demo:1.0

层 ID、摘要和大小会因镜像内容而不同。首次推送时多数层显示 Pushed;仓库中已存在相同内容时会显示 Layer already exists。最后出现 digest: sha256:...,表示仓库已经接收镜像清单并生成内容摘要。

判断各镜像层是否上传成功

Docker 镜像由多个只读层组成,推送时会逐层比较内容摘要。相同层不会重复上传,所以第二次推送通常明显更快。只要命令最终返回摘要且没有错误退出,显示为 Pushed 或 Layer already exists 的层都可视为成功。

docker image pull 会再次访问远程仓库。即使本地已有相同镜像,它仍会校验远程清单,因此出现 Image is up to date 也能证明指定标签可以被读取。团队发布时还应记录最终摘要,因为标签可能被覆盖,而摘要唯一对应一份镜像内容。

标签与版本管理

建议每次发布推送明确版本,例如 1.0.0、1.0.1 或提交号,而不是只推送 latest。latest 只是普通标签,不代表时间最新,也不会自动指向最大版本。

同一镜像可以同时拥有版本标签和稳定标签。发布验证通过后,可再将同一镜像标记为 stable 并单独推送,但不要用新构建直接覆盖已经交付的不可变版本标签。

常见失败与处理

现象 常见原因 处理方式
unauthorized 未登录、令牌失效或用户名错误 重新登录并确认令牌权限
denied 无目标命名空间的写权限 检查账户、组织成员和仓库权限
name unknown 仓库名错误或仓库要求预先创建 核对完整镜像地址并创建目标仓库
TLS 或超时错误 代理、证书或网络链路异常 先验证仓库域名、证书和网络连通性

排查时先确认目标镜像地址,再检查登录身份,最后处理网络与证书问题。不要反复重建镜像来掩盖仓库权限错误。

本课总结

  • 推送前必须为本地镜像增加完整的远程仓库标签
  • Pushed 与 Layer already exists 都表示对应层已可在仓库复用
  • 最终摘要和再次拉取可以共同验证指定版本已成功发布

下一课预告

下一课将运行一个带持久化存储的私有 Registry,并通过实际推送、删除本地标签和重新拉取完成闭环验证。

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

目录与阅读设置

阅读设置

17

记录一个想法

推送镜像

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

登录哪都通