222 lines
6.9 KiB
Markdown
222 lines
6.9 KiB
Markdown
# 动态配置管理功能设计文档
|
||
|
||
## 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. 配置文件示例
|
||
|
||
```json
|
||
{
|
||
"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. **配置备份** - 建议定期导出配置文件备份
|
||
|