15.9.4 镜像推送、拉取与访问控制

镜像推送、拉取与访问控制是镜像分发的核心环节，需要结合命名规范、权限模型与审计机制，确保来源可信与可追溯。

一、原理草图（推送/拉取/鉴权）

二、镜像推送流程与示例（含命令解释）
1. 规范打标签：
- 统一格式：registry.example.com/project/app:1.2.3
- 生产禁止 latest，使用语义化版本或构建号。

推送完整流程：

# 1) 构建镜像
docker build -t app:1.2.3 .

# 2) 打标签（指向私有仓库命名空间）
docker tag app:1.2.3 registry.example.com/project/app:1.2.3

# 3) 登录仓库（触发鉴权）
docker login registry.example.com
# 预期：Login Succeeded

# 4) 推送
docker push registry.example.com/project/app:1.2.3
# 预期：各 layer 上传完成，显示 digest

推送校验：

# 查看远端镜像列表（以 Harbor 为例）
curl -u user:pass "https://registry.example.com/api/v2.0/projects/project/repositories"
# 预期：返回包含 app 的仓库条目

三、镜像拉取流程与示例（含命令解释）
1. 拉取固定版本（推荐）：

docker login registry.example.com
docker pull registry.example.com/project/app:1.2.3
# 预期：Pull complete

使用 Digest 保证不可变：

docker pull registry.example.com/project/app@sha256:xxxxxxxx
# 预期：只拉取指定内容，不随 tag 变更

四、访问控制模型与示例配置
1. 角色与权限策略（建议）：
- 管理员：仓库管理/用户管理
- 开发：dev/staging 推送
- 运维：生产只读拉取
- CI/CD：生产推送（可审计）

仓库侧访问控制示例（Nginx 反向代理 + 基础认证）
文件：/etc/nginx/conf.d/registry.conf

server {
    listen 443 ssl;
    server_name registry.example.com;

    auth_basic "Registry";
    auth_basic_user_file /etc/nginx/registry.htpasswd;

    location /v2/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

生成认证文件：

# 安装工具（Debian/Ubuntu）
apt-get install -y apache2-utils

# 生成账号（示例：ciuser）
htpasswd -c /etc/nginx/registry.htpasswd ciuser
# 预期：输入密码后生成文件

五、常见错误与排错步骤（含命令）
1. denied: requested access to the resource is denied
- 原因：权限不足或命名空间错误
- 处理：

docker login registry.example.com
docker tag app:1.2.3 registry.example.com/project/app:1.2.3
# 确认 project 是否存在且账户有 push 权限

manifest unknown
- 原因：标签不存在或大小写错误
- 处理：

# 列出仓库镜像标签（Harbor API）
curl -u user:pass "https://registry.example.com/api/v2.0/projects/project/repositories/app/artifacts"

拉取慢
- 处理：检查 DNS/网络、开启仓库加速或镜像层复用

# 验证网络
ping registry.example.com
# 查看镜像层复用情况
docker history registry.example.com/project/app:1.2.3

六、练习
1. 将本地镜像 app:1.0.0 推送到私有仓库 registry.example.com/project/app:1.0.0，验证 Harbor API 可查询到该镜像。
2. 使用 Digest 方式拉取镜像，并对比 docker images 显示的 IMAGE ID 是否一致。
3. 为只读账号配置 auth_basic，测试该账号只能拉取不能推送。

七、最佳实践
- 生产环境仅允许 CI/CD 推送，禁止人工直接推送。
- 使用 Digest 进行生产拉取，确保可追溯与可回滚。
- 定期清理无用标签与镜像，降低仓库存储压力。
- 推送与拉取日志统一纳入审计与告警系统。