Deer-Flow 的配置系统：版本化与热重载
Deer-Flow 的配置系统：版本化与热重载
学习目标
- 理解 Deer-Flow 的配置文件解析和优先级链
- 掌握配置版本检查和热重载机制
- 学会区分热重载字段和重启-required 字段
项目实践
配置优先级链
config.yaml 的解析遵循优先级链：
- 显式
config_path参数 DEER_FLOW_CONFIG_PATH环境变量config.yaml在当前目录（backend/）config.yaml在父目录（项目根目录 — 推荐位置）
配置值以 $ 开头时自动解析为环境变量（如 $OPENAI_API_KEY）。
配置版本检查
config.example.yaml 包含 config_version 字段。启动时 AppConfig.from_file() 比较用户版本与示例版本：
- 用户版本 < 示例版本 → 发出警告，提示配置可能过期
- 缺失
config_version→ 视为版本 0 make config-upgrade→ 自动合并缺失字段
热重载机制
get_app_config() 缓存解析后的配置，但自动在以下情况重载：
- 解析的配置路径发生变化
- 文件的 mtime 增加
这使得 Gateway 和 LangGraph 的读取与 config.yaml 编辑保持同步，无需手动重启。
热重载 vs 重启边界
并非所有配置字段都支持热重载。下表列出了需要重启的字段：
| 字段 | 需要重启的原因 |
|---|---|
database.* | SQLAlchemy 引擎在启动时创建连接池 |
checkpointer.* | 持久化 checkpointer 在启动时绑定 |
run_events.* | 选择内存或 SQL 支持的 RunEventStore 实现 |
stream_bridge.* | 构建 StreamBridge 对象 |
sandbox.use | Provider 单例缓存在进程启动时 |
log_level | 仅在 app.py 启动时应用 |
channels.* IM 凭证 | 渠道服务在启动时创建，不动态重建 |
运行时字段（自动热重载）：models[*].max_tokens、summarization.*、title.*、memory.*、subagents.*、tools[*]、Agent 系统提示。
设计决策：AppConfig 不在 app.state 上缓存——lifespan() 保留本地 startup_config 变量用于一次性引导工作，显式传递给 langgraph_runtime(app, startup_config)。基础设施字段重启-required。
问题与规避
配置不一致
用户修改了热重载字段但未意识到某些字段需要重启。
规避：make doctor 命令验证配置状态，启动日志中明确标注哪些变更需要重启。
环境变量未设置
配置值引用了未设置的环境变量。
规避：解析时检测未设置的环境变量，返回明确的错误信息。
参考来源
- Deer-Flow CLAUDE.md — Configuration System 章节
packages/harness/deerflow/config/— 配置系统源码