HtmlToPdf/docs/动态配置管理功能设计文档.md

动态配置管理功能设计文档

1. 需求背景

原有系统所有配置都在 appsettings.json 中进行配置，存在以下问题：

• 修改配置需要手动编辑 JSON 文件
• 修改后需要重启服务才能生效
• 首次部署没有引导流程，用户不知道如何配置

2. 需求描述

2.1 核心需求

1. 配置页面化管理 - 在管理后台可以直接编辑配置，而不是只能查看
2. 配置热加载 - 修改配置后程序能动态生效，不需要重启服务
3. 首次启动初始化向导 - 第一次部署时引导用户配置，选择启用哪些功能

2.2 关键约束

• 用户第一次启动时，必须先完成配置，配置完成后才初始化浏览器池
• 配置文件不存在即为首次启动
• 配置文件路径：./config/user-config.json
• 敏感配置不需要脱敏显示

3. 技术方案

3.1 配置存储方式

采用 覆盖模式：

• appsettings.json - 保留默认配置（开发/兜底用）
• ./config/user-config.json - 用户自定义配置，覆盖默认值

3.2 启动流程

程序启动
    ↓
检查 ./config/user-config.json 是否存在
    ↓
┌─────────────────┬─────────────────┐
│     不存在      │      存在       │
│  (首次启动)     │   (正常启动)    │
└────────┬────────┴────────┬────────┘
         ↓                  ↓
    初始化模式          正常模式
         ↓                  ↓
  只注册轻量服务      加载用户配置
         ↓                  ↓
  不初始化浏览器池    注册完整服务
         ↓                  ↓
  显示初始化向导      预热浏览器池
         ↓                  ↓
  用户完成配置        正常运行
         ↓
  保存配置文件
         ↓
  提示刷新页面

3.3 配置分类

分类	配置项	热加载支持
基础	Redis 连接、任务队列类型	需重启
性能	浏览器池参数、Worker 数量	部分支持
存储	存储类型、路径、云存储配置	需重启
安全	认证开关、限流参数	支持
回调	回调开关、重试策略	支持
监控	Prometheus、Jaeger	需重启

4. 实现清单

4.1 后端实现

配置服务层 (HtmlToPdfService.Core/Configuration/)

文件	说明
IConfigurationManager.cs	配置管理接口
FileConfigurationManager.cs	基于文件的配置管理实现
UserConfiguration.cs	用户配置模型

API 控制器 (HtmlToPdfService.Api/Controllers/)

文件	说明
SetupController.cs	初始化向导 API
ConfigController.cs	配置管理 API

中间件和服务

文件	说明
Middleware/SetupRequiredMiddleware.cs	未初始化拦截中间件
Services/ConfigurationReloadService.cs	配置热加载服务

4.2 前端实现

文件	说明
views/SetupWizard.vue	初始化向导页面
views/Settings.vue	配置管理页面（改造）
router/index.ts	路由守卫（添加）
api/index.ts	API 扩展

5. API 接口

5.1 初始化 API

接口	方法	说明
/api/setup/status	GET	检查初始化状态
/api/setup/default-config	GET	获取默认配置模板
/api/setup/test-redis	POST	测试 Redis 连接
/api/setup/test-storage	POST	测试存储配置
/api/setup/validate	POST	验证配置
/api/setup/initialize	POST	完成初始化

5.2 配置管理 API

接口	方法	说明
/api/config	GET	获取当前配置
/api/config	PUT	更新配置
/api/config/reload	POST	重新加载配置
/api/config/export	GET	导出配置文件
/api/config/import	POST	导入配置文件
/api/config/meta	GET	获取配置元信息

6. 初始化向导流程

快速模式（推荐新用户）

1. 欢迎页 - 选择配置模式
2. Redis 配置 - 连接地址、数据库、测试连接
3. 存储配置 - 类型选择、路径配置
4. 确认完成 - 配置摘要

完整模式（高级用户）

1. 欢迎页 - 选择配置模式
2. Redis 配置 - 连接地址、数据库、测试连接
3. 存储配置 - 类型选择（Local/OSS/COS）、详细参数
4. 性能配置 - 浏览器池参数、Worker 数量
5. 安全配置 - 认证开关、限流参数
6. 确认完成 - 配置摘要

7. 目录结构变更

HtmlToPdfService.Api/
├── config/                          # 新增：配置目录
│   └── user-config.json             # 用户配置文件（首次配置后生成）
├── Controllers/
│   ├── SetupController.cs           # 新增：初始化 API
│   └── ConfigController.cs          # 新增：配置管理 API
├── Middleware/
│   └── SetupRequiredMiddleware.cs   # 新增：初始化检查中间件
├── Services/
│   └── ConfigurationReloadService.cs # 新增：配置热加载服务
└── Program.cs                        # 修改：条件化服务注册

HtmlToPdfService.Core/
└── Configuration/                    # 新增：配置管理模块
    ├── IConfigurationManager.cs
    ├── FileConfigurationManager.cs
    └── UserConfiguration.cs

HtmlToPdfService.Admin/src/
├── api/
│   └── index.ts                      # 修改：添加 setupApi, configApi
├── router/
│   └── index.ts                      # 修改：添加路由守卫
└── views/
    ├── SetupWizard.vue               # 新增：初始化向导
    └── Settings.vue                  # 修改：配置编辑页面

8. 配置文件示例

{
  "version": "1.0",
  "createdAt": "2025-12-11T10:00:00Z",
  "updatedAt": "2025-12-11T10:00:00Z",
  "browserPool": {
    "maxInstances": 10,
    "minInstances": 2,
    "maxConcurrent": 5
  },
  "taskQueue": {
    "type": "Redis",
    "redis": {
      "connectionString": "192.168.195.15:6379",
      "database": 11,
      "keyPrefix": "htmltopdf:"
    },
    "workerCount": 5
  },
  "storage": {
    "type": "Local",
    "localPath": "./files",
    "retentionHours": 168
  },
  "features": {
    "pdfConversion": true,
    "imageConversion": true,
    "callback": true,
    "rateLimit": true,
    "authentication": false
  }
}

9. 注意事项

1. 首次启动必须配置 - 不完成配置无法使用转换功能
2. 部分配置需重启 - Redis 连接、存储类型等关键配置修改后需重启服务
3. 配置热加载 - 浏览器池参数、限流参数等支持运行时更新
4. 配置备份 - 建议定期导出配置文件备份