Docker Compose 啟動順序怎麼等服務就緒：healthcheck 與 service_healthy

把資料庫的可用條件寫成 healthcheck#

以下 PostgreSQL 範例以 pg_isready 檢查連線能力；注意 $${...} 的雙錢號，讓 Compose 不要在解析 YAML 時先替換環境變數。

1
services:
2
  db:
3
    image: postgres:18
4
    environment:
5
      POSTGRES_USER: app
6
      POSTGRES_DB: app
7
    healthcheck:
8
      test: ['CMD-SHELL', 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
9
      interval: 10s
10
      timeout: 10s
11
      retries: 5
12
      start_period: 30s

healthcheck 應測真正的相依條件，不要只測 process 是否存在。對 Redis 可用 redis-cli ping；對 HTTP API 可用一個不需登入、能反映必要依賴的 health endpoint。

讓 app 等到健康狀態#

1
services:
2
  app:
3
    build: .
4
    depends_on:
5
      db:
6
        condition: service_healthy
7
        restart: true

service_healthy 會讓 Compose 等到 db 的 healthcheck 成功才建立 app。restart: true 的意義較窄：當你明確用 Compose 操作更新或重啟 dependency 時，依賴端也會被重啟以重新建立連線；它不是容器崩潰時的萬用修復機制。

不要把啟動等待當成連線韌性#

運行中的資料庫仍可能因網路、重啟或維護而暫時不可用。app 的 database client 仍需要適合自身協議的 timeout、重試與錯誤回應；Compose 的 healthcheck 只處理 up 當下的依賴就緒順序。

先用以下指令確認 Compose 實際解析結果與健康狀態：

1
docker compose config
2
docker compose up -d
3
docker compose ps
4
docker compose logs app db

若 stack 還分散在多個 Compose 檔，先檢查 Docker Compose include 的路徑與變數邊界；拆檔正確不會自動處理服務就緒，兩者要分開驗證。

參考資料：

Docker Docs：Control startup and shutdown order

Docker Docs：Compose healthcheck