请求故障定位

保留时间、公开模型、HTTP 状态和 x-litellm-call-id。先找到对应请求日志，再修改配置。

诊断请求

此请求会调用模型，可能产生供应商费用。

curl -i "$XHUB_BASE_URL/v1/chat/completions"   -H "Authorization: Bearer $XHUB_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"company-chat","messages":[{"role":"user","content":"Reply with ready."}]}'

分享证据前移除凭据、个人信息及签名媒体 URL。不要删除生产数据来修复测试。

源码与验证

计费入口 · 运行边界

go test ./internal/gateway/usage -count=1

独立磁盘用量队列

Compose 为每个网关挂载 xhub-usage-spool:/var/lib/xhub/usage-spool，并通过 XHUB_USAGE_SPOOL_DIR 启用独立磁盘账单快照。收到最终用量后，网关先保存完整 UsageRecord（含预占 ID、冻结费率和原有日志设置允许保存的正文），执行文件 fsync、原子改名和目录 fsync，然后同步提交 PostgreSQL。只有数据库确认成功 才删除文件。PG 完全断连、无 Redis 时，重启仍可恢复；恢复只结算账单，不重试上游。 原有 usage_pending 和旧 Redis 队列继续恢复，新请求启用磁盘队列后不再重复入 Redis。

这是同步持久化路径：每次调用增加磁盘同步和数据库提交延迟，以减少最终账单仅留在 内存中的窗口。吞吐量取决于持久盘与数据库；不要把该目录放在容器可写层、临时目录或 多个实例共享的卷上。单目录持有进程排他锁，各副本必须各有持久卷。停机或迁移时保留 整个目录，不能仅迁移数据库；确认队列清空后再删除旧卷。

容量可用以下启动环境变量调整（正整数）：

默认字节配置最多容纳 64 个同时在途预留，有待结算文件时更少。准入在调用上游前验证 目录写入和同步，目录/文件权限分别为 0700/0600。容量满、不可写或隔离证据存在时， 新调用返回 503 billing_storage_unavailable，响应头 X-XHub-Usage-Persistence: unavailable。已有未落库费用时搜索软预算调用返回 503 billing_storage_pending，防止用旧余额继续放行；硬额度原有预占继续保留。 恢复成功前用量页只包含已入账部分，不能把显示值当作全部已产生费用。

文件含版本和 SHA-256 内容校验，损坏/版本不符/同调用不同快照进入 quarantine/， 不自动删除。运维应保留目录并核对证据、恢复备份或核销，不能清空队列“解决”故障。 重复恢复依靠数据库调用 ID、完整快照 SHA-256 指纹和预占核销规则去重； 数据库同 ID 存在不同待结算载荷或已提交指纹时拒绝确认，保留磁盘证据。启动幂等补齐 usage_fingerprint 字段；旧账单不回填伪造指纹，无指纹历史不能被严格恢复自动确认， 需核对后通过预占核销处理。结算冲突保留原载荷、记录错误，单条 失败至少间隔 30 秒重试且不阻塞其他有效记录。日志只记录请求 ID/摘要文件名与错误， 不要把账单文件或用户正文贴到工单。更改配置后需重启。

边界：未设置目录的非 Compose 部署仍使用原持久化路径；需显式配置持久目录才能获得 此保证。容量预留是本队列的逻辑预留，不能防止外部进程在准入后耗尽磁盘、硬件损坏或 进程在最终用量尚未持久化前退出。单条快照超出上限不会截断，写失败仍尝试 PG/Redis； 所有介质均不可写时仅能告警并保留既有硬额度占用，不能宣称已保存实际账单。官方异步 任务的可变生命周期仍由 RecordTaskUsage 管理，不属于本次最终用量快照覆盖范围。