docker-patterns

Docker 模式

Docker 與 Docker Compose 容器化開發最佳實務。

何時啟用

• 設定 Docker Compose 進行本機開發
• 設計多容器架構
• 排解容器網路或磁碟區問題
• 審查 Dockerfile 的安全性與大小
• 從本機開發遷移至容器化工作流程

本機開發的 Docker Compose

標準 Web 應用堆疊

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # 使用多階段 Dockerfile 的 dev 階段
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # 綁定掛載以支援熱重載
      - /app/node_modules             # 匿名磁碟區 — 保留容器內的相依套件
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data

  mailpit:                            # 本機郵件測試
    image: axllent/mailpit
    ports:
      - "8025:8025"                   # Web 管理介面
      - "1025:1025"                   # SMTP

volumes:
  pgdata:
  redisdata:

開發 vs 生產 Dockerfile

# 階段：相依套件
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# 階段：開發（熱重載、除錯工具）
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]

# 階段：建置
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production

# 階段：生產（最小映像）
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

覆寫檔案

# docker-compose.override.yml（自動載入，僅開發用）
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    ports:
      - "9229:9229"                   # Node.js 除錯器

# docker-compose.prod.yml（明確用於生產）
services:
  app:
    build:
      target: production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

# 開發（自動載入覆寫）
docker compose up

# 生產
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

網路設定

服務探索

相同 Compose 網路中的服務可透過服務名稱解析：

# 從 "app" 容器：
postgres://postgres:postgres@db:5432/app_dev    # "db" 解析為 db 容器
redis://redis:6379/0                             # "redis" 解析為 redis 容器

自訂網路

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net              # 僅 api 可連線，frontend 無法

networks:
  frontend-net:
  backend-net:

僅暴露必要埠

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"   # 僅主機可存取，不對外開放
    # 生產環境中省略 ports — 僅 Docker 網路內可存取

磁碟區策略

volumes:
  # 具名磁碟區：容器重啟後仍保留，由 Docker 管理
  pgdata:

  # 綁定掛載：將主機目錄映射至容器（開發用）
  # - ./src:/app/src

  # 匿名磁碟區：避免綁定掛載覆寫容器產生的內容
  # - /app/node_modules

常見模式

services:
  app:
    volumes:
      - .:/app                   # 原始碼（綁定掛載以支援熱重載）
      - /app/node_modules        # 保護容器內的 node_modules 不受主機影響
      - /app/.next               # 保護建置快取

  db:
    volumes:
      - pgdata:/var/lib/postgresql/data          # 持久化資料
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # 初始化腳本

容器安全

Dockerfile 強化

# 1. 使用特定標籤（絕不使用 :latest）
FROM node:22.12-alpine3.20

# 2. 以非 root 使用者執行
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app

# 3. 移除權限（在 compose 中設定）
# 4. 盡可能使用唯讀根檔案系統
# 5. 映像層中不包含機密資訊

Compose 安全設定

services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /app/.cache
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE          # 僅在綁定低於 1024 的埠時需要

機密管理

# 良好做法：使用環境變數（執行時注入）
services:
  app:
    env_file:
      - .env                     # 絕不將 .env 提交至 git
    environment:
      - API_KEY                  # 從主機環境繼承

# 良好做法：Docker secrets（Swarm 模式）
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# 錯誤做法：在映像中寫死
# ENV API_KEY=sk-proj-xxxxx      # 絕對不要這樣做

.dockerignore

node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/

除錯

常用指令

# 檢視日誌
docker compose logs -f app           # 持續追蹤 app 日誌
docker compose logs --tail=50 db     # 顯示 db 最後 50 行

# 在執行中的容器內執行指令
docker compose exec app sh           # 進入 app 的 shell
docker compose exec db psql -U postgres  # 連線至 postgres

# 檢查
docker compose ps                     # 顯示執行中的服務
docker compose top                    # 顯示每個容器內的行程
docker stats                          # 顯示資源使用量

# 重新建置
docker compose up --build             # 重新建置映像
docker compose build --no-cache app   # 強制完整重建

# 清理
docker compose down                   # 停止並移除容器
docker compose down -v                # 同時移除磁碟區（破壞性操作）
docker system prune                   # 移除未使用的映像/容器

排解網路問題

# 檢查容器內的 DNS 解析
docker compose exec app nslookup db

# 檢查連線
docker compose exec app wget -qO- http://api:3000/health

# 檢查網路
docker network ls
docker network inspect <project>_default

反模式

# 錯誤：在生產環境中使用 docker compose 而無編排工具
# 生產環境的多容器工作負載應使用 Kubernetes、ECS 或 Docker Swarm

# 錯誤：將資料儲存在容器中而未使用磁碟區
# 容器是短暫的 — 沒有磁碟區，重啟後所有資料都會遺失

# 錯誤：以 root 執行
# 務必建立並使用非 root 使用者

# 錯誤：使用 :latest 標籤
# 鎖定特定版本以確保可重複建置

# 錯誤：一個巨型容器包含所有服務
# 關注點分離：每個容器執行一個行程

# 錯誤：將機密資訊寫入 docker-compose.yml
# 使用 .env 檔案（已加入 .gitignore）或 Docker secrets