This resume is also available in English.

五、上線與維運第 2 / 4 篇 · 全部目錄

專欄 › 五、上線與維運 › 第 18 篇

設定與優雅關閉

Configuration and Graceful Shutdown in Go

依 12-factor 原則從環境變數、旗標與檔案讀取設定並在啟動時驗證,妥善處理密鑰;再用 signal.NotifyContext、http.Server.Shutdown 與統一的生命週期管理,讓服務在部署與縮容時不掉請求、不丟訊息。

  • Go
  • Configuration
  • Reliability
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:12-factor 的設定原則
  3. 第 2 步:讀進結構並在啟動時驗證
  4. 第 3 步:密鑰的處理
  5. 第 4 步:用 signal.NotifyContext 接收關閉訊號
  6. 第 5 步:HTTP 伺服器與消費者的優雅關閉
  7. 第 6 步:用 errgroup 簡化生命週期
  8. 第 7 步:關閉期間的 readiness 與 liveness
  9. 常見陷阱
  10. 重點整理
  11. 下一篇

上一篇〈可觀測性:日誌、指標、追蹤〉我們用日誌、指標與追蹤讓服務的狀態看得見;這篇接著處理服務生命週期的兩端:設定從哪裡來,以及結束時怎麼體面地離開。

這篇要解決什麼

這一篇處理服務生命週期的兩端:啟動時拿到正確的設定,以及結束時體面地離開。

這兩件事看起來很瑣碎,實際上卻是上線之後最常見的事故來源。設定方面,常見的情況是:資料庫位址寫死在程式裡,換環境就得重新編譯;某個環境變數拼錯了,程式照樣啟動,直到第一個請求才因為空字串而失敗;或是密碼不小心被印進日誌。關閉方面,每一次部署、每一次自動縮容、每一次節點維護,舊的執行個體都會被停掉,如果它在收到訊號後立刻結束,正在處理的下單請求就會中斷,使用者看到錯誤;正在處理的佇列訊息只做了一半,最後要靠〈冪等與分散式鎖〉的機制來收拾。

這篇的目標是:設定有單一來源、有明確優先順序、啟動時就驗證;關閉時依序停止接新工作、做完手上的工作、釋放資源,並且整個流程有時間上限。範例延續 cmd/order/main.go 的訂單服務:它有一個 HTTP API、一個消費「付款完成」事件的背景消費者,以及資料庫連線池。

第 1 步:12-factor 的設定原則

「The Twelve-Factor App」是一份廣為引用的雲端應用原則,其中關於設定的一條是:把設定存在環境裡。所謂設定,是指「在不同部署環境之間會變動的東西」,例如資料庫位址、外部服務的網址、密鑰、功能開關;而不會隨環境改變的東西(例如路由表、業務規則)屬於程式碼,不算設定。

把設定與程式碼分開有幾個直接的好處:同一個映像檔可以從測試環境一路推到正式環境,只換環境變數;不會因為忘記改某個檔案而把測試資料庫的位址帶上線;密鑰不會進入版本控制。

實務上常見的設定來源有四種,優先順序通常由高到低排列:

來源適合放什麼備註
命令列旗標本機開發、臨時覆寫會出現在程序列表,不放密鑰
環境變數大部分的部署設定容器與 Kubernetes 都原生支援
設定檔結構較複雜、較長的設定由 ConfigMap 或掛載提供
程式內預設值合理的預設讓本機開發零設定就能啟動
優先權高 命令列旗標 -addr :9090 環境變數 ORDER_ADDR 設定檔(ConfigMap 掛載) 程式內預設值 優先權低 Config 結構 合併 啟動時驗證 錯就退出

圖:越上層的來源優先權越高,最後合併成一個結構,並在啟動時一次驗證完畢。

有一個原則值得強調:設定只在啟動時讀一次,讀進一個型別明確的結構,之後全程只傳這個結構。不要在業務程式碼深處到處呼叫 os.Getenv,那樣既無法一眼看出服務需要哪些設定,也無法在啟動時統一驗證,更難寫測試。這和〈分層架構與依賴注入〉的精神一致:設定也是一種依賴,應該從 main 往下注入。

第 2 步:讀進結構並在啟動時驗證

下面這個完整範例只用標準函式庫:先放預設值,再用環境變數覆寫,最後用旗標覆寫;接著執行驗證,任何一項不合法就把所有錯誤一起印出並以非零代碼結束。

package main

import (
	"errors"
	"flag"
	"fmt"
	"log/slog"
	"net/url"
	"os"
	"strconv"
	"time"
)

// Secret 讓密鑰在日誌與 fmt 輸出時自動遮蔽。
type Secret string

func (Secret) String() string          { return "***" }
func (Secret) LogValue() slog.Value    { return slog.StringValue("***") }
func (s Secret) Reveal() string        { return string(s) }

type Config struct {
	Addr            string
	DatabaseURL     Secret
	InventoryURL    string
	ShutdownTimeout time.Duration
	MaxInFlight     int
}

func load(args []string, getenv func(string) string) (Config, error) {
	// 1. 預設值
	cfg := Config{Addr: ":8080", ShutdownTimeout: 20 * time.Second, MaxInFlight: 100}

	// 2. 環境變數覆寫
	var errs []error
	if v := getenv("ORDER_ADDR"); v != "" {
		cfg.Addr = v
	}
	cfg.DatabaseURL = Secret(getenv("ORDER_DATABASE_URL"))
	cfg.InventoryURL = getenv("ORDER_INVENTORY_URL")
	if v := getenv("ORDER_SHUTDOWN_TIMEOUT"); v != "" {
		d, err := time.ParseDuration(v)
		if err != nil {
			errs = append(errs, fmt.Errorf("ORDER_SHUTDOWN_TIMEOUT: %w", err))
		}
		cfg.ShutdownTimeout = d
	}
	if v := getenv("ORDER_MAX_IN_FLIGHT"); v != "" {
		n, err := strconv.Atoi(v)
		if err != nil {
			errs = append(errs, fmt.Errorf("ORDER_MAX_IN_FLIGHT: %w", err))
		}
		cfg.MaxInFlight = n
	}

	// 3. 旗標覆寫(只對有明確給的旗標生效)
	fs := flag.NewFlagSet("order", flag.ContinueOnError)
	fs.StringVar(&cfg.Addr, "addr", cfg.Addr, "HTTP 監聽位址")
	fs.DurationVar(&cfg.ShutdownTimeout, "shutdown-timeout", cfg.ShutdownTimeout, "優雅關閉上限")
	if err := fs.Parse(args); err != nil {
		return cfg, err
	}

	// 4. 驗證:把所有問題一次收齊
	if cfg.DatabaseURL == "" {
		errs = append(errs, errors.New("ORDER_DATABASE_URL 必填"))
	}
	if u, err := url.Parse(cfg.InventoryURL); err != nil || u.Scheme == "" || u.Host == "" {
		errs = append(errs, fmt.Errorf("ORDER_INVENTORY_URL 必須是完整網址,目前為 %q", cfg.InventoryURL))
	}
	if cfg.ShutdownTimeout <= 0 || cfg.ShutdownTimeout > 5*time.Minute {
		errs = append(errs, errors.New("shutdown timeout 必須介於 0 與 5 分鐘之間"))
	}
	if cfg.MaxInFlight < 1 {
		errs = append(errs, errors.New("ORDER_MAX_IN_FLIGHT 至少為 1"))
	}
	return cfg, errors.Join(errs...)
}

func main() {
	cfg, err := load(os.Args[1:], os.Getenv)
	if err != nil {
		fmt.Fprintln(os.Stderr, "設定錯誤:\n"+err.Error())
		os.Exit(2)
	}
	// DatabaseURL 會被印成 ***,不會外洩。
	slog.Info("config loaded", "addr", cfg.Addr, "db", cfg.DatabaseURL,
		"inventory", cfg.InventoryURL, "shutdown_timeout", cfg.ShutdownTimeout)
}

幾個設計重點:

  • load 接收 args 與 getenv 參數,而不是直接讀 os.Args 與 os.Getenv。測試時可以傳入一個 map 包成的函式,不必真的改動行程的環境變數,〈測試:表格驅動、httptest、整合測試〉介紹的表格驅動測試在這裡非常好用。
  • 驗證把所有錯誤收集起來,用 Go 1.20 起的 errors.Join 一次回傳。比起「修一個、重啟、再看下一個錯」,一次看到全部問題能省下很多時間。
  • 設定錯誤就立刻失敗(fail fast)。程式在啟動階段就以非零代碼結束,Kubernetes 會看到 Pod 不斷重啟,部署也會停在這一步,舊版本繼續服務;這比帶著錯誤設定上線、等到流量進來才出事安全得多。
  • 環境變數加上服務前綴(ORDER_),避免與其他程式或平台注入的變數撞名。

若設定結構很大,可以考慮用社群套件把環境變數自動對應到結構欄位標籤,但原則不變:單一結構、啟動時驗證、往下注入。

第 3 步:密鑰的處理

密鑰(資料庫密碼、第三方 API 金鑰、簽章用的私鑰)是一種特別的設定,除了「不寫死在程式裡」之外,還有幾條額外規則:

  1. 不進版本控制。 連範例設定檔也只放佔位字串。萬一不小心提交了,正確處理方式是立刻作廢並更換那把金鑰,而不是只把它從最新版本刪掉,因為歷史紀錄裡還在。
  2. 不進映像檔。 Dockerfile 裡用 ENV 或 COPY 放入的密鑰,任何拿得到映像檔的人都看得到,下一篇〈Docker 與 Kubernetes 部署(單一服務)〉會再提到這點。
  3. 不進日誌與錯誤訊息。 上面範例的 Secret 型別同時實作了 fmt.Stringer 與 slog.LogValuer,不論用 %v 印出或交給 slog,都只會顯示 ***。真正需要明文的地方(建立資料庫連線)才呼叫 Reveal(),讓「使用明文」變成程式碼裡看得見、搜得到的動作。
  4. 優先用檔案掛載,而不是環境變數。 環境變數會被子程序繼承,也可能出現在當機時的除錯資訊裡。Kubernetes 的 Secret 可以掛成唯讀檔案,程式讀取檔案內容,也方便在不重啟的情況下輪替。一個常見慣例是支援 ORDER_DATABASE_URL_FILE:有給檔案路徑時讀檔,否則讀環境變數。
  5. 最小權限與輪替。 每個服務只拿自己需要的密鑰;金鑰要能定期更換,程式要能接受新舊金鑰並存一段時間。

提示:Kubernetes 的 Secret 預設只是 base64 編碼,不是加密。是否在 etcd 中加密、誰能讀取 Secret,是叢集管理者要另外設定的事;更嚴格的環境會改接外部的密鑰管理服務。

第 4 步:用 signal.NotifyContext 接收關閉訊號

接著處理生命週期的另一端。在容器環境中,平台要停掉一個程序時,會先送 SIGTERM,等待一段寬限時間(Kubernetes 預設 30 秒),時間到了還沒結束才送 SIGKILL 強制終止。SIGKILL 無法被攔截,所以程式必須在寬限時間內自己完成收尾。本機開發按 Ctrl+C 則會送出 SIGINT。

Go 1.16 起的 signal.NotifyContext 把「收到訊號」轉換成「context 被取消」,這讓關閉訊號可以跟〈context:取消、逾時與資料傳遞〉學到的取消機制無縫接軌:

// 片段
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

此後只要收到這兩種訊號,ctx.Done() 就會關閉。所有長時間執行的元件(HTTP 伺服器、消費者、定時工作)都從這個 ctx 衍生,就會一起收到「該結束了」的通知。stop() 的作用是恢復訊號的預設行為:第一次 Ctrl+C 觸發優雅關閉之後,如果關閉卡住,使用者再按一次就能直接結束程式,而不是被無限期攔截。

第 5 步:HTTP 伺服器與消費者的優雅關閉

http.Server.Shutdown(ctx) 是標準函式庫內建的優雅關閉:它先關閉監聽埠,不再接受新連線,接著關閉閒置連線,然後等待所有進行中的請求處理完畢才回傳。傳入的 ctx 是等待的上限,逾時就回傳錯誤,此時可以再呼叫 Close() 強制關閉剩下的連線。

需要注意的是,ListenAndServe 在 Shutdown 被呼叫後會立刻回傳 http.ErrServerClosed,這不代表請求已經處理完。所以 main 不能在 ListenAndServe 回傳後就結束,必須等 Shutdown 本身回傳。

背景消費者的關閉原則相同:先停止拉新訊息,再把手上這一則處理完並確認(ack),最後才結束。如果在處理到一半時被中斷,訊息不會被確認,佇列稍後會重新投遞;只要消費端如〈冪等與分散式鎖〉所說是冪等的,重複處理也不會出錯。但優雅關閉能讓這種情況盡量少發生。

下面的完整範例把 HTTP 伺服器、模擬的消費者與資源清理串成一個統一的生命週期。每個元件在自己的 goroutine 中執行,任何一個出錯都會觸發整體關閉,關閉時按順序執行收尾,整體有時間上限:

package main

import (
	"context"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"sync"
	"sync/atomic"
	"syscall"
	"time"
)

// consume 模擬佇列消費者:ctx 取消後不再取新訊息,但會把手上這則做完。
func consume(ctx context.Context, msgs <-chan string) error {
	for {
		select {
		case <-ctx.Done():
			slog.Info("consumer: stop fetching")
			return nil
		case m := <-msgs:
			// 用獨立的 context 處理,避免關閉訊號打斷處理到一半的訊息。
			work, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
			err := handle(work, m)
			cancel()
			if err != nil {
				return fmt.Errorf("handle %s: %w", m, err)
			}
		}
	}
}

func handle(ctx context.Context, m string) error {
	select {
	case <-time.After(300 * time.Millisecond):
		slog.Info("consumer: acked", "msg", m)
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	var ready atomic.Bool
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
		w.WriteHeader(http.StatusOK) // liveness:程序還活著就回 200
	})
	mux.HandleFunc("GET /readyz", func(w http.ResponseWriter, _ *http.Request) {
		if !ready.Load() {
			http.Error(w, "draining", http.StatusServiceUnavailable)
			return
		}
		w.WriteHeader(http.StatusOK)
	})
	mux.HandleFunc("POST /orders", func(w http.ResponseWriter, _ *http.Request) {
		time.Sleep(500 * time.Millisecond) // 模擬寫資料庫、呼叫庫存服務
		w.WriteHeader(http.StatusCreated)
	})
	srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}

	msgs := make(chan string)
	go func() { // 模擬佇列不斷送來「付款完成」事件
		for i := 0; ; i++ {
			select {
			case msgs <- fmt.Sprintf("payment-%d", i):
			case <-ctx.Done():
				return
			}
		}
	}()

	// 生命週期:任一元件失敗就取消 runCtx,讓其他元件一起收尾。
	runCtx, cancel := context.WithCancelCause(ctx)
	var wg sync.WaitGroup
	run := func(name string, fn func() error) {
		wg.Add(1)
		go func() {
			defer wg.Done()
			if err := fn(); err != nil {
				cancel(fmt.Errorf("%s: %w", name, err))
			}
		}()
	}

	run("http", func() error {
		if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
			return err
		}
		return nil
	})
	run("consumer", func() error { return consume(runCtx, msgs) })
	ready.Store(true)
	slog.Info("started", "addr", srv.Addr)

	<-runCtx.Done()
	slog.Info("shutting down", "cause", context.Cause(runCtx))

	// 1. 先讓 readiness 失敗,給負載平衡器時間把自己移出名單。
	ready.Store(false)
	time.Sleep(2 * time.Second) // 正式環境依平台的端點更新延遲調整

	// 2. 整體關閉有上限,必須小於平台的寬限時間。
	shutdownCtx, done := context.WithTimeout(context.Background(), 20*time.Second)
	defer done()
	if err := srv.Shutdown(shutdownCtx); err != nil {
		slog.Error("http shutdown", "err", err)
		_ = srv.Close()
	}

	// 3. 等所有元件結束(消費者把手上的訊息做完)。
	finished := make(chan struct{})
	go func() { wg.Wait(); close(finished) }()
	select {
	case <-finished:
	case <-shutdownCtx.Done():
		slog.Error("components did not stop in time")
	}

	// 4. 最後才關閉共用資源:資料庫連線池、TracerProvider、日誌緩衝。
	slog.Info("bye")
	if err := context.Cause(runCtx); err != nil && !errors.Is(err, context.Canceled) {
		os.Exit(1)
	}
}

這個結構有幾個值得注意的地方。消費者處理單則訊息時用 context.WithoutCancel(ctx) 另外包一個有逾時的 context:關閉訊號只用來停止「取新訊息」,不會打斷正在處理的那一則,但處理本身仍然有上限,不會無限期拖住關閉。context.WithCancelCause 讓我們在日誌裡記下是哪個元件、因為什麼原因觸發關閉,排查時很有用。最後一步才關閉共用資源,因為前面的元件在收尾時還需要它們:如果先關掉資料庫連線池,正在處理的請求就會在最後一刻失敗。

第 6 步:用 errgroup 簡化生命週期

上面手寫的 run 函式其實就是 golang.org/x/sync/errgroup 的核心功能:errgroup.WithContext 回傳一個 group 與衍生的 ctx,任何一個 g.Go 回傳錯誤時,ctx 會被取消,g.Wait() 回傳第一個錯誤。用它改寫,主程式會更簡潔:

// 片段:使用 golang.org/x/sync/errgroup
g, gctx := errgroup.WithContext(ctx)

g.Go(func() error {
	if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
		return err
	}
	return nil
})
g.Go(func() error { return consume(gctx, msgs) })
g.Go(func() error {
	<-gctx.Done() // 收到訊號或其他元件失敗
	ready.Store(false)
	time.Sleep(2 * time.Second)
	sctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	return srv.Shutdown(sctx)
})

if err := g.Wait(); err != nil {
	slog.Error("exit", "err", err)
	os.Exit(1)
}

注意「負責關閉 HTTP 伺服器」的那個 goroutine 也是 group 的一員,它等待 gctx.Done() 再執行收尾。這種「每個元件都有一個執行函式和一個關閉函式,全部交給同一個 group」的寫法,讓新增元件(例如一個 gRPC 伺服器、一個 Outbox 轉送程式)時,只要照同樣的模式加兩段即可。

第 7 步:關閉期間的 readiness 與 liveness

在 Kubernetes 上,優雅關閉還牽涉到平台的流量切換時機。Pod 被刪除時,「送 SIGTERM 給容器」與「把 Pod 從 Service 的端點名單移除」是同時開始、各自進行的。端點名單的更新要傳到每個節點的 kube-proxy 或負載平衡器需要一點時間,在這段時間裡,仍然可能有新請求被送到已經開始關閉的 Pod。如果程式收到 SIGTERM 就立刻關閉監聽埠,這些請求就會遇到連線被拒。

這就是範例裡「先讓 readiness 失敗,再等幾秒」的原因。兩種探針的角色要分清楚:

探針問的問題失敗時平台的動作關閉期間應該
liveness程序還活著嗎?是否卡死?重啟容器繼續回 200,否則可能在收尾途中被重啟
readiness現在可以接新流量嗎?從 Service 端點移除,不重啟回 503,讓流量提早移走

另一個常見做法是在 Pod 規格裡設定 preStop,讓平台在送出 SIGTERM 之前先等幾秒,效果類似,而且不需要改程式:

spec:
  terminationGracePeriodSeconds: 30 # 必須大於 preStop + 程式內的關閉上限
  containers:
    - name: order
      lifecycle:
        preStop:
          sleep:
            seconds: 5 # Kubernetes 1.30 起支援;舊版可用 exec 執行 sleep
      readinessProbe:
        httpGet: { path: /readyz, port: 8080 }
        periodSeconds: 5
      livenessProbe:
        httpGet: { path: /healthz, port: 8080 }
        periodSeconds: 10
SIGTERM/Pod 刪除 寬限時間到 → SIGKILL readyz 回 503 等端點移除 preStop/sleep Shutdown 停止接新連線 消費者停止拉取 完成手上工作 請求、訊息 ack 釋放資源 連線池、追蹤 每段總和必須小於 terminationGracePeriodSeconds

圖:從收到 SIGTERM 到程序結束,每一段都要在平台的寬限時間內完成,否則會被 SIGKILL 強制終止。

時間預算要算清楚:preStop 等待時間+端點移除緩衝+Shutdown 的上限+清理資源的時間,總和必須小於 terminationGracePeriodSeconds。若最長的請求可能需要 30 秒,寬限時間就要相應放寬,而不是讓請求在中途被殺掉。

常見陷阱

  • 到處呼叫 os.Getenv。 設定散落各處,無法一次驗證,也看不出服務依賴哪些變數。統一在 main 讀進結構再注入。
  • 缺值時默默用空字串。 必填設定沒給就應該在啟動時失敗,而不是等到第一個請求才發現。
  • 密鑰出現在日誌或錯誤訊息。 把整個設定結構用 %+v 印出來是最常見的外洩途徑;用專用型別遮蔽。
  • 把 ListenAndServe 回傳當成關閉完成。 它在 Shutdown 被呼叫後立即回傳,必須等 Shutdown 回傳才能確定請求都處理完。
  • 用 context.Background() 呼叫 Shutdown 卻沒有上限。 某個長連線不結束,程式就會一直等到被 SIGKILL,最後的清理全部沒做。
  • 用已取消的 ctx 做收尾。 收到訊號後 ctx 已經取消,若把它傳給資料庫或 Shutdown,收尾動作會立即失敗;收尾要用新的、有逾時的 context。
  • 關閉順序顛倒。 先關資料庫或訊息連線,再等請求處理完,進行中的請求會在最後一刻失敗。順序應該是:停止接新工作 → 完成手上工作 → 釋放共用資源。
  • liveness 探針檢查外部依賴。 資料庫短暫斷線時,所有 Pod 的 liveness 一起失敗、一起被重啟,問題反而擴大。外部依賴的狀態適合放在 readiness,或只反映在指標上。
  • 忽略長連線。 WebSocket、Server-Sent Events 或串流 gRPC 不會因為 Shutdown 而自動結束,需要用 RegisterOnShutdown 或自己的訊號通知它們收尾。

重點整理

  • 設定是「隨部署環境變動的值」,依 12-factor 原則放在環境中;來源優先順序通常是旗標 > 環境變數 > 設定檔 > 預設值。
  • 啟動時把設定讀進單一結構、一次驗證所有欄位、有錯就以非零代碼退出,再往下注入。
  • 密鑰不進版本控制、不進映像檔、不進日誌;用遮蔽型別、檔案掛載與最小權限處理。
  • signal.NotifyContext 把 SIGTERM/SIGINT 轉成 context 取消,讓所有元件共用同一個關閉通知。
  • 關閉順序:readiness 先失敗 → 等待流量移走 → http.Server.Shutdown 與消費者停止拉取 → 完成進行中的工作 → 關閉資料庫、追蹤等共用資源。
  • 用 errgroup(或等效的 WaitGroup+取消)統一管理元件生命週期,任一元件失敗都觸發整體關閉。
  • 所有關閉步驟的時間總和要小於 terminationGracePeriodSeconds;liveness 在關閉期間保持成功,readiness 則回報 503。

下一篇

到這裡,服務會讀設定、會優雅關閉,也準備好了 /healthz 與 /readyz,但它還只是一個在本機執行的程式。〈Docker 與 Kubernetes 部署(單一服務)〉會把訂單服務打包成小而安全的映像檔,再用 Kubernetes 的探針與寬限時間把這篇的關閉流程真正接上平台。