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
This commit is contained in:
1 parent
1999b5e7ac
commit
09b79c1306
10 files changed
+1101
-4
No files matched your search
@@ -0,0 +1,84 @@
|
||||
# 调用日志落地设计(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 天清理后页空间会被复用,不会无限膨胀。
|
||||
Reference in new issue
Block a user