Table of Contents

42 用户 API Key 生命周期与 Portal 页面

背景与目标
最终方案
修改文件
验收结果
测试
遗留问题
相关提交
验收确认

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.

42 用户 API Key 生命周期与 Portal 页面

类型：需求
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2
状态：已完成
日期：2026-08-24
Gitea 工单：#42
Wiki 页面：Task-42-用户-API-Key-生命周期与-Portal-页面
Wiki revision：以线上页面 last_commit.sha 为准

背景与目标

面向现有受控登录用户交付 API Key 的自助生命周期管理：查看自己的 Key、创建并仅一次取得完整 token、修改名称和不可恢复地撤销。继续保持不开放注册、不引入计费、点数、每日配额和管理员代管的边界。

最终方案

在 Portal 增加 /api-keys 页面，以及会话认证的列表、创建、改名和撤销 JSON API；写操作沿用 CSRF，页面和响应统一禁止缓存。
Service 在事务内锁定并确认终端用户为 active，所有仓储操作同时约束 user_id。跨用户资源按不存在处理，停用用户拒绝管理。
使用安全随机源创建凭据；数据库仅保存 public id、前缀和 secret hash。完整 token 只放入创建成功响应，用户确认保存后从 DOM 清除，列表和刷新无法恢复。
页面覆盖加载、空、错误、停用、限流、一次展示、改名和撤销状态；桌面使用紧凑表格，移动端使用行卡片，交互目标至少 44px。
API Key 的 OpenAPI Bearer 认证、请求限流和审计不在本工单实现，继续由 MVP-2 后续单元工单交付。

修改文件

portal/service/api_keys.go、internal/core/apikey/repository.go：生命周期服务、active 用户事务门禁和 Unicode 名称校验。
portal/handler/api_keys.go、portal/handler/router.go：页面与 API 路由、CSRF、严格 JSON 和 no-store 响应。
portal/web/templates/api_keys.html、portal/web/static/api-keys.js、相关 CSS/Icon：完整 Portal 页面和响应式交互。
portal/handler/mysql_integration_test.go、portal/service/api_keys_test.go、portal/web/e2e/*：服务、真实 MySQL Handler 和四视口浏览器回归。
Wiki Architecture、Business Rules、Local Verification 及其 docs/ 核心镜像：记录长期架构、业务规则和验证方式。

验收结果

验收标准	结果
用户只能管理自己的 Key，覆盖 CSRF、越权和停用用户	通过
完整 Key 只在创建成功时显示一次，刷新和列表不能恢复	通过
页面符合已确认原型的主要流程、状态和响应式边界	通过
Portal Go 测试、前端构建和浏览器关键流程	通过
人工业务验收	2026-08-24 用户确认通过

测试

go test ./...、go vet ./...、go build ./...：通过。
go -C admin test ./...、go -C admin build .：通过。
pnpm --dir portal/web build：通过。
可丢弃 MySQL 8 隔离库：迁移回归及 Portal Handler/API Key 安全边界集成测试通过。
Playwright：API Key 四视口流程 4/4 通过；完整 Portal 套件 9 通过，3 个按既有视口条件跳过。
python dev_scripts/harness.py check --strict、42 项 Harness 单测、sync --check、git diff --check：通过。
未验证部分：无；未调用真实 Provider，OpenAPI Bearer、限流和审计不属于 #42。

遗留问题

#42 范围内无已知遗留缺陷。OpenAPI Bearer、限流和审计按 MVP-2 后续工单推进。

验收确认

2026-08-24：用户明确确认 #42 验收通过。