容器持续 restarting 表明进程启动后异常退出并被重启策略循环拉起，应通过查看实时日志、检查退出码与重启计数、临时禁用 restart 策略、验证依赖服务就绪性及排查磁盘空间五步定位根因。
如果您执行 docker-compose up 后发现容器持续处于 restarting 状态，则说明容器进程启动后异常退出，Docker 守护进程依据重启策略自动拉起，形成循环。以下是定位该问题的多种有效方法：
一、查看容器实时日志以捕获退出原因
日志是诊断 restarting 问题最直接的信息源，可揭示应用崩溃、配置错误或初始化失败等关键线索。必须在容器反复重启过程中快速获取首次或最近一次完整启动日志。
1、执行 docker-compose logs -f [service_name] 实时跟踪日志输出（例如 docker-compose logs -f mysql）。
2、若服务名未知，先运行 docker-compose ps 查看所有服务状态及名称。
3、若日志滚动过快或已被截断，添加 --tail=100 参数查看最近100行：docker-compose logs --tail=100 [service_name]。
4、重点查找以 ERROR、FATAL、panic、failed to initialize 或 connection refused 开头的行。
二、检查容器退出码与重启计数
Docker 将每次异常退出记录为非零退出码，并在 docker inspect 中持久化重启次数，该信息能确认是否为一次性失败还是持续性故障。
1、运行 docker-compose ps，观察 STATUS 列中显示的 Restarting (X) Y seconds ago，其中 X 即当前累计重启次数。
2、获取容器 ID：执行 docker-compose ps -q [service_name]。
3、执行 docker inspect [container_id]，在输出中定位 RestartCount 和 State.ExitCode 字段。
4、若 ExitCode 为 1，通常表示应用层错误；若为 137，则极可能因 OOMKilled（内存不足） 导致被内核终止。
三、临时禁用 restart 策略以固化错误状态
当容器被设为 restart: always 或 restart: unless-stopped 时，它会立即重启，掩盖原始错误。临时移除该策略可使容器退出后保持 stopped 状态，便于深入调试。
1、编辑 docker-compose.yml 文件，找到对应服务定义块。
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
2、删除或注释掉 restart: 行（例如将 restart: always 改为 # restart: always）。
3、执行 docker-compose down && docker-compose up 重新创建容器。
4、此时容器启动失败后将停留在 Exited (X) 状态，可安全执行 docker logs [container_id] 或 docker exec -it [container_id] /bin/sh（如镜像支持）进一步探查。
四、验证依赖服务就绪性与网络连通性
许多应用（如 Web 服务连接 MySQL、Redis）在启动时即尝试连接依赖项；若依赖未就绪或网络不通，会快速失败并触发重启循环。需确认依赖服务已运行且端口可达。
1、运行 docker-compose ps，确认所有 depends_on 所列服务均处于 Up 状态（注意：depends_on 仅控制启动顺序，不等待服务“就绪”）。
2、进入问题容器内部：docker-compose exec [service_name] /bin/sh（若无 sh，尝试 /bin/bash 或 ash）。
3、在容器内执行 telnet [dependency_service_name] [port] 或 nc -zv [dependency_service_name] [port] 测试连通性（例如 nc -zv mysql 3306）。
4、若测试失败，检查依赖服务日志、端口映射、network 配置及服务自身健康状态；必要时在应用启动命令前加入健康检查脚本（如使用 wait-for-it.sh）。
五、排查磁盘空间与 overlay2 存储层异常
宿主机磁盘空间耗尽（尤其是 /var/lib/docker/overlay2 所在分区）会导致容器无法写入文件系统，从而在初始化阶段失败并反复重启，该现象在长期运行环境中较常见。
1、在宿主机执行 df -h，检查 / 或 /var 分区使用率是否接近 100%。
2、若空间紧张，执行 du -sh /var/lib/docker/overlay2/* | sort -hr | head -n 5 定位最大占用目录。
3、确认是否为残留容器层：运行 docker system df 查看镜像、容器、卷的实际磁盘占用。
4、清理无用资源：docker system prune -a --volumes（注意：该命令将删除所有未被使用的镜像、容器、网络和卷，请提前备份重要数据）。
