Go / 系统课时
完成优雅升级与发布检查
完成优雅升级与发布检查
本节把“优雅升级”落实为一条可验证的发布路径:新版本先通过启动检查,再接流量;旧版本停止接收新请求并等待在途请求结束。你还会把配置、文件描述符限制、健康检查和停止超时纳入同一份上线前检查。
学习目标
- 实现可校验配置、启动探测和
SIGTERM优雅退出。 - 用一次本机演练验证健康检查、资源限制和停止流程。
- 把升级失败、退出超时等情况转化为明确的发布门禁。
把优雅升级拆成可验证流程
这里的“优雅升级”采用多实例或负载均衡场景下的滚动发布,而不是让单个 Go 进程继承监听文件描述符。发布顺序应是:先启动新实例并确认可用,再让它进入流量池;随后把旧实例标记为停止接流量,发送 SIGTERM,等待在途请求完成后退出。
如果新实例启动失败或健康检查不通过,旧实例应继续提供服务,不要先停旧版本再尝试启动新版本。这样回滚动作就从“重新抢救旧进程”变成“撤掉未通过检查的新实例”。

这条流程最重要的约束是:新版本通过启动与健康检查之前,旧版本不能失去服务能力。若平台支持 readiness/draining,应优先使用平台能力;没有平台配合时,也至少要保证停止接收新请求后再进入进程退出阶段。
让进程具备可控启动与停止
下面的 HTTP 服务把三个检查点放进程序本身:启动时先解析停止超时,再绑定监听地址;绑定成功才输出可用日志;收到 SIGTERM 或 SIGINT 后调用 http.Server.Shutdown,停止接收新连接并等待正在处理的 HTTP 请求完成。
package main
import (
"context"
"errors"
"log"
"net"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func envOr(key, fallback string) string {
if value := os.Getenv(key); value != "" {
return value
}
return fallback
}
func main() {
log.SetFlags(0)
addr := envOr("LISTEN_ADDR", ":8080")
rawTimeout := envOr("SHUTDOWN_TIMEOUT", "10s")
shutdownTimeout, err := time.ParseDuration(rawTimeout)
if err != nil || shutdownTimeout <= 0 {
log.Fatalf("invalid SHUTDOWN_TIMEOUT=%q", rawTimeout)
}
// 先绑定端口,绑定失败时直接阻止实例进入可用状态。
listener, err := net.Listen("tcp", addr)
if err != nil {
log.Fatalf("startup check failed: listen %s: %v", addr, err)
}
mux := http.NewServeMux()
mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok\n"))
})
server := &http.Server{
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
IdleTimeout: 30 * time.Second,
}
signalCtx, stop := signal.NotifyContext(
context.Background(),
os.Interrupt,
syscall.SIGTERM,
)
defer stop()
errCh := make(chan error, 1)
go func() {
log.Printf("listening on %s", addr)
errCh <- server.Serve(listener)
}()
select {
case <-signalCtx.Done():
log.Print("shutdown: stop accepting")
// 超时后不再无限等待,避免发布流程被旧实例永久卡住。
shutdownCtx, cancel := context.WithTimeout(
context.Background(),
shutdownTimeout,
)
err := server.Shutdown(shutdownCtx)
cancel()
if err != nil {
log.Printf("shutdown timeout: %v", err)
_ = server.Close()
}
serveErr := <-errCh
if serveErr != nil && !errors.Is(serveErr, http.ErrServerClosed) {
log.Fatalf("serve failed: %v", serveErr)
}
log.Print("shutdown complete")
case serveErr := <-errCh:
if serveErr != nil && !errors.Is(serveErr, http.ErrServerClosed) {
log.Fatalf("serve failed: %v", serveErr)
}
}
}预期结果
代码可成功编译;配置合法且端口可绑定时,服务进入监听状态。收到终止信号后,它会先停止接收新请求,再等待在途 HTTP 请求完成;超过 SHUTDOWN_TIMEOUT 时会强制关闭剩余连接。这里把“配置正确”和“端口可用”都放在接流量之前。实际项目还可以加入证书、必需目录或关键依赖的启动检查,但不要让非关键外部依赖把实例永久挡在启动阶段。
在发布前做一次本机演练
网络服务的连接数最终会受到文件描述符限制影响,所以发布前至少检查 nofile 软限制是否达到团队设定的下限。下面的演练会编译服务、检查资源限制、启动实例、访问健康检查,再发送 SIGTERM 并确认进程正常退出。
go build -o server main.go
MIN_NOFILE=1024
SOFT_NOFILE=$(ulimit -Sn)
printf 'nofile_soft=%s\n' "$SOFT_NOFILE"
case "$SOFT_NOFILE" in
unlimited) ;;
''|*[!0-9]*)
echo "unrecognized nofile limit" >&2
exit 1
;;
*)
if [ "$SOFT_NOFILE" -lt "$MIN_NOFILE" ]; then
echo "nofile limit is below $MIN_NOFILE" >&2
exit 1
fi
;;
esac
LISTEN_ADDR=:8080 SHUTDOWN_TIMEOUT=5s ./server >server.log 2>&1 &
PID=$!
HEALTH=
for _ in 1 2 3 4 5 6 7 8 9 10; do
if HEALTH=$(curl -fsS http://127.0.0.1:8080/healthz 2>/dev/null); then
break
fi
sleep 0.2
done
test "$HEALTH" = "ok"
printf 'health=%s\n' "$HEALTH"
kill -TERM "$PID"
wait "$PID"
cat server.log预期输出
nofile_soft=<LIMIT>
health=ok
listening on :8080
shutdown: stop accepting
shutdown complete<LIMIT> 是当前 Shell 的实际软限制,可能是数值,也可能是 unlimited。生产环境若由 systemd、容器或编排平台启动服务,还要检查它们施加的限制,因为交互式 Shell 的 ulimit 不一定等于服务进程最终拿到的限制。
把检查项收敛为发布门禁
发布检查不应停留在“看起来能启动”。可以把上线前后检查压缩成下面四类,只要任一关键项失败,就不要继续淘汰旧实例。
| 检查点 | 通过条件 | 失败动作 |
|---|---|---|
| 配置 | 必填项可解析,超时等数值范围合法 | 阻止新实例启动 |
| 资源 | nofile 等限制满足预估并留有余量 |
调整运行环境后重发 |
| 启动 | 端口绑定成功,进程未立即退出 | 保留旧实例并回滚 |
| 健康 | 新实例在规定窗口内通过 readiness/health 检查 | 不加入流量池 |
| 停止 | 旧实例在停止超时内退出,连接与请求无异常激增 | 暂停继续滚动并排查 |
对于高并发 TCP 服务,还应在发布时观察活动连接数、文件描述符使用量、请求错误率和退出耗时。重点不是收集更多指标,而是确认“新实例已经能接流量”和“旧实例已经安全退出”这两个状态都可证实。
识别优雅退出的边界
http.Server.Shutdown 会关闭监听器、处理空闲连接,并等待活跃 HTTP 请求结束,但它不会替你管理所有长连接语义。WebSocket、被 Hijack 接管的连接、原生 TCP 会话或自定义协议,都应由应用自己登记连接,在进入 draining 后拒绝新会话,并在超时前主动通知或关闭仍未结束的连接。
因此,优雅升级不是单个 Shutdown 调用,而是一组有顺序的发布条件:新版本先通过启动检查并具备接流量能力,旧版本再停止接流量并在限定时间内退出。只要把这两个阶段和资源、配置、健康检查一起固化为门禁,发布就能从“手工观察”变成可重复验证的流程。