Files
xiaoyin-gateway/docs/call-log-design.md
T
jidekin 2c53504ad4 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

85 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 调用日志落地设计(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 天清理后页空间会被复用,不会无限膨胀。