feat: 实现 MVP-2 API Key 核心与迁移 (#41)
This commit is contained in:
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Architecture-and-Code-Map
|
||||
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Architecture-and-Code-Map.-
|
||||
wiki_revision: 1e8fea6c058d6d23f4a40183dd51708c8a4dae84
|
||||
synchronized_at: 2026-08-24T03:48:52Z
|
||||
wiki_revision: f0a042b18061ece7423e3e7bb4219f84df78d71e
|
||||
synchronized_at: 2026-08-24T04:20:08Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
@@ -388,3 +388,10 @@ Provider 限流检查发生在真实上游调用前。放行后才执行 `BeginP
|
||||
`000006_mvp2_openapi_governance` 创建两张表、`available_at`/队列索引和管理端菜单/API/Casbin seed；down 按稳定键删除 seed、索引、列和新表。必须在固定隔离 MySQL 8 上完成空库及含 MVP-1 数据的 up/down/up，并验证现有 generation 仍可领取。回退前停止 portal/worker；回退会删除 API Key 和新增审计，属于需人工确认的数据丢失操作，不能在生产自动执行。
|
||||
|
||||
必测矩阵包括：随机格式/哈希/常量比较、完整 Key 只出现一次、撤销/到期/用户停用、三条认证链不混用、CSRF、跨用户 404、幂等重放/冲突、JSON 与 multipart 边界、历史 cursor、文件归属、429 与 Retry-After、user/key/provider 三维桶、重启边界、Provider 本地限流不调用上游且不改变 retryable/circuit/attempt、Defer CAS 和旧 lease、审计脱敏、管理员权限、OpenAPI schema 合约、MySQL up/down/up，以及 mock 上游完整链路。不得使用真实 Provider 额度做回归。
|
||||
|
||||
### #41 已实现的数据与凭据核心（2026-08-24，待验收）
|
||||
|
||||
- `migrations/000006_mvp2_openapi_governance` 已实现 `api_keys`、`api_audit_events`、`generations.available_at`、新队列索引以及管理端 API Key 菜单/API/Casbin 种子。`public_id` 固定 24 字符、可见前缀固定 32 字符、哈希固定 32 字节，并包含用户状态、最近使用时间和唯一定位索引。
|
||||
- `internal/platform/apikey` 使用 `crypto/rand` 生成 256 bit secret，令牌格式为 `chorus_<public_id>_<secret>`；只计算并保存 secret 的 SHA-256，认证比较使用常量时间。完整令牌与哈希均被排除在默认 JSON 序列化之外。
|
||||
- `internal/core/apikey` 提供按 `user_id` 隔离的创建、读取、列表、改名和撤销仓储。改名与撤销可安全重放；跨用户读取不会返回其他用户记录。
|
||||
- `000006` 的 down 在 `api_keys` 或 `api_audit_events` 存在数据时主动失败，防止静默丢失安全数据。不得在生产用 `force` 绕过；只有完成备份、停服、风险确认和数据处置后才能回退。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Business-Rules-and-Glossary
|
||||
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Business-Rules-and-Glossary.-
|
||||
wiki_revision: e3789d9b44c51d9f1363df03f1bbc51db1c296a2
|
||||
synchronized_at: 2026-08-24T03:48:57Z
|
||||
wiki_revision: 00ab703e701a3b9cb4107a3fb9a48fef6acea27d
|
||||
synchronized_at: 2026-08-24T04:20:13Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -139,3 +139,10 @@ synchronized_at: 2026-08-24T03:48:57Z
|
||||
5. Provider 本地限流不得记作上游 429、不得增加 Provider attempt、不得触发熔断或消耗故障转移；所有候选受限时只延后 generation。
|
||||
6. API 安全审计禁止保存 Prompt、文件、完整 Key、Authorization、Cookie、响应正文或原始 IP；未知 Key 失败不允许制造无限数据库审计行。
|
||||
7. API Key 只撤销不物理删除；本 MVP 不自动删除 Key、审计、生成任务或生成物。
|
||||
|
||||
## MVP-2 API Key 持久化规则（#41，2026-08-24 待验收）
|
||||
|
||||
- API Key 完整值只允许在创建成功响应中出现一次；数据库不保存原始 Key，只保存 24 字符公开标识、32 字符可见前缀和 32 字节 SHA-256。
|
||||
- Key 的有效性同时取决于未撤销、未到期以及所属终端用户可用；管理员凭据与终端用户 API Key 继续分离。
|
||||
- API Key 名称去除首尾空白后必须为 1 至 80 字符。改名和撤销按 Key 所属用户执行并支持幂等重放，不物理删除记录。
|
||||
- `api_audit_events` 是追加写安全审计模型，摘要只能保存脱敏结构化信息；完整 Key、Authorization、Cookie、Prompt、文件内容和响应正文不得进入审计。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Local-Development-and-Verification
|
||||
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.-
|
||||
wiki_revision: 7ac7e6b87149b70514488e836a6d5a5336ecdb6f
|
||||
synchronized_at: 2026-08-24T03:49:02Z
|
||||
wiki_revision: 9661a72756f4c6d53eabd454df03625d382f1ac0
|
||||
synchronized_at: 2026-08-24T04:20:17Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 本地开发与验证
|
||||
@@ -402,3 +402,25 @@ D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf status
|
||||
| `chorus-admin-ui` | Vue 开发服务 | `config/local-services.yml` 的 `admin_ui`；API 基址由 Admin 地址派生 |
|
||||
|
||||
单个实例可使用 `ctl ... stop <名称>`、`start <名称>` 或 `restart <名称>` 管理。日志位于 `D:\supervisor\logs\chorus-*.log`。更新代码、端口或配置路径后必须重新运行安装器并 `reload`；安装器不复制敏感配置，也不执行迁移、seed、账号创建或依赖安装。
|
||||
|
||||
## #41 MVP-2 迁移与 API Key 核心验证
|
||||
|
||||
普通回归不执行破坏性迁移测试：
|
||||
|
||||
```powershell
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go -C admin test ./...
|
||||
```
|
||||
|
||||
真实迁移和仓储集成测试必须显式指定一个可丢弃且名称完全匹配的隔离库，并顺序运行，避免迁移 down 与仓储测试争用同一数据库：
|
||||
|
||||
```powershell
|
||||
$env:CHORUS_MIGRATION_TEST_DATABASE = "chorus_mvp2_test"
|
||||
$env:CHORUS_RUN_MIGRATION_TESTS = "1"
|
||||
$env:CHORUS_RUN_MYSQL_TESTS = "1"
|
||||
go test ./migrations -count=1
|
||||
go test ./internal/core/apikey -count=1
|
||||
```
|
||||
|
||||
`CHORUS_DSN` 与 `CHORUS_MIGRATE_URL` 必须指向同一个明确创建的可丢弃库。测试会重置目标库结构，严禁指向 `chorus`、当前开发库、共享库或生产库。#41 已在本机 MySQL 8.4.8 独立库完成迁移 up/down/up、非空数据 down 拒绝、仓储创建/读取/改名/撤销和事务回滚验证。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Deployment-and-Operations
|
||||
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Deployment-and-Operations.-
|
||||
wiki_revision: c19a066002ec15cdacdf454dea4da4b67c3a4529
|
||||
synchronized_at: 2026-08-24T02:18:23Z
|
||||
wiki_revision: 2eb4eb745005bbc3c7467b1202e4f0b779525224
|
||||
synchronized_at: 2026-08-24T04:20:48Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 部署与运维
|
||||
@@ -207,3 +207,10 @@ D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf status
|
||||
```
|
||||
|
||||
回退时停止 `chorus-user`、`chorus-admin-api`、`chorus-admin-ui`，移除 `D:\supervisor\programs\chorus.conf` 后 reload，再按需使用 `scripts/start-all.bat`。不得同时使用两套入口占用相同端口。
|
||||
|
||||
## MVP-2 迁移 000006 运维门禁（#41）
|
||||
|
||||
- 发布包含 #41 或后续 MVP-2 服务代码前，必须先备份并执行 `000006_mvp2_openapi_governance.up.sql`；应用启动仍不会自动迁移或 AutoMigrate。
|
||||
- `000006` 为 `generations` 增加非空 `available_at` 并重建队列索引，同时新增 API Key、安全审计表和管理端授权种子。升级后要检查 migration version、两张表、队列索引和稳定键 seed。
|
||||
- down 会删除 API Key 与安全审计结构，因此在任一新表非空时必定失败。生产不得使用 migrate `force` 绕过保护；需要回退时先停止 portal/worker、备份并核验、明确处置数据、取得人工确认，再在已演练步骤下执行。
|
||||
- 仅回退二进制不能撤销本次数据库结构。旧二进制与 `available_at` 的兼容性必须在具体发布工单中验证，不能把隔离库测试替代真实发布演练。
|
||||
|
||||
Reference in New Issue
Block a user