go-zero 框架通过内置的优雅停机机制实现平滑重启,核心做法是监听系统信号并在收到 sigterm 后停止接收新请求,同时等待正在处理的请求完成超时。生产环境部署时,需要配合 systemd 或 docker 等进程管理器发送信号,并合理配置 gracetime 参数以确保旧实例完全退出后再启动新实例。

如何配置优雅停机的超时时间?
在 Go-Zero 中,可以通过修改 server.ServerConfig 结构体中的 GraceTime 字段来调整平滑重启的等待时长。默认情况下,该值通常为 5 秒,如果业务逻辑处理时间较长,建议适当增加此值以防止请求被强制中断。

package main
import (
"context"
"github.com/zeromicro/go-zero/core/service"
"github.com/zeromicro/go-zero/rest"
)
func main() {
// 创建服务器配置
conf := rest.MustNewServer(rest.RestConfig{
Service: service.ServiceConfig{
Name: "my-service",
},
Host: "0.0.0.0",
Port: 8888,
// 设置优雅停机等待时间为 30 秒
GraceTime: 30 * time.Second,
})
// 注册路由
conf.AddRoute(rest.Route{
Method: http.MethodGet,
Path: "/hello",
Handler: helloHandler,
})
// 启动服务
defer conf.Stop()
conf.Start()
}
func helloHandler(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello World"))
}
上述代码展示了如何在 rest.RestConfig 中设置 GraceTime。当进程收到终止信号时,服务器将不再接受新的连接,但会允许现有的连接继续处理,直到达到设定的超时时间或所有连接关闭。预期结果是:在启动服务后,若向进程发送 SIGTERM 信号,控制台会打印出停止日志,且在 30 秒内正在处理的请求不会报错。
生产环境中如何配合进程管理器使用?
在生产环境中,通常使用 systemd 来管理 Go-Zero 应用。systemd 会在停止服务时向主进程发送 SIGTERM 信号,这正是 Go-Zero 触发优雅停机的关键。需要确保 systemd 的 TimeoutStopSec 大于等于 Go-Zero 配置的 GraceTime,以避免 systemd 强制杀死进程导致重启失败。

[Unit] Description=My Go-Zero Service After=network.target [Service] Type=simple User=www-data Group=www-data WorkingDirectory=/opt/my-service ExecStart=/opt/my-service/bin/server Restart=always RestartSec=5 # 关键配置:确保 systemd 等待时间足够长 TimeoutStopSec=35 [Install] WantedBy=multi-user.target
这段 systemd 配置文件定义了服务的运行方式。其中 TimeoutStopSec=35 表示 systemd 最多等待 35 秒来停止服务,这比 Go-Zero 内部的 30 秒 GraceTime 多出了 5 秒缓冲,确保旧实例有足够时间完成清理。预期结果是:执行 systemctl restart my-service 时,旧进程会平滑退出,新进程会在 5 秒后启动,期间服务可能短暂不可用,但不会出现因进程未完全退出而导致的端口冲突。
如果请求处理时间超过 GraceTime 会发生什么?
如果某个请求的处理时间超过了配置的 GraceTime,Go-Zero 会在超时结束后强制关闭该连接。此时客户端可能会收到连接重置或超时的错误。为了避免这种情况,应确保业务逻辑的执行时间远小于 GraceTime,或者在代码中主动检查上下文是否已取消。
ctx.Done()











