容器与云原生 / 系统课时
推送镜像
推送镜像
本课完成从本地镜像到远程仓库的完整推送流程:检查源镜像、登录仓库、补全镜像地址、推送指定版本,并根据各镜像层的状态判断上传是否成功。
学习目标
- 理解远程镜像名称的组成规则
- 使用安全方式登录并推送指定标签
- 根据层状态和摘要验证推送结果
镜像地址必须包含仓库命名空间
远程镜像通常使用 仓库地址/命名空间/镜像名:标签。例如 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> 替换为自己的账户名。令牌通过隐藏输入读取,避免直接写入脚本或命令历史。
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}"预期输出
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,并通过实际推送、删除本地标签和重新拉取完成闭环验证。