cicd Troubleshooting

CI 中 Docker 构建失败排查方法

CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。

先用 --progress=plain --no-cache 看完整构建日志，再查层缓存是否命中和权限，CI 里 Docker 失败多在 Dockerfile 指令、缓存失效或 socket 权限。

适用环境Jenkins / GitLab CI / GitHub Actions

风险等级低

最后验证2026-07-04

建议权限普通用户 + sudo

2026-07-04 更新·约 3 分钟阅读

Scenario

这篇文章解决什么问题

适用于“CI 中 Docker 构建失败排查方法”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先用 --progress=plain --no-cache 看完整构建日志，再查层缓存是否命中和权限，CI 里 Docker 失败多在 Dockerfile 指令、缓存失效或 socket 权限。

Symptoms

典型现象

CI 流水线 docker build 报错、层缓存失效或 permission denied 时，用 --progress=plain --no-cache 输出完整构建日志，检查 docker.sock 权限、buildx builder 和 Dockerfile 指令顺序，常见根因是 socket 无权限、上下文频繁变化或缓存未持久化。
相关日志、命令或页面中反复出现 ci、docker-build、buildx 等关键词。
同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

先确认是流水线配置问题，还是 Runner / 执行环境问题，避免在 YAML 和基础设施之间来回横跳。
保留失败 job 的完整日志、触发上下文、分支和 commit，而不是只看最后几行报错。
区分本地能复现但 CI 不行的问题，重点对比环境、密钥、缓存和网络差异。

Root Causes

常见根因分层

Runner 离线或标签不匹配

job 一直 pending 通常是可用 Runner 不足、标签没匹配上或 Runner 被并发占满，而不是流水线语法错误。

查看 Runner 在线状态和标签
确认 job 声明的 runs-on/tags
看并发队列和 executor 资源

缓存失效或 key 计算错误

缓存 key 用了时间戳或分支变量、路径没覆盖真实依赖目录，会让命中率为零甚至复用错误产物。

用 lockfile hash 做 key
核对 cache path 与真实路径
看 restore 日志是否命中

构建环境差异

Docker socket 没挂载、网络走不了内网、secrets 没注入、镜像架构不一致，都会让 CI 表现和本地不同。

确认 secrets 作用域和变量
检查 docker socket 与网络
对比本地与 CI 镜像架构

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。CI 中 Docker 构建失败排查方法这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

截图或保存完整错误文本
记录请求域名/IP/端口/namespace/服务名
标出最近发布、配置、证书、镜像或依赖变更

1. 固定现场，避免追着变化状态跑

docker build --progress=plain --no-cache -t img .
docker buildx build --progress=plain .

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

从报错服务所在机器执行测试
必要时加 Host、SNI、namespace 或代理参数
把成功路径和失败路径的输出并排比较

2. 在故障发生的同一位置复现

docker buildx build --progress=plain .
docker buildx ls
docker buildx du

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

用 --progress=plain 输出完整构建过程，定位具体失败的层和指令。
加 --no-cache 重新构建，排除层缓存命中了错误或损坏的层。
检查 CI 是否挂载 docker.sock 或使用 buildx，权限拒绝多来自 socket 访问或镜像仓库认证。

3. 读取服务端证据，而不是只看客户端提示

docker buildx ls
docker buildx du
docker system df

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

检查 CI 是否挂载 docker.sock 或使用 buildx，权限拒绝多来自 socket 访问或镜像仓库认证。
用 buildx ls 和 buildx du 检查 builder 实例和缓存占用，缓存失效或膨胀时清理重建。
确认 Dockerfile 指令顺序、基础镜像 tag 和上下文大小，把易变指令放后面提升缓存命中。

4. 做最小修复并立即回归验证

docker buildx du
docker system df

Commands