# TrustedRouter
[](https://github.com/Lore-Hex/quill-router/actions/workflows/ci.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/deploy.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/prod-smoke.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/trust-drift.yml)
[](https://status.trustedrouter.com)
[](https://trust.trustedrouter.com)
[](https://www.npmjs.com/package/@lore-hex/trusted-router)
[](https://pypi.org/project/trusted-router-py/)
[](LICENSE)
# 端到端加密的大语言模型。一个 API。可验证的隐私。
不必再担心谁能看到你的提示词。让你的编码智能体帮你迁移项目，选择你想要的隐私级别，挑选一个模型，填入密钥——搞定。同一个 API，30+ 个模型，一个密钥。网关运行在硬件安全飞地中，你可以通过密码学方式验证它从不记录你的数据。
### 用一条提示词迁移你的项目
把下面这段粘贴到 Codex、Claude Code 或 Cursor 中——它会替你完成迁移：
```text
Migrate this project to TrustedRouter, a privacy-first LLM router
(https://trustedrouter.com). Repoint my LLM client to base_url
"https://api.trustedrouter.com/v1" (or "https://api.trustedrouter.com" for the
Anthropic SDK), read the key from the TRUSTEDROUTER_API_KEY env var, and keep
all my existing calls working.
For a hard provider-side confidential-compute and end-to-end-encryption
requirement, add {"provider": {"min_privacy": "confidential"}}. TrustedRouter
fails closed when the selected model or provider cannot satisfy both controls.
Then tell me to sign up at trustedrouter.com, add a card, and paste my sk-tr
key into TRUSTEDROUTER_API_KEY.
```
然后：
1. **选择你的隐私级别或区域** — 使用
`{"provider": {"min_privacy": "zdr"}}` 设定硬性零保留下限，或
使用 `{"provider": {"min_privacy": "confidential"}}` 设定更严格的硬性
机密计算 + E2EE 下限。便捷的 `trustedrouter/zdr` 和
`trustedrouter/e2e`（`trustedrouter/confidential`）别名会选择这些
池。使用 `trustedrouter/eu` 搭配
`https://api-europe-west4.quillrouter.com/v1` 可实现以欧盟为中心的路由。
2. **选择模型** — 数百个模型任选，或使用 `trustedrouter/auto` 在提供商覆盖范围比最严格的隐私
过滤器更重要时自动回退。
3. **注册、添加银行卡、获取你的密钥**，网址为 https://trustedrouter.com。
4. **发布** — 你的提示词现在会经过一条你可以验证的路径运行。
<details>
<summary>更愿意手动配置？</summary>
```bash
# Codex
export OPENAI_BASE_URL="https://api.trustedrouter.com/v1"
export OPENAI_API_KEY="sk-tr-v1-..."
# Claude Code
export ANTHROPIC_BASE_URL="https://api.trustedrouter.com"
export ANTHROPIC_API_KEY="sk-tr-v1-..."
```
```python
# Any OpenAI SDK
client = OpenAI(base_url="https://api.trustedrouter.com/v1", api_key="sk-tr-v1-...")
```
</details>
- **获取密钥 / 付费支持我们：** https://trustedrouter.com
- **先试用（无需注册）：** https://trustedrouter.com/chat
- **技术细节（面向技术爱好者）：** https://trustedrouter.com/security
- **生成图像：** [docs/image-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/image-generation.md)
- **生成视频：** [docs/video-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/video-generation.md)
- **我们为何构建它：** https://jperla.com/blog/attestation-is-all-you-need
---
<details>
<summary><strong>面向技术爱好者：隐私如何得到可证明的保障</strong></summary>
TrustedRouter 的网关运行在 GCP Confidential Space 内。该平台会对运行中的容器进行度量并签名。请验证该签名证据，并将其镜像摘要与已发布的版本度量值进行比对。源代码审查与发布构建来源可确立该被度量镜像的行为；仅凭摘要匹配并不能证明不存在缺陷或日志记录。
无需账户即可检查 GCP 证据：
```bash
NONCE=$(openssl rand -hex 16)
curl --fail --silent --show-error \
"https://api-us-central1.quillrouter.com/attestation?nonce=$NONCE" \
--output attestation.jwt
# GCP returns a raw Google-signed JWT, not a JSON response.
# Decoded claims include eat_nonce and submods.container.image_digest.
# GCP evidence has no pcrs field; PCRs belong to AWS Nitro evidence.
```
保存或解码 JWT **并不等于验证**。请使用来自经过审查的 `quill-cloud-proxy` 检出目录中的
[attestation verifier](https://github.com/Lore-Hex/quill-cloud-proxy/blob/main/tools/verify-attestation.py)
来验证签发者/签名、新鲜 nonce、TLS 证书/exporter 绑定以及预期的发布度量值。
对于 GCP 端点，请从该检出目录运行：
```bash
DIGESTS=$(curl --fail --silent --show-error \
https://trust.trustedrouter.com/trust/accepted-image-digests-gcp.txt)
test -n "$DIGESTS" && uv run --script tools/verify-attestation.py \
--api-host api-us-central1.quillrouter.com --expect-digest "$DIGESTS"
```
验证器会在其验证的 TLS 连接上获取最新证据。该检查并不能证明之后独立的 `curl` 或 SDK 连接。这些示例使用已发布的美国中部 GCP 主机名来选择 GCP 证据格式。全局端点可以选择其他云；请使用其云特定的验证策略以及来自[信任站点](https://trust.trustedrouter.com/)的测量值。
| | 信任模型 |
|---|---|
| OpenRouter、托管提供商 | “我们不记录日志。”一条你无法核查的策略。 |
| Portkey、Cloudflare AI Gateway | 为可观测性记录一切。 |
| LiteLLM | 自托管，但运行中的代理未经验证。 |
| **TrustedRouter** | **开源 + 硬件证明。验证代码路径；它不记录任何日志。** |
诚实的范围说明：证明只能证明运行中的二进制文件是已发布的二进制文件，且运行在你可以用 nonce 挑战的硬件上。它无法抵御拥有物理主机访问权限的国家级攻击者，也无法证明开源二进制文件没有缺陷。信任锚点是 Google Confidential Computing 的硬件支持证明链。上游提供商按其自身策略处理提示词——每个提供商的立场都发布在模型页面上。
</details>
---
## 仓库布局
本仓库实现控制平面契约：路由覆盖、认证/密钥管理、计费账本语义、用量元数据、提示词/输出日志记录禁令、Sentry 清理器以及提供商抽象。经证明的网关实现位于 `quill-cloud-proxy`。
信任边界：`api.trustedrouter.com` 是经证明的提示词路径，必须在 Confidential Space 内终止 TLS。`trustedrouter.com` 是控制平面，绝不能提供生产推理回退。
`api.quillrouter.com` 仍然是永久可用的别名（相同的经证明网关和证书），因此现有集成无需迁移即可继续工作。
## 本地
```bash
uv sync
uv run pytest
uv run uvicorn trusted_router.main:app --reload
```
针对运行中实例的端到端冒烟测试：
```bash
TR_SMOKE_BASE_URL=http://127.0.0.1:18080/v1 uv run python scripts/smoke_e2e.py
```
在生产环境中，请设置 `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1`，如果内部网关路由受令牌保护，还需设置 `TR_SMOKE_INTERNAL_TOKEN`。
在以下位置设置本地操作员/提供商密钥：
```text
/Users/jperla/claude/.quill_cloud_keys.private
```
该文件永远不会被提交。它应当是 dotenv 风格的：
```text
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...
CEREBRAS_API_KEY=...
DEEPSEEK_API_KEY=...
MISTRAL_API_KEY=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
SENTRY_DSN=...
```
部署脚本还接受一些运维文件中已在使用的本地别名：Anthropic 使用 `CLAUDE_API_KEY`，OpenAI 使用 `CHATGPT_API_KEY`，`STRIPE_SECRET_KEY` 使用 `STRIPE_KEY`。
Vertex 与其他提供商平台不同：生产环境的 GCP 部署使用 Cloud Run 或 Confidential Space 服务账号，以及来自 metadata/ADC 的短期 Google 访问令牌。对于第一方预付费 Vertex 路由，不要在此文件中放置长期有效的 Vertex 密钥；而应授予运行时服务账号 Vertex 权限。
## 许可证
Business Source License 1.1。源代码公开，任何人都可以阅读、构建并验证 TrustedRouter 隐私与证明声明背后的确切代码（https://trust.trustedrouter.com）——这正是它存在的目的。非生产用途（安全审查、审计、本地评估）免费。生产用途需要获得 Lore Hex Corp 的商业许可：[email protected]。每个版本在发布四年后转换为 Apache License 2.0。2026 年 7 月 3 日之前发布的代码仍保持 Apache-2.0。
## 安全默认值
- 提示词和输出内容从不记录日志。普通的同步和流式推理不会保留这些内容。可选的 Batch API 会临时保留 enclave 加密的产物，最长 30 天。
- 使用日志仅包含元数据。
- API 密钥以加盐 SHA-256 哈希形式存储，并配有不可猜测的密钥 ID。
- 用户提交的 BYOK 提供商密钥以信封加密的密文行存储，而不是每个密钥一个 Secret Manager 对象。在生产环境中，Cloud KMS 封装每个密钥的 DEK；外部 `env://...` 引用仍支持用于运维人员管理的密钥。
- 网关授权包含用于加密 BYOK 信封的非机密 `byok_cache_key`。经证明的网关使用它进行短 TTL、仅内存的解密密钥缓存；BYOK 轮换会更改密钥，删除操作会停止返回该信封。
- BYOK 原始密钥仅作为一次性输入；公共/控制平面响应仅暴露简短的首/尾密钥提示和加密引用元数据，绝不暴露明文。
- 生产配置在缺少内部网关令牌、已签名的 Stripe webhook 密钥和非内存存储后端时会失败关闭。
- 生产控制平面应用不注册 `/chat/completions`、`/messages`、`/responses` 或 `/embeddings`；这些属于经证明的 API 平面。
- Sentry 仅限控制平面使用，并会清除请求体、认证头、API 密钥、BYOK 密钥、提示词消息和输出文本。客户端 Sentry 洪泛门控会按指纹限制重复问题，并按进程/窗口限制总事件数，以免单个嘈杂的集成再次消耗整个错误预算。
- 经证明的 enclave 中不应包含任何 Sentry 配置。
## 广播可观测性
工作区所有者可以在 `/v1/broadcast/destinations` 或控制台的 Broadcast 下配置广播目标。支持的目标是 PostHog 和 OTLP JSON webhook。广播默认仅包含元数据：模型、提供商、token 计数、延迟、成本、路由类型、区域和自定义追踪元数据。仅当目标显式启用 `include_content` 时才导出提示词/输出内容；这些启用了内容导出的加密目标仅返回给经证明的网关，而不会出现在普通管理响应中。仅元数据的投递会先写入持久化广播发件箱，然后由 `/internal/broadcast/drain` 异步排空，因此 PostHog/webhook 故障不会阻塞推理，也不会在进程重启时丢失已结算的元数据。
## 固定路由层级
这些别名使用显式排序的模型池：首选第一个成员，其余为回退。它们每次尝试运行一个模型，不进行合成、编排或隐式隐私下限。需要时请显式设置 `provider.min_privacy`。实时 `/v1/models` 目录会在 `auto_candidates` 中发布每个模型池。
- `trustedrouter/frontier`：固定的前沿模型池。
- `trustedrouter/advanced`：固定的高级模型池。
- `trustedrouter/professional`：固定的专业模型池。
- `trustedrouter/efficient`：固定的高效模型池。
## 合成监控
TrustedRouter 拥有一个独立的合成监控平面，用于公开的正常运行时间监测。
合成工作进程在 enclave 之外运行，向公开的可验证 API 发送微小的真实请求，
并且只存储元数据。监控模型别名如下：
- `trustedrouter/free`：OpenRouter 风格的免费池。对用户有用，但不是
SLA 信号。
- `trustedrouter/cheap`：最便宜的付费池，具有提供商多样性。
- `trustedrouter/eu`：以欧盟为重点的提供商池。它优先选择欧洲、
可部署于欧盟区域以及注重隐私的提供商，尤其是与
`https://api-europe-west4.quillrouter.com/v1` 搭配使用时。这是一种路由策略，而非
全面的数据驻留保证。
- `trustedrouter/monitor`：用于 PONG 和回退检查的内部正常运行时间池。
它在目录中可见以保持透明，但授权需要
配置的 `TR_SYNTHETIC_MONITOR_API_KEY`；普通 API 密钥会收到 403。
工作进程应从 `us-central1` 和 `europe-west4` 运行，使用专用的
`trustedrouter-synthetic-monitoring` 工作区/密钥，并设置硬性支出上限和
自动充值。原始样本是仅追加的 Bigtable 行；公开状态页面
读取在 `/status`、`/status.json` 和
`/status/history?window=5m|24h|daily` 处暴露的紧凑汇总。合成生成使用
`TrustedRouter Synthetic` 应用标签，并被排除在客户/应用
分析之外。
每次监控调用还会发起一个 `stream: true` 的聊天补全，并且除非
收到 SSE 数据事件、终止块和 `[DONE]`，否则会失败。循环的 Stage D 任务会添加
`--expect-stage-d`，然后查找该请求的
类型化授权，并要求绑定的 `stage_d_boot_kid` 以及
`heartbeat_seq > 0`。其工作区有意保持独立：使用
`scripts/provision_stage_d_probe_workspace.py` 进行配置，并将其 id 添加到
`TR_STAGE_D_PILOT_WORKSPACE_IDS`。该密钥必须是
支持心跳的本地类型化密钥；部署从
`trustedrouter-stage-d-probe-api-key` 读取它，并使用 `trustedrouter/cheap`，因此它
独立于普通的仅监控密钥。正常发布会使 Stage D
资格保持禁用状态，因此仅创建密钥并不会启用 Stage D。
提供商测量使用两个独立的探测类别：
- 短 PONG 探测随机覆盖整个活跃目录，并测量正常运行时间、
TTFB、TTFT 和上游 API 漂移。
- 持续的 512 token 流从 `us-central1` 以确定性轮换覆盖 200 个最重要的提供商/模型
路由。它测量首个 token 之后的
每秒输出 token 数。它运行在单独的 Cloud Run Job 中，
因此慢速流不会延迟正常运行时间探测。长探测失败永远不会计入
提供商正常运行时间或 API 漂移告警。
当前的两分钟调度使每个持续路由每周获得约 25 个样本，
每 30 天获得 108 个样本。CI 根据实时
目录计算满容量支出估算，如果超过经审核的月度上限则会失败。
状态将两个服务 SLO 类别分开，而不是将它们与
上游提供商行为混在一起：
- `router_core`：可验证 API 可达、密钥授权有效、路由
候选/回退可用，并且结算/退款持久化。
- `control_plane`：仪表盘、计费 UI、密钥、额度、文档、信任和
状态界面。
部署看门狗和内部燃烧率告警默认使用 `router_core`。
仅提供商故障按提供商在 `/status` 和
`/leaderboard` 上测量；当回退仍然可用时，它们不会消耗 router-core 错误预算。
## 公开定位
- 定价：预付费和 BYOK 用量以整数微美元（microdollars）记录，而非浮点美元，因此微小的 token 成本在账本中仍可审计。
- 正常运行时间目标：`trustedrouter/auto` 在本地/测试控制平面推理中是一个真实的聊天模型别名，在上游提供商故障时会滚动切换到下一个已配置的提供商。`trustedrouter/eu` 优先选择以欧盟为重点的提供商池，`trustedrouter/zdr` 强制要求零保留提供商下限并优先选择 Anthropic，`trustedrouter/e2e` 强制要求机密 + E2EE 路由并优先选择 Tinfoil。聊天请求还遵循 OpenRouter 风格的 `models` 和 `provider` 路由过滤器（`order`、`only`、`ignore`、`allow_fallbacks`、`min_privacy`、`data_collection`、`sort`、`max_price`、`require_parameters` 和 `zdr`），因此客户端可以请求显式的回退链或提供商偏好。在启用回退时，`provider.order` 是一种偏好，未列出的提供商在首选列表之后仍然符合条件。当 `allow_fallbacks=false` 时，路由被限制在有序的提供商集合内，并且只有其第一个可用路由被授权。`provider.only` 始终是硬性提供商允许列表。在请求顶层或作为 `provider.allow_fallbacks` 设置 `allow_fallbacks=false` 也会阻止替换为其他模型。`min_privacy="confidential"` 是提供商侧的硬性机密计算 + E2EE 要求，并且会失败关闭（fail closed）；请求值别名 `e2e` 和 `e2ee` 选择同一层级，而不是回退到较弱的路径。未知的请求或提供商选项会返回 `400` 并附带确切的字段名。已识别但未实现的 OpenRouter 控制项会返回稳定的 `501 not_supported_in_alpha`；它们绝不会被接受为路由器的空操作。
- 计费：优先使用预付费额度和 BYOK；无需订阅。
- 信任：托管开源，运行中 API 的源代码提交、镜像引用、镜像摘要和证明策略发布在 `trust.trustedrouter.com`。
- 注册：电子邮件注册会为工作区创建一个一次性管理密钥。
- 钱包/加密货币：请求时，稳定币结账通过 Stripe Checkout 的 Crypto 支付方式接入。银行卡/默认 Checkout 仍是默认路径。
## 规模目标
目标是支持 OpenRouter 级别的规模：
- 每天 1 万亿 token，或按一天平均约每秒 1160 万 token。
- 100 万至 400 万开发者账户。
- 300+ 个可主动路由的模型。
- 60+ 个提供商。
- 全球路由开销与边缘部署的路由器相比具有竞争力。
当前生产部署**尚未**达到该目标。它在全球 LB 后面的四个 GCP 区域运行控制平面，每个区域有 Serverless NEG，并有四个实时证明的 API 区域。随着更多证明池上线，容量会水平扩展；正确性、信任、计费和 SDK 兼容性处于稳态。
请求量在很大程度上取决于平均生成大小。在每天 1 万亿 token 时：
| 平均 token/请求 | 请求/天 | 平均请求速率 |
| ---: | ---: | ---: |
| 1,000 | 10 亿 | 11.6k rps |
| 2,500 | 4 亿 | 4.6k rps |
| 10,000 | 1 亿 | 1.2k rps |
该架构可以演进到这一规模，但前提是热路径避免每请求的全局瓶颈。这意味着区域无状态网关集群、区域提供商池、分片配额租约、仅追加的元数据写入以及异步聚合。
## 当前延迟
于 2026 年 5 月 2 日从此开发机器测量到集中式 GCP `us-central1` 证明 API：
| 探测 | p50 | p95 | 备注 |
| --- | ---: | ---: | --- |
| 未认证的 `/v1/chat/completions` 拒绝 | 174 ms | 184 ms | 包括 DNS、TCP、公共 TLS、enclave 请求处理。 |
| TCP 连接 | 55 ms | 59 ms | 从此机器到 `us-central1` 的网络路径。 |
| TLS 握手完成 | 112 ms | 124 ms | 公共 ACME 证书在 enclave 内终止。 |
| `/attestation` | 1.06 s | 1.12 s | 包括 GCP 证明令牌生成，因此不能代表正常路由开销。 |
集中式网络开销远高于 OpenRouter 所报告的边缘开销，但模型延迟通常主导交互式请求。第一个生产扩展步骤应该是多区域，而不是立即构建自定义的全球边缘。
## 水平扩展形态
生产路径的设计目标是通过保持提示网关无状态来实现扩展：
- `api.trustedrouter.com` 实例可以在 TCP 直通后面进行复制。它们通过控制平面进行授权、预留和结算，但提示字节永远不会离开经过认证的路径。
- Spanner 存储强一致的控制平面和计费状态：用户、工作区、密钥、BYOK 元数据、支付事件幂等性、余额、聚合、活动预留，以及 30 天的终端请求审计窗口。
- Bigtable 存储按工作区和日期键控的有界高容量活动元数据。活动和提供商基准保留 30 天，原始合成样本保留 14 天，紧凑状态汇总保留 24 个月。提示、输出和工具调用参数不会被存储。
- API 密钥验证使用高熵查找哈希进行点读取；它不会扫描密钥。
- 速率限制在路由处理器之前强制执行，并使用配置的存储，因此生产计数器在 Cloud Run 实例之间共享。
在 OpenRouter 规模的流量下，下一个瓶颈不是 enclave 二进制文件；而是同步的计费/授权路径。在允许公共流量爬升之前，架构需要分片预留、区域 Bigtable 集群、Cloud Armor 边缘限制和多个网关副本。
## 多区域计划
多区域在保留信任边界的同时是可行的，但必须谨慎进行：
圣保罗（`southamerica-east1`）仍然是一个活跃的 Cloud Run 控制平面：`trusted-router` 继续通过全局负载均衡器进行部署和服务。只有其 enclave 网关 MIG 已退役（quill-cloud-proxy #309）；其过时的区域网关 DNS 记录已被删除。控制平面部署区域仍为 `us-central1`、`us-east4`、`europe-west4` 和 `southamerica-east1`。
俄勒冈（`us-west1`）是相反的情况：一个仅网关区域。它在 `api-us-west1.quillrouter.com` 运行一个经过认证的网关池，并且没有 Cloud Run 控制平面。其网关通过全局负载均衡器到达控制平面，全局负载均衡器将其发送到最近的控制平面区域（`us-central1`）。`scripts/deploy` 中没有任何内容在那里创建 Cloud Run 服务、调度器作业或 NEG，并且它在热区域或最小实例默认值中没有条目。
- 在 `us-central1`、`us-east4`、`europe-west4` 和 `us-west1` 中运行独立的预热且经过认证的网关池。enclave 清单为 `src/trusted_router/enclave_regions.py`，由合成探测、提供商冒烟检查、看门狗默认值以及 `TR_REGIONS` 部署默认值共享。同一模块还列出了没有本地控制平面的网关区域（`ENCLAVE_REGIONS_WITHOUT_LOCAL_CONTROL_PLANE`）。
- 将 TLS 私钥保留在每个区域性的 Confidential Space 工作负载内部。
- 将证书签发保留在经过认证的工作负载内部。证书通过加密缓存在各副本之间共享。只有在每个节点都通过规范认证并收到稳定的 PONG 之后，首个区域主机名才会暴露给一个节点；只有在每个节点上区域证书和相同的门禁都通过之后，才会进行扩展。
- 保留诸如 `api-us-central1.quillrouter.com`、`api-us-east4.quillrouter.com`、`api-europe-west4.quillrouter.com` 和 `api-us-west1.quillrouter.com` 等区域主机名，用于确定性认证、冒烟测试和 SDK 故障转移。
- 将 `api.trustedrouter.com` 置于不终止 TLS 的延迟/地理 DNS 或 TCP 直通之后。Cloudflare 橙色云代理仍与提示路径信任声明不兼容。
- 通过分片计费行进行授权，而不是对每个请求使用单一的全局 Spanner 计数器变更。新的工作区和密钥以 16 个精确计费分片开始。区域配额租约仍属于未来工作：2026-09 的区域配额和支出租约试点已被移除。
- 将生成元数据写入区域 Bigtable 集群，然后异步聚合到全局活动视图中。
- 保持提供商路由的区域性，并具有提供商特定的熔断器、回退策略和每提供商速率限制。
关键设计规则：区域中断可以故障关闭或路由到另一个经过认证的区域，但绝不能静默降级到未经认证的提示处理器。
## Router-Core 四个九目标
该目标是内部 SLO，而非合同 SLA。99.99% 允许每年约 52 分 36 秒的停机时间。在至少存在 30-60 天的实测 99.99% router-core 正常运行时间之前，公共状态将此数字标记为目标。
Router-core 可用性意味着：
- 经过认证的 TLS 可访问；
- API 密钥验证和网关授权正常工作；
- 返回路由候选，并且回退可以选择健康的提供商；
- 结算/退款是持久的或可安全修复的；
- 任何提示请求都不会回退到未经认证的路径。
目前支持此路线图的代码路径包括：
- `/status.json` 导出 `slo_classes.router_core`、`slo_classes.control_plane`，以及针对 5m、1h、6h 和 24h 窗口的燃烧率告警。
- 部署看门狗默认读取 `router_core`，因此仅提供商中断不会自动回滚控制平面部署。
- SDK 应在暴露失败之前，跨区域认证端点重试连接失败和 502/503/504。
- Bigtable 活动写入可从持久结算发件箱中修复。结算使用确定性生成 ID，因此重试会覆盖相同的索引行，不会重复收费或重复活动。
在将四个九描述为实测可用性而非目标之前，需要三个预热的 GCP 认证区域、经过测试的寻呼、router-core 混沌测试、带回滚门禁的分阶段区域部署，以及至少 30 天的实测 router-core 正常运行时间达到或超过 99.99%。
## 内部网关契约
经过认证的 API 平面可以预留和结算用量，而无需将提示或输出内容发送到控制平面：
- `POST /v1/internal/gateway/authorize`：校验 API 密钥哈希，预留
额度/密钥限额，并返回 provider/BYOK 路由元数据、由 `model`、`models` 和 `provider` 请求过滤器
派生出的路由候选，
以及已配置的区域端点。
- `POST /v1/internal/gateway/settle`：结算成功的使用量，并追加
仅含元数据的活动记录行。
- `POST /v1/internal/gateway/refund`：在 provider
失败或客户端断开连接后释放预留。
在本地开发环境之外设置 `TR_INTERNAL_GATEWAY_TOKEN`。
## 生产存储
生产环境使用：
```text
TR_STORAGE_BACKEND=spanner-clickhouse
TR_SPANNER_INSTANCE_ID=trusted-router-nam6
TR_SPANNER_DATABASE_ID=trusted-router
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_URL=http://<clickhouse-ilb>:8123
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_PASSWORD=<control-read secret>
```
`scripts/deploy-gcp.sh` 会启用相关 API、创建 Spanner 表
`tr_entities`、部署 Cloud Run，并将当前的 GCP 信任元数据接入信任页面。
## 计费
当配置了 `TR_STRIPE_SECRET_KEY` 时，`POST /v1/billing/checkout` 会创建一个 Stripe Checkout 会话，否则返回一个确定性的本地模拟响应。Stripe webhook 使用 Checkout 元数据中的工作区 ID 以幂等方式为工作区入账。银行卡支付即时结算。ACH 支付使用 `{"payment_method":"ach"}`，仅在 Stripe 发送 `checkout.session.async_payment_succeeded` 之后才会入账；在借记处理期间完成 Checkout 绝不会授予额度。`POST /v1/billing/portal` 遵循相同的 Stripe 或模拟模式进行计费管理。
对于稳定币结账，请发送 `{"payment_method":"stablecoin"}`。当 `TR_STABLECOIN_CHECKOUT_ENABLED=true` 时，Checkout 会话会使用 Stripe 的 `crypto` 支付方式创建，并且仍会通过已签名的 `checkout.session.completed` webhook 为工作区入账。
ACH 使用 Stripe Checkout 的 `us_bank_account` 支付方式。默认处理费率为 0.8%，上限为 $5，可通过 `TR_STRIPE_ACH_FEE_BASIS_POINTS`、`TR_STRIPE_ACH_FEE_FIXED_CENTS` 和 `TR_STRIPE_ACH_FEE_MAX_CENTS` 覆盖。已保存银行卡的自动充值仍然仅支持银行卡。
