asyncio热重启不能用SIGUSR1,因默认事件循环不处理该信号且add_signal_handler仅支持主线程;应改用文件监听+子进程触发优雅关闭再由进程管理器拉起新实例。

asyncio进程热重启为什么不能直接用signal.SIGUSR1?
因为asyncio默认事件循环不处理SIGUSR1(Linux/macOS)或SIGHUP(部分守护场景),调用loop.add_signal_handler()也仅支持主线程,而生产中常使用uvloop或子进程托管——这时信号会被内核直接发给主进程,但事件循环可能正阻塞在epoll_wait或kqueue里,根本收不到。
真正可行的路径是:绕过信号,改用进程间通信触发优雅关闭再拉起新实例。常见错误是试图在asyncio.run()外重置asyncio.get_event_loop(),这会导致RuntimeError: asyncio.run() cannot be called from a running event loop。
用文件锁+子进程实现零停机热重启
核心思路是让主进程监听一个控制文件的修改时间,子进程负责更新它;主进程检测到变更后,启动 graceful shutdown 流程,等所有 pending task 完成后再退出,由外部进程管理器(如 systemd、supervisord 或自研 wrapper)拉起新实例。
- 控制文件路径必须可被所有相关进程读写,推荐
/var/run/myapp/reload.trigger,权限设为644 - 主进程需用
asyncio.to_thread()轮询os.path.getmtime(),避免阻塞事件循环;间隔建议1.0秒,太短加重IO,太长响应延迟高 - 收到 reload 信号后,立即调用
loop.create_task(shutdown()),并在shutdown()中取消未完成的asyncio.Task,等待timeout(如30秒)后强制退出 - 不要在
shutdown()里调用loop.stop()或sys.exit()——交给进程管理器收尾更可靠
systemd配置要显式启用Restart=on-failure且禁用Type=simple
如果用Type=simple,systemd认为进程一启动就“就绪”,热重启时旧进程还没退出,新进程就被kill掉;正确做法是:
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
- 设
Type=notify,并在主进程启动后调用sd_notify("READY=1")(需systemd-python或直接写/run/systemd/notifysocket) -
Restart=on-failure确保崩溃重启,但热重启依赖ExecReload=/bin/sh -c 'touch /var/run/myapp/reload.trigger' - 加
RestartSec=1避免密集重启,StartLimitIntervalSec=0禁用启动频率限制(否则连续reload会触发throttle)
漏掉NotifyAccess=all会导致sd_notify调用失败,日志报Failed to send notification message: Permission denied。
用aiofiles+watchdog替代轮询更省资源但有兼容代价
轮询简单但每秒一次stat开销在高负载机器上不可忽视;改用watchdog监听文件系统事件更高效,但要注意:
-
watchdog底层依赖inotify(Linux)或kqueue(macOS),容器环境若挂载为shared或slavepropagation,事件可能无法透传到容器内 - 必须用
AsyncIOEventLoop适配器,否则回调仍在主线程执行,会阻塞事件循环 -
aiofiles适合读写trigger文件内容(比如写入版本号做幂等校验),但别用它做高频日志——异步文件IO在Linux上实际仍是线程池模拟,不如logging.handlers.RotatingFileHandler稳定
热重启不是“换掉event loop”,而是换掉整个Python进程实例。任何试图在单个进程中反复启停asyncio.run()的方案,在生产中都会因资源泄漏、FD未释放、SSL上下文残留等问题逐渐退化。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










