Go / 系统课时

完成优雅升级与发布检查

完成优雅升级与发布检查

本节把“优雅升级”落实为一条可验证的发布路径:新版本先通过启动检查,再接流量;旧版本停止接收新请求并等待在途请求结束。你还会把配置、文件描述符限制、健康检查和停止超时纳入同一份上线前检查。

学习目标

  • 实现可校验配置、启动探测和 SIGTERM 优雅退出。
  • 用一次本机演练验证健康检查、资源限制和停止流程。
  • 把升级失败、退出超时等情况转化为明确的发布门禁。

把优雅升级拆成可验证流程

这里的“优雅升级”采用多实例或负载均衡场景下的滚动发布,而不是让单个 Go 进程继承监听文件描述符。发布顺序应是:先启动新实例并确认可用,再让它进入流量池;随后把旧实例标记为停止接流量,发送 SIGTERM,等待在途请求完成后退出。

如果新实例启动失败或健康检查不通过,旧实例应继续提供服务,不要先停旧版本再尝试启动新版本。这样回滚动作就从“重新抢救旧进程”变成“撤掉未通过检查的新实例”。

滚动升级与回滚检查流程

这条流程最重要的约束是:新版本通过启动与健康检查之前,旧版本不能失去服务能力。若平台支持 readiness/draining,应优先使用平台能力;没有平台配合时,也至少要保证停止接收新请求后再进入进程退出阶段。

让进程具备可控启动与停止

下面的 HTTP 服务把三个检查点放进程序本身:启动时先解析停止超时,再绑定监听地址;绑定成功才输出可用日志;收到 SIGTERM 或 SIGINT 后调用 http.Server.Shutdown,停止接收新连接并等待正在处理的 HTTP 请求完成。

go
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)
        }
    }
}

预期结果

text
代码可成功编译;配置合法且端口可绑定时,服务进入监听状态。收到终止信号后,它会先停止接收新请求,再等待在途 HTTP 请求完成;超过 SHUTDOWN_TIMEOUT 时会强制关闭剩余连接。

这里把“配置正确”和“端口可用”都放在接流量之前。实际项目还可以加入证书、必需目录或关键依赖的启动检查,但不要让非关键外部依赖把实例永久挡在启动阶段。

在发布前做一次本机演练

网络服务的连接数最终会受到文件描述符限制影响,所以发布前至少检查 nofile 软限制是否达到团队设定的下限。下面的演练会编译服务、检查资源限制、启动实例、访问健康检查,再发送 SIGTERM 并确认进程正常退出。

bash
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

预期输出

text
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 调用,而是一组有顺序的发布条件:新版本先通过启动检查并具备接流量能力,旧版本再停止接流量并在限定时间内退出。只要把这两个阶段和资源、配置、健康检查一起固化为门禁,发布就能从“手工观察”变成可重复验证的流程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

完成优雅升级与发布检查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通