# CHANGELOG ## 2026-10-23 · 按建议落地:WAF 自愈 / 存活监控 / 恢复演练 / 指标口径(2.9.15 → 2.9.16) 老板:「剩下的可选项有啥好的建议吗」→「按你的建议来」。 ### ① WAF 白名单自愈(防故障复发) `^/v1/` 的 URL 白名单是手工改文件加的 —— 面板保存一次 WAF 设置就可能被覆盖, 客户会立刻又开始 403(真实工单复发过)。新增 `waf-whitelist-guard.sh` + **每小时 timer**: 规则不在就原子补回 + reload,幂等、静默(规则在时零输出)。 ### ② 接口存活监控(补最大盲区) 每日巡检此前只看「进程在不在」—— 进程活着但接口 500 / EO 回源断了,报告依然全绿。 新增 `uptime-check.sh`(接入每日报告):本机 `/health`、公网 api/blog/`/v1/models`/管理台, 以及 4 台的关键服务(x-ui / 1Panel+容器 / 容器数)。异常项进「需要关注」。 ### ③ 备份恢复演练(备份不验证等于没有) 新增 `backup-restore-drill.sh`(接入每日报告):解包最新备份 → 校验 SQLite integrity 与行数、 users/sessions/history/feedback 可解析、备份包权限 600。实测通过。 ### ④ `/metrics?days=N` + 指标页口径切换 - 后端:`/metrics` 新增 `days` 参数(0=保留期内全部、1=今天、7、30…),响应里带 `days`。 - 前端:指标页顶部加「今天 / 近 7 天 / 近 30 天 / 全部」切换。 ### ⑤ 体检文档留痕 新增 `docs/project-audit-2026-10-23.md`:已修项、已落地项、**评估后决定不做的项及理由**、 体检通过项、已知取舍。 **明确不做**:CSP 去 `unsafe-eval`(vue-i18n JIT 依赖,去掉会打断全部翻译)、 FTS5(当前 400 行无感)、echarts 按需引入(收益 < 风险)。 ## 2026-10-23 · 按体检建议落地:每日备份 + 每人 QPS + 库体积上限(2.9.14 → 2.9.15) 老板:「按你的建议做,全部做」。 ### ① 应用数据每日备份(新增) 此前每日任务只做「进程巡检」,**完全没备份网关数据**(账号/会话/历史/反馈/调用日志)。 - 新增 `<运维脚本目录>/backup-app-data.sh`: - `calllog.db` 用 **`VACUUM INTO` 做一致性快照**(不锁业务读写,比 `cp` 安全) - 账号/会话/历史/反馈/agents.yaml/gateway.yaml/`.env` 一并打包 - 打包 → `<备份目录>/app-data-YYYY-MM-DD.tar.gz`,权限 600,**保留 14 份** - 新增 systemd 定时器 `dsh-gateway-backup.timer`:**每天 03:30**(在 03:00 巡检之后); 实测触发 `status=0/SUCCESS`,首份备份 6.7 MB。 ### ② 每人 QPS 限流(从「不限」改为 20/s) - `data/gateway.yaml`:`server.rate_limit_rps: null` → **20**(按账号分桶,桶容量 40) - 实测:120 个并发请求 → **65 个 400(放行)+ 55 个 429(限流)**;3 秒后单请求恢复 200。 - 说明:**串行**请求触发不了(每次耗时 >50ms,令牌边用边满)—— 这是令牌桶的正常特性, 它防的是"瞬间并发打爆额度",不是限制日常速度。 - 供应商级限流(如 Dots AI 的 1 rps)保持不变,两者取更严的。 ### ③ 调用日志库体积上限 + 定期 VACUUM 「内容不截断」后单条可达 MB 级(库里已有一条 **1.4 MB** 的 prompt),光靠 90 天保留兜不住体积。 - 新增 `CALLLOG_MAX_BYTES`(默认 **2 GiB**):有效数据超限时**从最旧开始精确删除**, 删到上限的 80% 停手(按平均行大小算出要删几条,不再固定批量以免删过头)。 - 新增按需 `VACUUM`:空闲页占比 > 25% 时回收(每天最多一次;体积收紧后强制回收一次)。 - **踩了两个坑**:① 用文件大小判断是否超标 → 删光了也不降(DELETE 只是把页挂到 freelist), 必须看 `(page_count − freelist) × page_size`;② WAL 模式下 VACUUM 的产物先进 `-wal`, 必须 `PRAGMA wal_checkpoint(TRUNCATE)` 才会让主库文件真正变小。 - 实测:11.8 MB / 300 行 → 收紧到 4 MB 目标 → **删 220 行、剩 80 行、文件降到 3.2 MB**。 ### 更正上一轮体检的一处误判 「sessions.json 明文存 token」**是我看错了** —— `app/sessions.py` 早就只存 `sha256("sess:" + token)`(盘上永远不出现可直接使用的凭证),无需改动。 ## 2026-10-23 · 代码体检:修 7 个测试失败 + 测试隔离(2.9.13 → 2.9.14) 老板:「检查 ai 网关项目,看下有什么问题或者可以优化的点」→ 体检中发现测试套件跑不起来/有回归。 ### 发现并修复 | 问题 | 处理 | |---|---| | **pytest 未安装**,`tests/` 里 6197 行 / 225 个用例根本跑不了 | 装到 venv,新增 `requirements-dev.txt` | | **测试直接读写生产库**(`data/calllog.db`、`data/users.json`)| 新增 `tests/conftest.py`:导出 `CALLLOG_DB` 到临时目录 + 自动打开库(TestClient 不走 lifespan)| | **4 个用例断言内存版 `/logs`**(2.9.6 改读库后失效)→ 我引入的回归 | 改为断言前 `calllog.store.flush()`;「只看自己」用例改为往库里塞记录,并改用 `/logs/calls` 断言管理员视角 | | **3 处夹具引用 `grok-4.6`**(模型清单同步后已下线)| 改为 `grok-4.7` | | `/logs` 的库映射**缺 `video_id`** | `api_calls` 增 `video_id` 列(自动迁移),读写与查询都带上 | | 测试不幂等(失败会残留 `bob2` 账号)| 用例开头先删 | **结果:225/225 全部通过**(此前 218/225)。 ## 2026-10-23 · 消灭最后两处内存态:视频回调任务落库 + /logs 改读库(2.9.12 → 2.9.13) 老板:「看下项目的数据还有什么数据是放在内存重启就没了的吗」→ 盘点后「都做」。 盘点结论:日志/账单/配置/会话/资产都已落盘,剩两处仍是内存态: ### ① 待回调的视频任务(唯一有业务影响的) `callback_url` 异步通知原先只挂在 `_bg_tasks` 里 —— **进程重启 = 回调永远不会触发**。 - 新表 `video_jobs`:`video_id / provider / model / callback_url / rid / account / created / status / wait_timeout / last_error / done_at`。 - **先落库再派生任务**;任务结束(成功/失败)`finish_job()` 标记。 - **启动续跑**:`lifespan` 里读 `pending_jobs()`(默认只续 6 小时内的), 按当前配置重建任务;provider 已不存在则标记 failed;太老的标记 expired。 - 完成超过 7 天的任务记录由清理任务删掉。 - 实测:登记一个待回调任务 → 重启 → 日志/库状态变为 `done`(任务被接回来了)。 ### ② `/logs` 端点(遗留的内存环形缓冲) 前端早已改走 `/logs/recent`,但 `/logs` 还读内存 —— 重启后为空。 现在抽了公共函数 `_recent_entries()`,`/logs` 与 `/logs/recent` **同源读库**, `/logs` 的权限口径不变(只看自己的)。顺手删掉不再使用的 `_logs_for_account()`。 ### 剩下的内存态(评估后**不需要**落盘) | 数据 | 为什么不用落盘 | |---|---| | 熔断器状态 | 重启重置成 closed 是**安全的默认**(宁可多打一次也不要一直熔断)| | 限流令牌桶 | 重启重置只会短暂放宽,不影响正确性 | | 鉴权失败计数 | 同上 | | `_metrics` 内存副本 | 展示已全部读库,只剩 `uptime_seconds`/`in_flight` 这类实时值 | | 在途请求临时缓存 | 请求级生命周期,本来就不该跨重启 | ## 2026-10-23 · 调用日志详情彻底不截断(2.9.11 → 2.9.12) 老板:「调用日志的详情内容都不要截断记录,都要显示完整的,像提示词、回复这些」。 上一轮(2.9.2)把上限提到 128KiB / 256KiB,但**真实业务会超** —— 代码上下文的提示词 上百万字符很常见(实测客户有 8.6 万 token ≈ 300KB 的请求),仍会被截断。本轮彻底放开: | 环节 | 之前 | 现在 | |---|---|---| | 请求体捕获 | 128 KiB | **4 MiB**(`CALLLOG_BODY_MAX`)| | 入库 | 256 KiB | **8 MiB**(`CALLLOG_CONTENT_MAX`)| | 内存占用控制 | 在途 128 条 | 在途 **64 条**(4MiB × 64 = 最坏 256MiB,日常远低)| **实时页的完整内容**:列表为了轻量只给前 8KB 预览(200 条 × 几百 KB 会拖垮接口), 新增 `GET /logs/entry/{id}` —— 展开某条时按需取**完整**提示词与回复: - 权限:**本人的记录**或管理员,其余 403 - 前端展开时自动调用,并显示「完整 N 字」;加载中显示进度文案 **实测**:285 KiB(292,168 字)的提示词 → 库里 292,168 字**无截断标记**、`/logs/calls/{id}` 全文返回、`/logs/entry/{id}` 全文返回。 测试记录已清理。 > 更早(2.9.2 之前)写的记录在入库时就已被截断,无法回溯。 ## 2026-10-23 · 资产卡片模型名/日期分两行 + 命中率口径说明(2.9.10 → 2.9.11) 老板:「模型名称和日期换行展示吧,不要挤一起了,然后日志的实时里为什么命中缓存率一直都是 0」。 ### ① 资产卡片:模型名与日期分两行 `{{ model }} · {{ 时间 }}` 挤一行、窄卡片里被省略号吃掉。改成两行: - 第一行:模型名(`code` 字体,超长省略 + hover 看全) - 第二行:日期/耗时(小一号、淡色) 图像与视频两个页签同时生效。 ### ② 「实时里命中率一直 0」——机制没问题,是样本问题 用 admin 自己连发 3 次**相同长提示词**(996 token)实测: | 第几次 | 输入 | 缓存命中 | 命中率 | |---|---|---|---| | 第 1 次 | 996 | 0 | **0.0%** | | 第 2 次 | 996 | 896 | **90.0%** | | 第 3 次 | 996 | 896 | **90.0%** | 而 38 / 41 token 的短测试请求永远是 0。也就是说: - **首次请求必然 0**(上游还没有可复用的前缀) - **短提示词不缓存**(几十 token 不满足上游最小缓存长度) - **前缀变了就整段失效** 另外「实时」页签按设计**只看自己的调用**(admin 也只看自己的),所以 admin 看到的多是自己那几条短测试 → 全是 0;要看真实分布请去「调用日志」页签。 为避免以后再被误读,命中率(列表列 + 实时展开 chip)都加了 hover 说明: 「首次请求、短提示词、或前缀有变化时,上游不会命中缓存,命中率为 0 属正常」。 ## 2026-10-23 · 用户管理资产卡片的文字压叠修复(2.9.9 → 2.9.10) 老板截图反馈:用户管理展开账号后,图像/视频资产的「标题 / 模型·时间 / 下载按钮」全都压叠在一起。 **根因**:`.asset-grid` 是 `display: flex` + `.asset-cell { width: 150px }` —— flex 子项默认 `flex-shrink: 1`,卡片被挤压后宽度趋近于 0,卡片内的文字与按钮就**互相压叠**。 **修复**: - 栅格改成 `display: grid; grid-template-columns: repeat(auto-fill, minmax(170px, 1fr))`, 宽度由栅格决定,不再依赖固定 px。 - `.asset-cell` 加 `min-width: 0`(grid/flex 子项溢出压叠的经典解法); 改成纵向 flex,下载按钮 `margin-top: auto` 贴底对齐。 - 缩略图 `width: 100%; aspect-ratio: 4/3`(原来是固定 150×110)。 - 元信息行 `overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 100%`。 - **顺带修「加载失败」**:部分资产的 CDN 直链带过期签名(`?UCloudPublicKey=…`), 图源本身已失效 —— 给 `el-image` 加了 `#error` 插槽,显示「链接已失效」占位, 不再是一大块刺眼的「加载失败」。 ## 2026-10-23 · 调用日志列表加「缓存命中」列(2.9.8 → 2.9.9) 老板:「调用日志的命中缓存率为什么一直都是 0」。 **先给结论:数据没坏,是列表上看不到这一列。** 缓存命中率一直只在**详情弹窗**里显示, 列表没有;而 admin 自己那几条测试请求都是 38~41 token 的短提示词,上游不会缓存 → 所以看起来"一直是 0"。真实业务的调用是命中的。 实测(同一时刻库里的 107 条带 token 记录): - **命中 62 条 / 未命中 45 条** - 命中组:最低 11.1%、**中位 83.9%**、最高 99.7% - 未命中组:输入 38 ~ 60192 token(短提示词不触发上游缓存;长提示词的前缀不一致也不命中) 改动: - 调用日志列表新增「缓存命中」列(在耗时之后):显示 `命中量 / 命中率%`, 量按 k/M 缩写,命中率按档位配色(≥50% 绿、>0 黄、0 淡显)。 - 数据直接取列表接口已返回的 `tok_cached` / `tok_prompt`,无额外查询。 ## 2026-10-23 · 视频轮询时间线落库(2.9.7 → 2.9.8) 老板:「视频任务的轮询时间线也要落库」。 轮询快照原来只存在内存(`metrics.VIDEO_POLLS`,有界 200 任务 × 500 条),重启就没了, 日志页展开视频任务时只能看到创建那条、看不到「排队 → 生成中 → 完成」的过程。 - **新表 `video_polls`**(同一 SQLite 库):`video_id / ts / status / progress / ok / error / raw`, 索引 `(video_id, ts)`。保留策略与 `api_calls` 共用(90 天一起清)。 - **写入**:`metrics.video_poll_push()` 是唯一写入点 —— 它同时写内存(保持原有行为)与库 (轮询频率低,单条 insert 足够,不排队)。 - **读取**:`_attach_polls()` 改为**优先读库**、库里没有再回落内存;`/logs/recent`(实时页签) 之前漏了调用 `_attach_polls`,一并补上。 - **实测**:模拟 3 次轮询(created/processing/completed)→ 库内 3 条 → **重启网关** → `/logs/recent` 仍返回 3 条轮询(`✅ 持久化成功`)。测试数据已清理。 ## 2026-10-23 · 用户管理里的「调用日志」页签移除(2.9.6 → 2.9.7) 老板:「admin 用户管理里面的调用日志可以去掉了」。 调用日志已有独立入口(「日志 → 调用日志」页签,支持按时间/账号/模型/成功失败/关键词筛选、 分页、CSV 导出、看完整内容),用户管理里那份是重复且简陋的(只有最近的、无筛选)。 - **前端** `Users.vue`:移除活动抽屉里的「调用日志」页签与该表格,展开后默认停在「图像」; 活动数据只再拉 `history/images` 与 `history/videos` 两个接口。 - **后端**:删除 `GET /auth/users/{username}/logs`(唯一调用方就是上面那个页签)。 资产端点 `/auth/users/{username}/history/{kind}` 保留不动。 - **i18n**:移除 `users.tabLogs`(zh / en 同步)。 - 实测:`/auth/users/chenghongchang/logs` → 404;`/history/images` → 200; `/logs/calls` → 200(admin)/ 403(member)不变。 ## 2026-10-23 · 实时日志改为读库:重启不再丢(2.9.5 → 2.9.6) 老板:「实时的日志为什么一重启就没了,也要落地可以查看」。 **原因**:「实时」页签读的是 `AccessLog` 内存环形缓冲(默认 500 条),进程一重启就清空。 但其实**每条访问记录早就在落库了**(`api_calls`),只是这个页面没去读它。 **改动**: - 新增 `GET /logs/recent?n=200`:从 `api_calls` 取最近 N 条,字段形状与原来 `/logs` 的条目 完全一致(body/response/tokens/ok/stream/model/status/latency…),前端**零渲染改动**。 - `/logs/recent` 权限口径与 `/logs` 一致:**只看自己的**(admin 也只看自己的;看全站走 `/logs/calls`)。 - 前端「实时」页签改调 `/logs/recent?n=200`,保留 5 秒自动刷新。 - **顺带修**:`query()` 的 SELECT 列表漏了 `tok_prompt/tok_completion/tok_cached/tok_reasoning` 四列 → 实时页的 token 显示为 0(库里其实有值)。补上后正常。 **实测**:发 2 条调用 → **重启网关** → 实时页仍是 9 条,含那 2 条(「重启持久化验证 第1/2条」); token 正常(输入 41 / 输出 12 / 推理 12);成员视角只看到自己的 89 条(全为 chenghongchang)。 **仍有的小差异**:视频轮询时间线(`polls`)只在内存里合成,重启后不显示(视频任务本身的记录仍在)。 ## 2026-10-23 · 修复:流式请求的「请求内容」为空(2.9.4 → 2.9.5) 老板:「为什么请求内容看不到,是空的」。 **根因**:`_flush_calllog()`(请求中间件收尾)里对请求体用的是 `BODY_BY_RID.pop(rid)` —— 一次性取走。但**流式请求**的访问日志条目要等 SSE 真正发完才由 `AccessLog.add()` 产生, 而中间件收尾在 SSE **开始之前**就跑完了 → 请求体被提前 pop 掉,等条目生成时已经没了。 **表现**:非流式请求内容正常;**所有流式请求**的「请求内容」在实时日志与调用日志里都是空。 (`tokens` 不受影响,它走的是 `TOKENS_BY_RID` 侧信道,与 body 无关。) **修复**:流式时只 `peek` 不 `pop`(把请求体留给 `AccessLog.add()` 取走);非流式仍直接 pop (早失败的 synthetic 条目不会再产生条目,必须在这里 pop,否则 `BODY_BY_RID` 会泄漏)。 **实测**:修复后流式条目 `body` 长度 119 字、`tokens` 同时存在;调用日志里该条 `prompt_text` 正常显示 `流式请求内容修复验证 ABCDEF`。 > 修复前已产生的流式记录内容无法回溯(当时就没落库)。 ## 2026-10-23 · 实时日志展开显示单笔 token 用量与缓存命中率(2.9.3 → 2.9.4) 老板:「日志里的实时点开后可以查看单笔使用的 token 量和命中缓存多少、命中率多少」。 - **数据链路**:token 原本只进了调用日志的落库路径(`note_tokens` 侧信道 → `_row` pop)。 实时日志(内存环形缓冲)拿不到 —— 新增 `calllog.peek_tokens(rid)`(**只读不消耗**), `AccessLog.add()` 把它挂到条目的 `tokens` 字段上。落库那份仍由 `_row()` 负责 pop 清空, 两条路互不抢数据。 - **实时日志页**(日志 → 实时 → 点开任意一条)新增一块「Token 用量」: 输入 / 输出 / 缓存命中 / 推理,外加**缓存命中率**(`cached ÷ prompt`,保留一位小数)。 命中率按档位配色:≥50% 绿、>0 黄、0 淡显。 - **调用日志详情弹窗**也补了同样一行 token(数据来自库里的 `tok_*` 列),两处口径一致。 - 实测:同一把 key 连发 3 次相同请求 → 实时日志三条都带 `输入 73 / 输出 20 / 缓存命中 0 / 推理 20`;命中率 0%(该次上游未报缓存命中,字段本身完整)。 ## 2026-10-23 · 详情弹窗固定高度,内容区内部滚动(2.9.2 → 2.9.3) 老板:「点开详情的弹出框高度固定下,不要出现滚动条了,内容高度固定滚动条」。 - 弹窗整体固定高度 `min(78vh, 860px)`(手机上 86vh),**弹窗自身 `overflow: hidden`** —— 不再随内容长短撑高、也就不会出现整页/整框的滚动条。 - 弹窗体内的「内容 / 提示词 / 回复」三个 `
` 用 flex 等分剩余高度,
  **各自 `overflow: auto`** —— 滚动条只出现在内容区内部。
- 原来的 `max-height: 460px` 改为 `max-height: none`(交给 flex 分配),`min-height: 90px` 兜底。
- 实现要点:el-dialog 会 **teleport 到 body**,`scoped` 样式命中不了它 —— 
  所以这段用**非 scoped** 的全局样式块,选择器统一挂在 `.calllog-dlg` 下,避免污染其它页面。

## 2026-10-23 · 详情不再截断记录(2.9.1 → 2.9.2)

老板:「点击进去看详情内容的时候不要截断记录」。

截断原本发生在**三个环节**,逐个拆掉:

| 环节 | 原来 | 现在 |
|---|---|---|
| 请求体捕获 | `raw[:2000]`(后提到 8000)| `raw[:_CONTENT_MAX]`,默认 **128 KiB**(≈32k tokens)|
| 回复文本 | `_logsafe(..., 8000)` | 新增 `_content()`:上限 **128 KiB**,且**保留换行/制表** |
| 入库 | `CALLLOG_CONTENT_MAX=8000` | 默认 **262144(256 KiB)**,实际等于不截断 |

**为什么换掉 `_logsafe`**:它是给单行文本日志用的(把 `\n` 压成 `?` 防日志行伪造),
用在调用日志上会把多行提示词全压成一行 `?`,详情根本没法看。新加的 `_content()`
只剥 NUL 等不可见控制字符,**换行与制表原样保留**。

- 详情接口新增 `prompt_full`:**完整提取出的输入内容**(保留换行排版),前端详情页
  分两块展示 ——「内容(完整,保留换行)」+「原始请求体 JSON」(两者都不截断)。
- 列表那列仍是单行预览(240 字),不因为详情放开而变重。
- `BODY_BY_RID` 有界保留 128 条(宽上限下防止内存膨胀)。

**实测**:1499 行 / 46860 字符的提示词 → 详情 `prompt_full` 46860 字符 1499 行、
原始 JSON 48454 字符,**均无截断标记**。

> 注意:本次改动只对**新产生**的记录生效;之前的记录在入库时就已被截断,无法回溯。

## 2026-10-23 · 调用日志列表加「内容」列(2.9.0 → 2.9.1)

老板:「列表的模型后面加一个字段,显示请求体的 content 内容」。

- 新增 `prompt_preview()`:从请求体 JSON 里抽出**用户实际说的话**(不是整包 JSON)——
  兼容 OpenAI chat / responses(`messages[-1].content`、`input` 字符串或数组)与
  Anthropic messages(`content` 字符串或多段 text parts);非 JSON 时退回原文。
- `GET /logs/calls` 现在每行都返回 `prompt_text`(单行、压空白、截 240 字),
  **列表不再吐原文 `prompt`**(几千字整包会拖慢列表);`content=1` 时仍给完整原文。
- `GET /logs/calls/{id}` 也带 `prompt_text`,详情弹窗第一屏就能看到用户说了什么。
- 前端:模型列后面新增「内容」列(超长省略 + 悬停看全文);详情弹窗增加「内容」块。

## 2026-10-23 · 指标改由数据库提供(重启不再清零)+ 月度用量导出(2.8.0 → 2.9.0)

老板:「全做」—— 指上一条列出的两项:① Dashboard 统计改从数据库读;② 按账号月度用量导出。

### ① 指标数据源:内存 → SQLite
- 新增 `_usage_snapshot()`:**调用数 / 供应商分布 / token / 耗时(含 p50/p95)** 全部改为从
  `api_calls` 聚合(保留期内 90 天),**进程重启不再清零**;**运行时长 / 在途请求 / 熔断状态**
  仍是进程内实时值。库不可用时自动回落到内存态(行为与之前一致)。
- 影响端点:`GET /metrics`、`GET /metrics/prometheus`、`GET /health` 的 `models` 字段。
- **口径变化(重要)**:Dashboard / 指标页看到的数字从「本次进程启动以来」变成「最近 90 天累计」,
  所以数字会一次变大。要"本次启动以来"的口径需要另加参数,目前没有。
- 成员视角不变:仍只聚合自己的账号(`account` 过滤)。

### ② token 也落库了
此前 `api_calls` 没存 token(方案里列了但首版没实现),导致指标切库后 token 只能是 0。
本轮补齐:
- 表加 4 列 `tok_prompt / tok_completion / tok_cached / tok_reasoning`,**老库自动 ALTER 迁移**。
- 用 **rid contextvar + token 侧信道** 把两处接起来:`_record_usage_metrics()` 只知道 token、
  不知道 rid;中间件只知道 rid、不知道 token。现在中间件 `RID.set(rid)`,
  记账时 `calllog.note_tokens(RID.get(), …)`,落库时按 rid 取走并清空。
- 直传流式(`_UsageScanner`)那条路径也补了。

### ③ 月度用量导出
- `GET /logs/usage/monthly?month=YYYY-MM`:按账号聚合调用数 / 成功 / 失败 / 平均耗时 / 涉及模型数(仅管理员)。
- `GET /logs/usage/monthly/export?month=YYYY-MM`:CSV(UTF-8 BOM,Excel 直接打开,含失败率)。
- 前端:调用日志页加「月份选择 + 月度用量」按钮 → 弹窗显示按账号的表格 + 导出 CSV。

### ④ 顺手修
- 模型统计排除「无模型行」(匿名 401 的早失败补记)—— 否则 Dashboard 上会出现一个 `?` 模型。

## 2026-10-23 · 调用日志落地(SQLite / 90 天 / 仅管理员可查全部)(2.7.3 → 2.8.0)

老板:「ai网关项目,现在我想把调用日志落地,有什么方案」→ 方案确认后:「1,要记 / 2,90天 /
3,要前端查询界面,然后这个查询界面集成在日志菜单里,只有管理员有这个权限查看全部人的日志」。

### 后端:`app/calllog.py`(SQLite,零新依赖)
- 表 `api_calls` **21 列**:时间、rid、账号、Key 前 8 位、类型、方法、路径、模型、实际模型、
  供应商、是否流式、成功、状态码、耗时、IP、UA、**提示词**、**回复**、网关版本。
- **异步批量写**:`AccessLog.add()` → 内存队列 → 后台 task 每 1 秒或攒满 200 条 `executemany` 提交;
  队列满(默认 1 万条)即丢弃并计数,**绝不反压请求**;进程退出前 flush。
- **双向握手**(本轮最关键的设计):一条日志的两半来自不同位置 —— 访问日志条目(`AccessLog.add`)
  和响应元数据(中间件收尾,含状态码/耗时/IP/UA)。两半先后顺序不确定:
  非流式是「条目先、元数据后」,**流式是「元数据先、条目后」**(SSE 真正发完才 add)。
  所以两边都先暂存,谁后到谁拼成一行落库。
- **早失败也记**:未知模型 400、鉴权 401/403、限流 429 这类请求走不到 `AccessLog.add`,
  中间件用请求体补一条(含模型名与提示词),否则日志里只剩一行"400、无模型",排查时没有信息量。
- **失败也记 Key 前缀**:401 时 `request.state.credential` 是空的,但恰恰这时最需要知道
  客户端拿的是哪把 Key —— 记前 8 位即可对账(2026-10-23 的真实工单就是靠这个抓到
  「客户端在发 `wjd-5Da_…`,而库里他的有效 Key 是 `wjd-15zs…`」)。
- 保留 **90 天**:启动时清理 + 每 6 小时清理一次;`CALLLOG_RETENTION_DAYS` 可调。
- 隐私:**API Key 只存前 8 位**;提示词/回复按 `CALLLOG_CONTENT_MAX`(默认 8000 字)截断;
  库文件权限 600。IP 存完整地址(仅管理员可见,便于与 WAF/防火墙日志对账)。

### 接口(新增 4 个,全部**仅管理员**)
| 端点 | 用途 |
|---|---|
| `GET /logs/calls` | 分页 + 筛选(时间段/账号/模型/成功失败/状态码/类型/关键词),`content=1` 时带内容 |
| `GET /logs/calls/stats` | 按天、按模型、按账号、按状态码聚合 + 库大小/写入/丢弃计数 |
| `GET /logs/calls/{id}` | 单条详情(含完整提示词与回复)|
| `GET /logs/calls/export` | CSV 导出(最多 5 万条,UTF-8 BOM,Excel 直接打开)|

成员访问以上端点一律 **403**(`_require_admin_logs`)。

### 前端:集成在「日志」菜单
- 日志页顶部新增两个页签:**实时**(原有内存环形缓冲)/ **调用日志**(仅管理员可见)。
- 新组件 `CallLogs.vue`:日期范围、账号、模型、仅成功/仅失败、关键词(内容/rid/IP/UA)筛选;
  列表显示时间/账号/模型/耗时/状态/流式/UA;点击行弹出详情看**完整提示词与回复**;CSV 导出。

### 2026-10-23 补丁:翻译键位置 + 内容上限
- **修**:`calllogs.*` 的 i18n 段首次插入时被放进了 `upload` 段内部(嵌套层级错),
  导致新面板全部显示原始键名(`calllogs.title` 之类)。已移为**顶层键**(`logs` 之后),
  并复核 zh/en 两份文件的顶层键数量与层级一致。
- **提上限**:请求体摘要 `raw[:2000]` → `8000`,回复文本 `_logsafe(..., 2000)` → `8000`(5 处)。
  实测 6000 字的提示词已能完整落库(此前会被截在 2000)。

### 现状说明
- `/metrics` 仍是内存态(重启清零),本次没动它;**调用日志是持久化的**,
  需要历史统计时可以基于 `api_calls` 做(二期可把 Dashboard 数据源切过来)。

## 2026-10-22 · 成员只看自己的用量 + AI 接口不再被 WAF 误杀(2.7.2 → 2.7.3)

老板:「改,替换重启,更新文档,推送 gitea」;随后补充「成员在首页是要看到自己调用的次数统计」。

起因是一个真实工单:成员 `chenghongchang` 反馈「拿 apikey 请求 403」。排查结论是**两层问题**:

### 1. `/health` 把全站用量给了成员(安全)
`/health` 只要带**任意有效 Bearer**(含 member 的 API Key)就返回
**全局 `tokens` 总量、各模型的全局调用量/失败率(`models`)、供应商熔断状态(`circuit` / `media_circuit`)**。

- 现在按角色分流:非 admin 只返回**运行态** —— `status` / `version` / `uptime_seconds` /
  `in_flight` / `in_flight_peak` / `providers`(仅 `name`、`api_key_set`、`models` 数量)。
- **全员** token 总量、模型级全局统计、熔断状态**仅管理员**可见。
- 前端没有用到被收敛的字段(Dashboard 只用 `version` / `uptime_seconds` / `in_flight` / `in_flight_peak` / `providers`),
  所以**前端零改动、无需重新构建**。

### 2. `/metrics` 明确保留按账号聚合(老板口径)
- 成员首页的「我今天调了多少次」来自 `/metrics`,因此**不收成仅管理员**;
  按账号聚合的逻辑保持原样(`_metrics.snapshot(request.state.account)`)。
- 实测:成员连调 2 次后自己看到 `deepseek-v4.1-flash: ok=2`,管理员看到全局 `ok=3`。

### 3. 运维侧:1Panel WAF 放行 `/v1/`
成员那台 403 的真正来源是 **1Panel WAF 检查请求体**:AI 编程客户端(WorkBuddy 等)
发出的提示词里带 `