Skip to content

perf(keys): API 密钥列表不再等待 30 天用量统计,并为其加覆盖索引 - #8346

Merged
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
hezhaoqian1:perf/upstream-keys-usage-index
Nov 10, 2026
Merged

Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
hezhaoqian1:perf/upstream-keys-usage-index

Conversation

@hezhaoqian1

Copy link
Copy Markdown
Contributor

Refs #5858

问题

数据量上来以后,/keys(API 密钥)页面经常一直停在表格骨架屏,等十几到三十几秒,甚至直到请求超时。

原因有两层:

  1. 前端串行等待:loadApiKeys 拿到密钥列表后,接着 await 用量统计 POST /usage/dashboard/api-keys-usage,两个都返回才把 loading 置回 false。列表本身只要几十毫秒,但表格要陪着慢的统计一起等。
  2. 统计查询需要回表:GetBatchAPIKeyUsageStats 按 api_key_id 汇总近 30 天的 usage_logs.actual_cost。现有索引里没有 actual_cost,近 30 天的每一行都要回表读取。

在一个实际部署上的测量(usage_logs 约 650 万行、10 GB,shared_buffers 2 GB):

场景 近 30 天行数 耗时
50 个 key 约 42 万 31.6 s(约 4.7 万次磁盘读)
6 个 key 约 120 万 12.8 s
2 个 key 约 330 万 浏览器侧超时

改动

  • 前端(KeysView.vue):列表返回后就渲染表格,用量列在统计返回前显示独立的加载占位,统计失败时回落为 $0.0000。切页、刷新时会通过已有的 AbortController 取消旧的统计请求。

  • 迁移 249_add_usage_logs_api_key_cost_index_notx.sql:

    CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_usage_logs_api_key_created_cost
        ON usage_logs (api_key_id, created_at) INCLUDE (actual_cost);

    加上这个索引后,统计可以走 index-only scan。写法沿用 174、226 等 usage_logs 索引迁移:在 prepareNonTransactionalMigration 里登记索引名,重试前先清理中断构建留下的 INVALID 索引。

上线后,同一部署上的实测:

场景 之前 之后
50 个 key 31.6 s 1.3 s(Parallel Index Only Scan)
6 个 key 12.8 s 0.7 s
2 个 key(约 330 万行) 超时 1.6 s
页面实际请求(缓存热) — 150–190 ms

索引大小约为行数 × 40 B(650 万行约 300 MB)。在该表上 CONCURRENTLY 构建约 70 秒,不阻塞写入。

和 #5859 的关系

#5859 用 usage_apikey_daily_rollups 预聚合解决的是同一个接口,范围更大,还包含 ops trend 和 system-logs。本 PR 是一个小而独立的修复:

测试

  • KeysView.spec.ts 新增 2 个用例:统计挂起时表格已经渲染(loading=false)且用量列显示占位;统计失败时占位消失。第一个用例在旧代码上会失败。
  • migrations/usage_log_api_key_cost_index_test.go:校验迁移内容。
  • migrations_runner_api_key_cost_index_test.go:校验存在 INVALID 索引时,重试会先 DROP 再 CREATE。
  • 本地已通过:go build ./...、相关 go test(含 -tags=unit)、KeysView.spec.ts 28/28、ESLint、vue-tsc --noEmit。

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA. ✅
Posted by the CLA Assistant Lite bot.

@hezhaoqian1

Copy link
Copy Markdown
Contributor Author

I have read the CLA Document and I hereby sign the CLA

/keys 页面要等密钥列表和每个 key 的用量统计都返回,才撤掉表格骨架屏。
用量统计(POST /usage/dashboard/api-keys-usage)按 api_key_id 汇总近 30 天的
usage_logs.actual_cost。数据量大时,要逐行回表读取几十万到上百万行,接口耗时
十几到三十几秒,甚至超时,页面就一直停在骨架屏。

- 前端:列表返回就渲染表格,用量列单独显示加载占位;统计失败时回落为 $0.0000。
- 后端:新增覆盖索引 (api_key_id, created_at) INCLUDE (actual_cost),使该统计可以
  index-only scan,不再回表。迁移采用 CONCURRENTLY 建索引;与其他 usage_logs
  索引迁移一样,重试前会先清理中断构建留下的 INVALID 索引。

Refs Wei-Shaw#5858

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hezhaoqian1
hezhaoqian1 force-pushed the perf/upstream-keys-usage-index branch from 632f74d to b8de5e1 Compare October 26, 2026 03:16
hjkl950217 added a commit to hjkl950217/sub2api that referenced this pull request Nov 6, 2026
hjkl950217 added a commit to hjkl950217/sub2api that referenced this pull request Nov 6, 2026
/profile 结论:POST /usage/dashboard/api-keys-usage 只有一条聚合查询,
WHERE api_key_id = ANY(...) AND created_at >= ...,已被 migration 249 的
idx_usage_logs_api_key_created_cost (api_key_id, created_at) INCLUDE (actual_cost)
覆盖,可走 index-only scan。批次 6 合入 Wei-Shaw#8346 时该索引已落地;此处在查询上方
标注依赖,避免后续改动给 created_at 套函数导致索引失效。

预聚合方案(上游 PR Wei-Shaw#5859,29 文件 +3062)未合入:属于更大改造,且该 PR 已长期
未更新、mergeable 未知。

Co-Authored-By: Claude Code <noreply@anthropic.com>
@Wei-Shaw
Wei-Shaw merged commit a870836 into Wei-Shaw:main Nov 10, 2026
9 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 10, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants