wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Open
opened 2026-05-22 21:00:16 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:16 +08:00
Owner
Copy Link

目标

设计知习后端密钥与服务商资产管理模块，为全系统提供 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. 访问日志页：

    • 密钥访问记录（时间、调用模块、密钥名称）

交付检查

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

验收标准

  1. 密钥加密存储方案（含加密算法和主密钥管理）
  2. SecretRecord / SecretAccessLog Prisma schema
  3. SecretService 接口设计
  4. 密钥轮换流程设计（含旧 Key 保留期）
  5. 到期提醒机制
  6. Admin 管理视图设计
  7. 集成测试覆盖密钥 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. 访问日志页： - 密钥访问记录（时间、调用模块、密钥名称） ## 交付检查 - [ ] 路由归属：Internal Provider + AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：否 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：是（密钥增删改、轮换操作） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 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
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#12
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?