Go“热重启”实为父进程监听信号、启动新子进程并优雅关闭旧进程的协作机制,核心是通过syscall.Exec复用监听socket文件描述符(fd),由endless等库封装fd传递、同步与超时逻辑,http.Server.Shutdown仅负责优雅关闭,需外部进程管理配合。

Go 本身不支持进程内热重启,所谓“热重启”实际是父进程监听信号、启动新子进程、优雅关闭旧子进程的协作机制——关键不在 http.Server 本身,而在进程生命周期控制和 socket 复用。
用 syscall.Exec + 文件描述符传递实现零停机重启
核心思路是:主进程监听 SIGHUP,调用 syscall.Exec 重新执行当前二进制,并把正在监听的 net.Listener 对应的文件描述符(fd)通过环境变量或参数传给新进程;新进程从 fd 恢复 listener,避免重新 bind 端口失败。
- 旧进程必须在调用
syscall.Exec前完成所有清理,但不能关闭 listener 的 fd——否则新进程无法复用 - 需用
net.FileListener从 fd 构造新 listener,且新进程启动后要立刻接管连接,否则客户端会收到Connection refused - 推荐使用
github.com/fvbock/endless或github.com/gin-contrib/graceful等成熟封装,它们已处理了 fd 传递、父子进程同步、超时等待等细节
用 http.Server.Shutdown 实现优雅关闭(必须配合外部进程管理)
Shutdown 只负责停止接收新连接并等待已有请求完成,它本身不启动新进程,也不监听信号——必须由外部工具(如 systemd、supervisord)或自定义信号 handler 触发。
- 务必设置
ReadTimeout和WriteTimeout,否则长连接可能无限阻塞Shutdown - 调用
Shutdown后,http.Server.Serve会返回http.ErrServerClosed,此时应退出 goroutine,避免资源泄漏 - 若服务依赖全局状态(如缓存、数据库连接池),需在
Shutdown前手动清理,否则新进程可能因状态冲突异常
常见错误:直接 fork/exec 但没传递 listener fd
很多初学者尝试用 os.StartProcess 启动新进程,却忘记把 listener 的 fd 传过去,导致新进程 bind 端口时报 address already in use,而旧进程又未退出,形成双实例竞争。
- 错误写法:
exec.Command(os.Args[0], os.Args[1:]...)—— 完全没传 fd - 正确做法:用
cmd.ExtraFiles = []*os.File{listener.(*net.TCPListener).File()},并在新进程中读取os.NewFile(uintptr(3), "") - 注意 fd 编号:标准输入/输出/错误占 0/1/2,第一个额外 fd 默认是 3;不同平台行为一致,但需检查是否被其他库占用
生产环境建议:用 systemd 替代手写热重启逻辑
除非有特殊定制需求,否则更推荐交由 systemd 管理进程生命周期。配置 Restart=on-failure + ExecReload=/bin/kill -s HUP $MAINPID,再配合 Go 中的 Shutdown,即可实现可靠热更新。
- systemd 自动处理进程树、资源回收、日志重定向,比手写信号逻辑更健壮
- 需在 main 函数中注册
signal.Notify监听SIGHUP,触发Shutdown后调用os.Exit(0)让 systemd 启动新实例 - 二进制替换必须原子:先
mv new_binary old_binary,再发信号,避免中间态运行旧代码
真正容易被忽略的是 listener fd 的生命周期管理——它横跨父子进程,既不能提前 close,也不能遗漏 dup;一旦出错,表现就是端口无法复用或连接突然中断。调试时优先检查 lsof -i :PORT 和 strace -p PID -e trace=bind,listen,close。


















