M0-12 Secret & Vendor Asset 基础版 #12

New Issue

wangdl · 2026-05-22T21:00:16+08:00

wangdl commented

2026-05-22 21:00:16 +08:00

目标

设计知习后端密钥与服务商资产管理模块，为全系统提供 API Key 的加密存储、生命周期管理和轮换机制。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习依赖多个外部服务：DeepSeek API、硅基流动 API、百度 OCR API、腾讯云 COS。每个服务都需要 API Key，这些 Key 不能明文存在于代码或配置文件中，需要加密存储、支持轮换、记录使用日志。

Secret 模块管理"密钥本身"，Config 模块管理"非敏感的动态参数"。敏感数据走 Secret，普通配置走 Config，不可混淆。

模块职责

本模块负责：
- API Key 加密存储（加密算法选择，请判断）
- API Key 元信息管理（名称、服务商、最后四位、到期时间）
- API Key 轮换记录（旧 Key → 新 Key，轮换时间）
- API Key 到期提醒
- API Key 使用日志（哪个模块在什么时间使用了哪个 Key）
- 测试连接功能（验证 Key 是否有效）
本模块不负责：
- 非敏感动态参数（走 Config Module）
- 服务商账单和成本（走 Quota, Billing & Cost）
- API Key 对应的额度监控（走 Quota Module）

候选数据对象

SecretRecord（密钥记录，含加密后的 Key 和元信息）
SecretVersion（密钥版本历史）
SecretAccessLog（密钥访问日志）
SecretRotationLog（密钥轮换记录）
VendorAccount（服务商账户信息）

基础设施依赖判断

MySQL：是（密钥元信息和访问日志）
Redis：否（密钥不应缓存，每次从 MySQL 读取并解密）
BullMQ：否
Qdrant：否
AI Gateway：否
COS：否
Config：否（敏感密钥不应走 Config）

安全设计

加密方案：
- 加密算法选择（AES-256-GCM 或类似，请判断）
- 主密钥管理（环境变量注入或 KMS，请判断）
- 密钥在内存中的生命周期
访问控制：
- 只有 Admin 能查看密钥元信息（不能查看明文）
- 只有经过授权的模块能获取解密后的 Key
- 获取解密 Key 的操作必须记录访问日志
轮换机制：
- 支持手动触发轮换
- 轮换时保留旧 Key 24 小时以便回滚
- 轮换记录完整的 before/after 元信息

API 设计

Internal Provider（供其他模块调用）：
- SecretService.getDecrypted(name)：获取解密的 Key
AAPI：
- 密钥列表（只显示元信息：名称、服务商、最后四位、状态、到期时间）
- 新增密钥
- 轮换密钥
- 删除/禁用密钥
- 测试连接
- 密钥访问日志查看

Domain Event 设计

SecretRotated：密钥轮换
SecretExpiring：密钥即将到期
SecretAccessLogged：密钥被访问

Admin 视图设计

密钥管理页：
- 列表（名称、服务商、最后四位、状态、到期时间）
- 新增表单（名称、服务商、Key 值、到期时间）
- 轮换操作、测试连接按钮
- 即将到期高亮提示
访问日志页：
- 密钥访问记录（时间、调用模块、密钥名称）

交付检查

路由归属：Internal Provider + AAPI
是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：否
是否需要 BullMQ：否
是否需要 Qdrant：否
是否需要 AI Gateway：否
是否需要 Content Safety：否
是否需要 Cost 记录：否
是否需要 AuditLog：是（密钥增删改、轮换操作）
是否需要 Domain Event：是
是否需要 Admin 视图：是
是否需要 E2E/集成测试：是

验收标准

密钥加密存储方案（含加密算法和主密钥管理）
SecretRecord / SecretAccessLog Prisma schema
SecretService 接口设计
密钥轮换流程设计（含旧 Key 保留期）
到期提醒机制
Admin 管理视图设计
集成测试覆盖密钥 CRUD 和访问控制

禁止事项

禁止密钥明文存入数据库
禁止密钥明文出现在日志中
禁止 Admin 直接查看密钥明文（只能看元信息）
禁止密钥不设到期时间
禁止将敏感密钥放入 Config 模块
禁止缓存解密后的密钥（每次使用从 MySQL 读取解密）

不建议当前阶段实现

KMS 集成（先环境变量主密钥）
自动轮换（先手动触发）
密钥使用频率异常检测
多环境密钥隔离管理

## 目标设计知习后端密钥与服务商资产管理模块，为全系统提供 API Key 的加密存储、生命周期管理和轮换机制。本 Issue 只做架构设计，不直接实现代码。 ## 背景说明知习依赖多个外部服务：DeepSeek API、硅基流动 API、百度 OCR API、腾讯云 COS。每个服务都需要 API Key，这些 Key 不能明文存在于代码或配置文件中，需要加密存储、支持轮换、记录使用日志。 Secret 模块管理"密钥本身"，Config 模块管理"非敏感的动态参数"。敏感数据走 Secret，普通配置走 Config，不可混淆。 ## 模块职责 1. 本模块负责： - API Key 加密存储（加密算法选择，请判断） - API Key 元信息管理（名称、服务商、最后四位、到期时间） - API Key 轮换记录（旧 Key → 新 Key，轮换时间） - API Key 到期提醒 - API Key 使用日志（哪个模块在什么时间使用了哪个 Key） - 测试连接功能（验证 Key 是否有效） 2. 本模块不负责： - 非敏感动态参数（走 Config Module） - 服务商账单和成本（走 Quota, Billing & Cost） - API Key 对应的额度监控（走 Quota Module） ## 候选数据对象 - SecretRecord（密钥记录，含加密后的 Key 和元信息） - SecretVersion（密钥版本历史） - SecretAccessLog（密钥访问日志） - SecretRotationLog（密钥轮换记录） - VendorAccount（服务商账户信息） ## 基础设施依赖判断 - MySQL：是（密钥元信息和访问日志） - Redis：否（密钥不应缓存，每次从 MySQL 读取并解密） - BullMQ：否 - Qdrant：否 - AI Gateway：否 - COS：否 - Config：否（敏感密钥不应走 Config） ## 安全设计 1. 加密方案： - 加密算法选择（AES-256-GCM 或类似，请判断） - 主密钥管理（环境变量注入或 KMS，请判断） - 密钥在内存中的生命周期 2. 访问控制： - 只有 Admin 能查看密钥元信息（不能查看明文） - 只有经过授权的模块能获取解密后的 Key - 获取解密 Key 的操作必须记录访问日志 3. 轮换机制： - 支持手动触发轮换 - 轮换时保留旧 Key 24 小时以便回滚 - 轮换记录完整的 before/after 元信息 ## API 设计 1. Internal Provider（供其他模块调用）： - SecretService.getDecrypted(name)：获取解密的 Key 2. AAPI： - 密钥列表（只显示元信息：名称、服务商、最后四位、状态、到期时间） - 新增密钥 - 轮换密钥 - 删除/禁用密钥 - 测试连接 - 密钥访问日志查看 ## Domain Event 设计 - SecretRotated：密钥轮换 - SecretExpiring：密钥即将到期 - SecretAccessLogged：密钥被访问 ## Admin 视图设计 1. 密钥管理页： - 列表（名称、服务商、最后四位、状态、到期时间） - 新增表单（名称、服务商、Key 值、到期时间） - 轮换操作、测试连接按钮 - 即将到期高亮提示 2. 访问日志页： - 密钥访问记录（时间、调用模块、密钥名称） ## 交付检查 - [x] 路由归属：Internal Provider + AAPI - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否 - [x] 是否需要 BullMQ：否 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：否 - [x] 是否需要 Content Safety：否 - [x] 是否需要 Cost 记录：否 - [x] 是否需要 AuditLog：是（密钥增删改、轮换操作） - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是 - [x] 是否需要 E2E/集成测试：是 ## 验收标准 1. 密钥加密存储方案（含加密算法和主密钥管理） 2. SecretRecord / SecretAccessLog Prisma schema 3. SecretService 接口设计 4. 密钥轮换流程设计（含旧 Key 保留期） 5. 到期提醒机制 6. Admin 管理视图设计 7. 集成测试覆盖密钥 CRUD 和访问控制 ## 禁止事项 - 禁止密钥明文存入数据库 - 禁止密钥明文出现在日志中 - 禁止 Admin 直接查看密钥明文（只能看元信息） - 禁止密钥不设到期时间 - 禁止将敏感密钥放入 Config 模块 - 禁止缓存解密后的密钥（每次使用从 MySQL 读取解密） ## 不建议当前阶段实现 - KMS 集成（先环境变量主密钥） - 自动轮换（先手动触发） - 密钥使用频率异常检测 - 多环境密钥隔离管理

wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:16 +08:00

wangdl self-assigned this 2026-05-22 21:00:16 +08:00

wangdl commented

2026-05-23 20:38:31 +08:00

实施完成

AES-256-GCM 加密存储
SecretRecord + SecretAccessLog
SecretService.encrypt/decrypt/getDecrypted
Admin AAPI: CRUD + 访问日志
Admin Web: 系统运维→密钥管理

## 实施完成 - AES-256-GCM 加密存储 - SecretRecord + SecretAccessLog - SecretService.encrypt/decrypt/getDecrypted - Admin AAPI: CRUD + 访问日志 - Admin Web: 系统运维→密钥管理

wangdl commented

2026-05-24 09:38:24 +08:00

✅ E2E 测试通过

M0 E2E 测试已全部通过 — 28/28 tests passed，耗时 ~1.4s。

本 Issue 测试内容

GET /admin-api/secrets → 200, POST create → 201, DELETE cleanup

运行方式

npm run test:e2e

测试架构

Mock 层: @prisma/client / ioredis / jose / @nestjs/bullmq
无需本地 MySQL/Redis，纯 mock 轻量集成测试
测试文件: test/m0.e2e-spec.ts

## ✅ E2E 测试通过 M0 E2E 测试已全部通过 — **28/28 tests passed**，耗时 ~1.4s。 ### 本 Issue 测试内容 GET /admin-api/secrets → 200, POST create → 201, DELETE cleanup ### 运行方式 ```bash npm run test:e2e ``` ### 测试架构 - Mock 层: `@prisma/client` / `ioredis` / `jose` / `@nestjs/bullmq` - 无需本地 MySQL/Redis，纯 mock 轻量集成测试 - 测试文件: `test/m0.e2e-spec.ts`

~~wangdl referenced this issue 2026-06-05 19:34:43 +08:00~~

H0-12 Quiz 模型与API #57

~~wangdl referenced this issue 2026-06-05 19:36:07 +08:00~~

H0-12 Quiz 模型与API #57

wangdl closed this issue

2026-06-06 18:50:35 +08:00

wangdl commented

2026-06-06 18:50:35 +08:00