AI API 正式上线前检查清单：环境变量、限流、日志与成本告警（2026）

开发环境里能成功调用 API，只说明“请求通了”，不代表可以直接承受真实用户流量。上线前建议按密钥、网络、错误处理、观测和成本五个方面逐项检查。

1. 密钥和环境变量

• API Key 只放在服务端环境变量，不写入前端代码、提交记录和截图；
• 为开发、测试、生产分别创建密钥，发现泄露时可以只撤销一把；
• 启动时检查变量是否存在，但错误日志不要打印变量值；
• 如果服务商支持权限范围，生产 Key 只保留调用所需权限；
• 轮换密钥时先配置新 Key，再撤销旧 Key，避免发布过程产生空窗。

2. 给每个请求设置边界

至少设置三类限制：连接超时、读取超时和最大输出 Token。没有上限的请求可能长期占用连接，也会让一次提示词失控地消耗余额。

建议同时生成自己的 request id，并把它传入日志。用户看到错误时，你可以通过 request id 找到对应的服务商响应，而不必记录完整对话内容。

3. 429 和 5xx 的处理规则

429 表示限流，不要立即高频重试。读取服务商返回的 Retry-After，或使用指数退避加随机抖动。502、503、504 可以在尚未收到正文时重试 1-2 次；如果已经收到流式内容，不能把整条请求静默重放。

重试必须设置总预算，例如单个用户请求最多 30 秒、最多 2 次。超过预算后返回清晰的错误信息，并提供切换备用服务商的入口。

4. 日志脱敏和告警

日志建议保留：request id、模型 ID、HTTP 状态码、首字节延迟、总耗时、输入输出 Token（如果服务商返回）。应删除或打码：API Key、Authorization 头、完整提示词、用户上传的图片和个人信息。

设置三类告警：5 分钟错误率、429 比例、单日费用。告警阈值不要照搬别人的数字，先观察一周基线，再设置“异常高于基线 2-3 倍”的阈值。

5. 成本控制的最小实现

给每个用户或项目设置月度预算，在数据库中记录 provider、model、input_tokens、output_tokens、amount 和 created_at。前端展示余额只能作为提示，真正的拦截必须在服务端完成。

无法取得 Token 用量时，不要假装精确计费。可以按请求次数或字符数做保守估算，并明确标注“估算值”，待服务商账单返回后再校正。

6. 健康检查和回滚

健康检查不要发送真实用户内容，使用最短提示词和低成本模型，周期也不要过于频繁。发布新配置前保留上一版 Base URL、模型和超时参数，出现连续错误时可以一键回滚。

7. 上线前最后一轮验收

• 新用户、余额不足、无效 Key、429、超时、上游 5xx 都有可读提示；
• 流式和非流式各成功测试一次；
• 重启应用后环境变量仍能正确加载；
• 日志中搜索不到完整 API Key；
• 超预算请求会在服务端被拒绝；
• 备用服务商切换后，模型 ID 和计费单位没有沿用错误配置。

先把这份清单变成发布前的固定流程，再逐步增加自动化监控。对小项目来说，能快速发现错误、控制损失，比一开始搭建复杂平台更重要。