CI中docker push报unauthorized错误，主因是未执行docker login；需用CI变量凭据显式登录，私有仓库URL须带协议端口；应避免latest标签，改用语义化或提交哈希标签，并校验镜像架构与manifest完整性。
push 镜像时 docker push 报错 unauthorized: authentication required
这是 CI 环境里最常卡住的第一步：Docker 客户端根本没登录 Registry。CI 机器默认不带凭据，docker login 必须显式执行，且不能靠本地 ~/.docker/config.json —— 那个文件在 CI runner 上通常不存在或为空。
- 用
echo "$REGISTRY_TOKEN" | docker login -u "$REGISTRY_USER" --password-stdin $REGISTRY_URL，确保 token 来自 CI 变量（如 GitHub Secrets、GitLab CI Variables），别硬编码 - 如果用私有 Registry（比如 Harbor），
$REGISTRY_URL必须带协议和端口，例如https://harbor.example.com:443，少一个字符都可能触发 401 - GitHub Actions 中，
docker/login-action是安全的替代方案，它自动处理凭据注入和 config.json 写入，比手写docker login更稳
CI 构建的镜像 tag 混乱，导致 docker push 覆盖线上版本
本地 docker build -t myapp:latest . 在 CI 里直接复用，等于把每次构建都推到 latest，根本没法回滚、也分不清哪个 commit 对应哪个镜像。
- 强制使用语义化 tag：
myapp:v1.2.3或提交短哈希myapp:$(git rev-parse --short HEAD) - CI 流水线里不要 push 多个 tag 到同一个镜像层（比如同时 push
v1.2.3和latest），除非你明确需要——这会增加 registry 存储压力，且latest的语义在自动化中极易误导人 - Harbor 或 ECR 等 registry 支持 tag 保留策略，但 CI 层面更可靠的做法是：只 push 唯一确定的 tag，让部署阶段按需 pull，而不是靠 tag 名做逻辑分支
流水线里 docker build 太慢，拉取基础镜像频繁超时
CI runner 每次都是干净环境，FROM ubuntu:22.04 这类公共镜像反复拉取，既拖慢构建又容易因网络抖动失败。
- 在 CI 步骤开头加一层缓存预热：
docker pull $BASE_IMAGE || true，配合 runner 的 job-level 缓存（如 GitHub Actions 的actions/cache缓存/var/lib/docker不现实，但可以缓存构建上下文或 layer tar） - 改用带 registry 前缀的 base image，比如
FROM registry.cn-hangzhou.aliyuncs.com/library/ubuntu:22.04，走国内镜像源降低超时概率 - Docker BuildKit 开启后，
--cache-from可复用上一次成功构建的 layer，但注意：CI 中不同 branch/tag 的 cache key 必须隔离，否则 A 分支的 cache 污染 B 分支的构建结果
GitLab CI / GitHub Actions 里 push 成功但镜像实际不可用
常见假阳性：docker push 返回 0，日志显示 “pushed”，但进 registry 查看，镜像 manifest 缺失、layer 损坏，或者 pull 时报 manifest unknown。
- 检查是否漏了
docker build的--platform参数。比如在 Apple Silicon CI runner 上构建 x86_64 镜像，必须显式加--platform linux/amd64，否则 push 的镜像是 arm64 架构，目标服务器 pull 时直接失败 - 多 stage 构建中，最后
FROM scratch或FROM alpine阶段若没正确COPY二进制，镜像能 push 成功但运行时exec format error—— 推送不校验可运行性，得靠后续的docker run --rm简单验证 - 某些 registry（如旧版 Harbor）对 manifest list 支持不全，如果你用
docker buildx build --platform linux/amd64,linux/arm64，得确认 registry 后端已启用 OCI index 支持，否则部分平台镜像会静默丢失
真正麻烦的不是 push 失败，而是 push 成功却无法部署——架构、manifest、tag 生成逻辑这些点，往往要等上线才暴露，CI 阶段就得卡住校验。
