Claude Code Router Docker 的 /health 返回 502 怎么排查【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router在 Claude Code RouterCCR的 Docker 部署里请求http://127.0.0.1:3458/health返回502并不一定代表容器出了问题。这个接口检查的是容器内部的模型网关而不是 Nginx 或管理 UINginx 把/health转发到容器内127.0.0.1:3456的网关进程网关没起来时 Nginx 就返回502。新数据卷上还没配置供应商和模型时502属于预期行为不是故障。本文按官方文档给出判断和恢复步骤目标是让/health回到200并带上运行状态。先弄清/health到底检查什么Docker 镜像只对外发布 Nginx 的容器端口8080宿主机默认映射3458其余端口都是容器内部实现不要单独映射到宿主机宿主机 3458 - 容器 Nginx 8080 |- 静态管理 UI |- 管理 RPC127.0.0.1:3459 |- 模型网关127.0.0.1:3456 - Core Runtime127.0.0.1:3457Nginx 的路由分工如下路径用途/、/pages/home/index.html管理 UI。根路径会跳转到带管理 Token 的页面。/api/ccr/rpc需要管理 Token 的管理 RPC。/health模型网关健康状态容器或 UI 状态不在此接口反映。/v1/*、/v1beta/*、/messages、/chat/completions、/responses、/interactions、/mcp/*模型和 MCP 网关接口。由此可以得出排查的第一条判断依据管理界面能打开、docker compose ps显示容器健康都不代表模型网关已运行。docker compose ps显示的是容器健康/health显示的是模型网关健康两者不能互相替代。排查步骤第一步确认容器本身正常docker compose ps docker compose logs -f ccr容器起不来时优先看日志这和502是两个层面的问题。容器正常时继续第二步。第二步判断是否属于尚未配置的预期 502文档明确指出新数据卷尚未配置供应商 / 模型时/health会返回502。首次使用 Docker 启动后管理 UI 立即可用但模型网关要在添加供应商和模型之后才能正常启动。如果你的数据卷是全新的、还没配过供应商那么502就是当前正确状态直接进入第三步完成配置即可。第三步在 UI 里完成配置并启动网关打开http://127.0.0.1:3458根路径会 302 跳转到带 Token 的管理页这是正常行为按以下顺序操作添加供应商和至少一个模型在API 密钥页面创建 CCR 客户端 Key在服务页面点击启动网关请求/health确认返回200和运行状态把客户端 Base URL 指向http://127.0.0.1:3458并使用刚创建的 CCR 客户端 Key。完成后再验证一次网关curl http://127.0.0.1:3458/health成功条件是返回200和运行状态。之后可以用 CCR 客户端 Key 向兼容路径发一个最小模型请求并在日志页面确认请求模型、最终供应商 / 模型、状态码和耗时。第四步配置完成后仍返回 502 怎么办如果供应商、模型都配好了网关也点过启动/health还是502按文档逐项检查CCR_NO_GATEWAY环境变量设为1、true或yes时启动阶段只运行管理 UI、不启动网关此时/health自然拿不到网关。确认你的 Compose 或docker run没有设置该变量默认0。服务状态回到服务页面确认状态为运行中不在运行时点击启动或重启。容器日志docker compose logs --tail200 ccr文档对容器健康但模型请求失败给出的检查面是服务状态、供应商连通性、CCR 客户端 Key、路由和请求日志再配合上面的日志命令查看启动或运行错误。注意502只说明 Nginx 到127.0.0.1:3456这段没有拿到网关响应具体原因要看网关自身是否启动。两个容易混淆的点改了端口或地址后/health请求的是你实际使用的公开地址默认http://127.0.0.1:3458。如果改过宿主机端口CCR_PUBLIC_BASE_URL也要同步设置并且右侧容器端口仍应保持8080不要改成内部网关的3456。502不代表 Nginx / UI 坏了管理页能打开时只说明静态 UI 和 RPC 链路正常网关健康单独由/health反映。桌面版 / CLI 同理没有可用模型时也可能只保留管理服务而网关不可用。相关文档Docker 部署端口拓扑、环境变量完整参考、备份与升级以及/health502 等常见问题原文。安装并启动 CCR三种发行方式的默认管理地址与网关地址对照、安装验证四步。服务配置网关 Host / Port 字段说明与启动和验证流程。Docker 说明docker/README.md镜像架构与中文排查清单仓库还提供npm run test:docker烟雾测试会在临时容器中配置网关并检查/health。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
