API 中转站日志审计功能怎么搭：从 TraceID 留痕到账单口径一致的落地顺序

一个 API 中转站跑起来不难，难的是跑起来之后还能说清楚每一次调用。上游接了多家模型，下游把 Key 分给不同团队甚至不同客户，一旦出现超时、扣费争议或异常调用，运维需要在不翻代码的前提下回答三个问题：谁调的、调了什么、为什么失败。日志审计功能就是把这三个问题变成可查询的记录，它不是上线之后再补的装饰，而是中转网关的基础设施。

采集范围要先定清楚。一条合格的调用日志至少应包含请求 ID、时间戳（统一用 UTC）、租户与子 Key 标识、请求模型名与实际路由到的上游、输入与输出 token 数、首字延迟与总耗时、HTTP 状态码、上游返回的错误码、重试次数，以及是否为流式请求。少一项，排查时就要多绕一圈；尤其是实际落点的上游，在多模型路由场景下请求模型名往往只是别名，只记别名不记落点，故障归因会直接断档。

贯穿全链路的请求标识值得单独强调。网关入口生成一个 TraceID，透传给上游、写入响应头、同时落进日志，用户报障时报出这串字符就能定位到具体那一次调用，而不必靠时间戳加 Key 去猜。对同时接入多家上游的中转站，TraceID 还应在中转层做一次映射，把上游返回的请求 ID 一并存下，便于拿着对方 ID 去其工单系统核对，省去反复沟通。

流式响应的记录是容易被低估的部分。SSE 连接边生成边返回，日志写入时机不能放在响应头发出的瞬间，而要等流结束后再补齐用量字段。如果上游只在流末尾返回用量，取到即可；如果上游根本不返回，只能按分片数或字符数估算，此时务必在日志里标注这是估算值，避免它被当成账单依据，造成前后端数字对不上。

内容要不要落库，需要在设计阶段就做决定。把 prompt 与 completion 原文完整保存，检索体验最好，但数据面暴露风险同步放大；只存元数据则安全，代价是复杂问题难以复现。折中做法是按租户配置：默认只记录元数据，需要排查时由具备权限的账号临时开启原文记录，并设置自动关闭时间。手机号、证件号、卡号这类字段应在写入前用正则脱敏。

存储要分层，不然日志表会以肉眼可见的速度膨胀。热数据放在支持高并发检索的库中，保留七到三十天，满足日常排障；超过窗口的记录转入对象存储做冷归档，按需加载。索引别贪多，把租户、Key、模型、状态码、时间这几个高频筛选字段建好即可，全文索引会显著抬高写入成本。写入建议异步化，用消息队列削峰，避免日志拖慢主链路。

日志只有被消费才有价值。基于日志可以设置的告警包括：单 Key 错误率越过阈值、某个模型在短时间内失败集中、同一账号调用量陡增、出现大量鉴权失败、余额低于预设水位。触发后除了通知，还应当支持自动动作，例如临时禁用可疑 Key、把流量切到备用上游。这一层做得越顺，值班人员的介入就越晚，用户感知到的可用性反而越高。

日志与账单必须共用一套计量口径。同一个 token 数，日志里按上游返回统计、账单里按网关估算，两边必然打架。做法是把用量计算收敛到一处：网关在记录日志的同时生成计费事件，账单由这些事件汇总而来，而不是另走一条链路。时间归属也要统一，跨零点的长请求按开始时间还是结束时间计费，规则要在文档里写明，并保证所有报表口径一致。

从选型角度看，海外聚合平台 OpenRouter 在模型覆盖面上有明显优势，统一接口让多厂商接入省去不少对接工作；国内团队使用时，结算方式与账单呈现往往需要额外花点心思。快米兔 API 采用 OpenAI 兼容方式接入，注册送 5 元测试金、按量计费，试用门槛较低，团队可以在小规模阶段先验证调用记录与账单能否对得上，再决定是否扩大接入范围。

落地顺序建议按先记录、再检索、后告警推进。第一步保证字段齐全且写入不丢，哪怕暂时只有一张表和简单的查询页面；第二步做 TraceID 检索与按租户过滤，让排障从翻表变成查一条记录；第三步接入告警与自动化动作；最后再考虑长周期归档与合规留存。反过来先堆告警、日志字段却缺三少四，只会制造噪音，让真正的问题淹没在误报里。

几个反复出现的坑值得提前避开：只记录成功请求，而失败与超时恰恰最需要留痕；日志里存了 Key 明文，等于把凭据又抄了一份；时间戳混用本地时区与 UTC，跨团队对账时争论不休；重试不单独记录，一次用户请求在日志里变成三条，用量统计随之虚高。这些细节在功能搭建阶段确认一遍，比上线之后返工便宜得多。