Docker常用指令彙整

適用：Docker CLI v24+/v25+、Docker Compose v2。
提醒：--rm 代表「容器結束就自動刪除（含匿名 volume）」，不可與 --restart 同時使用。

---

0) 快速觀念

• Image：唯讀模板
• Container：Image 的執行實例
• Volume：持久化資料（具名/匿名）
• Bind mount：映射主機路徑
• Registry：鏡像倉庫（Docker Hub、GHCR…）

---

1) docker run 常用選項

選項	用途	範例 / 備註
--name <N>	指定容器名稱	--name web
-d	背景執行	伺服器程式常用
-p H:C	連接埠對映	-p 8080:80
-e KEY=VAL / --env-file .env	環境變數	祕密建議用 secrets
-v 名稱:/path	具名 volume	-v pg:/var/lib/postgresql/data
-v /主機路徑:/path	bind mount	-v $(pwd):/app
--mount type=...,src=...,target=...	新式掛載語法	更明確、推薦
--network <NET>	指定網路	--network appnet
-it	互動式終端	常配 sh/bash
--rm	自動刪容器＋匿名 volume	一次性測試很方便
--restart=always|on-failure|unless-stopped	重啟策略	不能配 --rm
--cpus / --memory	資源限制	--cpus 1.5 --memory 512m
--user UID:GID	切換執行者	降低權限風險
--workdir /app	工作目錄	與 -v 常搭配
--entrypoint <bin>	覆寫 entrypoint	除錯用
--pull=always	先拉最新 image	CI 常用
--platform linux/amd64	指定平台	多架構時使用
--gpus all	指定 GPU	需 NVIDIA runtime
--health-cmd 等	健康檢查	見 §7

常見組合

# 互動開發
docker run --rm -it -v $(pwd):/app -w /app node:22-alpine sh

# 長期服務（含重啟策略）
docker run -d --name web -p 8080:80 --restart unless-stopped nginx:1.27

---

2) docker build / buildx build

選項	用途	範例
-t 名稱:標籤	命名 image	-t ghcr.io/me/app:1.0
-f Dockerfile	指定檔案	-f Dockerfile.prod
--build-arg K=V	傳遞 ARG	--build-arg NODE_ENV=prod
--target <stage>	multi-stage 目標	--target runner
--no-cache / --pull	快取/基底更新	失效或強更時用
--platform ...	多平台	--platform linux/amd64,linux/arm64
--cache-from/--cache-to	外部快取	buildx 推薦
--secret id=...,src=... / --ssh	機密/SSH	BuildKit

建議啟用 BuildKit：DOCKER_BUILDKIT=1 docker build ...

---

3) docker compose 指令與 YAML

常用指令

docker compose up -d            # 啟動
docker compose down -v          # 關閉並刪除 volume（小心）
docker compose logs -f          # 追蹤日誌
docker compose ps               # 檢視服務
docker compose exec app sh      # 進入服務容器
# 全域：-f <檔.yml>（合併）、-p <專案名>

YAML 常見鍵

services:
  app:
    build: .
    image: my/app:latest
    ports: ["8080:8080"]
    env_file: .env
    environment:
      - TZ=Asia/Taipei
    depends_on: [db, redis]
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"]
      interval: 10s
      timeout: 2s
      retries: 5
      start_period: 10s

  db:
    image: postgres:16
    volumes: [pg:/var/lib/postgresql/data]

  redis:
    image: redis:7

volumes:
  pg: {}
networks:
  default: { name: appnet }

Compose 與 .env 快速記憶

• 預設 .env：與 compose.yaml 同層的 .env 會被 自動載入用於插值。
• 多個 .env：可用多個 --env-file，後者覆蓋前者；docker compose config 可查看解析結果。
• 帶進容器：需在服務寫 environment: 或 env_file:，否則 .env 只做插值、不會自動進容器。
• docker run：不會自動讀 .env；請用 --env-file 或多個 -e KEY=VAL。

常見指令

# 指定 .env
docker compose --env-file .env.dev up -d

# 多個 .env（後者覆蓋前者），先看展開結果
docker compose --env-file .env --env-file .env.override config

---

4) Volume / Network 快查

# Volume
docker volume ls
docker volume inspect pg
docker volume prune -f   # 刪未用 volume（小心）

# Network
docker network ls
docker network create appnet
docker network inspect appnet

具名 volume不會因 --rm 被刪；匿名 volume在 --rm 時會刪除。

---

5) 日誌 / 進入 / 檢查 / 拷檔

docker logs -f web
docker exec -it web sh
docker inspect web | less
docker top web
docker stats
docker cp ./local.txt web:/tmp/in.txt

---

6) 清理與磁碟

docker system df
docker system prune -af     # 刪未用容器/網路/映像（**危險**）
docker image prune -af
docker volume prune -f

在生產環境執行 prune 前務必確認資源是否仍被使用。

---

7) 健康檢查與重啟策略

• Healthcheck：讓編排器/監控知道服務是否健康
• Restart policy：容器異常退出後自動復原

# run 版健康檢查
docker run -d --name web \
  --health-cmd='curl -fsS http://localhost/ || exit 1' \
  --health-interval=10s --health-retries=5 \
  --restart unless-stopped nginx

--rm 與 --restart 不可同時使用。

---

8) 安全性與權限

• 以非 root 使用者執行：USER 1000:1000
• .dockerignore 避免把金鑰/大型檔打包進 image
• 機密使用 secrets / 環境變數，避免寫死在 Dockerfile
• 嚴格權限：--cap-drop ALL --cap-add NET_BIND_SERVICE（按需開）
• 避免 --privileged；必要時限制來源與檔案權限

---

9) 平台 / GPU / 多架構

# 指定平台
docker run --platform linux/amd64 alpine uname -m

# buildx 多架構建置並推送
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/me/app:1.0 --push .

# GPU（NVIDIA）
docker run --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

---

10) Swarm 超簡速查

docker swarm init
docker swarm join --token <token> <manager-ip>:2377
docker node ls

docker service create --name web -p 80:80 --replicas 3 nginx
docker service ls
docker service update --image nginx:1.27 web

# 用 Compose 發佈 Stack
docker stack deploy -c docker-compose.yml mystack
docker stack services mystack
docker stack rm mystack

GUI 可用 Portainer 管理 Swarm 節點與 Stack。

---

--rm vs --restart

• 一次性測試/工具容器 → --rm
• 長期常駐服務 → --restart unless-stopped/always（不要配 --rm）
• 要保留資料 → 具名 volume；臨時資料 → 匿名 volume 或 bind mount