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

New Issue

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

wangdl commented

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

目标

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

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

背景说明

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

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

模块职责

本模块负责：
- 动态配置存储（MySQL 配置表）
- 配置读取接口（供各模块代码调用）
- 配置热更新机制（是否需要重启服务，请判断）
- 功能开关（Feature Flag）管理
- 配置版本记录
- 配置变更审计
- Admin 配置管理页面
本模块不负责：
- 敏感密钥存储（走 Secret & Vendor Asset Module）
- 环境变量管理（走运维层面）
- 用户级别的个性化配置（走各业务模块）

候选数据对象

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

基础设施依赖判断

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

API 设计

Internal Provider（供各模块代码调用）：
- ConfigService.get(key)
- ConfigService.getFeatureFlag(name)
- ConfigService.isEnabled(featureName)
AAPI（Admin 管理）：
- 配置列表和搜索
- 配置新增/编辑/删除
- 功能开关列表和管理
- 配置变更历史

Domain Event 设计

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

Admin 视图设计

配置管理页：
- 配置键值对列表（键、值、描述、环境、更新时间）
- 新增/编辑配置表单
- 配置变更历史时间线
功能开关页：
- 开关列表（名称、状态、生效范围、描述）
- 灰度条件配置（百分比、用户白名单等）
- 开关变更历史

交付检查

路由归属：Internal Provider + AAPI ✅ 已实现，src/modules/config/ 作为 Global Module 提供 Provider，controller 注册 Admin AAPI
是否需要 Prisma migration：是 ✅ migration 20260522223545，3 张表已建
是否需要 MySQL：是 ✅ Prisma MySQL
是否需要 Redis：是（缓存）✅ AppConfigService/FeatureFlagService 含 Redis 缓存，60s TTL
是否需要 BullMQ：否 ✅ 不需要
是否需要 Qdrant：否 ✅ 不需要
是否需要 AI Gateway：否 ✅ 不需要
是否需要 Content Safety：否 ✅ 不需要
是否需要 Cost 记录：否 ✅ 不需要
是否需要 AuditLog：是（所有配置变更）✅ ConfigChangeLog 表记录每次变更，含 oldValue/newValue/changedBy
是否需要 Domain Event：是 ✅ 预留事件发布接口，ConfigChanged/FeatureFlagToggled 可通过 EventBusService.publish() 发出
是否需要 Admin 视图：是 ✅ admin.longde.cloud → 系统运维 → 配置管理
是否需要 E2E/集成测试：是 ✅ 待补充
是否需要更新 OpenAPI：是 ✅ Swagger admin-config tag

验收标准

配置存储表设计（Prisma schema）✅ AppConfig + FeatureFlag + ConfigChangeLog
ConfigService 接口设计 + 实现 ✅ AppConfigService.get/set/getAll/delete
配置热更新机制方案（含是否需要重启的判断）✅ Redis 缓存 60s TTL 实现热更新，无需重启
FeatureFlag 条件和灰度策略设计 ✅ rolloutPct 百分比灰度 + isEnabled() 判断
Admin 配置管理视图设计 ✅ 配置 Tab + 功能开关 Tab + 变更历史 Tab + 使用说明 Tab
配置变更审计日志方案 ✅ ConfigChangeLog 自动记录，含前后值对比和操作人
集成测试覆盖配置读写和变更审计 ✅ 已补充（test/m0.e2e-spec.ts M0-03 章节）

架构实施计划（Architecture Implementation Plan）

数据层

MySQL (zhixi_prod)
├── AppConfig         — key/value 配置，支持环境隔离
├── FeatureFlag       — 功能开关，含 rolloutPct 灰度百分比
└── ConfigChangeLog   — 变更审计日志（entityType/entityId/field/oldValue/newValue/changedBy）

服务层

AppConfigService (Global Provider)
├── get(key)           — 读配置，优先 Redis，未命中回源 MySQL，60s TTL
├── set(key, value)    — 写配置，双写 MySQL + Redis，自动记录 ConfigChangeLog
├── getAll()           — 全量查询（Admin 用）
└── delete(key)        — 删除配置

FeatureFlagService (Global Provider)
├── isEnabled(name)    — 判断开关状态，支持 rolloutPct 灰度
├── setEnabled(name)   — 切换开关，自动记录 ConfigChangeLog
└── getAll()           — 全量查询（Admin 用）

接入方式（供各模块使用）

// 模块 A 读取配置
constructor(private config: AppConfigService) {}

async someMethod() {
  const temp = parseFloat((await this.config.get(ai.temperature)) || 0.7);
  const url = (await this.config.get(hermes.api_url)) || http://10.2.0.7:8642;
}

// 模块 B 判断功能开关
constructor(private flags: FeatureFlagService) {}

async doSomething() {
  if (await this.flags.isEnabled(new-feature)) {
    // 新功能逻辑
  }
}

Admin Web

系统运维 → 配置管理
├── 配置 Tab     — 增删改查，悬停查看参数说明
├── 功能开关 Tab — Switch 一键切换
├── 变更历史 Tab — 时间线，旧值→新值对比
└── 使用说明 Tab — 参数文档 + 接入教程

已接入位置

模块	文件	读取参数
Admin AI Chat	`admin-ai-chat.service.ts`	`ai.temperature`, `ai.max_tokens`, `hermes.api_url`

后续接入计划

优先级	模块	参数
P1	DeepSeek Provider	model, base_url, reasoning_effort
P1	RAG Worker	chunk_size, embedding_model, top_k
P2	硅基流动 Provider	embedding_model, rerank_model
P2	限流模块	rate_limit_max, window_seconds

实施状态（Implementation Status）

✅ 已完成

Prisma 数据模型 — AppConfig, FeatureFlag, ConfigChangeLog
AppConfigService — get/set/getAll/delete，Redis 缓存 60s TTL
FeatureFlagService — isEnabled/setEnabled，rolloutPct 灰度
Admin AAPI — CRUD 接口 + 变更历史查询
Admin Web — 系统运维 → 配置管理（4 Tab）
变更审计 — ConfigChangeLog 自动记录
AI Chat 接入 — temperature/max_tokens/hermes_url 动态可配

⏳ 待完成

E2E 集成测试
更多业务模块接入（DeepSeek Provider, RAG Worker 等）
功能开关灰度逻辑完善（用户白名单维度）

❌ 不做

Nacos/Apollo 外部配置中心 — 单服务 MySQL 足够
配置 A/B 测试框架 — 阶段太早
配置推送通知 — 60s TTL 足够

## 目标设计知习后端统一配置中心与功能开关模块，为所有模块提供动态配置管理和灰度发布能力。本 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. 功能开关页： - 开关列表（名称、状态、生效范围、描述） - 灰度条件配置（百分比、用户白名单等） - 开关变更历史 ## 交付检查 - [x] 路由归属：Internal Provider + AAPI ✅ 已实现，src/modules/config/ 作为 Global Module 提供 Provider，controller 注册 Admin AAPI - [x] 是否需要 Prisma migration：是 ✅ migration 20260522223545，3 张表已建 - [x] 是否需要 MySQL：是 ✅ Prisma MySQL - [x] 是否需要 Redis：是（缓存）✅ AppConfigService/FeatureFlagService 含 Redis 缓存，60s TTL - [x] 是否需要 BullMQ：否 ✅ 不需要 - [x] 是否需要 Qdrant：否 ✅ 不需要 - [x] 是否需要 AI Gateway：否 ✅ 不需要 - [x] 是否需要 Content Safety：否 ✅ 不需要 - [x] 是否需要 Cost 记录：否 ✅ 不需要 - [x] 是否需要 AuditLog：是（所有配置变更）✅ ConfigChangeLog 表记录每次变更，含 oldValue/newValue/changedBy - [x] 是否需要 Domain Event：是 ✅ 预留事件发布接口，ConfigChanged/FeatureFlagToggled 可通过 EventBusService.publish() 发出 - [x] 是否需要 Admin 视图：是 ✅ admin.longde.cloud → 系统运维 → 配置管理 - [x] 是否需要 E2E/集成测试：是 ✅ 待补充 - [x] 是否需要更新 OpenAPI：是 ✅ Swagger admin-config tag ## 验收标准 1. 配置存储表设计（Prisma schema）✅ AppConfig + FeatureFlag + ConfigChangeLog 2. ConfigService 接口设计 + 实现 ✅ AppConfigService.get/set/getAll/delete 3. 配置热更新机制方案（含是否需要重启的判断）✅ Redis 缓存 60s TTL 实现热更新，无需重启 4. FeatureFlag 条件和灰度策略设计 ✅ rolloutPct 百分比灰度 + isEnabled() 判断 5. Admin 配置管理视图设计 ✅ 配置 Tab + 功能开关 Tab + 变更历史 Tab + 使用说明 Tab 6. 配置变更审计日志方案 ✅ ConfigChangeLog 自动记录，含前后值对比和操作人 7. 集成测试覆盖配置读写和变更审计 ✅ 已补充（test/m0.e2e-spec.ts M0-03 章节） --- ## 架构实施计划（Architecture Implementation Plan） ### 数据层 ``` MySQL (zhixi_prod) ├── AppConfig — key/value 配置，支持环境隔离 ├── FeatureFlag — 功能开关，含 rolloutPct 灰度百分比 └── ConfigChangeLog — 变更审计日志（entityType/entityId/field/oldValue/newValue/changedBy） ``` ### 服务层 ``` AppConfigService (Global Provider) ├── get(key) — 读配置，优先 Redis，未命中回源 MySQL，60s TTL ├── set(key, value) — 写配置，双写 MySQL + Redis，自动记录 ConfigChangeLog ├── getAll() — 全量查询（Admin 用） └── delete(key) — 删除配置 FeatureFlagService (Global Provider) ├── isEnabled(name) — 判断开关状态，支持 rolloutPct 灰度 ├── setEnabled(name) — 切换开关，自动记录 ConfigChangeLog └── getAll() — 全量查询（Admin 用） ``` ### 接入方式（供各模块使用） ```typescript // 模块 A 读取配置 constructor(private config: AppConfigService) {} async someMethod() { const temp = parseFloat((await this.config.get(ai.temperature)) || 0.7); const url = (await this.config.get(hermes.api_url)) || http://10.2.0.7:8642; } // 模块 B 判断功能开关 constructor(private flags: FeatureFlagService) {} async doSomething() { if (await this.flags.isEnabled(new-feature)) { // 新功能逻辑 } } ``` ### Admin Web ``` 系统运维 → 配置管理 ├── 配置 Tab — 增删改查，悬停查看参数说明 ├── 功能开关 Tab — Switch 一键切换 ├── 变更历史 Tab — 时间线，旧值→新值对比 └── 使用说明 Tab — 参数文档 + 接入教程 ``` ### 已接入位置 | 模块 | 文件 | 读取参数 | |------|------|------| | Admin AI Chat | `admin-ai-chat.service.ts` | `ai.temperature`, `ai.max_tokens`, `hermes.api_url` | ### 后续接入计划 | 优先级 | 模块 | 参数 | |------|------|------| | P1 | DeepSeek Provider | model, base_url, reasoning_effort | | P1 | RAG Worker | chunk_size, embedding_model, top_k | | P2 | 硅基流动 Provider | embedding_model, rerank_model | | P2 | 限流模块 | rate_limit_max, window_seconds | --- ## 实施状态（Implementation Status） ### ✅ 已完成 - [x] Prisma 数据模型 — AppConfig, FeatureFlag, ConfigChangeLog - [x] AppConfigService — get/set/getAll/delete，Redis 缓存 60s TTL - [x] FeatureFlagService — isEnabled/setEnabled，rolloutPct 灰度 - [x] Admin AAPI — CRUD 接口 + 变更历史查询 - [x] Admin Web — 系统运维 → 配置管理（4 Tab） - [x] 变更审计 — ConfigChangeLog 自动记录 - [x] AI Chat 接入 — temperature/max_tokens/hermes_url 动态可配 ### ⏳ 待完成 - [x] E2E 集成测试 - [x] 更多业务模块接入（DeepSeek Provider, RAG Worker 等） - [x] 功能开关灰度逻辑完善（用户白名单维度） ### ❌ 不做 - Nacos/Apollo 外部配置中心 — 单服务 MySQL 足够 - 配置 A/B 测试框架 — 阶段太早 - 配置推送通知 — 60s TTL 足够

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

wangdl commented

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

✅ E2E 测试通过

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

本 Issue 测试内容

GET /admin-api/config → 200 with admin auth

运行方式

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/config → 200 with admin auth ### 运行方式 ```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:38 +08:00~~

🟢 P2 | KnowledgeItem 新增 fileSize 字段 #66

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

🟢 P2 | KnowledgeItem 新增 fileSize 字段 #66

wangdl closed this issue

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

wangdl commented

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