docker镜像推送与拉取基于分层存储、sha256内容寻址和会话认证机制，通过比对层摘要仅传输差异部分，并依赖manifest组装镜像，实现高效复用与安全分发。
镜像推送与拉取不是简单的“上传下载”，而是围绕分层存储、内容寻址和身份认证构建的一套协作机制。理解底层逻辑，才能避开 tag 冲突、认证失败、私有仓库无法访问等高频问题。
镜像为什么能高效推送和拉取
Docker 镜像由多个只读层（Layer）组成，每层对应 Dockerfile 中一条指令，且拥有唯一 SHA256 摘要值。Registry 不存储完整镜像，而是按层索引和缓存：
- 推送时，客户端先比对本地层与远程 Registry 已有层的摘要，只上传缺失层
- 拉取时，Docker 引擎自动跳过本地已存在的层，仅下载差异部分
- 同一基础镜像（如 ubuntu:22.04）被多个应用复用，网络和磁盘开销大幅降低
- 镜像清单（Manifest）描述层的组织关系和配置信息，是拉取后能正确组装容器的关键元数据
推送镜像的四步关键流程
执行 docker push 并非一键完成，实际经历四个明确阶段：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
-
认证：调用 Registry 的 token 服务（如
https://auth.docker.io/token），凭用户名密码或 Access Token 换取短期访问令牌 - 检查：向 Registry 查询目标镜像各层是否存在；若某层已存在，跳过上传
-
传输：对缺失层采用分块上传（
POST /v2/.../blobs/uploads/+PATCH+PUT），支持断点续传 -
提交：上传 Manifest 文件，绑定所有层与 tag（如
v1），Registry 更新索引并返回成功响应
拉取镜像的实用要点与避坑提示
docker pull 表面简单，但细节决定成败：
- 不写标签默认拉取 :latest，但该标签无版本语义——生产环境务必指定精确标签，例如
nginx:1.25.5 - 从私有仓库拉取需提前登录：
docker login myreg.example.com；若使用 HTTP 仓库（如本地localhost:5000），须在/etc/docker/daemon.json中配置"insecure-registries" - 拉取失败常见原因包括：网络不通、证书不可信（HTTPS 私有仓库）、权限不足（401/403）、镜像不存在（404）或平台不匹配（如尝试拉取
arm64镜像到amd64主机） - 可通过
--platform linux/amd64显式指定目标架构，避免多架构镜像解析错误
公有与私有仓库的典型操作对比
不同场景下命令组合略有差异，核心逻辑一致：
-
Docker Hub（公有）：
docker tag myapp:v1 username/myapp:v1→docker push username/myapp:v1 -
企业私有 Registry（HTTPS）：
docker tag myapp:v1 reg.example.com/team/myapp:v1→ 登录 →docker push reg.example.com/team/myapp:v1 -
本地测试 Registry（HTTP）：启动
registry:2容器后，标记为localhost:5000/myapp:v1，并确保 Docker daemon 允许 insecure registry
