Files
xiaoyin-gateway/docs/call-log-design.md
T
jidekin 0e52c6820f feat(calllog): 调用日志落地(SQLite / 90 天 / 管理员可查全部)
- 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
2026-10-23 10:02:07 +08:00

3.9 KiB
Raw Blame History

调用日志落地设计(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 天清理后页空间会被复用,不会无限膨胀。