docker compose up 逐行解剖

Compose 沒有發明任何新技術。它做的事，你用 docker 指令全部都做得到——只是要打很多字，而且沒有紀錄。

對照一下就懂了

# 沒有 Compose 的世界：每次都要打這些，還要記得順序
docker network create myapp-net
docker volume create mssql-data
docker run -d --name sqlserver --network myapp-net \
  -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD=xxx \
  -p 1433:1433 -v mssql-data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest
docker run -d --name app --network myapp-net -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:sqlserver://sqlserver:1433 myapp:1.0

# 有 Compose 的世界：寫成檔案，一句指令
docker compose up -d

它的定位（很重要，避免誤用）

• Compose 是「單機」工具：所有容器跑在同一台機器上。
• 它非常適合本機開發環境、CI 的整合測試、小型單機部署。
• 但它不是正式環境的部署方案——沒有跨機器調度、沒有自動故障轉移、沒有滾動更新。那些是 Kubernetes 的工作（ch14）。

這個概念沒搞清楚，會遇到一堆詭異現象。

所有資源都會被加上專案名前綴

目錄名：myapp/

容器： myapp-sqlserver-1        ← 專案名-服務名-序號
網路： myapp_default            ← 自動建立的專屬網路
Volume：myapp_mssql-data        ← 具名 volume 也會加前綴

由此解釋三個常見困惑

1. 「我把資料夾改名，結果資料全不見了！」
   因為專案名變了 → volume 名稱從 myapp_mssql-data 變成 newname_mssql-data → 那是一個全新的空 volume。舊的資料還在，只是沒被掛上。
2. 「同一份 compose 檔複製到兩個資料夾，變成兩套獨立環境」
   對，這是特性不是 bug。想同時跑兩套（例如兩個分支）就這樣做，或用 -p 指定不同專案名。
3. 「A 專案的 app 連不到 B 專案的資料庫」
   因為各自的預設網路不同（ch07 說的網路隔離）。要跨專案連線得用 external 網路明確共用。

# 明確指定專案名（不依賴目錄名，CI 上特別有用）
docker compose -p myproject up -d

# 或寫在檔案裡
name: myproject
services:
  ...

name: myapp                          # 專案名（可省略，預設用目錄名）

services:                            # ① 服務定義（主體）
  app:
    build:                           # 用 Dockerfile 建置（與 image 二選一）
      context: .                     #   build context（ch08 那個點）
      dockerfile: Dockerfile
      args:                          #   對應 Dockerfile 的 ARG
        JAR_FILE: target/app.jar
    image: myapp:1.0                 # 建置後標記的名字；單獨用則是直接拉取
    ports:
      - '8080:8080'                  # 宿主機:容器（ch07）
    environment:                     # 環境變數（ch09 設定注入）
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:sqlserver://sqlserver:1433;databaseName=mydb
    env_file:
      - .env                         # 從檔案批次載入環境變數
    volumes:
      - ./logs:/app/logs             # bind mount（ch06）
    depends_on:                      # 啟動順序（有大坑，見下一張卡）
      sqlserver:
        condition: service_healthy
    restart: unless-stopped          # 重啟策略（ch05）
    healthcheck:                     # 健康檢查（ch05）
      test: ['CMD', 'wget', '-qO-', 'http://localhost:8080/actuator/health']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s              # Java 冷啟動一定要留
    deploy:
      resources:
        limits:                      # cgroup 上限（ch02）
          memory: 1G
          cpus: '1.5'
    networks:
      - backend

  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: 'Y'
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}   # 從 .env 展開（見下下張卡）
    volumes:
      - mssql-data:/var/opt/mssql
    networks:
      - backend

volumes:                             # ② 具名 volume 宣告（ch06）
  mssql-data:

networks:                            # ③ 網路宣告（ch07）
  backend:

幾個容易搞混的細節

• build vs image：兩者都寫時，用 build 建置，然後標記成 image 指定的名字。只寫 image 就是直接拉現成的。
• environment vs env_file：前者寫在檔案裡（會進版控，不要放密碼），後者從外部檔案讀（.env 要 gitignore）。同名時 environment 優先。
• ports vs expose：ports 是真的對外映射；expose 只是宣告（ch07）。只給其他容器用的服務不要寫 ports——資料庫不對外開，安全性直接提升一大截。
• deploy.resources：在 Swarm 模式外，docker compose 仍會套用 limits。想更明確也可以用頂層的 mem_limit、cpus。

這是 Compose 最多人誤解、也最常導致「第一次啟動失敗、重啟就好」的地方。

services:
  app:
    depends_on:
      - sqlserver      # 直覺：等資料庫好了再啟動 app

解法一：healthcheck + condition（Compose 層的正解）

services:
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    healthcheck:
      test: ['CMD-SHELL', '/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -C -Q "SELECT 1" || exit 1']
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

  app:
    depends_on:
      sqlserver:
        condition: service_healthy    # ← 關鍵：等到 healthcheck 通過才啟動

• $$ 是逃脫寫法：Compose 會展開 $VAR，寫 $$ 才能把 $ 原樣傳給容器內的 shell。這個細節卡過很多人。
• 三種 condition：service_started（預設，只等啟動）、service_healthy（等健康檢查通過）、service_completed_successfully（等它跑完並成功結束，適合初始化任務）。

解法二：應用層自己重試（真正的正解）

# Spring Boot：連線池自帶重試與健康檢查
spring:
  datasource:
    hikari:
      initialization-fail-timeout: -1   # 啟動時連不上也不要直接死，繼續重試
      connection-timeout: 30000

# 或用 Resilience4j 對外部呼叫加上重試與斷路器

把 Compose 的 healthcheck 當成「讓開發體驗順暢」的優化，把應用層重試當成「正確性的保證」。兩者並用最理想。

解法三：等待腳本（遺留做法，了解即可）

過去常見用 wait-for-it.sh、dockerize 之類的腳本，在容器啟動指令前先輪詢對方的 port。缺點是「port 開了」不等於「服務就緒」（資料庫可能還在跑復原程序），而且要在映像裡多裝東西。有 condition: service_healthy 之後已不建議。

「.env 到底是給誰用的？」——這是 Compose 最常被搞混的地方。關鍵在於分清楚「變數用在 compose 檔裡」還是「變數送進容器裡」。

第一層：.env 檔 → 給「compose 檔本身」做變數展開

# .env（放在 compose 檔旁邊，Compose 自動讀取）
MSSQL_SA_PASSWORD=YourStrong!Passw0rd
APP_PORT=8080

# docker-compose.yml
services:
  app:
    ports:
      - '${APP_PORT}:8080'          # ← 在「解析 compose 檔的當下」被替換掉

第二層：environment → 真正送進容器的環境變數

services:
  app:
    environment:
      SPRING_PROFILES_ACTIVE: dev                    # 寫死
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}        # 從 .env 取值再送進去 ✅
      DB_PASSWORD:                                   # 只寫名字 = 從 shell 環境繼承

第三層：env_file → 從檔案批次載入到容器

services:
  app:
    env_file:
      - ./config/app.env      # 這個檔案裡的每一行都會變成容器的環境變數 ✅

優先序（高到低）

1. docker compose run -e KEY=VAL（指令列）
2. compose 檔的 environment
3. env_file 指定的檔案
4. Dockerfile 裡的 ENV

兩個實用語法

${VAR:-預設值}     # VAR 沒設定或為空時使用預設值
${VAR:?錯誤訊息}   # VAR 沒設定就直接報錯中止（強制必填，很好用）
$$VAR             # 逃脫：不要展開，原樣傳給容器內的 shell

docker compose config

自動合併：docker-compose.override.yml

Compose 預設會自動讀取並合併這兩個檔案：

docker-compose.yml            # 共通設定（進版控）
docker-compose.override.yml   # 本機開發專用的覆蓋（可以 gitignore）

# docker-compose.yml —— 基礎
services:
  app:
    image: myapp:1.0
    environment:
      SPRING_PROFILES_ACTIVE: prod

# docker-compose.override.yml —— 開發時自動疊上去
services:
  app:
    build: .                          # 開發時改成本機建置
    environment:
      SPRING_PROFILES_ACTIVE: dev     # 覆蓋掉 prod
    volumes:
      - ./src:/app/src                # 開發才需要的原始碼掛載
    ports:
      - '5005:5005'                   # 遠端除錯埠

明確指定多檔（CI／不同環境用）

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
#               ↑ 基礎              ↑ 後面的覆蓋前面的

Profiles：可選的服務

services:
  app:
    image: myapp:1.0
  adminer:                # 資料庫管理介面，不是每次都要開
    image: adminer
    profiles: ['tools']
  test-runner:
    image: myapp:test
    profiles: ['test']

docker compose up -d                      # 只啟動沒有 profile 的服務（app）
docker compose --profile tools up -d      # app + adminer
docker compose --profile test up          # app + test-runner

日常工作流指令

docker compose up -d --build          # 重新建置並啟動
docker compose up -d --no-deps app     # 只重啟 app，不動它的相依服務 ⭐常用
docker compose logs -f app             # 跟隨單一服務的日誌
docker compose exec app bash           # 進某個服務的容器
docker compose ps                      # 看狀態（含 healthy 與否）
docker compose restart app             # 重啟單一服務
docker compose down                    # 停止並移除容器與網路（volume 保留）
docker compose down -v                 # 💣 連 volume 一起刪（ch06）
docker compose config                  # 印出合併後的最終設定