This resume is also available in English.

六、實戰部署第 1 / 5 篇 · 全部目錄

專欄 › 六、實戰部署 › 第 21 篇

用 Docker Compose 部署整套微服務

Deploying a Whole Microservice System with Docker Compose

把 api-gateway、order、payment、inventory 連同 PostgreSQL、NATS、Redis 寫進一份 compose.yaml:網路隔離、健康檢查決定啟動順序、遷移當一次性工作、機密與設定分開,再談 Compose 適合做什麼、不適合做什麼。

  • Docker
  • Docker Compose
  • Microservices
  • Go
這篇的步驟
  1. 第 1 步:先畫出整個系統與目錄結構
  2. 第 2 步:一份 Dockerfile 給四個服務共用
  3. 第 3 步:寫出基礎設施——資料庫、訊息代理、快取
  4. 第 4 步:加入四個服務,並用網路決定誰看得到誰
  5. 第 5 步:設定、機密與環境檔
  6. 第 6 步:啟動順序與資料庫遷移
  7. 第 7 步:日常操作——看日誌、更新單一服務
  8. 第 8 步:用 profiles 開關開發工具與觀測工具
  9. 第 9 步:Compose 能走到哪裡,什麼時候該換
  10. 常見陷阱
  11. 重點整理
  12. 下一篇

上一篇〈效能調校:pprof 與 benchmark〉我們把單一服務的熱點找出來、量測並調快;這篇接著把視野拉回整個系統,讓四個服務一起跑起來。

在〈Docker 與 Kubernetes 部署(單一服務)〉那一篇,我們把一個 Go 服務包成映像檔:多階段建置、distroless 基底、一個 Deployment 加一個 Service。可是訂單系統拆完之後,手上其實有四個服務(api-gateway、order、payment、inventory),外加資料庫、訊息佇列(這裡用 NATS 當訊息代理)與快取。每個都能單獨 docker run,但要讓它們一起跑起來、按順序啟動、互相找得到、而且只有入口對外開放,就需要一份描述「整個系統」的檔案。

這篇要解決的問題很具體:

  • 用一份 compose.yaml 描述整套訂單系統,一個指令就能在筆電或一台主機上把它完整跑起來。
  • 服務之間怎麼用名稱找到彼此、哪些埠(port)該對外、哪些不該。
  • 資料庫還沒準備好、遷移(migration)還沒跑完時,服務不要搶先啟動。
  • 密碼不寫在檔案裡,設定與機密分開管理。
  • 只改一個服務時,怎麼只重建、只重啟那一個。
  • 觀測工具(Prometheus、Grafana、Jaeger)與開發工具需要時才開。
  • 最後誠實地談:Compose 在正式環境能做到哪裡,哪裡該交給下一篇的 Kubernetes。

本文使用的是 Compose Specification:檔名是 compose.yaml、檔案最上面不需要也不應該再寫 version:,指令是 Docker 內建的 docker compose(中間是空白,不是舊的 docker-compose)。

第 1 步:先畫出整個系統與目錄結構

動手寫 YAML 之前,先把要部署的東西列清楚。延續前面幾篇的訂單系統,執行時需要的元件如下:

元件角色對誰開放
api-gateway唯一入口:驗證、限流、路由到後端對外(主機的 8080 埠)
order建立訂單、協調 Saga、寫 Outbox只對內
payment扣款、退款,需要呼叫外部金流只對內,但需要對外連線
inventory預留與釋放庫存只對內
postgres每個服務一個獨立資料庫(同一個執行個體)只對內
nats訊息代理(啟用 JetStream 做持久化)只對內
redis快取、限流計數、冪等鍵只對內

這張表裡最重要的一欄是最後一欄。微服務在本機跑起來很容易,難的是「只開該開的門」。在 Compose 裡,這件事是用網路與埠的發佈來表達的,後面會一步一步做出來。

接著決定檔案放在哪裡。下面是一個單一儲存庫(monorepo)的配置:四個服務共用一個 Go 模組,各自在 cmd/ 底下有自己的 main,部署相關的檔案都在 deploy/,Compose 用的集中在 deploy/compose/:

shop/                               # 模組路徑 example.com/shop
├── go.mod
├── cmd/
│   ├── api-gateway/main.go
│   ├── order/main.go
│   ├── payment/main.go
│   └── inventory/main.go
├── internal/                       # 各領域的程式碼(order/、payment/、inventory/…)
├── api/proto/                      # gRPC 的 .proto
└── deploy/
    ├── docker/
    │   └── Dockerfile              # 四個服務共用,用 SERVICE 參數挑 cmd/ 底下的程式
    └── compose/
        ├── compose.yaml            # 整個系統的描述(本篇主角)
        ├── .env                    # 給 Compose 自己做變數替換用:TAG、GATEWAY_PORT
        ├── env/                    # 進到容器裡的非機密設定
        │   ├── common.env
        │   ├── api-gateway.env
        │   ├── order.env
        │   ├── payment.env
        │   └── inventory.env
        ├── secrets/                # 機密檔案,不進版本控制(.gitignore)
        │   ├── postgres_password.txt
        │   ├── order_db_password.txt
        │   ├── payment_db_password.txt
        │   └── inventory_db_password.txt
        ├── postgres/initdb/10-create-databases.sh
        └── prometheus/prometheus.yml

這個結構有三個刻意的選擇。第一,compose.yaml 裡的相對路徑(./env、./secrets)都是相對於 compose.yaml 所在的目錄,而建置內容(build context)則用 ../.. 指回儲存庫根目錄,因為 Go 的建置需要整個模組。第二,.env 與 env/*.env 是兩種不同的東西:前者是 Compose 在解析 compose.yaml 時用來替換 ${TAG} 這類變數的,後者是送進容器成為環境變數的。把它們放在不同位置,可以避免「改了 .env 卻發現容器裡沒有這個變數」的常見混淆。第三,secrets/ 獨立成一個目錄,整個加進 .gitignore,讓「哪些東西不能進版本控制」一眼就看得出來。

提示:如果你的四個服務是四個獨立的儲存庫,結構一樣成立,只是 build.context 會指向各自的路徑(例如 ../../../order),或乾脆不寫 build,直接用 CI 推上映像檔倉庫(registry)的映像檔。

第 2 步:一份 Dockerfile 給四個服務共用

〈Docker 與 Kubernetes 部署(單一服務)〉已經詳細拆解過多階段建置與 distroless,這裡只放精簡版本,重點是用建置參數(build arg)決定要編哪一個服務,四個服務就不必各維護一份幾乎一樣的 Dockerfile:

# syntax=docker/dockerfile:1
FROM golang:1.27 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG SERVICE
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/${SERVICE}

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /app/server
USER nonroot:nonroot
ENTRYPOINT ["/app/server"]
CMD ["serve"]

注意兩件事。第一,每個服務的執行檔在容器裡都叫 /app/server,所以後面的健康檢查、遷移指令可以寫成同一個形狀。第二,distroless 映像檔裡沒有 shell、沒有 curl、沒有 wget,Compose 的健康檢查不能靠 curl localhost/healthz。解法是讓程式本身多一個子指令:

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

// envOrFile 先讀 NAME_FILE 指向的檔案(Compose secrets、Kubernetes Secret 掛載),
// 沒有才讀 NAME 本身。這讓同一支程式在本機與叢集都不必改。
func envOrFile(name string) (string, error) {
	if path := os.Getenv(name + "_FILE"); path != "" {
		b, err := os.ReadFile(path)
		if err != nil {
			return "", fmt.Errorf("read %s: %w", path, err)
		}
		return strings.TrimSpace(string(b)), nil
	}
	if v := os.Getenv(name); v != "" {
		return v, nil
	}
	return "", fmt.Errorf("%s or %s_FILE is required", name, name)
}

// healthcheck 給 Compose 的 healthcheck 使用:distroless 沒有 curl,只好自己打。
func healthcheck(addr string) int {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://"+addr+"/readyz", nil)
	if err != nil {
		return 1
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Fprintln(os.Stderr, "healthcheck:", err)
		return 1
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return 1
	}
	return 0
}

func serve(addr string) error {
	if _, err := envOrFile("DB_PASSWORD"); err != nil {
		return err
	}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /livez", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })
	mux.HandleFunc("GET /readyz", func(w http.ResponseWriter, _ *http.Request) {
		// 真實服務在這裡檢查資料庫連線池、訊息代理連線是否就緒。
		w.WriteHeader(http.StatusOK)
	})
	srv := &http.Server{Addr: addr, Handler: mux, ReadHeaderTimeout: 5 * time.Second}
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		return err
	}
	return nil
}

func main() {
	cmd := "serve"
	if len(os.Args) > 1 {
		cmd = os.Args[1]
	}
	switch cmd {
	case "healthcheck":
		os.Exit(healthcheck("127.0.0.1:8080"))
	case "serve":
		if err := serve(":8080"); err != nil {
			log.Fatal(err)
		}
	default:
		fmt.Fprintln(os.Stderr, "unknown command:", cmd)
		os.Exit(2)
	}
}

這段程式只示範結構;真正的 serve 會照〈設定與優雅關閉〉那篇處理訊號與關機,migrate 子指令則呼叫〈database/sql、交易與連線池〉一篇用的遷移工具。重點是 envOrFile:它讓程式同時支援「直接給密碼」與「給一個檔案路徑」,後面的 Compose secrets 與下一篇的 Kubernetes Secret 都會用到這個慣例。

提示:healthcheck 子指令打的是 /readyz 而不是 /livez。Compose 的「健康」用來決定別人能不能開始依賴你,語意上比較接近 Kubernetes 的 readiness,而不是 liveness。

第 3 步:寫出基礎設施——資料庫、訊息代理、快取

先從「沒有依賴別人」的元件開始寫,這是 compose.yaml 的骨架。一開始就把共用的設定抽成擴充欄位(x- 開頭的頂層鍵,Compose 會忽略它們,專門拿來放 YAML 錨點):

name: shop

x-logging: &default-logging
  driver: json-file
  options:
    max-size: '10m'
    max-file: '3'

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    logging: *default-logging
    networks: [backend]
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
    secrets:
      - postgres_password
      - order_db_password
      - payment_db_password
      - inventory_db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./postgres/initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres -d postgres']
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
      start_interval: 1s

  nats:
    image: nats:2.10-alpine
    restart: unless-stopped
    logging: *default-logging
    networks: [backend]
    command: ['-js', '-sd', '/data', '-m', '8222']
    volumes:
      - natsdata:/data
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://127.0.0.1:8222/healthz']
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
      start_interval: 1s

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    logging: *default-logging
    networks: [backend]
    command: ['redis-server', '--save', '', '--appendonly', 'no']
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 5

逐項說明幾個決定:

每個服務一個資料庫,但共用一個 PostgreSQL 執行個體。 〈什麼時候該拆:邊界與拆分策略〉一篇強調過「資料各自擁有」:order 不能直接讀 inventory 的表。這個原則在部署上有三種做法:

做法隔離程度成本適合
每個服務一個 PostgreSQL最高:版本、資源、故障都獨立最高正式環境、負載差異大
同一個執行個體、分資料庫中:帳號與資料隔離,資源共用低開發、測試、小型單機部署
同一個資料庫、分 schema低:靠權限擋住跨 schema 存取最低資源非常吃緊時

在 Compose 的情境裡,第二種是很好的平衡:每個服務有自己的帳號與資料庫,沒有權限碰別人的資料,但只要跑一個 PostgreSQL 容器。關鍵是每個服務用自己的帳號,而不是全部都用 postgres 超級使用者,否則「資料各自擁有」只是口頭約定。

建立帳號與資料庫交給官方映像檔的初始化機制:/docker-entrypoint-initdb.d/ 裡的腳本會在資料目錄第一次建立時執行一次。因為密碼放在 secrets,用 shell 腳本讀出來:

#!/bin/sh
# deploy/compose/postgres/initdb/10-create-databases.sh
# 只在 pgdata volume 第一次初始化時執行。
set -eu

for svc in order payment inventory; do
  pw="$(cat "/run/secrets/${svc}_db_password")"
  psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname postgres <<SQL
CREATE ROLE ${svc} LOGIN PASSWORD '${pw}';
CREATE DATABASE ${svc} OWNER ${svc};
REVOKE ALL ON DATABASE ${svc} FROM PUBLIC;
SQL
done

健康檢查是後面一切的基礎。 pg_isready 確認 PostgreSQL 已經接受連線;NATS 的監控埠 8222 提供 /healthz,alpine 版映像檔裡有 busybox 的 wget 可用;Redis 用 redis-cli ping。start_period 是啟動寬限期,這段時間內失敗不計入重試次數;start_interval 讓寬限期內檢查得更頻繁,服務一就緒就能更快被標成健康(需要較新的 Docker Engine 與 Compose 版本才支援,舊版會忽略或報錯,遇到時拿掉即可)。

Redis 在這裡只當快取與計數器,所以關掉持久化、不掛 volume;容器重建後資料消失是預期行為。如果你把冪等鍵存在 Redis(〈冪等與分散式鎖〉),要評估遺失後的影響,必要時改開 AOF 並掛上 volume。

日誌輪替一定要設。 Docker 預設的 json-file 驅動不會自動刪舊日誌,一個吵雜的服務可以默默把主機磁碟寫滿。x-logging 錨點讓每個服務一行就套用同一組上限。

提示:映像檔版本號(postgres:17-alpine、nats:2.10-alpine 等)在本文只是示意。正式使用時請固定到你驗證過的版本,最好連 digest 一起固定,避免某天重新拉取時默默升級。

第 4 步:加入四個服務,並用網路決定誰看得到誰

基礎設施就緒後,把四個 Go 服務加進來。它們有大量相同的設定(重啟策略、日誌、健康檢查、共用環境檔),同樣抽成錨點:

x-go-service: &go-service
  restart: unless-stopped
  logging: *default-logging
  networks: [backend]
  healthcheck:
    test: ['CMD', '/app/server', 'healthcheck']
    interval: 10s
    timeout: 3s
    retries: 3
    start_period: 15s
    start_interval: 1s

services:
  order:
    <<: *go-service
    build: &order-build
      context: ../..
      dockerfile: deploy/docker/Dockerfile
      args:
        SERVICE: order
    image: shop/order:${TAG:-dev}
    env_file:
      - ./env/common.env
      - ./env/order.env
    environment:
      DB_HOST: postgres
      DB_NAME: order
      DB_USER: order
      DB_PASSWORD_FILE: /run/secrets/order_db_password
      PAYMENT_ADDR: payment:9090
      INVENTORY_ADDR: inventory:9090
      NATS_URL: nats://nats:4222
      REDIS_ADDR: redis:6379
    secrets: [order_db_password]
    depends_on:
      order-migrate:
        condition: service_completed_successfully
      nats:
        condition: service_healthy
      redis:
        condition: service_healthy

  payment:
    <<: *go-service
    build: &payment-build
      context: ../..
      dockerfile: deploy/docker/Dockerfile
      args:
        SERVICE: payment
    image: shop/payment:${TAG:-dev}
    networks: [backend, egress] # 需要連到外部金流
    env_file:
      - ./env/common.env
      - ./env/payment.env
    environment:
      DB_HOST: postgres
      DB_NAME: payment
      DB_USER: payment
      DB_PASSWORD_FILE: /run/secrets/payment_db_password
      NATS_URL: nats://nats:4222
    secrets: [payment_db_password]
    depends_on:
      payment-migrate:
        condition: service_completed_successfully
      nats:
        condition: service_healthy

  # inventory 與 payment 同一個形狀,只是沒有 egress 網路,省略。

  api-gateway:
    <<: *go-service
    build:
      context: ../..
      dockerfile: deploy/docker/Dockerfile
      args:
        SERVICE: api-gateway
    image: shop/api-gateway:${TAG:-dev}
    networks: [edge, backend]
    ports:
      - '${GATEWAY_PORT:-8080}:8080'
    env_file:
      - ./env/common.env
      - ./env/api-gateway.env
    environment:
      ORDER_ADDR: order:9090
      PAYMENT_ADDR: payment:9090
      INVENTORY_ADDR: inventory:9090
      REDIS_ADDR: redis:6379
    depends_on:
      order:
        condition: service_healthy
      payment:
        condition: service_healthy
      inventory:
        condition: service_healthy
      redis:
        condition: service_healthy

networks:
  edge: {}
  backend:
    internal: true
  egress: {}

這一步有三個核心觀念。

服務名稱就是主機名稱。 Compose 會為專案建立網路,Docker 內建的 DNS 伺服器讓同一個網路上的容器用服務名稱互相解析:order 連 postgres:5432、api-gateway 連 order:9090,完全不需要知道 IP。這就是〈服務發現與負載平衡〉一篇提到的「平台提供的服務發現」最簡單的形式。如果之後用 docker compose up --scale inventory=3 開了三份 inventory,DNS 查詢 inventory 會回傳三個位址;gRPC 客戶端用 dns:///inventory:9090 搭配 round_robin 策略,就能把請求分散到三個容器上。要注意 HTTP 用戶端若重用長連線,可能一直黏在同一個容器,這和那一篇談的情況一樣。

只有 api-gateway 發佈埠。 ports 是把容器的埠綁到主機上,只有 api-gateway 有這一行。order、payment、inventory 在容器網路裡聽 9090 與 8080,但從主機或外部都連不到。這不只是安全上的好處,也確保所有流量都經過 api-gateway 的驗證與限流,不會有人繞過入口直接打後端。

用網路切出信任區域。 這裡定義三個網路:

  • edge:api-gateway(以及之後的開發工具)在這裡,負責對外。
  • backend:所有服務與基礎設施都在這裡,設了 internal: true,代表這個網路沒有對外的路由,容器連不出去網際網路。
  • egress:只有 payment 加入,讓它能呼叫外部金流 API。

internal: true 是很實用但常被忽略的設定:就算某個依賴套件被植入惡意程式,在 backend 網路裡它也沒辦法把資料傳出去。代價是服務真的需要對外時(金流、寄信、第三方 API)要明確加入另一個網路,而這正是我們要的——對外連線變成一個看得見、需要審查的決定。

外部用戶端 主機 8080 埠(唯一發佈的埠) edge 網路 api-gateway backend 網路(internal: true,不能連外) order inventory payment 資料儲存:每個服務自己的資料庫,共用訊息代理與快取 postgres nats redis egress 網路(只有 payment 加入) 外部金流 API

圖:外部只能連到 api-gateway 的 8080 埠;後端服務與資料儲存都在不對外路由的 backend 網路,只有 payment 額外加入 egress 網路連外部金流。

depends_on 這裡刻意不照呼叫關係寫。order 執行時會呼叫 payment 與 inventory,但它的 depends_on 只列了資料庫遷移、NATS 與 Redis——這些是「沒有它就根本無法啟動」的硬性依賴。服務之間的呼叫依賴應該靠〈逾時、重試與熔斷〉那一篇的機制在執行期處理:對方暫時不在,重試或回傳錯誤,而不是讓整個系統必須以特定順序啟動。如果把呼叫圖完整複製到 depends_on,任何一個服務重啟都可能連帶卡住一串服務,而且很容易寫出循環依賴。api-gateway 依賴三個後端的健康狀態則是一種方便:在開發環境裡,等 api-gateway 能接流量時,後端一定都準備好了。

第 5 步:設定、機密與環境檔

設定分三層,各有不同的用途:

位置誰讀取放什麼進版本控制
.envCompose 解析 YAML 時TAG、GATEWAY_PORT 等替換用變數可以
env/*.env(env_file)容器內的程式日誌等級、逾時、功能旗標等非機密設定可以
environment:容器內的程式與拓樸相關的位址(order:9090)可以
secrets/(secrets)容器內的程式(讀檔)資料庫密碼、API 金鑰不可以

範例的環境檔很短,因為它們只放「每個環境可能不同、但不是機密」的值:

# deploy/compose/env/common.env —— 四個服務共用
LOG_LEVEL=info
LOG_FORMAT=json
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
SHUTDOWN_TIMEOUT=20s

# deploy/compose/env/order.env —— 只有 order 用
ORDER_SAGA_TIMEOUT=30s
OUTBOX_POLL_INTERVAL=500ms

env_file 列多個檔案時,後面的會覆蓋前面的;environment: 又會覆蓋 env_file。善用這個順序:共用預設放 common.env,服務專屬的值放自己的檔案,與 Compose 拓樸綁在一起的位址直接寫在 environment:,因為它們跟著 compose.yaml 的服務名稱走。

機密則用頂層的 secrets: 宣告,再在服務裡列出要拿哪幾個:

secrets:
  postgres_password:
    file: ./secrets/postgres_password.txt
  order_db_password:
    file: ./secrets/order_db_password.txt
  payment_db_password:
    file: ./secrets/payment_db_password.txt
  inventory_db_password:
    file: ./secrets/inventory_db_password.txt

服務列出的每個 secret 會以檔案的形式出現在容器的 /run/secrets/<名稱>。程式透過 DB_PASSWORD_FILE 讀取,也就是第 2 步的 envOrFile。每個服務只拿得到自己的密碼:order 容器裡沒有 payment 的資料庫密碼,就算 order 被攻破,也不會順便洩漏別人的憑證。

為什麼不直接用環境變數放密碼?因為環境變數很容易外洩:docker inspect 看得到、程式崩潰時的除錯輸出可能印出、子程序會繼承。檔案形式的機密至少把它們從這些管道移開。不過要誠實說明:在單機 Compose 裡,file: 型的 secret 本質上是把主機上的檔案以唯讀方式掛進容器,並沒有加密,保護的是「不要散落到不該出現的地方」,而不是「主機被入侵也安全」。主機上的 secrets/ 目錄權限要收緊(例如只有部署帳號可讀)。

提示:用 docker compose config 可以印出變數替換、錨點合併、多個檔案疊加之後的最終設定。懷疑「為什麼容器裡的值不是我想的那樣」時,第一件事就是看它。

第 6 步:啟動順序與資料庫遷移

有了健康檢查,就可以把啟動順序寫得很精確。目標是:

  1. PostgreSQL、NATS、Redis 先啟動,等到健康。
  2. 每個服務的資料庫遷移以一次性工作執行,跑完就結束。
  3. 遷移成功結束後,對應的服務才啟動,並等它健康。
  4. 三個後端都健康,api-gateway 才啟動並開始接流量。

遷移是用同一個映像檔、換一個指令的「一次性服務」:

services:
  order-migrate:
    build: *order-build
    image: shop/order:${TAG:-dev}
    command: ['migrate', 'up']
    restart: 'no'
    logging: *default-logging
    networks: [backend]
    environment:
      DB_HOST: postgres
      DB_NAME: order
      DB_USER: order
      DB_PASSWORD_FILE: /run/secrets/order_db_password
    secrets: [order_db_password]
    depends_on:
      postgres:
        condition: service_healthy
        restart: true

幾個細節值得說明:

  • build: *order-build 重用 order 的建置設定,兩者產出同一個映像檔標籤。這樣 docker compose up 不會試圖去遠端拉一個還不存在的 shop/order:dev。
  • command: ["migrate", "up"] 會接在 Dockerfile 的 ENTRYPOINT ["/app/server"] 後面,實際執行 /app/server migrate up。
  • restart: "no" 讓它跑完就停,不會被不斷重啟。
  • order 的 depends_on 寫的是 condition: service_completed_successfully:遷移的結束碼必須是 0,order 才會啟動;遷移失敗時 order 不會啟動,docker compose up 會回報錯誤,而不是讓服務在舊的資料表結構上跑。
  • 依賴 postgres 的地方加了 restart: true:之後若手動重啟 postgres,Compose 也會重啟依賴它的服務,避免殘留的壞連線。

把遷移從服務的啟動流程中拿出來,而不是在 main 一開始自動跑,有幾個好處:多個副本不會同時搶著改結構;遷移失敗時錯誤訊息集中在一個地方;在正式環境也能用相同的指令手動執行。下一篇的 Kubernetes Job 是完全相同的概念。

1 基礎設施 2 遷移(一次性) 3 服務 4 對外入口 postgres nats redis order-migrate payment-migrate inventory-migrate order payment inventory api-gateway service_healthy completed_successfully service_healthy 開始接流量 任何一步失敗,後面的容器都不會啟動

圖:基礎設施健康之後才跑遷移,遷移成功結束後才啟動服務,三個後端都健康後 api-gateway 才對外。

本篇的指令都在 deploy/compose/ 目錄下執行;從儲存庫根目錄執行時,加上 -f deploy/compose/compose.yaml 即可。實際啟動時用 --wait,讓指令一直等到所有服務都達到健康(或一次性工作成功結束)才回傳,非常適合放在 CI 的整合測試前面:

# 建置並啟動整個系統,等到全部健康才回傳
docker compose up -d --build --wait

# 看每個容器的狀態與健康程度
docker compose ps

# 只想手動再跑一次 order 的遷移
docker compose run --rm order-migrate

提示:depends_on 只管「啟動的那一刻」。系統跑起來之後如果 PostgreSQL 重啟,服務還是要有重連的能力。啟動順序是讓開發體驗順暢的工具,不能取代程式本身的韌性。

第 7 步:日常操作——看日誌、更新單一服務

系統跑起來後,日常最常做的事情是看日誌和改某一個服務。

日誌:每個服務照〈可觀測性:日誌、指標、追蹤〉一篇輸出結構化的 JSON 到標準輸出,Compose 會把所有容器的輸出集中起來,並在每一行前面標上服務名稱:

# 追蹤 order 與 payment 的最新日誌
docker compose logs -f --tail=100 order payment

# 只看最近 10 分鐘,搭配 jq 篩出錯誤
docker compose logs --since 10m --no-log-prefix order | jq -c 'select(.level == "ERROR")'

只更新一個服務:改了 order 的程式碼後,不需要重啟整個系統:

# 重建 order 的映像檔,並只重建 order 容器(不動它依賴的服務)
docker compose up -d --build --no-deps order

# 結構有變動時,先跑遷移再換服務
docker compose build order
docker compose run --rm order-migrate
docker compose up -d --no-deps order

--no-deps 很重要。少了它,Compose 會檢查並啟動 order 的所有依賴;雖然通常不會重建已經在跑的容器,但加上它能讓意圖更明確:只動這一個。另外要知道,Compose 換容器的方式是先停舊的、再起新的,中間會有短暫的空窗;api-gateway 在這段時間打 order 會失敗,要靠重試撐過去。這是 Compose 與 Kubernetes 滾動更新最大的差別之一。

開發時可以進一步用 develop.watch,讓 Compose 監看原始碼,有變動就自動重建:

services:
  order:
    develop:
      watch:
        - action: rebuild
          path: ./internal/order
        - action: rebuild
          path: ./cmd/order

接著執行 docker compose watch 就會開始監看。Go 是編譯語言,rebuild 是最直接的動作;對直譯語言才比較常用 sync 把檔案直接同步進容器。

幾個要小心的指令:

指令作用注意
docker compose stop停止容器,保留容器與資料安全
docker compose down刪除容器與網路,保留具名 volume安全,資料還在
docker compose down -v連具名 volume 一起刪資料庫資料會消失
docker compose restart重啟容器,不會重新讀取 compose.yaml改了設定要用 up -d
docker compose exec order …在執行中的容器裡跑指令distroless 沒有 shell

第 8 步:用 profiles 開關開發工具與觀測工具

有些容器不是每次都需要:資料庫管理介面、NATS 命令列工具、Prometheus、Grafana、Jaeger。把它們寫在同一份 compose.yaml,但加上 profiles,預設的 docker compose up 就不會啟動它們:

services:
  adminer:
    image: adminer:5
    profiles: [dev]
    networks: [edge, backend]
    ports:
      - '127.0.0.1:8081:8080'

  nats-box:
    image: natsio/nats-box:latest
    profiles: [dev]
    networks: [backend]
    environment:
      NATS_URL: nats://nats:4222

  prometheus:
    image: prom/prometheus:v3.5.0
    profiles: [observability]
    networks: [edge, backend]
    ports:
      - '127.0.0.1:9090:9090'
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - promdata:/prometheus

  grafana:
    image: grafana/grafana:12.1.0
    profiles: [observability]
    networks: [edge, backend]
    ports:
      - '127.0.0.1:3000:3000'
    volumes:
      - grafanadata:/var/lib/grafana

  jaeger:
    image: jaegertracing/jaeger:2.9.0
    profiles: [observability]
    networks: [edge, backend]
    ports:
      - '127.0.0.1:16686:16686'

volumes:
  pgdata: {}
  natsdata: {}
  promdata: {}
  grafanadata: {}

開發工具的埠全部綁在 127.0.0.1,只有本機瀏覽器連得到,就算這台機器有公開 IP 也不會意外暴露。這和「只有 api-gateway 對外」的原則一致:api-gateway 是給使用者的入口,其他埠只是給開發者看的窗口。

Prometheus 的抓取設定也直接用服務名稱:

# deploy/compose/prometheus/prometheus.yml
global:
  scrape_interval: 15s
scrape_configs:
  - job_name: shop
    static_configs:
      - targets:
          - api-gateway:8080
          - order:8080
          - payment:8080
          - inventory:8080

啟用的方式有兩種:

# 指令列指定
docker compose --profile dev --profile observability up -d

# 或用環境變數(也可以寫進 .env)
COMPOSE_PROFILES=observability docker compose up -d

# 一次性的工具用 run,不必常駐
docker compose --profile dev run --rm nats-box nats stream ls
預設(沒有 profile) api-gateway order・payment・inventory 三個遷移工作 postgres・nats・redis 永遠啟動 profile:dev adminer nats-box 埠只綁 127.0.0.1 profile:observability prometheus grafana jaeger 埠只綁 127.0.0.1 docker compose up --profile dev --profile observability

圖:沒有 profile 的服務永遠會啟動;dev 與 observability 兩組只在指定時加入。

這裡有個規則要遵守:預設啟動的服務不能依賴有 profile 的服務。如果 order 寫了 depends_on: jaeger,而 jaeger 只在 observability 下啟動,平常執行 up 時 Compose 會報錯。追蹤資料的匯出應該設計成「收集端不在也沒關係」:OpenTelemetry 的匯出器連不上時會丟棄資料並記錄錯誤,不會讓服務停下來。

第 9 步:Compose 能走到哪裡,什麼時候該換

把前面幾步組起來,一份 compose.yaml 就描述了完整的訂單系統:四個服務、三種基礎設施、遷移、網路隔離、機密、可選的觀測工具。它在幾個場景裡非常好用:

  • 本機開發:新加入的開發者 clone 下來,準備好 secrets/,一個指令就有完整環境。
  • CI 整合測試:docker compose up -d --wait 之後跑端到端測試,最後 docker compose down -v 清乾淨,每次都是乾淨的環境。
  • 示範與預覽環境:每個功能分支起一套,用專案名稱(-p)區隔。
  • 單機的小型正式部署:流量不大、可以接受短暫停機更新、一台主機就夠的系統。

但當系統走向正式環境,Compose 的邊界會很清楚:

需求Compose 的狀況Kubernetes 的對應
多台主機本質上是單機工具叢集排程
主機故障restart 只救得了容器,救不了主機Pod 自動排到其他節點
不停機更新先停後起,有空窗滾動更新、readiness 把關
依負載擴縮--scale 要手動,且綁埠的服務無法多開HPA 自動調整副本數
機密管理主機上的檔案,未加密Secret 搭配外部金鑰管理
服務間存取控制網路層級粗略切分NetworkPolicy 細到每個服務
回滾自己記住上一個標籤再 upkubectl rollout undo

這不代表 Compose 不能上正式環境,而是要清楚知道你接受了哪些限制:單點故障、更新時的短暫中斷、手動擴縮。如果這些都可以接受,一台主機加一份 compose.yaml 是非常簡單、好理解的架構;如果不能,就是下一篇〈在 Kubernetes 部署整套微服務〉要處理的事。值得高興的是,這一篇建立的習慣——一個映像檔多個子指令、健康檢查、遷移當一次性工作、_FILE 機密慣例、用服務名稱找彼此——在 Kubernetes 裡全部都直接沿用。

常見陷阱

  • 把 depends_on 寫成短語法。 depends_on: [postgres] 只保證容器已經啟動,不保證 PostgreSQL 已經能接受連線。一定要用長語法加上 condition: service_healthy,而且被依賴的服務要有 healthcheck,否則條件永遠等不到。
  • distroless 映像檔裡寫 curl 健康檢查。 映像檔裡沒有 curl,檢查會一直失敗,服務永遠「不健康」。改用程式內建的 healthcheck 子指令。
  • 混淆 .env 與 env_file。 .env 只給 Compose 做 ${VAR} 替換,不會自動進到容器;要讓容器拿到變數,必須透過 env_file 或 environment。
  • 以為改了 initdb 腳本會重新執行。 /docker-entrypoint-initdb.d/ 只在資料目錄是空的時候執行。volume 已經存在時要用遷移處理,或在開發環境刪掉 volume 重來。
  • 在 compose.yaml 裡寫死密碼。 這個檔案會進版本控制,密碼也就跟著進去了。用 secrets 搭配被 .gitignore 排除的檔案。
  • 到處發佈埠。 為了除錯方便替資料庫加上 ports: ["5432:5432"],又忘了拿掉,等於把資料庫綁在主機的所有介面上。真的要連,綁在 127.0.0.1 並放進 dev profile。
  • 以為 docker compose restart 會套用新設定。 它只是重啟現有容器;改了 compose.yaml 或環境檔要執行 docker compose up -d,Compose 才會比對差異並重建。
  • 手滑執行 down -v。 這會刪除具名 volume,資料庫資料一起消失。正式環境的資料要有備份,而不是只靠 volume。
  • 讓 Docker 日誌無限長大。 沒設 max-size 的 json-file 日誌會一直增長,最終寫滿磁碟。
  • 把呼叫關係全部寫進 depends_on。 造成啟動緩慢、連鎖重啟,甚至循環依賴。只寫硬性依賴,其餘靠重試與熔斷。

重點整理

  • 一份 compose.yaml(不寫 version:)描述整個系統:四個服務、PostgreSQL、NATS、Redis、遷移與可選工具。
  • 一份 Dockerfile 搭配 SERVICE 建置參數供四個服務共用;執行檔提供 serve、healthcheck、migrate 子指令。
  • 服務之間用服務名稱互相連線;只有 api-gateway 發佈埠,後端網路設 internal: true,需要連外的服務明確加入 egress 網路。
  • 每個服務擁有自己的資料庫與帳號;開發與單機環境可共用一個 PostgreSQL 執行個體。
  • 設定分層:.env 給 Compose、env_file 給容器、environment 放拓樸位址、secrets 放機密並以 _FILE 慣例讀取。
  • 啟動順序靠 depends_on 長語法:基礎設施 service_healthy → 遷移 service_completed_successfully → 服務 service_healthy → api-gateway。
  • depends_on 只列硬性依賴;服務間呼叫的暫時失敗由重試、逾時與熔斷處理。
  • 更新單一服務用 docker compose up -d --build --no-deps <服務>;用 logs -f、ps、config 觀察與除錯。
  • 開發工具與觀測工具放進 profiles,埠綁在 127.0.0.1。
  • Compose 適合本機開發、CI、預覽與小型單機部署;需要多主機、不停機更新、自動擴縮與細緻存取控制時,交給 Kubernetes。

下一篇

Compose 讓整套系統在一台主機上跑得很順,但多主機、不停機更新、自動擴縮與服務之間細緻的存取控制它都給不了。下一篇〈在 Kubernetes 部署整套微服務〉把同一套服務搬進叢集,用 Deployment、HPA、NetworkPolicy 與 Kustomize 補上這些缺口。