- app/calllog.py:SQLite 表 api_calls(21 列,含提示词与回复)+ 异步批量写 + 双向握手
(流式请求的访问日志条目比响应晚到也能落库)+ 早失败补记 + 失败也记 Key 前 8 位
- 新增 4 个仅管理员端点:/logs/calls、/logs/calls/stats、/logs/calls/{id}、/logs/calls/export
- 前端:日志页新增「实时 / 调用日志」页签,新组件 CallLogs.vue(筛选/分页/详情/CSV 导出)
- 保留 90 天;队列满丢弃计数,不反压请求;零新依赖
- docs:新增 docs/call-log-design.md(方案对比与三个关键设计)
- 版本 2.7.3 → 2.8.0
3.9 KiB
调用日志落地设计(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 天清理后页空间会被复用,不会无限膨胀。