Docker Compose pre_start 怎麼用？用 init container 做啟動前準備

pre_start 的執行邊界#

pre_start 有三個值得先記住的行為：

• 每個 step 都在自己的 ephemeral container 執行，並依宣告順序完成。
• 所有 step 都以 exit code 0 結束後，主服務才會啟動；任何非零結果都會讓該服務和依賴它的服務 bring-up 失敗。
• step 可以使用父服務的 image，也可以指定另一個 image；它會在主服務 container 建立後、啟動前執行。

因此，pre_start 和「主程式啟動後再背景執行一個命令」是不同的生命週期。前者可以阻擋主服務啟動，後者不一定能保證準備工作已完成。

用 migration 與 volume 權限做一個範例#

以下範例示範兩個啟動前步驟：第一個使用 app image 執行 migration，第二個使用 BusyBox 修正共用 volume 的擁有者。manage.py、volume 路徑和 UID 都是示意，請換成專案實際命令。

1
services:
2
  app:
3
    image: example/app:latest
4
    depends_on:
5
      db:
6
        condition: service_healthy
7
    pre_start:
8
      - command: ["./manage.py", "migrate"]
9
      - image: busybox
10
        command: ["sh", "-c", "chown -R 1000:1000 /data"]
11
        user: root
12
    volumes:
13
      - app-data:/data
14

15
  db:
16
    image: postgres:16
17
    healthcheck:
18
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-postgres}"]
19
      interval: 5s
20
      timeout: 5s
21
      retries: 10
22

23
volumes:
24
  app-data:

depends_on 先等 db 通過 healthcheck，pre_start 再處理 app 的 migration 和 volume。這裡的重點是把「相依服務已就緒」與「本服務啟動前要完成的準備」分成兩個條件；如果想先理解 service_healthy，可以看 Docker Compose 的 healthcheck 與啟動順序。

pre_start、entrypoint、post_start 怎麼選#

不要把 post_start 當成 pre_start 的替代品。官方 lifecycle hooks 文件特別提醒，post-start hook 的執行時間沒有保證；如果 app 必須等 migration 完成才能提供服務，應把步驟放在真正能阻擋啟動的邊界。

重跑時機與 scaled service 的陷阱#

成功的 pre_start step 在定義沒有變化時，不會因為主服務依 restart policy 重啟就再次執行。它會在 step 定義改變、上次失敗，或 service 被重新建立時再跑。若 migration 需要每次 container restart 都執行，pre_start 可能不是正確位置。

當服務有多個 replica 時，per_replica: false 可以讓某個 step 在整個 service 只跑一次，但它只能使用 named volume 或 bind mount 這類共享資源；tmpfs 和 anonymous volume 等 per-instance mount 不能被單一 step 代表。需要每個 replica 各自準備時，則要明確評估預設的 per-replica 行為，以及命令是否具備重入性。

上線前先檢查 Compose 版本與實際模型#

先在執行部署的環境確認版本，再驗證 YAML 解析結果：

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

如果版本低於官方要求，pre_start 可能無法被目前的 Compose 實作接受；不要只在本機升級，還要檢查 CI、開發者容器和正式部署主機的 Compose 版本。docker compose config 能先把插值、合併檔和實際模型攤開，方便確認 step、volume 與 depends_on 是否真的套用。

結論：把啟動前準備寫成可驗證的 gate#

pre_start 的價值是把 init container 變成 Compose service lifecycle 的一部分：成功才啟動主服務，失敗就停止 bring-up。實作時先確認 Compose 版本，再把 dependency readiness、migration、權限與 scaled service 的執行次數分開驗證；不要只把 entrypoint 裡的長腳本原封不動搬進 YAML。

常見問題#