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

M0-03 Config & Feature Flag 基础版 #3

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

目标

设计知习后端统一配置中心与功能开关模块，为所有模块提供动态配置管理和灰度发布能力。

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

背景说明

知习后端在开发和运营过程中需要频繁调整参数，例如模型路由配置、复习算法参数、免费/付费额度、功能灰度开关等。如果每次调参都改代码重新部署，效率太低且风险大。

Config & Feature Flag 模块提供 MySQL 配置表作为配置存储，Admin 管理页面作为配置变更入口，所有配置变更必须记录审计。

模块职责

  1. 本模块负责：

    • 动态配置存储（MySQL 配置表）
    • 配置读取接口（供各模块代码调用）
    • 配置热更新机制（是否需要重启服务，请判断）
    • 功能开关（Feature Flag）管理
    • 配置版本记录
    • 配置变更审计
    • Admin 配置管理页面

  2. 本模块不负责：

    • 敏感密钥存储（走 Secret & Vendor Asset Module）
    • 环境变量管理（走运维层面）
    • 用户级别的个性化配置（走各业务模块）

候选数据对象

  • AppConfig（应用配置键值对）
  • FeatureFlag（功能开关，含灰度条件和生效范围）
  • ConfigChangeLog（配置变更记录）
  • ConfigEnvironment（配置环境标识，如 dev/staging/production）

基础设施依赖判断

  • MySQL：是，配置存储
  • Redis：是，配置缓存减少数据库查询
  • BullMQ：否（配置变更通知可走同步事件）
  • Qdrant：否
  • AI Gateway：否
  • COS：否
  • Content Safety：否

API 设计

  1. Internal Provider（供各模块代码调用）：

    • ConfigService.get(key)
    • ConfigService.getFeatureFlag(name)
    • ConfigService.isEnabled(featureName)

  2. AAPI（Admin 管理）：

    • 配置列表和搜索
    • 配置新增/编辑/删除
    • 功能开关列表和管理
    • 配置变更历史

Domain Event 设计

  • ConfigChanged：配置变更时发布
  • FeatureFlagToggled：功能开关变更时发布

Admin 视图设计

  1. 配置管理页：

    • 配置键值对列表（键、值、描述、环境、更新时间）
    • 新增/编辑配置表单
    • 配置变更历史时间线

  2. 功能开关页：

    • 开关列表（名称、状态、生效范围、描述）
    • 灰度条件配置（百分比、用户白名单等）
    • 开关变更历史

交付检查

  • 路由归属：Internal Provider + AAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：是（缓存）
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否
  • 是否需要 AuditLog：是（所有配置变更）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是
  • 是否需要更新 OpenAPI：是

验收标准

  1. 配置存储表设计（Prisma schema）
  2. ConfigService 接口设计 + 实现
  3. 配置热更新机制方案（含是否需要重启的判断）
  4. FeatureFlag 条件和灰度策略设计
  5. Admin 配置管理视图设计
  6. 配置变更审计日志方案
  7. 集成测试覆盖配置读写和变更审计

禁止事项

  • 禁止敏感密钥存入 Config 表（走 Secret Module）
  • 禁止配置热更新绕过审计
  • 禁止使用 json 大字段存储配置（应结构化存储）
  • 禁止配置变更不做版本记录
  • 禁止在代码中硬编码配置默认值绕过 ConfigService

不建议当前阶段实现

  • Nacos/Apollo 等外部配置中心
  • 配置灰度自动回滚
  • 配置 A/B 测试框架
  • 配置推送通知（配置变更后通知各模块刷新）
## 目标 设计知习后端统一配置中心与功能开关模块，为所有模块提供动态配置管理和灰度发布能力。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习后端在开发和运营过程中需要频繁调整参数，例如模型路由配置、复习算法参数、免费/付费额度、功能灰度开关等。如果每次调参都改代码重新部署，效率太低且风险大。 Config & Feature Flag 模块提供 MySQL 配置表作为配置存储，Admin 管理页面作为配置变更入口，所有配置变更必须记录审计。 ## 模块职责 1. 本模块负责： - 动态配置存储（MySQL 配置表） - 配置读取接口（供各模块代码调用） - 配置热更新机制（是否需要重启服务，请判断） - 功能开关（Feature Flag）管理 - 配置版本记录 - 配置变更审计 - Admin 配置管理页面 2. 本模块不负责： - 敏感密钥存储（走 Secret & Vendor Asset Module） - 环境变量管理（走运维层面） - 用户级别的个性化配置（走各业务模块） ## 候选数据对象 - AppConfig（应用配置键值对） - FeatureFlag（功能开关，含灰度条件和生效范围） - ConfigChangeLog（配置变更记录） - ConfigEnvironment（配置环境标识，如 dev/staging/production） ## 基础设施依赖判断 - MySQL：是，配置存储 - Redis：是，配置缓存减少数据库查询 - BullMQ：否（配置变更通知可走同步事件） - Qdrant：否 - AI Gateway：否 - COS：否 - Content Safety：否 ## API 设计 1. Internal Provider（供各模块代码调用）： - ConfigService.get(key) - ConfigService.getFeatureFlag(name) - ConfigService.isEnabled(featureName) 2. AAPI（Admin 管理）： - 配置列表和搜索 - 配置新增/编辑/删除 - 功能开关列表和管理 - 配置变更历史 ## Domain Event 设计 - ConfigChanged：配置变更时发布 - FeatureFlagToggled：功能开关变更时发布 ## Admin 视图设计 1. 配置管理页： - 配置键值对列表（键、值、描述、环境、更新时间） - 新增/编辑配置表单 - 配置变更历史时间线 2. 功能开关页： - 开关列表（名称、状态、生效范围、描述） - 灰度条件配置（百分比、用户白名单等） - 开关变更历史 ## 交付检查 - [ ] 路由归属：Internal Provider + AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：是（缓存） - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：是（所有配置变更） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 - [ ] 是否需要更新 OpenAPI：是 ## 验收标准 1. 配置存储表设计（Prisma schema） 2. ConfigService 接口设计 + 实现 3. 配置热更新机制方案（含是否需要重启的判断） 4. FeatureFlag 条件和灰度策略设计 5. Admin 配置管理视图设计 6. 配置变更审计日志方案 7. 集成测试覆盖配置读写和变更审计 ## 禁止事项 - 禁止敏感密钥存入 Config 表（走 Secret Module） - 禁止配置热更新绕过审计 - 禁止使用 json 大字段存储配置（应结构化存储） - 禁止配置变更不做版本记录 - 禁止在代码中硬编码配置默认值绕过 ConfigService ## 不建议当前阶段实现 - Nacos/Apollo 等外部配置中心 - 配置灰度自动回滚 - 配置 A/B 测试框架 - 配置推送通知（配置变更后通知各模块刷新）
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +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#3
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?