# 调用日志落地设计(2026-10-23) > 方案对比与取舍记录。实现在 `app/calllog.py`,界面在「日志」页的「调用日志」页签。 ## 为什么需要 `AccessLog` 是内存环形缓冲(默认 500 条,**重启即丢**),`/metrics` 只有聚合计数。 2026-10-22 的真实工单很说明问题:成员反馈「拿 apikey 请求 403」,最后是靠 grep 1Panel 的 WAF `access.log` 才定位 —— 网关这边**没有任何一条可查的调用记录**。调用日志要解决的就是这个。 ## 方案对比 | | **A. SQLite(采用)** | B. JSONL 文件 | C. MySQL | D. Loki/ELK | |---|---|---|---|---| | 新增依赖 | **0**(标准库)| 0 | 驱动+连接池 | 整套平台 | | 查询/聚合 | SQL ✅ | grep/jq | 强 | 最强 | | 写入风险 | 低(WAL + 单写者 + 队列)| 最低 | 中(DB 挂了影响写)| 中 | | 运维成本 | 极低(一个文件)| 极低 | 中 | 高 | | 适合 | 单机、日调用 < 50 万 | 只求能查 | 多节点统一账单 | 规模化 | 选 A:项目依赖极简(7 个包),引入 MySQL 驱动破坏基调;MySQL 容器是 Gitea 在用,混用会把 「日志」和「业务库」绑死。 ## 表结构要点 21 列,见 `app/calllog.py` 的 `SCHEMA`。索引覆盖四条最常用的查询路径: `ts`、`(account, ts)`、`(model, ts)`、`(ok, ts)`、`(status, ts)`、`rid`。 ## 三个关键设计 ### 1. 双向握手(两半日志拼起来) 一条日志由两处产生,**先后顺序不确定**: | 场景 | 先到 | 后到 | |---|---|---| | 非流式 | 访问日志条目(请求处理中途)| 响应元数据(状态码/耗时/IP/UA)| | **流式** | 响应元数据(StreamingResponse 建好就返回)| 访问日志条目(SSE 真发完才 add)| 实现上两边都先暂存(`_PEND_ENTRY` / `_PEND_META`),谁发现对方已就绪就立刻拼成一行落库; 元数据最多等 5 分钟(`sweep()` 定期丢弃),避免泄漏。 ### 2. 早失败也记 未知模型(400)、鉴权失败(401/403)、限流(429)这些请求**走不到** `AccessLog.add`。 中间件在收尾时若发现"没有条目 + `/v1/` 下 + status ≥ 400",就用请求体补一条记录, 并解析出 `model` 字段 —— 否则日志里只有一行"400、无模型",排查时没有任何信息量。 ### 3. 失败也记 Key 前缀 401 时 `request.state.credential` 是空的,但**恰恰这时最需要知道客户端拿的是哪把 Key**。 所以从 `Authorization` / `x-api-key` 里取前 8 位落库(完整 Key 绝不落盘)。 > 2026-10-23 实测:靠这个字段抓到客户一直在发 `wjd-5Da_…`,而库里他的有效 Key 是 > `wjd-15zs…` —— 用的是旧 Key,与网关无关。 ## 体量与保留 | 日调用量 | 单条约 | 90 天 | |---|---|---| | 100 次 | 400 B | ~4 MB | | 1,000 次 | 400 B | ~36 MB | | 10,000 次 | 400 B | ~360 MB | 默认保留 **90 天**(`CALLLOG_RETENTION_DAYS`),启动时 + 每 6 小时清理;`VACUUM` 未自动跑, 需要时手动执行(或等保留策略删够量后由 SQLite 复用页)。 ## 配置 | 环境变量 | 默认 | 说明 | |---|---|---| | `CALLLOG_DB` | `data/calllog.db` | 库路径 | | `CALLLOG_RETENTION_DAYS` | `90` | 保留天数 | | `CALLLOG_QUEUE_MAX` | `10000` | 内存队列上限(满了丢弃并计数)| | `CALLLOG_CONTENT_MAX` | `8000` | 提示词/回复各自截断长度 | | `CALLLOG_DISABLED` | 空 | 设为 1 可整体关闭(不影响现有行为)| ## 已知限制 - 提示词内容受上游 `BODY_BY_RID` 的 2000 字符上限约束 —— 编码类长 prompt 会被截断。 想放长需要调 `app/main.py` 里 `limit_body` 中间件的 `raw[:2000]`。 - 流式请求的 `latency_ms` 是**响应头返回的时间**(≈首字节时间),不是流的总时长。 - 没有自动 `VACUUM`;库文件会随写入增长,90 天清理后页空间会被复用,不会无限膨胀。