应优先使用 watchdog，因其基于 inotify/kqueue/ReadDirectoryChangesW 事件驱动、CPU 开销近乎为零；轮询 os.stat 在生产环境易导致性能瓶颈，仅限 inotify 不可用的特殊场景。
watch 用 watchdog 还是轮询 os.stat？watchdog 底层依赖 inotify（Linux）/kqueue（macOS）/ReadDirectoryChangesW（Windows），事件驱动，几乎零 CPU 开销；轮询靠反复调用 os.stat 检查 mtime，频率稍高（比如 100ms 一次）就会明显拖慢进程，尤其配置文件多或磁盘慢时。生产环境别碰轮询，除非你明确知道目标系统不支持 inotify（如某些容器挂载场景）且能接受延迟与开销。
-
watchdog 启动时会自动 fallback 到 polling observer（日志里会 warn），但这是保底行为，不是默认选项
- 如果用
docker run -v 挂载宿主机配置，确保挂载方式支持 inotify（Docker Desktop 默认支持，Linux 上需确认 kernel 版本 ≥ 2.6.27 且未禁用 inotify）
- 轮询的
os.stat 示例：每次检查都触发一次系统调用，10 个文件 × 10 次/秒 = 100 次/秒，而 watchdog 在无变更时基本不消耗 CPU
FileSystemEventHandler 里 reload 配置容易卡主线程
热更新本质是「监听 → 触发 reload → 应用新配置」，但很多人把整个配置解析、校验、写入全局变量的过程直接塞进 on_modified 回调里。这会导致：如果解析耗时（比如 YAML 嵌套深、含远程拉取逻辑），后续文件事件会被阻塞，甚至丢事件（watchdog 默认事件队列长度为 1024，溢出就丢）。
- 把重载逻辑移到线程或 asyncio 任务里：
threading.Thread(target=reload_config).start()
- 避免在回调里做 I/O 密集操作（如读多个文件、连数据库、调 HTTP）
- 加个简单去重：记录上次修改时间戳，
if event.event_type == 'modified' and event.src_path == CONFIG_PATH and event.timestamp > last_reload_ts 再触发
多个配置文件怎么避免重复 reload？
项目常有 app.yaml、db.yaml、logging.conf 几个文件，各自独立修改。如果每个都绑定一个 handler，改一个就 reload 全局配置三次，既浪费又可能引发竞态（比如 db 配置先加载，app 配置后加载，中间状态不一致）。
- 统一监听整个配置目录：
observer.schedule(handler, path='config/', recursive=False)
- 在
on_modified 里判断 event.src_path 是否属于已知配置路径列表，再决定是否触发完整 reload
- 更稳妥的做法：加个 debounce，比如 300ms 内收到多个修改事件，只执行最后一次后的 reload（用
threading.Timer 或 asyncio.create_task(asyncio.sleep(0.3)) 实现）
reload 时如何不中断正在处理的请求？
常见错误是 reload 直接覆盖全局字典或模块变量，比如 CONFIG = load_yaml('config.yaml')。如果此时某条请求正读到一半的 CONFIG['timeout']，而另一边 reload 已把整个 CONFIG 替换掉，可能拿到部分旧、部分新的值，或触发 KeyError。
- 用不可变结构：reload 时生成新配置对象，再原子替换引用：
global _config; _config = new_config（Python 中对全局名的赋值是原子的）
- 或者用线程本地存储（
threading.local）+ 懒加载，每个请求首次访问时读取当前 _config 快照
- 避免在 reload 过程中修改正在被读取的嵌套 dict/list —— 即使加锁，也容易让业务代码变复杂，不如换引用干净
watchdog 启动时会自动 fallback 到 polling observer（日志里会 warn），但这是保底行为，不是默认选项docker run -v 挂载宿主机配置，确保挂载方式支持 inotify（Docker Desktop 默认支持，Linux 上需确认 kernel 版本 ≥ 2.6.27 且未禁用 inotify）os.stat 示例：每次检查都触发一次系统调用，10 个文件 × 10 次/秒 = 100 次/秒，而 watchdog 在无变更时基本不消耗 CPUFileSystemEventHandler 里 reload 配置容易卡主线程
热更新本质是「监听 → 触发 reload → 应用新配置」，但很多人把整个配置解析、校验、写入全局变量的过程直接塞进 on_modified 回调里。这会导致：如果解析耗时（比如 YAML 嵌套深、含远程拉取逻辑），后续文件事件会被阻塞，甚至丢事件（watchdog 默认事件队列长度为 1024，溢出就丢）。
- 把重载逻辑移到线程或 asyncio 任务里：
threading.Thread(target=reload_config).start() - 避免在回调里做 I/O 密集操作（如读多个文件、连数据库、调 HTTP）
- 加个简单去重：记录上次修改时间戳，
if event.event_type == 'modified' and event.src_path == CONFIG_PATH and event.timestamp > last_reload_ts再触发
多个配置文件怎么避免重复 reload？
项目常有 app.yaml、db.yaml、logging.conf 几个文件，各自独立修改。如果每个都绑定一个 handler，改一个就 reload 全局配置三次，既浪费又可能引发竞态（比如 db 配置先加载，app 配置后加载，中间状态不一致）。
- 统一监听整个配置目录：
observer.schedule(handler, path='config/', recursive=False)
- 在
on_modified 里判断 event.src_path 是否属于已知配置路径列表，再决定是否触发完整 reload
- 更稳妥的做法：加个 debounce，比如 300ms 内收到多个修改事件，只执行最后一次后的 reload（用
threading.Timer 或 asyncio.create_task(asyncio.sleep(0.3)) 实现）
reload 时如何不中断正在处理的请求？
常见错误是 reload 直接覆盖全局字典或模块变量，比如 CONFIG = load_yaml('config.yaml')。如果此时某条请求正读到一半的 CONFIG['timeout']，而另一边 reload 已把整个 CONFIG 替换掉，可能拿到部分旧、部分新的值，或触发 KeyError。
- 用不可变结构：reload 时生成新配置对象，再原子替换引用：
global _config; _config = new_config（Python 中对全局名的赋值是原子的）
- 或者用线程本地存储（
threading.local）+ 懒加载，每个请求首次访问时读取当前 _config 快照
- 避免在 reload 过程中修改正在被读取的嵌套 dict/list —— 即使加锁，也容易让业务代码变复杂，不如换引用干净
observer.schedule(handler, path='config/', recursive=False)
on_modified 里判断 event.src_path 是否属于已知配置路径列表，再决定是否触发完整 reloadthreading.Timer 或 asyncio.create_task(asyncio.sleep(0.3)) 实现）CONFIG = load_yaml('config.yaml')。如果此时某条请求正读到一半的 CONFIG['timeout']，而另一边 reload 已把整个 CONFIG 替换掉，可能拿到部分旧、部分新的值，或触发 KeyError。
- 用不可变结构：reload 时生成新配置对象，再原子替换引用：
global _config; _config = new_config（Python 中对全局名的赋值是原子的） - 或者用线程本地存储（
threading.local）+ 懒加载，每个请求首次访问时读取当前_config快照 - 避免在 reload 过程中修改正在被读取的嵌套 dict/list —— 即使加锁，也容易让业务代码变复杂，不如换引用干净
配置热更新真正的难点不在监听本身，而在 reload 的时机、范围和线程安全性。inotify 机制再快，挡不住一次 yaml.load() 解析卡住 200ms，也防不住两个 handler 同时写同一个全局变量。这些细节不压平，线上就容易出现「配置改了但没生效」「服务卡顿几秒」「偶发 KeyError」之类的问题。
