cch 架构是什么，Nginx 又是什么，针对 Claude Code AI 的请求链路拆解

1. 从一次 499 报错说起cch 架构与 Nginx 在 Claude Code 链路里到底谁管什么如果你正在用 Claude Code 接入自建网关多半见过这个场景终端里claude命令跑着跑着突然卡住日志里蹦出一行API Error: 499或者local proxy failed再或者reading choices这种看起来跟模型八竿子打不着的报错。我第一次遇到时也懵了——明明 Key 是对的模型 ID 也没写错为什么请求就是落不到后端后来把链路一层层拆开才明白Claude Code 发出的请求中间可能穿过 Nginx、穿过 cchClaude Code Hub这类自研网关最后才到真正的 API 通道。每一层都有自己的职责也都有自己的坑。cch 架构是什么简单说CCH Claude Code Hub是一个自研的 AI API 代理网关系统技术栈是 Next.js 15App Router做前端入口、Hono 做 API 核心逻辑、PostgreSQL 存配置和用量、Redis 做限流和会话状态。它解决的是多个 Claude Code 客户端如何统一鉴权、统一计费、统一转发的问题。而Nginx 是什么它是一个高性能的 Web 服务器和反向代理服务器负责在最外层接收请求、做 SSL 终止、做负载均衡、做超时控制然后把请求转给后面的 cch 或直接转给上游 API。这两者的关系用一句话概括Nginx 是门卫 调度员cch 是翻译官 记账员。Claude Code 客户端只认一个 Base URL这个 URL 指向 NginxNginx 根据配置把请求转给 cchcch 再根据你的 Key 和模型映射把请求转发到 TaoToken 这类统一 API 通道。链路里任何一环配置错了你看到的报错都不一样。这篇就按这个顺序把每一层的角色、配置、验证方法和常见报错拆开讲让你能自己定位问题出在哪一层。适合谁看如果你正在用 Claude Code并且想通过自建网关或统一 API 通道来管理多个项目的 Key、控制用量、或者只是想搞清楚请求到底走了哪条路这篇就是写给你的。不需要你懂 Nginx 源码也不需要你读过 Hono 文档跟着配置和验证步骤走就行。2. 接入前的准备TaoToken 统一 Key 通道与 cch 网关的定位在动手配 Nginx 之前得先把请求最终要落到哪里这件事定下来。Claude Code 本身只是一个客户端它需要一个兼容 Anthropic API 的端点。你可以直接填官方端点也可以填一个统一网关的端点。我这边实测下来用 TaoToken 作为统一 Key/API 通道比较省心因为它把 Key 管理、模型映射、用量查看都放在一个控制台里Claude Code 侧只需要改一个 Base URL 和 Key 就行。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。控制台和 Key 管理在https://taotoken.net/console和https://taotoken.net/api-keys模型对话测试页在https://taotoken.net/model-chat。如果你打算长期用 Claude Code 做编码或 Agent 任务可以看一下 Coding Plan 页面https://taotoken.net/coding-plan它针对长期编码场景做了额度规划。接入文档在https://taotoken.net/docClaude Code 相关的说明在https://taotoken.net/claude-code-anthropic。那 cch 在这里扮演什么角色如果你只是一个人用 Claude Code其实可以跳过 cch直接让 Claude Code 指向 TaoToken 的 API 地址。但如果你团队里有多个开发者、多个项目、多个 Key 需要统一管理cch 就有价值了它可以在 TaoToken 的 Key 之上再做一层项目级或用户级的 Key做用量隔离和审计。Nginx 则是在 cch 前面再加一层负责 HTTPS、域名、超时和负载均衡。所以典型的链路是Claude Code 客户端 - NginxSSL 终止、反向代理、超时控制 - cchHono 核心逻辑鉴权、Key 映射、用量记录 - TaoToken API统一 Key/API 通道 - 上游模型如果你不部署 cch链路就短一层Claude Code 客户端 - Nginx可选也可以直连 - TaoToken API这篇的重点是讲清楚每一层的作用和配置所以下面会给出 Nginx 反代配置片段、Claude Code 侧 Base URL 设置步骤以及一次真实请求的验证方法。你根据自己的实际情况决定要不要加 cch 这一层。有一点要提前说清楚Nginx 和 cch 都不是必须的。Nginx 的价值在于统一入口、HTTPS、超时可控cch 的价值在于多租户和多 Key 管理。如果你只是本地开发Claude Code 直接指向https://taotoken.net/api就能跑。但一旦你要把服务暴露给团队或外部Nginx 这层就值得加上。3. 可复制配置Nginx 反代片段与 Claude Code Base URL 设置这一节是整篇最核心的部分配置直接给全你复制后改域名和端口就能用。先给 Nginx 的反代配置再给 Claude Code 侧的设置最后给 cch 的 Docker Compose 环境变量片段。3.1 Nginx 反向代理配置片段假设你的 cch 服务跑在本机127.0.0.1:3000Next.js Hono 默认端口你想通过https://cch.yourdomain.com对外提供服务。Nginx 配置文件放在/etc/nginx/conf.d/cch.confupstream cch_backend { server 127.0.0.1:3000; keepalive 32; } server { listen 443 ssl http2; server_name cch.yourdomain.com; ssl_certificate /etc/nginx/ssl/cch.yourdomain.com.pem; ssl_certificate_key /etc/nginx/ssl/cch.yourdomain.com.key; # Claude Code 的请求体可能较大放宽限制 client_max_body_size 20m; # 关键AI 请求耗时长读超时要给足 proxy_read_timeout 600s; proxy_send_timeout 600s; proxy_connect_timeout 30s; # 关闭缓冲让流式响应实时透传 proxy_buffering off; proxy_cache off; location / { proxy_pass http://cch_backend; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Connection ; } } server { listen 80; server_name cch.yourdomain.com; return 301 https://$host$request_uri; }几个参数值得单独说。proxy_read_timeout 600s是必须调的默认 60s 对于长上下文或 Agent 任务根本不够请求还没返回就被 Nginx 掐断客户端看到的就是 499。proxy_buffering off是为了让 SSE 流式响应不被 Nginx 缓冲否则 Claude Code 会感觉卡住不动然后一次性吐出来。proxy_http_version 1.1和Connection 配合 keepalive减少频繁建连的开销。如果你不想部署 cch直接让 Nginx 反代到 TaoToken API把proxy_pass改成proxy_pass https://taotoken.net/api; proxy_ssl_server_name on; proxy_set_header Host taotoken.net;但注意这种直连方式下 Nginx 只是做了一层转发鉴权还是靠 Claude Code 侧带的 Key。如果你需要 cch 的 Key 映射和用量记录还是走 cch 那一层。3.2 Claude Code 侧 Base URL 设置Claude Code 通过环境变量读取 API 端点。在~/.claude/settings.json或项目级.claude/settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://cch.yourdomain.com, ANTHROPIC_API_KEY: sk-your-cch-or-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你跳过 cch直接指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里三个字段必须成对出现Base URL、Key、Model ID。少任何一个都会报鉴权或模型不存在的错。Model ID 要跟你实际在 TaoToken 控制台里开通的模型一致写错了会返回model not found。3.3 cch 的 Docker Compose 环境变量片段如果你要部署 cch克隆项目后编辑.envgit clone https://github.com/ding113/claude-code-hub.git cd claude-code-hub cp .env.example .env.env里必须改的是ADMIN_TOKEN其他保持默认ADMIN_TOKENyour-secure-token-here DSNpostgres://postgres:postgrespostgres:5432/claude_code_hub REDIS_URLredis://redis:6379启动docker compose up -d docker compose ps docker compose logs -f app看到 app 容器状态是Up且日志没有报错就说明 cch 起来了。然后在 cch 后台里配置上游为 TaoToken 的 API 地址和 Key这样 cch 就能把 Claude Code 的请求转发到 TaoToken。4. 验证请求链路一次真实请求如何落到 TaoToken配置写完不算完得验证请求真的按预期走了。我常用的方法是分三层验证先验证 Nginx 能通再验证 cch 能通最后验证 Claude Code 端到端能通。4.1 验证 Nginx 层用 curl 直接打 Nginx 的域名看是否返回 cch 的响应curl -i https://cch.yourdomain.com/health如果 cch 有健康检查接口应该返回 200。如果没有可以打一个不存在的路径看返回的是 cch 的 404 页面还是 Nginx 的 502。返回 502 说明 Nginx 连不上后端检查upstream里的地址和端口。4.2 验证 cch 到 TaoToken 的转发在 cch 后台配置好上游后用 curl 模拟一次 Anthropic 格式的请求curl -X POST https://cch.yourdomain.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-your-cch-key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: ping}] }如果返回里有content字段和正常的文本说明 cch 成功把请求转发到了 TaoToken 并拿到了响应。如果返回 401检查 cch 后台里配置的 TaoToken Key 是否正确如果返回model not found检查 Model ID 是否在 TaoToken 控制台里开通。4.3 验证 Claude Code 端到端最后在终端里跑 Claude Codeclaude -p 用一句话说明当前请求走的是哪个端点如果 Claude Code 正常返回内容说明整条链路通了。这时候你可以去 TaoToken 控制台的用量页面看应该能看到这次请求的记录。如果看不到说明请求没落到 TaoToken可能被 cch 拦截了或者 Nginx 转到了别的地方。我实测下来最容易出问题的是 Model ID 和超时设置。Model ID 写错会直接报错超时设置太短会在长任务里随机失败。把这两个盯住链路基本就稳了。5. 常见报错排查401、local proxy failed、reading choices、OAuth链路一长报错就多。下面这几个是我踩过的坑按报错信息对照排查。5.1 401 Unauthorized这个最常见原因有三个Key 没带、Key 错了、Key 没权限。先检查 Claude Code 的settings.json里ANTHROPIC_API_KEY是否填了再检查这个 Key 在 cch 或 TaoToken 后台是否有效。如果用了 cch还要检查 cch 后台里配置的上游 Key 是否正确。注意Claude Code 侧的 Key 和 cch 上游的 Key 是两回事前者用于 cch 鉴权后者用于 cch 向 TaoToken 鉴权。5.2 local proxy failed这个报错通常出现在 Claude Code 启动时说明它连不上你配置的 Base URL。检查ANTHROPIC_BASE_URL是否写对域名是否能解析Nginx 是否在跑。如果是本地开发确认端口没被占用。还有一个容易忽略的点如果你的 Base URL 带了路径比如https://cch.yourdomain.com/api而 Nginx 的location没匹配上也会报这个错。5.3 reading choices这个报错看起来像 OpenAI 格式的残留实际上是因为请求发到了不兼容 Anthropic 格式的端点。Claude Code 发的是 Anthropic Messages API 格式如果你的 Base URL 指向了一个只支持 OpenAI Chat Completions 格式的服务就会在解析响应时报reading choices。解决办法是确认你的端点支持 Anthropic 格式。TaoToken 的/api端点是兼容 Anthropic 格式的cch 也是按 Anthropic 格式转发的所以走这两条路不会出这个问题。5.4 OAuth 相关报错如果你在 Claude Code 里用了 OAuth 登录而不是 API Key可能会遇到 token 过期或刷新失败。这种情况下检查你的 OAuth 配置是否指向了正确的端点。如果你用的是统一 Key 通道建议直接用 API Key 模式避免 OAuth 的额外复杂度。在settings.json里确保ANTHROPIC_API_KEY有值Claude Code 会优先用 Key 而不是 OAuth。5.5 499 和超时499 是 Nginx 特有的状态码表示客户端在服务端返回前断开了连接。在 Claude Code 场景里这通常是因为proxy_read_timeout太短Nginx 等不及后端返回就掐断了客户端收到断开后重试或报错。把proxy_read_timeout和proxy_send_timeout都调到 600s 以上基本能解决。如果调了还不行检查 cch 或 TaoToken 侧是否有更短的超时限制。排查的顺序建议是先看 Claude Code 的报错确定是哪一层的问题再用 curl 逐层验证最后对照上面的报错表定位。不要一上来就改配置先确认问题出在哪一层改起来才有方向。6. 把链路固定下来Claude Code 长期接入的配置建议链路调通之后下一步是让它稳定跑下去。我自己的做法是把配置分成三层管理Nginx 层管域名和超时cch 层管 Key 和用量Claude Code 层只管 Base URL 和 Model ID。这样任何一层出问题改动范围都可控。如果你团队里有多个人用 Claude Code建议在 cch 里给每个人分配独立的 Key这样用量和审计都能分开。cch 的 PostgreSQL 会记录每个 Key 的请求量Redis 做限流避免某个人跑飞了影响其他人。Nginx 层可以再加一层limit_req做粗粒度限流但精细限流交给 cch 更合适。对于长期编码和 Agent 任务TaoToken 的 Coding Plan 页面有专门的额度规划比按量付费更适合高频使用。接入文档在https://taotoken.net/docClaude Code 相关的说明在https://taotoken.net/claude-code-anthropic遇到配置问题可以先翻文档。Key 管理在https://taotoken.net/api-keys模型对话测试在https://taotoken.net/model-chat这两个页面在调试阶段用得最多。最后说一个实用技巧在 Nginx 配置里加一行add_header X-Upstream $upstream_addr;这样响应头里会带上实际转发的后端地址。调试时用curl -i一看就知道请求落到了哪个 upstream比翻日志快得多。链路这东西配一次调通之后后面就是复制粘贴的事关键是第一次要把每一层的作用搞清楚。