HAProxy 平滑重载需用 haproxy-systemd-wrapper 替代原生 reload，配合 Type=notify、ExecStart 使用 -Ws、ExecReload 发送 USR2、KillMode=mixed，确保旧进程自然退出不中断连接。
HAProxy 的平滑重载（haproxy-reload）不是靠简单执行 systemctl reload 就能实现的——默认 systemd 配置下，它大概率会卡住、超时、甚至导致连接中断。真正无损的关键，在于让旧主进程持续运行直到所有已有连接自然关闭，同时新进程接管新连接。
为什么 systemctl reload haproxy 会卡住或中断连接
systemd 默认把 reload 当作“原子替换”：它向旧主进程发 SIGUSR2 后，会等待旧进程退出（即完成 graceful shutdown），但 HAProxy 的旧主进程不会主动退出——它要等所有已建立连接（尤其是长连接）全部结束才退出。systemd 等不到，90 秒后就报 reload timeout，并可能强制杀掉旧进程，造成连接中断。
- 旧进程不退出是设计使然，不是 bug；它是“优雅重启”的核心保障
- systemd 的
Reload行为假设服务进程能快速响应 reload 并退出，HAProxy 不符合这个假设 - 直接用
kill -USR2 $PID手动触发是可行的，但无法被 systemd 正确追踪状态
必须用 haproxy-systemd-wrapper 替代原生 ExecReload
官方推荐且生产验证有效的解法，是用一个轻量 wrapper 进程作为 systemd 和 HAProxy 主进程之间的桥梁。这个 wrapper 自身永不退出，只负责 fork 新 HAProxy 进程、传递信号、等待旧进程自然退出。
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- wrapper 源码极简（C 写成，约 150 行），编译后体积小、无依赖
- 它让 systemd 认为“服务进程一直活着”，从而绕过 reload 超时逻辑
- 必须配合
Type=notify和sd_notify()使用，否则 systemd 无法感知 readiness - 安装路径建议统一为
/usr/local/bin/haproxy-systemd-wrapper，避免和系统包冲突
systemd service 文件里关键配置项怎么写
以下字段是平滑 reload 能否生效的决定性配置，缺一不可：
-
Type=notify：要求 HAProxy 或 wrapper 主动通知 systemd “已 ready”，否则 reload 会卡在启动阶段 -
ExecStart=/usr/local/bin/haproxy-systemd-wrapper -f /etc/haproxy/haproxy.cfg -p /var/run/haproxy.pid -Ws：注意-Ws启用 master-worker 模式，这是热加载前提 -
ExecReload=/bin/kill -USR2 $MAINPID：wrapper 收到该信号后，会启动新 HAProxy 并向旧主进程发SIGUSR2 -
KillMode=mixed：确保 reload 时只杀主进程，不误杀 worker 进程（否则连接中断） -
Restart=on-failure：避免因配置错误导致服务静默失败（restart会清空旧连接，reload才是目标）
验证 reload 是否真的无损的三个实操检查点
别只看 systemctl status 显示 active，要确认连接层面没丢包、没重置：
- 用
ss -tnp | grep :80观察 reload 前后，同一客户端 IP 的 ESTAB 连接是否持续存在（旧进程 PID 不变） - 开一个长连接测试：
curl -N http://your-lb/ | head -n1，reload 期间看输出是否中断；HTTP/1.1 keep-alive 连接应始终不断 - 查 stats 页面（
http://your-lb:8404/stats）或echo "show proc" | socat stdio /var/run/haproxy.sock，确认 old 和 new 两组 worker 同时存在，且 old 的active sessions缓慢归零
最容易被忽略的是：reload 后旧进程可能存活数分钟（取决于后端 Keep-Alive 超时和客户端行为），这段时间内不能删旧 pid 文件、不能改配置路径、也不能手动 kill 旧进程——它还在干活。
