用量记录与错误归因

HTTP 返回成功只代表客户端拿到了结果，不代表用量、余额、统计和账号状态一定已经正确更新。

RecordUsage 输入

记录任务通常包含：

• user、API Key、group、subscription、account ID。
• requested/upstream/billing model。
• 输入、输出、缓存、图片等 usage。
• 流式/非流式和请求类型。
• 请求耗时、TTFT、状态和端点。
• 分组、用户和账号倍率快照。
• failover、cache billing 和平台元数据。

使用快照而不是稍后重新读配置，可以避免请求执行期间管理员修改倍率导致结算口径变化。

成功路径

upstream success
  → parse usage
  → calculate user/account cost
  → billing dedup
  → update balance/subscription/key/platform quota
  → insert usage log
  → update account stats
  → invalidate dashboard caches

具体操作可能在事务和缓存写 worker 中拆分，但目标是让同一请求只结算一次。

没有 usage 怎么办

某些上游错误、兼容 API 或流异常不会返回完整 usage。系统可能：

• 从流事件累计。
• 从请求/响应估算部分 Token。
• 使用 cache billing 标志。
• 记录零费用错误请求。
• 跳过不可靠结算并写错误日志。

运营者应单独监控“成功请求但 usage 缺失”，否则收入和成本都会偏差。

Worker 提交模式

模式	含义
enqueued	进入有界异步队列
sync_fallback	队列满，提交方同步执行
dropped	策略允许丢弃或池已停止

默认 overflow policy 是 sync，优先保证计费。持续 sync fallback 会把数据库延迟重新带回请求尾延迟，是容量不足信号。

错误的三个来源

客户端错误

无效 Key、权限、余额、JSON、模型名或参数。这类错误不应惩罚上游账号。

本地基础设施错误

PostgreSQL、Redis、队列、协议转换或配置错误。需要归因到本地，不应伪装成上游失败。

上游错误

网络、代理、TLS、限流、账号失效、平台 5xx 或内容策略。可能触发账号冷却和 failover。

为什么要标准化端点

同一能力可能有多个别名：

• /v1/responses
• /responses
• /backend-api/codex/responses

统计会把它们归一到逻辑端点，同时保留 inbound/upstream 信息，避免仪表盘把同一类请求拆散。

错误日志应记录什么

• Request ID。
• user/API Key/group/account ID。
• inbound 与 upstream endpoint。
• 平台、模型和请求类型。
• HTTP status 与错误分类。
• 是否在 stream started 之后发生。
• failover 次数和最终账号。
• 经过脱敏和截断的上游错误。

不应记录完整 Authorization、Cookie、refresh token 或用户敏感 prompt。

错误透传规则

管理员可以配置特定错误是否原样或按规则透传。使用场景是保留客户端需要识别的上游 code，但风险包括：

• 暴露上游供应商和内部信息。
• 返回与下游协议不兼容的 JSON。
• 让客户端依赖不稳定的上游文本。

规则应按平台、状态码和错误类型收窄，而不是全局透传所有响应。

Stream Started 后的错误

HTTP header 已发出后不能再改成 500。处理方式取决于协议：

• 发送 Anthropic error event。
• 发送 Responses failed/completed event。
• 发送 Chat Completion error chunk。
• 无合法事件时关闭连接。

客户端日志中的“unexpected EOF”可能只是最终表象，要用 Request ID 查看服务端真正的上游错误。

运维查询顺序

1. 在用户使用记录找到请求。
2. 打开错误详情，看标准化分类和账号。
3. 在管理员 Ops 查看同期错误率和上游分布。
4. 查看账号状态、限流窗口和最近测试。
5. 查看应用日志中的同一 Request ID。
6. 必要时检查代理和上游原始响应。

对账指标

每天至少比较：

• HTTP 成功请求数 vs 成功 usage logs。
• 用户费用总和 vs 余额/订阅变动。
• account cost vs 上游后台用量。
• worker submitted/completed/failed/dropped。
• billing dedup 命中和冲突。
• pricing not found 与零费用成功请求。

数据保留

Usage Log、错误日志、小时/日聚合和 payment audit 的保留需求不同：

• 原始请求数据体积最大，保留期可以较短。
• 聚合指标用于长期趋势，可以更久。
• 支付与余额审计要满足财务和合规要求。
• 删除原始数据前要确认争议处理和对账已经完成。

项目提供 usage cleanup 与 ops cleanup，但生产环境要根据业务要求显式配置，不要盲目沿用默认天数。