Systemd环境下Gunicorn随机收TERM信号后无法重启问题求助

一、信号处理与进程退出异常排查 #

• 定位TERM信号来源：通过journalctl -u <你的systemd服务名>查看Systemd是否主动触发终止操作，比如服务重启策略、Watchdog监控触发的信号。
• 检查残留进程：问题发生后立刻执行ps aux | grep gunicorn，确认是否有未退出的worker进程——这类残留进程可能仍持有端口，导致主进程无法正常释放socket。
• 调整Gunicorn启动参数：尝试添加--preload预加载应用代码，减少子进程对socket的操作冲突；或调整--worker-connections参数，避免因连接数超限引发socket异常。

二、端口占用深层排查 #

• 精准定位占用进程：用ss -tulpn | grep :8000查看端口的实际占用者，不要只局限于Gunicorn，可能是僵尸进程或其他意外抢占的进程。
• 处理TIME_WAIT状态：如果大量连接处于TIME_WAIT，可调整系统参数（开启net.ipv4.tcp_tw_reuse，注意net.ipv4.tcp_tw_recycle在NAT环境下慎用），或修改Gunicorn的--keep-alive参数，减少不必要的长连接。
• 显式开启端口复用：在Gunicorn启动参数中添加--reuse-port，确保进程重启时可复用处于TIME_WAIT状态的端口。

三、Systemd服务配置优化 #

• 优化停止指令：将Systemd服务的ExecStop改为发送QUIT信号（更优雅的退出方式），比如配置ExecStop=/usr/bin/pkill -QUIT gunicorn，确保所有Gunicorn进程都收到退出信号。
• 调整重启策略：若当前是Restart=always，改为Restart=on-failure，避免异常退出后频繁重启加剧端口占用；同时添加RestartSec=5，给进程退出留足资源释放时间。
• 彻底杀死进程树：在服务配置中添加KillMode=mixed，确保主进程和子进程都被彻底终止，避免残留worker进程持有端口。

四、Gunicorn版本与配置调整 #

• 升级Gunicorn版本：21.2.0存在已知的socket关闭相关bug，建议升级到21.x系列的最新补丁版本，或切换到稳定的20.x版本，验证问题是否修复。
• 更换worker类型：FastAPI是ASGI应用，默认的sync worker适配性较差，建议改用uvicorn worker，启动参数为--worker-class uvicorn.workers.UvicornWorker，提升并发处理和退出稳定性。
• 开启debug日志：添加--log-level debug，获取退出时的详细日志，比如子进程退出状态、socket操作记录，帮助定位具体异常点。

五、FastAPI应用自身排查 #

• 检查未关闭资源：排查应用中是否有未正确关闭的数据库连接、文件句柄、第三方服务长连接——这些资源泄漏会导致worker进程无法正常退出，进而阻塞端口释放。
• 排查自定义信号处理：若应用中自定义了SIGTERM等信号处理函数，可能与Gunicorn的信号逻辑冲突，暂时注释后验证问题是否复现。
• 模拟优雅退出测试：手动执行kill -TERM <gunicorn主进程PID>，观察进程是否正常退出、端口是否释放，模拟生产环境的退出场景，缩小问题范围。

内容的提问来源于stack exchange，提问作者Jonathan Mugan