87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# 技术设计文档
|
||
|
||
## 上下文
|
||
当前系统支持从 `config.yaml` 和环境变量读取配置，环境变量可以覆盖 `config.yaml` 中的值。这种双重配置来源增加了系统的复杂性和维护成本。为了简化配置管理，需要移除环境变量支持，统一使用 `config.yaml` 作为唯一配置来源。
|
||
|
||
## 目标 / 非目标
|
||
|
||
### 目标
|
||
- 简化配置管理，统一配置来源为 `config.yaml`
|
||
- 减少代码复杂度，移除环境变量处理逻辑
|
||
- 提高配置的可追溯性和可维护性
|
||
- 确保所有配置都通过文件管理，便于版本控制
|
||
|
||
### 非目标
|
||
- 不支持配置热重载（需要重启应用）
|
||
- 不支持多环境配置文件（如 dev.yaml, prod.yaml）
|
||
- 不支持配置加密（敏感信息如 API key 以明文存储在 config.yaml 中）
|
||
|
||
## 决策
|
||
|
||
### 1. 配置来源：仅使用 config.yaml
|
||
**决策**：移除所有环境变量支持，仅从 `config.yaml` 文件读取配置
|
||
|
||
**原因**：
|
||
- 简化配置管理逻辑
|
||
- 统一配置来源，减少混淆
|
||
- 配置文件便于版本控制和审查
|
||
- 降低配置管理的认知负担
|
||
|
||
**考虑的替代方案**：
|
||
- 保留环境变量但仅用于敏感信息（如 API key）：增加了复杂性，不符合简化目标
|
||
- 支持多环境配置文件：超出当前需求范围，可以后续添加
|
||
|
||
### 2. 错误处理策略
|
||
**决策**：在配置缺失时抛出明确的异常，而不是使用默认值或静默失败
|
||
|
||
**原因**：
|
||
- 快速发现配置问题
|
||
- 避免运行时错误
|
||
- 提供清晰的错误消息指导用户修复
|
||
|
||
**考虑的替代方案**：
|
||
- 使用默认值：可能导致配置错误被忽略，不符合明确失败的原则
|
||
|
||
### 3. 代码清理范围
|
||
**决策**：删除所有环境变量相关代码，包括：
|
||
- `app/config.py` 中的 `_apply_env_overrides()` 方法
|
||
- 所有 `os.getenv()` 调用
|
||
- 启动脚本中的环境变量检查
|
||
- 文档中的环境变量说明
|
||
|
||
**原因**：
|
||
- 彻底移除功能，避免遗留代码
|
||
- 减少维护负担
|
||
- 防止未来误用
|
||
|
||
## 风险 / 权衡
|
||
|
||
### 风险
|
||
1. **迁移成本**：使用环境变量的用户需要迁移配置
|
||
- **缓解措施**：提供清晰的迁移指南和错误消息
|
||
|
||
2. **安全性**：API key 等敏感信息存储在配置文件中
|
||
- **缓解措施**：在文档中说明安全最佳实践（不要提交到版本控制）
|
||
|
||
3. **灵活性降低**：无法通过环境变量快速切换配置
|
||
- **缓解措施**：对于需要多环境配置的场景，可以后续添加多配置文件支持
|
||
|
||
### 权衡
|
||
- **简化 vs 灵活性**：选择简化，牺牲了环境变量的灵活性
|
||
- **统一 vs 多样性**：选择统一配置来源，提高可维护性
|
||
|
||
## 迁移计划
|
||
|
||
### 步骤
|
||
1. 更新代码，移除环境变量支持
|
||
2. 更新文档，说明配置迁移方法
|
||
3. 更新错误消息，提供配置指导
|
||
4. 验证所有配置项都能正确读取
|
||
|
||
### 回滚
|
||
如果需要回滚，可以恢复之前的代码，但建议用户迁移到 `config.yaml` 配置方式。
|
||
|
||
## 开放问题
|
||
无
|
||
|