feat: 实现 MVP-1 管理端 API、凭据轮换与连通性审计 (#19) #23

New Issue

2026-08-21T16:07:28+08:00

ila commented

2026-08-21 16:07:28 +08:00

基本信息

类型：需求
所属 Epic：#3
所属 MVP / 版本：#19 / MVP-1
阶段：已完成

原始需求

来源：用户对话与已确认 MVP-1 技术设计、管理端原型 #17、用户端原型 #18。
提出时间：2026-08-21
脱敏摘要：按已确认 MVP-1 范围建立生产实现单元工单。

文档影响

更新项目档案：记录嵌套 admin module、受限生产入口和构建命令。
更新架构与代码地图：记录 /api/v1/chorus API、脱敏审计、JWT/Casbin 与出站探测门禁。
更新本地开发与验证：记录管理端安全启动及 MySQL 集成测试命令。
更新部署与运维：修正嵌套 admin module 的构建命令。
更新业务规则与术语，原因：已确认业务规则不变。
更新常见修改或故障排查，原因：现有边界说明足够。

交付文档影响

无交付文档影响，原因：本工单交付内部管理 API；管理端 UI 与最终用户操作文档待后续集成评估。

变更控制

未增加计费扣点、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 或其他已排除范围。
未使用真实 Provider 额度；自动化和开发测试只使用 mock Probe 与 .invalid 合成地址。
管理员 sys_user 与终端用户 users 保持分表；生成链路未改动。

依赖与并行

前置工单：#20、#21、#22，均已完成。
是否允许并行：否；实现已在依赖完成后进行。

最终方案

将用户指定固定提交 f06540883b41d03782bb6b2c4150f298f328c6b6 的必要 go-admin 后端代码导入 admin/ 嵌套 Go module；生产只有 chorus-admin server --config <受保护配置>，不导入 AutoMigrate、代码生成、Swagger、WebSocket 或静态文件路由。
实现 /api/v1/chorus 的 Provider、ProviderModel、PromptTemplate、RoutePool、Generation 和终端用户查询。生产注册复用 go-admin JWT 与 Casbin；JWT 只接受 Authorization: Bearer，拒绝 Query/Cookie token。Chorus API 不提供 DELETE。
Provider API Key 仅在创建或轮换请求中接收一次，使用既有 AES-GCM key ring 加密写入 provider_credentials；响应仅返回 has_credential、活动版本和 key_id。轮换保留历史版本，激活历史版本可回退；普通更新省略 key 时保持当前凭据。
RoutePool 使用 version 乐观锁，发布时验证模板/能力、成员、权重、breaker 参数、启用状态与活动凭据。
连通性检查默认拒绝且记录脱敏审计，不构造出站请求；只有运行时显式设置授权开关、冷却、HTTP 超时和响应上限后，才使用同一 SSRF-safe HTTP client 运行固定最小 Probe。运行中先原子预留，冷却返回 429。
/api/v1/chorus 从通用 go-admin 操作日志中排除，请求体和结果不会持久化到 sys_oper_log；配置和探测审计写入 admin_audit_events，不含明文或密文。

验收标准

CRUD/启停查询、权限路由、审计和被引用记录不物理删除：HTTP/服务层测试覆盖 401、403、无 DELETE 路由及创建/查询边界。
凭据创建、轮换、回退、空值不清除，以及响应/audit 不含明文或密文：MySQL 集成测试覆盖。
路由发布校验能力、成员、权重、模板与 breaker 参数，并处理乐观锁冲突：MySQL 集成测试覆盖发布与 stale version 冲突。
连通性冷却并发仅预留一个检查；未授权时不发起真实请求：mock Probe/MySQL 集成测试覆盖。

验证结果

go test -count=1 ./...（在 admin/，CHORUS_RUN_ADMIN_TESTS=1）：通过；仅使用隔离 chorus_test`、随机后缀合成数据与 mock Probe。
go vet ./...（在 admin/）：通过。
go test -count=1 ./...（仓库根目录，含 CHORUS_RUN_MIGRATION_TESTS=1）：通过；MVP-1 migration up/down/up 通过。
go vet ./...（仓库根目录）、python dev_scripts/harness.py check --strict、python -m unittest discover -s tests -v：通过。
核心 Wiki 镜像在线校验通过：Project-Profile 811dfc91e824、Architecture-and-Code-Map 8c1c40529eb6、Local-Development-and-Verification 6975232fead6、Deployment-and-Operations c319c623c7e3。

未验证部分

未实际启动带真实管理员账号的长期进程，也未执行真实 Provider 探测；这是本工单的刻意安全限制，真实探测仍需要人工明确授权并由运行时环境开关放行。
管理端 UI 和浏览器端到端流程不属于 #23，后续由管理端 UI 工单处理。

任务归档

Wiki：Task-23-MVP-1-管理端-API、凭据轮换与连通性审计 @ df219c00cae9e68ccb2d32d35a797ed78d9f5f83。
未导出 docs/task/；任务归档仅在用户明确要求导出时生成本地快照。

人工验收

用户于 2026-08-22 明确确认 #23 验收通过。
工单关闭后，管理端 UI 与真实 Provider 探测仍按已列范围和门禁另行推进。

## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#19 / MVP-1 - 阶段：已完成 ## 原始需求 - 来源：用户对话与已确认 MVP-1 技术设计、管理端原型 #17、用户端原型 #18。 - 提出时间：2026-08-21 - 脱敏摘要：按已确认 MVP-1 范围建立生产实现单元工单。 ## 文档影响 - [x] 更新项目档案：记录嵌套 admin module、受限生产入口和构建命令。 - [x] 更新架构与代码地图：记录 `/api/v1/chorus` API、脱敏审计、JWT/Casbin 与出站探测门禁。 - [x] 更新本地开发与验证：记录管理端安全启动及 MySQL 集成测试命令。 - [x] 更新部署与运维：修正嵌套 admin module 的构建命令。 - [ ] 更新业务规则与术语，原因：已确认业务规则不变。 - [ ] 更新常见修改或故障排查，原因：现有边界说明足够。 ## 交付文档影响 - [x] 无交付文档影响，原因：本工单交付内部管理 API；管理端 UI 与最终用户操作文档待后续集成评估。 ## 变更控制 - 未增加计费扣点、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 或其他已排除范围。 - 未使用真实 Provider 额度；自动化和开发测试只使用 mock Probe 与 `.invalid` 合成地址。 - 管理员 `sys_user` 与终端用户 `users` 保持分表；生成链路未改动。 ## 依赖与并行 - 前置工单：#20、#21、#22，均已完成。 - 是否允许并行：否；实现已在依赖完成后进行。 ## 最终方案 - 将用户指定固定提交 `f06540883b41d03782bb6b2c4150f298f328c6b6` 的必要 go-admin 后端代码导入 `admin/` 嵌套 Go module；生产只有 `chorus-admin server --config <受保护配置>`，不导入 AutoMigrate、代码生成、Swagger、WebSocket 或静态文件路由。 - 实现 `/api/v1/chorus` 的 Provider、ProviderModel、PromptTemplate、RoutePool、Generation 和终端用户查询。生产注册复用 go-admin JWT 与 Casbin；JWT 只接受 `Authorization: Bearer`，拒绝 Query/Cookie token。Chorus API 不提供 DELETE。 - Provider API Key 仅在创建或轮换请求中接收一次，使用既有 AES-GCM key ring 加密写入 `provider_credentials`；响应仅返回 `has_credential`、活动版本和 `key_id`。轮换保留历史版本，激活历史版本可回退；普通更新省略 key 时保持当前凭据。 - RoutePool 使用 version 乐观锁，发布时验证模板/能力、成员、权重、breaker 参数、启用状态与活动凭据。 - 连通性检查默认拒绝且记录脱敏审计，不构造出站请求；只有运行时显式设置授权开关、冷却、HTTP 超时和响应上限后，才使用同一 SSRF-safe HTTP client 运行固定最小 Probe。运行中先原子预留，冷却返回 429。 - `/api/v1/chorus` 从通用 go-admin 操作日志中排除，请求体和结果不会持久化到 `sys_oper_log`；配置和探测审计写入 `admin_audit_events`，不含明文或密文。 ## 验收标准 - [x] CRUD/启停查询、权限路由、审计和被引用记录不物理删除：HTTP/服务层测试覆盖 401、403、无 DELETE 路由及创建/查询边界。 - [x] 凭据创建、轮换、回退、空值不清除，以及响应/audit 不含明文或密文：MySQL 集成测试覆盖。 - [x] 路由发布校验能力、成员、权重、模板与 breaker 参数，并处理乐观锁冲突：MySQL 集成测试覆盖发布与 stale version 冲突。 - [x] 连通性冷却并发仅预留一个检查；未授权时不发起真实请求：mock Probe/MySQL 集成测试覆盖。 ## 验证结果 - `go test -count=1 ./...`（在 `admin/`，`CHORUS_RUN_ADMIN_TESTS=1）：通过；仅使用隔离 `chorus_test`、随机后缀合成数据与 mock Probe。 - `go vet ./...`（在 `admin/`）：通过。 - `go test -count=1 ./...`（仓库根目录，含 `CHORUS_RUN_MIGRATION_TESTS=1`）：通过；MVP-1 migration up/down/up 通过。 - `go vet ./...`（仓库根目录）、`python dev_scripts/harness.py check --strict`、`python -m unittest discover -s tests -v`：通过。 - 核心 Wiki 镜像在线校验通过：Project-Profile `811dfc91e824`、Architecture-and-Code-Map `8c1c40529eb6`、Local-Development-and-Verification `6975232fead6`、Deployment-and-Operations `c319c623c7e3`。 ## 未验证部分 - 未实际启动带真实管理员账号的长期进程，也未执行真实 Provider 探测；这是本工单的刻意安全限制，真实探测仍需要人工明确授权并由运行时环境开关放行。 - 管理端 UI 和浏览器端到端流程不属于 #23，后续由管理端 UI 工单处理。 ## 相关提交 - `f182bfb` docs: 记录 MVP-1 管理端运行方式 (#23) - `4bb63f2` docs: 修正管理端嵌套模块构建命令 (#23) - `64f917b` feat: 实现 MVP-1 管理端 API 与凭据审计 (#23) - `b4bec89` test: 覆盖管理端 HTTP 凭据边界 (#23) ## 任务归档 - Wiki：[Task-23-MVP-1-管理端-API、凭据轮换与连通性审计](https://git.ilapage.cn/OPC/chorus/wiki/Task-23-MVP-1-%E7%AE%A1%E7%90%86%E7%AB%AF-API%E3%80%81%E5%87%AD%E6%8D%AE%E8%BD%AE%E6%8D%A2%E4%B8%8E%E8%BF%9E%E9%80%9A%E6%80%A7%E5%AE%A1%E8%AE%A1.-) @ df219c00cae9e68ccb2d32d35a797ed78d9f5f83。 - 未导出 docs/task/；任务归档仅在用户明确要求导出时生成本地快照。 ## 人工验收 - 用户于 2026-08-22 明确确认 #23 验收通过。 - 工单关闭后，管理端 UI 与真实 Provider 探测仍按已列范围和门禁另行推进。

ila referenced this issue

2026-08-21 16:08:04 +08:00

mvp: MVP-1 多上游可用性与运营管理 #19

ila referenced this issue

2026-08-21 16:08:06 +08:00

epic: chorus 图文生成服务交付 #3

ila referenced this issue

2026-08-21 16:10:58 +08:00

mvp: MVP-1 多上游可用性与运营管理 #19

ila referenced this issue from a commit

2026-08-21 23:13:17 +08:00

docs: 记录 MVP-1 管理端运行方式 (#23)