實戰：用 Compose 搭一整套開發環境

架構

              你的電腦（宿主機）
 ┌──────────────────────────────────────────┐
 │  localhost:8080 ──┐   localhost:1433 ──┐ │
 └───────────────────┼────────────────────┼─┘
                     │  port mapping      │
 ┌───────────────────┼────────────────────┼─┐
 │ myapp_default 網路（Compose 自動建立）   │
 │   ┌──────────┐   ┌────────────┐  ┌──────┐│
 │   │   app    │──→│ sqlserver  │  │ redis││
 │   │ (Spring) │──────────────────→│      ││
 │   └──────────┘   └─────┬──────┘  └───┬──┘│
 └────────────────────────┼─────────────┼───┘
                    mssql-data      redis-data （volume）

• app 連資料庫用 sqlserver:1433（服務名 + 內部埠，ch07）。
• 你用 SSMS 連 localhost:1433（走 port mapping）。
• 資料放 volume，down 之後還在（ch06）。

專案結構

myapp/
├── docker-compose.yml           # 共通定義（進版控）
├── docker-compose.override.yml  # 本機開發覆蓋（自動載入）
├── .env                         # 秘密與可變參數（gitignore！）
├── .env.example                 # 範本（進版控，給同事參考）
├── .dockerignore
├── Dockerfile
├── pom.xml
└── src/

name: myapp

services:
  # ========== 資料庫 ==========
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: 'Y'
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD:?請在 .env 設定 MSSQL_SA_PASSWORD}
      MSSQL_PID: Developer          # 開發版授權（免費）
    ports:
      - '127.0.0.1:1433:1433'       # 只綁本機，同網段的人連不到（ch07）
    volumes:
      - mssql-data:/var/opt/mssql
    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
    deploy:
      resources:
        limits:
          memory: 2G              # SQL Server 官方最低需求 2 GB
    restart: unless-stopped

  # ========== 快取 ==========
  redis:
    image: redis:7-alpine
    ports:
      - '127.0.0.1:6379:6379'
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  # ========== 資料庫結構初始化（一次性任務）==========
  db-init:
    image: mcr.microsoft.com/mssql-tools
    depends_on:
      sqlserver:
        condition: service_healthy   # 等 DB 真的可以連了才跑
    volumes:
      - ./db/init:/scripts:ro
    entrypoint:
      - /bin/bash
      - -c
      - /opt/mssql-tools/bin/sqlcmd -S sqlserver -U sa -P "$$MSSQL_SA_PASSWORD" -i /scripts/01-create-db.sql
    environment:
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}
    restart: 'no'                    # 跑完就結束，不要重啟

  # ========== 應用程式 ==========
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: myapp:local
    ports:
      - '8080:8080'
    environment:
      SPRING_PROFILES_ACTIVE: ${SPRING_PROFILES_ACTIVE:-dev}
      SPRING_DATASOURCE_URL: 'jdbc:sqlserver://sqlserver:1433;databaseName=mydb;encrypt=true;trustServerCertificate=true'
      SPRING_DATASOURCE_USERNAME: sa
      SPRING_DATASOURCE_PASSWORD: ${MSSQL_SA_PASSWORD}
      SPRING_DATA_REDIS_HOST: redis
      SPRING_DATA_REDIS_PORT: '6379'
      TZ: Asia/Taipei
    depends_on:
      sqlserver:
        condition: service_healthy
      redis:
        condition: service_healthy
      db-init:
        condition: service_completed_successfully   # 等初始化跑完
    healthcheck:
      test: ['CMD', 'wget', '-qO-', 'http://localhost:8080/actuator/health']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    deploy:
      resources:
        limits:
          memory: 1G
    restart: unless-stopped

volumes:
  mssql-data:
  redis-data:

如果你查過 PostgreSQL 或 MySQL 的教學，會看到這種寫法：

# PostgreSQL / MySQL 可以這樣（把 .sql 丟進去就自動執行）
volumes:
  - ./init:/docker-entrypoint-initdb.d

三種可行的做法

做法 A：一次性 init 容器（上面設定用的方式）

• 另開一個服務，用 mssql-tools 映像跑 sqlcmd 執行你的 SQL 腳本。
• 靠 depends_on: condition: service_healthy 確保資料庫已就緒，再靠 service_completed_successfully 讓 app 等它跑完。
• 優點：純 Compose 就能做到，職責清楚。
• 缺點：每次 up 都會跑一次——你的 SQL 必須寫成可重複執行的（idempotent）：

  IF DB_ID('mydb') IS NULL
      CREATE DATABASE mydb;
  GO
  IF OBJECT_ID('dbo.users') IS NULL
      CREATE TABLE dbo.users (...);
  GO

做法 B：自訂映像，包一層 entrypoint

FROM mcr.microsoft.com/mssql/server:2022-latest
USER root
COPY init.sql /init/
COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh
USER mssql
ENTRYPOINT ["/entrypoint.sh"]

entrypoint.sh 先在背景啟動 SQL Server，輪詢等它就緒後執行腳本，最後 wait。缺點是要自己維護一個映像，而且容易寫錯 PID 1 的處理（ch05）。

做法 C：交給應用層的資料庫遷移工具（強烈推薦）

<!-- pom.xml -->
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-sqlserver</artifactId>
</dependency>

# src/main/resources/db/migration/V1__create_users.sql
# Spring Boot 啟動時自動執行未套用的遷移

docker-compose.override.yml 會被自動載入並合併（ch11），拿來放只有本機開發才需要的東西最合適。

# docker-compose.override.yml —— 本機開發專用
services:
  app:
    build:
      target: dev              # 用 Dockerfile 裡的 dev 階段（有 shell 好除錯）
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DEVTOOLS_RESTART_ENABLED: 'true'
      JAVA_TOOL_OPTIONS: '-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005'
    ports:
      - '5005:5005'            # 遠端除錯埠
    volumes:
      - ./target/classes:/app/classes   # 編譯輸出掛進去，配合 DevTools 熱重載

  # 開發時才需要的資料庫管理介面
  adminer:
    image: adminer
    ports:
      - '8081:8080'
    profiles: ['tools']        # 預設不啟動，要用才 --profile tools

IDE 遠端除錯設定

• IntelliJ IDEA：Run → Edit Configurations → 新增 Remote JVM Debug → Host: localhost, Port: 5005。
• 連上之後，中斷點就跟本機執行一樣好用——這是很多人不知道容器也能做到的事。
• suspend=n 表示不等除錯器連上就啟動；改成 y 則會卡住等你連（要除錯啟動流程時用）。

兩種開發循環，選一個

• 循環 A：重建映像（單純可靠）

  mvn package -DskipTests && docker compose up -d --build --no-deps app

  約 30~60 秒。行為和正式環境完全一致，不會有「本機好好的、映像裡卻不對」的問題。
• 循環 B：熱重載（快，但有代價）
  掛載 target/classes ＋ Spring Boot DevTools，IDE 一編譯容器內就自動重啟，約 3~5 秒。
  代價：開發環境和正式映像的行為不完全一致，而且 Windows/macOS 上 bind mount 的檔案監聽有時不可靠（ch06 提過的檔案共享層問題）。

啟動與停止

docker compose up -d                    # 啟動全部（背景）
docker compose up -d --build            # 重新建置後啟動
docker compose --profile tools up -d    # 連 adminer 一起啟動
docker compose stop                     # 只停止，容器保留
docker compose down                     # 停止並移除容器/網路（資料保留）
docker compose down -v                  # 💣 連資料一起重置

開發循環（最常用）

docker compose up -d --build --no-deps app   # 只重建重啟 app，不動 DB ⭐
docker compose logs -f app                    # 跟隨 app 日誌
docker compose logs -f --tail 100             # 全部服務，只看最近 100 行
docker compose restart app                    # 單純重啟（不重建）
docker compose ps                             # 看誰活著、誰 healthy

進去操作

# 進 app 容器
docker compose exec app bash

# 直接對資料庫下 SQL（不用裝任何客戶端工具）
docker compose exec sqlserver /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -Q "SELECT name FROM sys.databases"

# 進 Redis
docker compose exec redis redis-cli

環境重置（常常需要）

# 完全重來：刪容器、網路、資料，重新建置
docker compose down -v && docker compose up -d --build

# 只重置資料庫，保留其他服務
docker compose stop sqlserver
docker compose rm -f sqlserver
docker volume rm myapp_mssql-data
docker compose up -d sqlserver

排查

docker compose config                   # 看變數展開與合併後的最終設定 ⭐
docker compose ps -a                    # 含已結束的（看 db-init 有沒有成功）
docker compose logs db-init             # 初始化任務的輸出
docker compose top                      # 各容器內的 process（驗證 PID 1）
docker stats                            # 即時資源用量

make up        # docker compose up -d --build
make logs      # docker compose logs -f app
make reset     # docker compose down -v && make up
make db        # 進 sqlcmd

你現在有一套很好用的開發環境。但直接把它搬到正式環境會出事——先看清楚差異在哪。

開發環境的設定，哪些必須改

• 密碼：.env 檔換成雲端的秘密管理服務（AWS Secrets Manager、K8s Secret）。
• 資料庫：正式環境不要把資料庫跑在容器裡——用受管服務（RDS、Azure SQL）。備份、故障轉移、版本升級、監控都由雲端商負責，這是你自己維護容器化資料庫很難做到的（AWS ch05）。
• 埠對外：資料庫的 ports 整段拿掉，只讓內部網路連得到。
• 映像：從 build: 改成 image: 指向 registry 上有明確版本（甚至 digest）的映像（ch04）——正式環境不該在機器上現場編譯。
• 資源限制：務必明確設定，不能靠預設（ch02）。
• 日誌：接到集中式日誌系統，而不是留在本機。

Compose 在正式環境的三個結構性限制

1. 單機：所有容器在同一台機器上。機器掛了，服務就全沒了——沒有跨機器的備援。
2. 沒有自我修復與調度：restart: unless-stopped 只能重啟同一台機器上的容器。機器本身故障、或需要把工作負載搬到另一台，Compose 做不到。
3. 沒有滾動更新：docker compose up 更新服務時會有停機空窗。沒有「先起新的、確認健康、再關舊的」這種零停機機制。