在使用 Codex 等依赖 Docker 环境运行的工具时，遇到服务无法启动或连接超时是常见痛点。这通常源于镜像拉取失败、端口冲突或权限配置错误。以下是一份针对 Codex Docker 环境的标准化故障排查步骤清单，帮助你快速恢复服务。
检查基础环境与日志
首先，确认宿主机已正确安装 Docker 且守护进程正在运行。通过终端执行 docker ps -a 查看容器状态。若发现容器处于 "Exited" 状态，请使用 docker logs <容器ID> 调取详细日志。重点关注是否有 "Permission denied"（权限拒绝）或 "Connection refused"（连接被拒）的错误提示，这能直接定位是网络问题还是文件权限问题。
清理缓存与重建镜像
很多时候，损坏的层文件或过时的镜像会导致启动异常。尝试清理未使用的资源以释放空间并移除潜在冲突：docker system prune -a。随后，强制重新构建项目镜像，忽略本地缓存以确保获取最新代码：docker build --no-cache -t codex-app .。此步骤能有效解决因依赖包版本不一致引发的兼容性问题。
验证端口映射与网络配置
Codex 通常需要绑定特定端口（如 8080 或 3000）。使用 netstat -tuln | grep <端口号> 检查该端口是否已被其他进程占用。若端口冲突，需修改 docker-compose.yml 中的端口映射规则，例如将宿主机的 8080 映射到容器的 3000 端口。同时，确保防火墙允许该端口的入站流量，并通过 curl localhost:<端口> 测试连通性，直至返回正常响应为止。