docker Troubleshooting
Docker Compose 容器反复重启排查
Docker Compose 容器一直 Restarting 时，用 docker compose ps 看退出码和重启次数，读取失败服务的历史日志、docker compose config 展开环境变量与端口卷，常见根因是启动命令失败、环境变量缺失、端口冲突或 depends_on 未等依赖 ready。
先看退出码和上一轮日志。反复重启不是 Docker 本身的问题，多数是应用启动失败、环境变量缺失、端口冲突或依赖服务不可达。
Scenario
这篇文章解决什么问题
适用于 docker compose up 后容器一直 Restarting、退出码非 0、重启次数持续增加的场景。排查核心是看退出码和上一轮日志，而不是反复 restart。
Symptoms
典型现象
- docker compose ps 显示服务状态为 Restarting，重启次数不断增加。
- docker compose logs 中能看到应用启动到一半就崩溃的输出。
- docker inspect 显示 ExitCode 非 0，常见的有 137（OOM Killed）、1（应用异常）、127（命令不存在）。
- depends_on 等待的数据库或缓存服务还没 ready，应用启动时就连接失败并退出。
Before Debugging
排查前先确认
- 先确认问题发生在镜像拉取、容器启动、容器内服务监听，还是宿主机/外部访问。
- 记录 docker ps、docker logs 和 docker inspect 的同一时间窗口，避免状态已变化后误判。
- 区分 Docker 网络、宿主机防火墙、云安全组和应用自身监听地址。
Root Causes
常见根因分层
容器状态和应用状态不是一回事
容器 Running 只代表主进程存在，不代表应用已经 ready；容器 Restarting 通常是应用启动失败或健康检查不断失败。
- 看退出码和最近 200 行日志
- 检查 healthcheck 是否过于激进
- 确认依赖服务是否 ready
端口、网络和监听地址不匹配
服务只监听 127.0.0.1、端口映射写错、bridge 网络不可达、宿主机防火墙拦截，都会造成“容器里通、外部不通”。
- 容器内 ss -lntp
- 宿主机 curl 127.0.0.1:端口
- 外部机器再测宿主机 IP
Registry、代理和平台架构问题
镜像拉取失败不仅是网络慢，也可能是认证、标签不存在、私有 CA、代理环境变量或 amd64/arm64 架构不匹配。
- 保留完整 pull 错误
- 检查 docker info 中代理配置
- 用 manifest inspect 看架构
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。Docker Compose 容器反复重启排查 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
docker compose ps
docker compose logs --tail=200 <service>2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
docker compose logs --tail=200 <service>
docker inspect <container> --format "{{.State.ExitCode}} {{.State.Error}}"
docker compose config3. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 用 docker compose ps 看服务状态、退出码和重启次数。
- 读取对应 service 最近日志，不要只看 compose up 的最后一屏。
- 用 docker compose config 展开最终环境变量、端口和卷配置。
docker inspect <container> --format "{{.State.ExitCode}} {{.State.Error}}"
docker compose config
docker events --since 10m4. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 用 docker compose config 展开最终环境变量、端口和卷配置。
- 检查 depends_on 只保证启动顺序，不保证依赖服务已经 ready。
- 临时关闭 restart 策略或单独 run 进入容器，复现真实启动命令。
docker compose config
docker events --since 10mCommands
排查命令与使用意图
命令 1
用于补充“Docker Compose 容器反复重启排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker compose ps命令 2
用于读取日志或配置文件内容。重点看时间戳附近的 ERROR、FATAL、refused、timeout 等关键词。
docker compose logs --tail=200 <service>命令 3
用于确认容器运行状态、端口映射和网络配置。inspect 能看到 HostConfig.PortBindings 和 NetworkSettings 等关键字段。
docker inspect <container> --format "{{.State.ExitCode}} {{.State.Error}}"命令 4
用于补充“Docker Compose 容器反复重启排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker compose config命令 5
用于补充“Docker Compose 容器反复重启排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker events --since 10mRisk Notes
容易踩坑的地方
- restart: always/unless-stopped 会不断拉起失败容器，日志滚动很快，排查时先看首次失败日志和退出码。
- depends_on 只保证容器启动顺序，不保证依赖服务 ready，数据库初始化可能需要几十秒。
- 退出码 137 是 OOM Killed，不要简单加内存，先确认是内存泄漏还是 JVM 堆配置不合理。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 Docker Compose 容器反复重启 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 为依赖服务添加 healthcheck，depends_on 使用 condition: service_healthy 等待真正 ready。
- 把应用启动失败时的退出行为设计为快速失败并打印清晰错误，而不是静默崩溃后重启。
- 在 compose 文件中设置合理的 restart_policy 和 max_attempts，避免无限重启风暴。
常见问题
restart: always 会不会掩盖问题？
会。它会不断拉起失败容器，导致日志滚动很快。排查时要看首次失败日志和退出码。
depends_on 为什么没等数据库可用？
depends_on 默认只等容器启动，不等数据库完成初始化。需要 healthcheck 或应用侧重试。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- docker compose 容器反复重启
- docker restart loop
- Restarting container docker compose
- docker logs 查看重启原因
- docker compose depends_on 健康检查
- container exited code 1
- docker compose healthcheck failed
- 容器启动后马上退出
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。