videoSummary/openspec/changes/remove-env-var-config/design.md

技术设计文档

上下文

当前系统支持从 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 配置方式。

开放问题

无