容器化排错手册

汇总容器化落地中最常见的故障与排查路径，按场景分类。

镜像构建类

构建缓存失效 / 构建慢

• 检查 Dockerfile 指令顺序：变动少的放前面（如先 COPY package*.json + RUN install，再 COPY . .）。
• CI 中用 --cache-from 复用远端缓存层。
• 排除无关文件：完善 .dockerignore。

基础镜像拉取超时

• 配置镜像加速器（见 安装 的 daemon.json）。
• 检查网络/代理；离线环境用 docker save/load 迁移。

多阶段 COPY 找不到文件

• 确认 --from=<阶段名> 与 FROM ... AS <阶段名> 一致。
• 确认源阶段文件路径正确，且未被 .dockerignore 排除。

运行类

容器启动立即退出（Exited）

docker logs <容器>                 # 看报错
docker run --rm -it <镜像> sh      # 交互式排查入口

• 常见原因：CMD 指向不存在的二进制、前台进程退出的脚本、缺失环境变量。

容器端口访问不通

docker ps                          # 确认端口映射存在
docker port <容器>                 # 查看实际映射
curl 127.0.0.1:<宿主机端口>        # 本机测

• 检查是否忘 -p，或应用监听 127.0.0.1（应监听 0.0.0.0）。
• host 网络下端口与宿主机冲突。

容器间无法互通

• 确认在同一自定义 bridge 网络（默认 bridge 不能按名解析）。
• docker exec -it <容器> nslookup <另一容器名> 验证 DNS。

数据丢失

• 有状态服务未挂 Volume，容器删除后数据消失。
• docker rm -v 会连带删匿名卷；命名卷不受影响。

磁盘被日志/镜像打满

docker system df
df -h /var/lib/docker

• 配置日志轮转（json-file max-size/max-file，见 存储）。
• 清理：docker system prune -a --volumes。

时区/中文乱码

# 挂载宿主机时区
docker run -v /etc/localtime:/etc/localtime:ro myapp
# 或设置环境变量
docker run -e TZ=Asia/Shanghai myapp

• 中文乱码：基础镜像缺 locale，Dockerfile 安装 locales 并设置 LANG。

非 root 运行报错（Permission denied）

• 进程尝试写受限目录（如 /var/run）。Dockerfile 中 chown 对应目录给运行用户。
• 挂载的宿主机目录权限不足：调整宿主机目录权限或加 :z/:Z（SELinux）。

监控采集类（cAdvisor / Prometheus）

cAdvisor 报 "failed to identify the read-write layer ID"

overlay2 下 cAdvisor 需读取宿主机 /var/lib/docker/image/overlay2/layerdb/mounts/{容器ID}/mount-id。容器指标三要件缺一不可：

1. docker.sock（列出容器）
2. /sys:/sys:ro（读取 cgroup）
3. /var/lib/docker:/var/lib/docker:ro（读取 layerdb）

只挂 /sys:/host/sys:ro（给 node_exporter）而缺 /sys:/sys:ro 会导致 cAdvisor 读不到宿主机 cgroup 视图。详见 Docker Compose 与 Docker Swarm 实战。

Grafana 容器面板变量为空

• 容器指标被 relabel 的 keep 规则误删（如 container_label_..._obs_namespace="cpsp" 把 up/scrape_* 一并丢弃）。
• 最终方案：放弃 namespace 过滤，删除该 keep 规则，全量采集容器指标，下游再按 namespace="cpsp" 过滤。

Kubernetes 类

Pod 一直处于 Pending

kubectl describe pod <pod>     # 看 Events：资源不足/污点/PVC 未绑定
kubectl get events --sort-by=.lastTimestamp

镜像拉取失败（ErrImagePull）

• 检查 imagePullSecret 是否配置。
• 私有仓库需登录并创建 docker-registry 类型 secret。
• 确认 tag 存在、仓库地址正确。

滚动更新卡住

kubectl rollout status deployment/<name>
kubectl describe deployment/<name>   # 看 maxUnavailable/maxSurge

• 探针配置不当（readiness 永远失败）会导致新版本无法就绪。

排错通用流程

1. docker logs / kubectl logs 看应用日志。
2. describe / inspect 看编排层事件与配置。
3. exec 进容器验证网络/文件/进程。
4. 本地 docker run --rm -it 复现最小场景。
5. 查资源（CPU/内存/磁盘）是否触及限制。