容器启动失败，提示STATUS Exited (255) 如何排查？

Question

容器启动后立即退出，显示 `STATUS Exited (255)`，常见原因是启动命令执行失败或配置错误。如何排查此类问题？

Answer 1

1. 初步现象识别与基础排查

当容器启动后立即退出，且状态显示为 STATUS Exited (255) 时，表明容器的主进程在执行过程中非正常终止。Exit Code 255 通常意味着命令无法执行或权限问题。

• 检查容器日志：docker logs <container_id> 是第一步，可查看启动过程中的输出信息。
• 确认镜像是否存在并可运行：docker images 查看本地镜像列表。
• 尝试手动运行容器并进入交互模式：docker run -it --entrypoint /bin/sh image_name，验证基础环境是否可用。

2. 分析启动命令与入口点配置

容器的启动依赖于正确的 CMD 或 ENTRYPOINT 指令。若命令不存在、路径错误或脚本权限不足，将导致 Exit 255。

配置项	可能问题	排查方法
CMD	命令拼写错误	docker inspect 镜像查看实际命令
ENTRYPOINT	脚本无执行权限	使用 chmod +x 或 Dockerfile 中添加 RUN chmod
Shell vs Exec 模式	环境变量未加载	改用 exec 格式：["/bin/bash", "-c", "start.sh"]

3. 深入镜像构建与文件系统验证

某些情况下，Dockerfile 构建过程中遗漏关键文件或工作目录设置错误，会导致启动失败。

1. 使用 docker inspect image_name 查看镜像元数据，重点关注 Config.Cmd 和 Config.WorkingDir。
2. 进入镜像文件系统调试：docker run --rm -it image_name /bin/sh，手动执行启动脚本。
3. 检查脚本依赖项是否完整，如 Python、Node.js 环境或配置文件是否存在。
4. 确认挂载卷或绑定目录未覆盖关键启动文件。

4. 权限与安全机制影响分析

现代容器运行时（如 rootless 模式、SELinux、AppArmor）可能阻止命令执行，引发 Exit 255。

# 示例：以非 root 用户运行但脚本需 root 权限
FROM alpine
RUN adduser -D myuser
USER myuser
CMD ["/app/start.sh"]  # 若 start.sh 需访问受保护端口则失败

解决方案包括调整用户权限、使用 capabilities 或禁用安全策略进行测试。

5. 容器编排环境下的特殊考量

在 Kubernetes 或 Docker Compose 场景中，配置错误更易被忽略。

1. 检查 command: 和 args: 是否覆盖了镜像原有指令。
2. 验证环境变量注入是否正确，缺失变量可能导致脚本提前退出。
3. 资源限制（如内存不足）也可能间接导致进程崩溃。

6. 自动化诊断流程图设计

为提升排查效率，可构建标准化故障树。

graph TD A[容器启动即退出 Exit 255] --> B{是否有日志输出?} B -->|否| C[检查 entrypoint/cmd 是否有效] B -->|是| D[分析日志关键词: Permission, Not Found, Syntax] D --> E[定位具体失败环节] C --> F[使用 /bin/sh 手动进入调试] F --> G[验证脚本权限与依赖] G --> H[修复后重建镜像]

7. 常见错误案例汇总

以下为高频触发 Exit 255 的场景：

• Dockerfile 中 CMD 写成 CMD ["nonexistent-command"]
• 启动脚本首行缺少 #!/bin/bash
• 多阶段构建中误复制了空目录
• Kubernetes 中 securityContext 阻止了可执行权限
• 使用 Windows 编辑器保存脚本导致 CR/LF 换行符问题

8. 高级调试技巧与工具链集成

对于复杂微服务架构，建议引入结构化日志与健康检查机制。

# Dockerfile 添加调试钩子
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost/health || exit 1

结合 Prometheus + Grafana 实现容器生命周期监控，提前预警异常退出。