Beego 框架原生支持优雅停机与重启,只需配置 Graceful = true 即可自动处理 SIGINT/SIGTERM(停机)和 SIGHUP(重启),内部调用 http.Server.Shutdown 并适配 context;但需手动关闭 DB、WebSocket 等非 HTTP 资源,且所有 I/O 操作必须使用带 context 的方法,否则仍会导致 shutdown 超时。

Beego 框架原生支持优雅停机与重启,无需手动接管 http.Server 或写信号监听逻辑——只要开启配置项 Graceful = true,它就会自动处理 SIGINT(Ctrl+C)、SIGTERM(kill $PID)和 SIGHUP(kill -1 $PID)信号。
Beego 的 Graceful = true 实际做了什么
开启后,Beego 会内部调用 http.Server.Shutdown(),并注册信号处理器:
-
SIGINT/SIGTERM→ 触发优雅关机:拒绝新连接,等待已有 HTTP 请求完成(含长轮询、文件上传等),再退出进程 -
SIGHUP→ 触发优雅重启:fork 新进程加载新代码,旧进程继续服务存量请求直到全部结束,然后退出 - 所有 handler 默认已适配
context.Context,包括内置的 session、cache、ORM 等模块(前提是没绕过 Beego 的 request 生命周期)
必须显式配置的两个地方
Beego 不会默认启用优雅模式,你得主动打开开关:
- 代码中设置:
beego.BConfig.Listen.Graceful = true,且必须在beego.Run()之前执行 - 或配置文件中设置(
conf/app.conf):Graceful = true,同样需在启动前加载生效 - ⚠️ 错误做法:在
beego.Run()后再赋值,此时监听已启动,信号监听器未注册,配置无效
常见失败原因:Handler 里藏着“不响应 cancel”的阻塞调用
即使 Graceful = true 开启了,shutdown 仍可能超时卡住。根本原因是 handler 内部用了无 context 控制的 I/O:
- 比如直接调
db.Query("SELECT ...")而非db.QueryContext(r.Context(), "...") - 比如用
redis.Client.Get(key)(无 context)而非redis.Client.GetWithContext(r.Context(), key) - 比如自定义中间件里起 goroutine 但没监听
r.Context().Done(),导致连接“挂着不走” - Beego 的
orm.Read()等方法默认不接受 context,需改用orm.ReadWithCtx(r.Context(), ...)(v2+ 支持)
生产环境必须补上的三件事
Beego 的优雅机制只管 HTTP 层,其他资源得你亲手关:
- DB 连接池:
orm.Close()或sql.DB.Close()必须在 shutdown 完成后、进程退出前调用;否则连接泄漏,下次启动可能连不上 - WebSocket 连接:
Graceful = true不自动关闭 ws,需在OnClose或 shutdown 阶段手动遍历beego.WebSocketManager发送websocket.CloseGoingAway - 自定义后台 goroutine:
sync.WaitGroup+context.WithCancel是标配,别让 goroutine 在 shutdown 后还活着
Beego 的优雅能力是开箱即用的,但“开箱即用”不等于“不用检查”。真正卡住 shutdown 的,永远是那些你以为“它自己会处理”的第三方调用。











