8.9 KiB

Raw Blame History

name	description
docker-patterns	Docker 和 Docker Compose 模式，涵蓋在地開發、容器安全性、網路配置、磁碟卷 (Volume) 策略以及多服務調度。

Docker 模式 (Docker Patterns)

針對容器化開發的 Docker 與 Docker Compose 最佳實踐。

何時啟用

為在地開發設置 Docker Compose。
設計多容器架構。
排除容器網路或磁碟卷相關故障。
審查 Dockerfile 的安全性與映像檔大小。
從在地開發流程遷移至容器化工作流。

用於在地開發的 Docker Compose

標準網頁應用技術棧 (Standard Web App Stack)

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # 使用多階段 Dockerfile 的 dev 階段
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # 綁定掛載 (Bind mount) 以實現熱重載 (Hot reload)
      - /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"                   # 網頁介面
      - "1025:1025"                   # SMTP 服務

volumes:
  pgdata:
  redisdata:

開發 vs 生產環境 Dockerfile

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

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

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

# 階段四：生產環境 (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"]

覆蓋檔案 (Override Files)

# 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

# 開發模式 (會自動載入 override 檔案)
docker compose up

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

網路配置 (Networking)

服務探索 (Service Discovery)

在同一個 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"   # 僅允許來自 Host 的存取，不對公開網路開放
    # 在生產環境中可完全省略 ports -- 僅讓 Docker 內部網路存取

磁碟卷策略 (Volume Strategies)

volumes:
  # 具名磁碟卷 (Named volume)：在容器重啟後仍保留資料，由 Docker 管理
  pgdata:

  # 綁定掛載 (Bind mount)：將主機目錄映射到容器內 (用於開發)
  # - ./src:/app/src

  # 匿名磁碟卷 (Anonymous volume)：保護容器內生成的內容不被綁定掛載覆蓋
  # - /app/node_modules

常見模式

services:
  app:
    volumes:
      - .:/app                   # 源碼 (綁定掛載，實現熱重載)
      - /app/node_modules        # 避免主機環境干擾容器內的 node_modules
      - /app/.next               # 保留建構快取 (Build cache)

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

容器安全性

Dockerfile 強化 (Hardening)

# 1. 使用具體的標籤 (絕對不要使用 :latest)
FROM node:22.12-alpine3.20

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

# 3. 移除不必要的權限能力 (Capabilities，於 compose 中設定)
# 4. 盡可能使用唯讀 (Read-only) 根文件系統
# 5. 映像檔各層 (Layers) 中不要包含敏感資訊 (Secrets)

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 的端口時

敏感資訊管理 (Secret Management)

# 推薦做法 (GOOD)：使用環境變數 (在執行時注入)
services:
  app:
    env_file:
      - .env                     # 絕不將 .env 提交至 git
    environment:
      - API_KEY                  # 從主機環境承襲

# 推薦做法 (GOOD)：使用 Docker Secrets (僅限 Swarm 模式)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# 錯誤做法 (BAD)：將敏感資訊寫死在映像檔中
# ENV API_KEY=sk-proj-xxxxx      # 絕對不要這樣做

.dockerignore 建議配置

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

排除故障 (Debugging)

常用指令

# 查看日誌
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   # 強制完整地重新建置 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 網路
docker network ls
docker network inspect <project名>_default

反模式 (Anti-Patterns)

# 不良做法：在生產環境使用 docker compose 而無任何調度機制
# 多容器的工作負載在生產環境應使用 Kubernetes, ECS 或 Docker Swarm

# 不良做法：在容器內存儲資料卻不使用磁碟卷 (Volumes)
# 容器是臨時性的 -- 若無磁碟卷，重啟後所有資料都會遺失

# 不良做法：以 root 使用者執行
# 務必建立並使用非 root 使用者

# 不良做法：使用 :latest 標籤
# 請固定具體版本，以確保建構的可重現性 (Reproducible builds)

# 不良做法：將所有服務塞進一個巨大的單一容器中
# 應落實關注點分離：一個容器原則上僅執行一個程序

# 不良做法：將敏感資訊寫在 docker-compose.yml 中
# 請使用 .env 檔案 (需 gitignore) 或 Docker secrets

8.9 KiB Raw Blame History Unescape Escape

Docker 模式 (Docker Patterns)

何時啟用

用於在地開發的 Docker Compose

標準網頁應用技術棧 (Standard Web App Stack)

開發 vs 生產環境 Dockerfile

覆蓋檔案 (Override Files)

網路配置 (Networking)

服務探索 (Service Discovery)

自定義網路

僅暴露必要的端口

磁碟卷策略 (Volume Strategies)

常見模式

容器安全性

Dockerfile 強化 (Hardening)

Compose 安全設定

敏感資訊管理 (Secret Management)

.dockerignore 建議配置

排除故障 (Debugging)

常用指令

排除網路問題

反模式 (Anti-Patterns)

8.9 KiB

Raw Blame History