Gushen888 Docs

主题

Gateway 运维 ​

Gateway 运维分两类场景:官方 Claude apps gateway 和通用 LLM gateway。前者面向 Claude apps 的组织级入口,由管理员运行和管理;后者面向 Claude Code 的 ANTHROPIC_BASE_URL,由 Gushen888 或自定义网关转发 Anthropic Messages 请求。

官方 Claude apps gateway 的登录入口必须能被用户设备在私网内访问。如果登录页、OIDC 回调或 gateway public URL 只在服务器本机可达,Claude apps 会卡在登录或策略拉取阶段。

协议字段、错误语义、模型发现和缓存验收清单见 Gateway 协议上线清单。用户侧 provider 选择和认证变量见 Provider 认证与云平台接入。

官方 Claude apps gateway ​

管理员用 claude binary 自托管 gateway:

claude gateway --config gateway.yaml

这个 gateway 运行在 claude binary 中,不需要额外部署一个独立应用框架。运维重点是把身份、策略、数据库、观测和上游模型路由配置清楚,并把登录入口放在 VPN、内网 DNS 或受控反向代理后面。

能力运维注意
OIDC配置 issuer、client、回调 URL、允许的 group/claim。确认用户设备能访问登录页和回调域名。
Postgres用持久化数据库保存 gateway 状态。纳入备份、迁移、连接池和监控。
Managed policies在 gateway 或组织策略里集中限制模型、工具、权限和默认配置。不要依赖每个用户手动设置。
Telemetry输出请求量、延迟、错误率、模型路由、spend 和策略命中。日志里默认不要记录完整 prompt。
Upstream routing按用户、团队、模型、成本或区域把请求路由到 Anthropic、Gushen888 或其他上游。
Spend limits设置 user/team/project 级预算和时间窗口。超限时返回明确错误,不要静默切到未知模型。

gateway.yaml 示例 ​

下面是运维结构示例,用于说明应覆盖哪些配置域。实际字段名以当前 claude gateway 版本的 schema 为准。

server:
  listen: "0.0.0.0:8443"
  public_url: "https://claude-gateway.internal.example.com"

auth:
  oidc:
    issuer_url: "https://idp.internal.example.com"
    client_id: "claude-apps-gateway"
    client_secret_env: "CLAUDE_GATEWAY_OIDC_CLIENT_SECRET"
    allowed_groups:
      - "engineering"
      - "support"

database:
  postgres:
    url_env: "CLAUDE_GATEWAY_DATABASE_URL"

policies:
  managed:
    enabled: true
    default_policy: "engineering-default"

telemetry:
  otlp:
    endpoint: "https://otel.internal.example.com/v1/traces"
    headers_env: "CLAUDE_GATEWAY_OTEL_HEADERS"

upstreams:
  - name: "anthropic"
    type: "anthropic"
    base_url: "https://api.anthropic.com"
    api_key_env: "ANTHROPIC_API_KEY"
  - name: "gushen888"
    type: "anthropic"
    base_url: "https://api.gushen888.cloud"
    auth_token_env: "GUSHEN888_API_KEY"

routing:
  default_upstream: "anthropic"
  rules:
    - group: "support"
      upstream: "gushen888"
      models:
        - "claude-sonnet-4"

spend_limits:
  defaults:
    user_daily_usd: 10
    team_monthly_usd: 1000
  on_exceeded: "deny"

把 OIDC secret、Postgres URL、上游 API key 和 telemetry headers 放在环境变量或 secret manager 中。不要把真实密钥写进 gateway.yaml。

通用 LLM gateway 协议 ​

Claude Code 接入 Gushen888 或自定义网关时,客户端仍发送 Anthropic Messages 请求。Base URL 写在 ANTHROPIC_BASE_URL,网关需要提供 Anthropic 兼容路径。

项目要求
Base URLANTHROPIC_BASE_URL 写到 host 根路径,例如 https://api.gushen888.cloud,通常不要带 /v1。
MessagesPOST /v1/messages 必须支持。
Token countPOST /v1/messages/count_tokens 可选,缺失时客户端会退回估算或部分功能降级。
Streamingstream: true 时必须返回 SSE stream,不要被反向代理缓冲成一次性响应。
Headers原样转发 anthropic-version 和 anthropic-beta,不要按固定旧版本重写。
Errors上游 JSON 错误应保留 status、type、message,便于 Claude Code 判断是否重试或降级。

自定义网关如果要校验 body,应使用开放列表而不是只允许最小字段。至少保留这些字段,并对未知 beta 字段采用灰度透传或显式拒绝:

字段说明
model、max_tokens、messages、systemMessages API 的核心字段。
stream控制 SSE 流式响应。
tools、tool_choiceMCP、内置工具和 deferred tool loading 依赖这些字段。
thinkingreasoning/effort 相关能力。
metadata、stop_sequences业务标记和停止条件。
temperature、top_p、top_k采样参数。
context_management、output_configClaude Code 的上下文和输出控制能力。
cache_control可能出现在 system、messages、tools 等嵌套 block 上。

system array 与 attribution ​

Claude Code 可能把 system 作为 array 发送,并把 attribution block 放在固定位置。gateway 必须保持 block 顺序、类型和嵌套字段:

不要做风险
把 system array 合并成字符串破坏 attribution 处理、prompt cache key 和 cache_control block。
在 attribution block 前插入自定义 system可能让 attribution 进入实际 prompt,也会改变缓存前缀。
对 system blocks 排序、去重或重写会导致缓存 miss、策略误判或上游能力异常。
删除未知 block 字段新版 Claude Code 的 beta 能力可能直接失效。

如果网关必须插入组织提示,优先用官方 managed policies 或上游支持的策略机制。必须改写 body 时,至少保留 attribution block 的相对顺序,并把改写行为打到审计日志里。

模型发现 ​

Claude Code 可以从 gateway 拉取模型列表,用于 /model picker。开启变量:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

发现请求是:

GET /v1/models?limit=1000

运维约束:

项目说明
超时客户端等待时间约 3s。网关慢、跳转或 OIDC 拦截都会导致静默失败。
缓存文件本机缓存通常在 ~/.claude/cache/gateway-models.json。
手动模型变量可用 ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_FABLE_MODEL 固定默认模型。
能力声明模型出现在列表里不代表支持 tool search、1M context、thinking 或 1h prompt cache。

模型列表返回要稳定、轻量、无需交互登录。不要让 /v1/models?limit=1000 返回 HTML 登录页或重定向到 IdP。

Prompt cache 与 1h TTL ​

1 小时 prompt cache 不是只靠客户端变量就能保证。自定义 gateway 要满足这些条件才适合透传:

条件运维检查
客户端请求API/provider 场景设置 ENABLE_PROMPT_CACHING_1H=1,且未设置 FORCE_PROMPT_CACHING_5M 或 DISABLE_PROMPT_CACHING。
上游支持实际路由到支持 1h TTL 的模型和 provider。
Header 透传anthropic-version、anthropic-beta 不被剥离或降级。
Body 稳定不重写 system array、messages、tools、cache_control 或模型参数。
Usage 返回保留 cache_creation_input_tokens 和 cache_read_input_tokens 等 usage 字段。

如果上游不支持 1h TTL,网关应明确降级为 5 分钟策略并在 telemetry 中标记。不要用 body 重写伪造缓存命中,否则成本和延迟都会失真。

Spend limits ​

spend limits 应在 gateway 层和上游账号层同时考虑:

层级建议
Gateway按 user、team、project、model、upstream 设置日/月预算和并发限制。
Upstream设置 provider 侧硬限额,防止 gateway bug 或凭证泄露导致无限消费。
响应超限返回稳定的 402、403 或 429 JSON 错误,包含 limit、window、reset 时间。
观测telemetry 中记录预算消耗、拒绝次数、触发规则和 fallback 行为。

不要在用户超限后自动切到更便宜但能力不同的模型,除非策略和 UI 明确告知。静默 fallback 会让调试、成本归因和安全审计都变复杂。

Server-managed settings 限制 ​

Anthropic server-managed settings 依赖官方账号、组织和服务端策略通道。使用 Gushen888 或其他 custom ANTHROPIC_BASE_URL 时,不要假设它会覆盖第三方 provider 场景,也不要依赖它下发自定义 Base URL 或网关 token。

场景推荐做法
统一设置 ANTHROPIC_BASE_URL用 MDM、endpoint-managed settings、系统级 managed settings 或本地模板。
统一分发 token用 apiKeyHelper、secret manager 或短期凭证,不要把 token 放进项目仓库。
统一限制模型和预算放在 gateway managed policies 和 spend limits 中。
官方 Claude apps gateway通过 gateway 自身的 OIDC、Postgres、managed policies 和 telemetry 管理。

Gushen888 / 自定义网关清单 ​

检查项说明
Base URLClaude Code 使用 https://api.gushen888.cloud 这类根路径,不要写成 OpenAI 兼容的 /v1 地址。
认证变量Gushen888 通常使用 ANTHROPIC_AUTH_TOKEN;不要和旧的 ANTHROPIC_API_KEY 登录状态混在一起排查。
私网入口官方 apps gateway 登录页、OIDC callback、admin health route 都应在受控网络内可达。
反向代理关闭 SSE buffering,保留长连接,设置合理 idle timeout。
字段透传headers、system array、tools、cache_control、usage 和 error body 都要原样保留。
安全审计可以记录 request id、用户、模型、token 和策略命中,默认不要记录完整 prompt/body。

curl 自检 ​

先确认环境变量:

export ANTHROPIC_BASE_URL="https://api.gushen888.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-..."
export ANTHROPIC_MODEL="claude-sonnet-4"

Messages JSON:

curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 64,
    "messages": [
      { "role": "user", "content": "只回答 ok" }
    ]
  }'

SSE stream:

curl -N "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 64,
    "stream": true,
    "messages": [
      { "role": "user", "content": "stream ok" }
    ]
  }'

模型发现,按客户端约束用 3s 自检:

curl -sS --max-time 3 "$ANTHROPIC_BASE_URL/v1/models?limit=1000" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01"

可选 token count:

curl -sS "$ANTHROPIC_BASE_URL/v1/messages/count_tokens" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "messages": [
      { "role": "user", "content": "count tokens" }
    ]
  }'

自检结果应满足:

项目通过标准
/v1/messages返回 Anthropic Messages JSON,不是 HTML、登录页或代理错误页。
SSEcurl -N 能持续看到 event/data 行,首包不被缓冲。
/v1/models?limit=10003s 内返回模型 JSON 或明确的 401/403 JSON。
count_tokens支持时返回 token count;不支持时返回明确错误,不要伪造空结果。
Spend limit超限时返回稳定 JSON 错误,并能在 telemetry 中查到触发规则。

官方参考 ​

相关页面 ​

Claude apps gateway 部署私网入口、OIDC、Kubernetes、Cloud Run、GCP、健康检查和升级。网关与协议Base URL、headers/body、模型发现、缓存和常见错误。企业部署总览provider、认证、managed settings、权限和观测的组织级决策。

面向编码工具与 Agent 工作流的稳定模型网关。

Gushen888 · 客服微信 zbzy_888 · 邮箱 gulin1989@163.com