# CHANGELOG ## 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 等)
发出的提示词里带 `