常用指令-Docker

分享
常用指令-Docker

這篇整理 Docker 的常用指令與實務心得:從安裝、映像檔與容器的日常操作、資料保存與網路,到 Dockerfile 的寫法、Docker Compose、清理空間、推送到 Registry,以及最常遇到的問題怎麼查。指令以 Docker Engine 28 與 Docker Compose v2 為準(Compose 已經是 docker compose 子指令,不再是舊的 docker-compose)。

這篇不是官方文件的翻譯,而是我自己在家用伺服器、公司專案、CI/CD 流水線裡反覆用到的東西:哪些參數幾乎每次都要加、哪些指令看起來無害其實會刪資料、輸出要怎麼讀、出問題時先查哪裡。文中的 Dockerfile 與 compose 範例,大部分都實際在 Docker 28 上建置、執行或用 docker compose config 驗證過;少數無法在單機驗證的(例如 rootless 安裝、NFS 實際掛載)會特別標註。

閱讀前的慣例:

  • <尖括號> 代表要換成你自己的值,例如 <容器名稱>。容器或映像檔可以用名稱,也可以用 ID 的前幾碼(只要不重複,打 3、4 碼就夠)。
  • 標示 ⚠️ 的指令會刪除資料或影響正在執行的服務;⚠️⚠️ 代表「刪了就救不回來」。
  • 範例中的網址一律用 example.com,內部網段用 10.x.x.x 的範例值,請換成你自己環境的設定,不要直接照抄網段(後面「daemon.json」一節會說明為什麼網段衝突很麻煩)。
  • 指令前面沒有 sudo 的,代表假設你已經把使用者加入 docker 群組,或是在 Docker Desktop 上操作。

文章很長,建議當作工具書查閱。大致順序是:先講 Dockerfile 最重要的習慣,再講 Docker 的架構概念(理解之後很多「奇怪的行為」都會變得理所當然),接著是安裝、映像檔、容器、資源限制、資料、網路、日誌、daemon 設定,然後是 Dockerfile 與建置、Compose、維運 SOP、清理、Registry、安全、除錯與排查,最後是速查表。

Dockerfile 必寫!

先講我自己最常提醒自己的一件事:在 Dockerfile 裡用 apt 安裝套件時,同一個 RUN 指令裡就要把不需要的東西清掉,否則映像檔會一直變胖:

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && apt-get autoremove -y \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/*

為什麼一定要寫在同一個 RUN 裡:Docker 映像檔是一層一層疊起來的,每個 RUN 都是一層。如果「安裝」和「清除」分成兩個 RUN,清除的那一層只是把檔案標記為刪除,下載的套件清單和快取仍然存在前一層裡,映像檔一點都沒有變小。

  • --no-install-recommends:只裝必要的相依,不裝「建議安裝」的額外套件,通常能省下很多空間。
  • apt-get autoremove -y:移除不再需要的相依套件。
  • apt-get clean 與 rm -rf /var/lib/apt/lists/*:清掉下載的 .deb 與套件清單(清單光是 Ubuntu 就有數十 MB)。
  • 在 Dockerfile 裡用 apt-get 而不是 apt:apt 是給人互動用的,輸出格式不保證穩定,在腳本裡會出現警告。

實測:分開寫和寫在一起差多少

用 debian:bookworm-slim(本身 97.2 MB)安裝 curl 做比較。錯誤示範是把安裝和清除拆成兩個 RUN,而且沒有加 --no-install-recommends:

# ❌ 錯誤示範
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y curl
RUN apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*

用 docker history 看每一層的大小,結果很清楚:

$ docker history --format '{{.Size}}\t{{.CreatedBy}}' myapt:bad
0B      RUN /bin/sh -c apt-get autoremove -y && apt-…
35.4MB  RUN /bin/sh -c apt-get update && apt-get ins…
97.2MB  # debian.sh --arch 'arm64' out/ 'bookworm' '…

$ docker history --format '{{.Size}}\t{{.CreatedBy}}' myapt:good
14.8MB  RUN /bin/sh -c apt-get update  && apt-get in…
97.2MB  # debian.sh --arch 'arm64' out/ 'bookworm' '…

清除那一層顯示 0B:它只記錄了「這些檔案被刪除」的標記(overlay 檔案系統叫做 whiteout),前一層的 35.4 MB 一個位元組都沒少。最後整個映像檔是 133 MB 對 112 MB,只裝一個 curl 就差了 21 MB;套件一多,差距常常是幾百 MB。

其他套件管理工具的對應寫法

同樣的原則適用在所有套件管理工具:「下載、安裝、清快取」要在同一層完成。

基底映像檔安裝並清理的寫法備註
Debian/Ubuntuapt-get update && apt-get install -y --no-install-recommends … && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*本篇的重點寫法
Alpineapk add --no-cache …--no-cache 不會留下索引檔,不需要再清
Alpine(編譯用的暫時套件)apk add --no-cache --virtual .build-deps gcc musl-dev && … && apk del .build-deps用虛擬套件名稱把編譯工具包起來,用完一次刪掉
RHEL/Rocky/Fedoradnf install -y --setopt=install_weak_deps=False … && dnf clean allinstall_weak_deps=False 相當於 apt 的不裝建議套件
Pythonpip install --no-cache-dir -r requirements.txt或改用 BuildKit 的快取掛載(後面會講)
Node.jsnpm ci --omit=dev && npm cache clean --force正式映像檔不裝 devDependencies

apt 在 Dockerfile 裡的幾個小細節

  • apt-get update 一定要和 install 寫在同一個 RUN:如果分開寫,update 那一層會被快取,下次只改了要安裝的套件清單時,Docker 會沿用好幾個月前的舊索引,結果出現「找不到套件版本」或裝到舊版。
  • 避免互動式提示:像 tzdata 這類套件安裝時會問你時區,建置就卡住。用 ARG DEBIAN_FRONTEND=noninteractive(用 ARG 而不是 ENV,只在建置時生效,不會帶進執行階段的環境變數)。
  • 需要固定版本時:apt-get install -y curl=7.88.1-10+deb12u12 這種寫法可以固定版本,但套件庫下架舊版後建置會失敗。我自己的做法是:基底映像檔固定版本、apt 套件不固定,靠定期重建拿到安全更新。
  • 套件清單排序並一行一個:多人維護時 diff 好讀,也比較不會重複安裝。
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      ca-certificates \
      curl \
      tzdata \
 && apt-get autoremove -y \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/*

Docker 架構概念:先懂這些,後面都好理解

很多人一開始把容器當成「輕量虛擬機」,然後被各種現象嚇到:為什麼容器裡改的檔案不見了?為什麼刪除檔案映像檔沒變小?為什麼容器裡看得到主機的 CPU 數量卻用不到?這些都跟 Docker 的架構有關。

元件:用戶端、daemon、containerd、runc

  • docker CLI(用戶端):你打的 docker run、docker ps 只是用戶端,它透過 REST API 把請求送給 daemon。預設走本機的 Unix socket /var/run/docker.sock,也可以透過 SSH 或 TCP 連到遠端主機(見後面的 docker context)。
  • dockerd(Docker daemon):真正管理映像檔、容器、網路、volume 的背景服務,以 root 身分執行(rootless 模式除外)。
  • containerd:dockerd 底下的容器執行管理層,負責容器的生命週期。Kubernetes 也常直接使用它。
  • runc:符合 OCI 規格的低階執行程式,實際呼叫 Linux 核心功能把程序「關進」容器。前面測試時看到的錯誤訊息 OCI runtime create failed: runc create failed 就是從這層來的。
  • BuildKit:Docker 23 之後預設的建置引擎,docker build 其實就是 docker buildx build。它支援平行建置、快取掛載、secret 掛載、跨架構建置等功能。

這個分層的實際意義:docker 指令只是遙控器。所以 docker context use 切換到另一台主機之後,你在本機打的 docker ps 看到的是遠端主機的容器;而在 Mac 上,daemon 其實跑在 Docker Desktop 管理的 Linux 虛擬機裡。

映像檔:唯讀的層疊

映像檔是由多個唯讀層(layer)疊成的。Dockerfile 裡會改變檔案系統的指令(RUN、COPY、ADD)各產生一層;ENV、CMD、EXPOSE、LABEL 這類只改中繼資料的指令不會產生有內容的層(docker history 裡顯示 0B)。

  • 每一層用內容的雜湊值(sha256)識別,相同的層在主機上只存一份。十個映像檔都用 debian:bookworm-slim 當基底,基底那幾層只佔一次空間;這也是為什麼 docker images 顯示的大小加總,常常比實際磁碟用量大很多。
  • 下載(pull)和上傳(push)也是以層為單位,已經存在的層會跳過。所以把很少變動的步驟放在前面,不只建置快,部署時下載量也小。
  • 層是只能新增、不能修改的,後面的層刪除前面層的檔案,只是蓋上一個「已刪除」標記。這就是「Dockerfile 必寫」的原理。
docker image inspect -f '{{len .RootFS.Layers}}' <映像檔>      # 有幾層
docker image inspect -f '{{json .RootFS.Layers}}' <映像檔>     # 每一層的雜湊值
docker history --no-trunc <映像檔>                            # 每一層由哪個指令產生

容器:映像檔加上一層可寫層

啟動容器時,Docker 在映像檔的唯讀層上面加一層可寫層。容器裡新增或修改的檔案都寫在這一層;要修改映像檔裡的既有檔案時,會先把整個檔案複製到可寫層再修改,這叫做 copy-on-write(寫入時複製)。

  • 容器刪除時,可寫層跟著刪除。這就是「用 docker exec 進去改的東西,容器一刪就消失」的原因。
  • 同一個映像檔啟動 100 個容器,映像檔本身只存一份,每個容器只多一層很薄的可寫層。
  • 大量寫入的資料(資料庫、日誌、上傳檔案)不要寫在可寫層:效能較差(要經過 overlay 檔案系統),容器重建就不見。請用 volume 或 bind mount。
  • docker ps -s 可以看到每個容器可寫層的大小;docker diff <容器> 可以列出改了哪些檔案(A 新增、C 修改、D 刪除)。

儲存驅動:overlay2

把多個層「疊」成一個完整檔案系統的機制叫做儲存驅動(storage driver)。現在 Linux 上的預設與推薦都是 overlay2,它使用核心內建的 OverlayFS:底下多個唯讀目錄(lowerdir)加上一個可寫目錄(upperdir),合併後呈現給容器(merged)。

docker info --format '{{.Driver}}'                                  # 通常是 overlay2
docker inspect -f '{{json .GraphDriver.Data}}' <容器>               # 看 LowerDir/UpperDir/MergedDir
sudo ls /var/lib/docker/overlay2 | head                              # 各層實際存放處(Linux 主機)

⚠️ 不要手動去改或刪 /var/lib/docker/overlay2 底下的東西,Docker 的中繼資料會和實際檔案對不上,輕則映像檔壞掉,重則 daemon 起不來。要清空間請用後面「清理空間」一節的指令。

補充:Docker 也有「containerd 映像檔儲存區」(containerd image store)模式,新版 Docker Desktop 預設會使用,Linux 上的 Docker Engine 28 預設仍是 overlay2 傳統儲存。差別在於 containerd 儲存區可以在本機保存多架構映像檔與 attestation,docker images 顯示的大小算法也不太一樣。用 docker info 輸出裡的 Storage Driver 欄位確認你用的是哪一種。

隔離的原理:namespace 與 cgroup

容器不是虛擬機,它就是主機上的一般程序,只是被 Linux 核心的兩個機制限制住:

Namespace隔離什麼實際效果
pid程序編號容器裡的主程式是 PID 1,看不到主機和其他容器的程序
net網路介面、路由、埠每個容器有自己的 eth0 與 IP,兩個容器都能監聽 80 埠而不衝突
mnt掛載點容器看到的是自己的根目錄,看不到主機檔案(除非掛載進來)
uts主機名稱容器可以有自己的 hostname
ipc共享記憶體、號誌容器之間不會互相干擾 System V IPC
user使用者 ID 對應rootless 或 userns-remap 時,容器裡的 root 對應到主機上的一般使用者
cgroupcgroup 階層視角容器只看得到自己的 cgroup

cgroup(control groups)則負責「限制用量」:記憶體上限、CPU 配額、程序數量上限、磁碟 I/O。現代 Linux 發行版都已改用 cgroup v2,docker info 會顯示 Cgroup Version: 2。設定 --memory 256m --cpus 0.5 之後,在容器裡看 cgroup 檔案就能看到限制值:

$ docker run --rm --memory 256m --cpus 0.5 alpine:3.22 \
    sh -c 'cat /sys/fs/cgroup/memory.max /sys/fs/cgroup/cpu.max'
268435456
50000 100000

cpu.max 的 50000 100000 意思是「每 100 毫秒最多用 50 毫秒的 CPU 時間」,也就是 0.5 顆 CPU。

理解這點很重要的一個例子:容器裡的 free、top、nproc 看到的常常是整台主機的數字,因為 /proc/meminfo 沒有被 cgroup 改寫。舊版 JVM、某些 Node.js 或 Python 程式依這些數字決定執行緒數或記憶體用量,就會在容器裡超用而被 OOM 砍掉。新版 JVM(10 以後)已經會讀 cgroup 限制,其他語言請自己設定 worker 數量。

容器和虛擬機的差別

項目容器虛擬機
核心和主機共用同一個 Linux 核心每台有自己的核心
啟動時間毫秒到秒數十秒到分鐘
額外開銷幾乎沒有每台要預留記憶體與磁碟
隔離強度較弱,核心漏洞可能影響所有容器較強
跑不同作業系統只能跑 Linux 容器(在 Linux 核心上)可以

所以「在 Mac 上跑 Linux 容器」其實需要一台 Linux 虛擬機,這就是 Docker Desktop 在背後做的事。

/var/lib/docker 裡有什麼

路徑內容
overlay2/映像檔的層與容器的可寫層
containers/<ID>/每個容器的設定、hostname、resolv.conf,以及 <ID>-json.log 日誌檔
volumes/named volume 的實際資料(volumes/<名稱>/_data)
image/映像檔中繼資料
network/網路設定資料庫
buildkit/建置快取

這個目錄的位置可以用 daemon.json 的 data-root 改到別顆磁碟,後面會說明。

安裝 Docker(Ubuntu)

建議用 Docker 官方套件庫安裝,版本比 Ubuntu 內建的 docker.io 新。如果主機之前裝過發行版內建的套件,先移除,避免兩套混在一起:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove -y $pkg
done

這只會移除套件,/var/lib/docker 裡既有的映像檔、容器、volume 不會被刪。接著加入官方套件庫並安裝:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run --rm hello-world     # 測試

各套件的角色:docker-ce 是 daemon,docker-ce-cli 是 docker 指令,containerd.io 是底層執行環境,docker-buildx-plugin 與 docker-compose-plugin 提供 docker buildx 與 docker compose 子指令。Debian 的步驟幾乎相同,只要把網址裡的 ubuntu 換成 debian。

指定版本安裝

正式環境的多台主機最好裝同一個版本,避免行為不一致:

apt-cache madison docker-ce | head          # 列出可安裝的版本
VERSION_STRING=<上一步列出的完整版本字串>
sudo apt-get install -y docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
sudo apt-mark hold docker-ce docker-ce-cli    # 避免被 apt upgrade 意外升級

⚠️ 用 apt upgrade 升級 docker-ce 時,daemon 會重啟,沒有開 live-restore 的話所有容器都會跟著重啟。正式環境請排維護時間,或參考後面 daemon.json 的 live-restore 設定。

官方另外提供 get.docker.com 的一鍵安裝腳本,適合測試機,但它不適合正式環境:會裝最新版、不容易控制版本,而且「把網路上的腳本直接丟給 root 執行」本身就是風險。

安裝後設定

讓一般使用者不用 sudo 就能用 docker:

sudo usermod -aG docker $USER
newgrp docker                        # 或登出再登入

⚠️ 加入 docker 群組等同給了 root 權限(可以掛載主機任何目錄進容器),只給信任的帳號。例如 docker run --rm -v /:/host alpine cat /host/etc/shadow 就能讀主機的密碼雜湊檔。若需要比較安全的做法,請看後面的 rootless Docker。

開機自動啟動(官方套件預設已啟用,確認一下即可):

sudo systemctl enable --now docker.service containerd.service
systemctl status docker --no-pager
journalctl -u docker -n 50 --no-pager      # daemon 的日誌(啟動失敗時第一個看這裡)

Mac 和 Windows 上則是安裝 Docker Desktop,它會在背景跑一個輕量 Linux 虛擬機,指令完全一樣。兩者在網路、檔案掛載、資源上的差異,後面「Docker Desktop 與 Linux 的差異」一節會整理。

確認環境

docker version              # 用戶端與伺服器版本
docker info                 # 容器數、儲存驅動、資料目錄、CPU 架構
docker compose version
docker buildx version

docker info 的輸出很長,我最常看的是這幾行:

欄位看什麼
Server Versiondaemon 版本(docker version 裡 Client 與 Server 版本可以不同,以 Server 為準)
Storage Driver應該是 overlay2;如果是 vfs,代表核心或檔案系統不支援 overlay,效能和空間都會很差
Logging Driver預設日誌驅動,正式環境建議確認有設輪替
Cgroup Driver/Cgroup Versionsystemd/2 是目前主流
Docker Root Dir資料目錄,磁碟滿的時候要看的就是這裡
Registry Mirrors/Insecure Registries確認 daemon.json 設定有生效
Live Restore Enableddaemon 重啟時容器是否保持執行
WARNING: 開頭的行例如沒有 swap 限制支援、bridge-nf-call-iptables 未啟用,通常是核心參數問題

只想取單一欄位時,用 --format 比 grep 穩定:

docker info --format '{{.Driver}} {{.DockerRootDir}} {{.CgroupVersion}}'
docker version --format '{{.Server.Version}}'

映像檔命名規則、標籤與 digest

一個完整的映像檔名稱長這樣:

registry.example.com:5000/team/myapp:1.4.2@sha256:<64 個十六進位字元>
└──── registry ────────┘ └ 命名空間/名稱 ┘ └tag┘ └──── digest ────┘
部分說明省略時的預設
registry映像檔存放的伺服器,可帶埠號docker.io(Docker Hub)
命名空間使用者或組織名稱,可有多層(如 GitLab 的 group/subgroup/project)Docker Hub 官方映像檔是 library
名稱(repository)只能用小寫英數、.、_、-(必填)
tag版本標籤,最長 128 字元,可用大小寫英數、.、_、-latest
digest映像檔內容的 sha256 雜湊值,內容不同 digest 就不同無

所以 nginx 其實是 docker.io/library/nginx:latest;myuser/tool 是 docker.io/myuser/tool:latest。Docker 判斷第一段是不是 registry 的規則是:含有 . 或 :,或是 localhost。因此 myregistry/app 會被當成 Docker Hub 上名為 myregistry 的使用者,而不是一台叫 myregistry 的伺服器。

tag 會變,digest 不會

tag 只是一個可以被移動的指標。nginx:1.27 今天指向 1.27.4,下個月官方重建後可能指向 1.27.5(或同一個版本但修補了基底的安全問題)。digest 則是內容本身的指紋,同一個 digest 永遠是同一份內容。

docker image ls --digests alpine                         # 列出本機映像檔的 digest
docker image inspect -f '{{index .RepoDigests 0}}' alpine:3.22
# alpine@sha256:2e0b81d6…(實際輸出為完整 64 碼)
docker pull alpine@sha256:<digest>                       # 用 digest 下載,保證內容一致

實務建議:

  • 開發、測試:用明確的版本 tag(postgres:17、node:22-bookworm-slim),可以自動拿到小版本修補。
  • 正式環境、需要重現的建置:用 tag@digest 並寫上 tag 方便人讀,例如 FROM node:22-bookworm-slim@sha256:…。Docker 會以 digest 為準,tag 只是註解。
  • 自己建置的映像檔:tag 用版本號或 Git commit 短碼(myapp:1.4.2、myapp:git-3f2a9c1),不要只推 latest,否則無法回滾到上一版。
  • 固定 digest 之後就不會自動拿到安全更新,要搭配 Renovate、Dependabot 這類工具定期提醒更新。

多架構映像檔的 digest 有兩層

多架構映像檔的名稱指向一個 index(manifest list),index 裡面再列出每個平台各自的 manifest。用 docker buildx imagetools inspect 可以看清楚:

$ docker buildx imagetools inspect alpine:3.22
Name:      docker.io/library/alpine:3.22
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:2e0b81d6…            ← index 的 digest(RepoDigests 記錄的是這個)

Manifests:
  Name:        docker.io/library/alpine:3.22@sha256:dc92f017…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64             ← amd64 版本自己的 digest
  …
  Name:        docker.io/library/alpine:3.22@sha256:ae0881df…
  Platform:    unknown/unknown         ← 這不是映像檔,是 attestation(SBOM、來源證明)

輸出裡的 unknown/unknown 常讓人困惑,它是建置時附加的證明文件(provenance、SBOM),不是可以執行的映像檔,看到可以忽略。docker manifest inspect <映像檔> 也能看類似的資訊,輸出是原始 JSON。

映像檔(Image)

docker pull nginx:1.27                  # 下載映像檔(建議指定版本,不要只寫 latest)
docker images                           # 列出本機映像檔
docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
docker image inspect nginx:1.27         # 詳細資訊(環境變數、預設指令、層數)
docker history nginx:1.27               # 每一層的大小與建立指令(找出哪一層最胖)
docker tag nginx:1.27 myrepo/nginx:prod # 加上新標籤
docker rmi <映像檔>                     # 刪除映像檔
docker image prune                      # 刪除沒有標籤的懸空映像檔(dangling)
docker image prune -a                   # ⚠️ 刪除所有沒被容器使用的映像檔

為什麼不要用 latest:latest 只是一個會變動的標籤,今天和下個月拉到的可能是完全不同的版本,正式環境出問題時也很難知道當時跑的是哪一版。正式環境請固定版本號,甚至固定 digest(nginx@sha256:…)。另外 latest 並不代表「最新」,它只是沒有指定 tag 時的預設名稱,有些專案的 latest 甚至好幾年沒更新。

更多查詢技巧

docker image ls --filter dangling=true             # 只看懸空映像檔(<none>:<none>)
docker image ls --filter reference='myapp:*'       # 名稱符合樣式的
docker image ls --filter before=myapp:1.4.2        # 比某個映像檔更早建立的
docker image ls -q                                 # 只輸出 ID(給其他指令用)
docker image ls --no-trunc                         # 顯示完整 ID
docker image ls --tree                             # 以樹狀顯示各平台與實際磁碟用量(較新版本才有)
docker image inspect -f '{{.Config.Cmd}} {{.Config.Entrypoint}}' nginx:1.27   # 預設指令
docker image inspect -f '{{json .Config.Env}}' nginx:1.27                      # 內建環境變數
docker image inspect -f '{{json .Config.ExposedPorts}}' nginx:1.27             # 宣告的埠
docker image inspect -f '{{.Created}}' nginx:1.27                              # 建置時間
docker history --no-trunc --format '{{.Size}}\t{{.CreatedBy}}' nginx:1.27     # 完整指令

docker images 的 SIZE 欄位是「這個映像檔所有層加總」的大小,不是它額外佔用的空間;共用的基底層會在多個映像檔重複計算。要看真正佔用多少,請用 docker system df -v,裡面有 SHARED SIZE 與 UNIQUE SIZE 兩欄。

什麼是懸空映像檔(dangling)

當你用相同的名稱重新建置(例如又建了一次 myapp:dev),標籤會移到新的映像檔上,舊的那個就變成 <none>:<none>,這就是懸空映像檔。它們通常可以放心刪除(docker image prune),除非還有已停止的容器在使用。

多架構映像檔

同一個映像檔名稱底下,通常同時有 amd64(Intel/AMD)和 arm64(Apple 晶片、AWS Graviton)兩種版本,Docker 會自動挑符合主機架構的那一個。在 Apple 晶片的 Mac 上建置、要部署到 x86 主機時,就要特別指定架構(見下方 buildx)。

docker image inspect --format '{{.Architecture}}' <映像檔>   # 這個映像檔是哪個架構
docker image inspect --format '{{.Os}}/{{.Architecture}}' <映像檔>
docker pull --platform linux/amd64 <映像檔>                  # 指定架構下載
docker run --rm --platform linux/amd64 alpine:3.22 uname -m  # 在 Apple 晶片上用模擬執行 amd64,輸出 x86_64

在 Apple 晶片上跑 amd64 映像檔會看到警告 The requested image's platform (linux/amd64) does not match the detected host platform,它能跑(透過模擬),只是速度慢,偶爾有相容問題,不適合當作效能測試的依據。

匯出與匯入:save/load 和 export/import

主機無法連 registry(例如隔離網路、現場部署)時,可以把映像檔存成檔案搬過去:

docker save -o myapp-1.4.2.tar myapp:1.4.2                 # 保留所有層、tag 與中繼資料
docker save myapp:1.4.2 | gzip > myapp-1.4.2.tar.gz        # 壓縮
docker load -i myapp-1.4.2.tar                             # 在另一台主機載入
gunzip -c myapp-1.4.2.tar.gz | docker load                 # 從壓縮檔載入
docker save myapp:1.4.2 | ssh user@host.example.com docker load   # 直接透過 SSH 傳過去
指令對象保留什麼用途
docker save/load映像檔所有層、tag、CMD、ENV 等設定搬移映像檔(推薦)
docker export/import容器只有扁平化的檔案系統,沒有歷史與設定極少用;需要把容器檔案系統攤平時
docker commit容器把容器目前狀態存成新映像檔只適合除錯時保留現場,正式映像檔請用 Dockerfile

用 docker commit 做出來的映像檔沒有人知道裡面做過什麼改動,下次要修改也無法重現,所以我只在「容器出了怪問題、想保留現場慢慢查」時使用:docker commit -m "除錯現場" <容器> debug/myapp:incident-1。

容器(Container)

容器的生命週期

一個容器會經過這幾個狀態,docker ps -a 的 STATUS 欄位就是它:

狀態意義怎麼到達
created已建立但從未啟動docker create,或 docker run 啟動失敗
running(Up)主程序執行中docker start/docker run
paused程序被凍結(cgroup freezer)docker pause
restarting依重啟策略正在重啟主程序結束且策略要求重啟
exited主程序已結束,可寫層還在程式結束、docker stop
dead刪除失敗等異常狀態通常是儲存驅動問題

重點觀念:容器的壽命等於它的主程序(PID 1)的壽命。主程序結束,容器就結束;容器裡用 & 丟到背景的其他程序不算數。

啟動容器

docker run -d --name web -p 8080:80 nginx:1.27

docker run 其實等於 docker create(必要時先 pull)加上 docker start。常用參數一次看懂:

參數用途範例
-d背景執行docker run -d …
--name指定容器名稱(之後用名稱操作,不用記 ID)--name web
-p 主機:容器對外開埠-p 8080:80、-p 127.0.0.1:3306:3306、-p 53:53/udp
-P把 Dockerfile 裡 EXPOSE 的埠全部對應到主機的隨機埠用 docker port 查對應結果
-v 來源:容器路徑掛載資料夾或 volume-v ./html:/usr/share/nginx/html:ro
--mount同上,但用明確的鍵值寫法--mount type=volume,src=db-data,dst=/var/lib/mysql
--tmpfs掛載記憶體檔案系統--tmpfs /tmp:size=64m
-e環境變數-e TZ=Asia/Taipei
--env-file從檔案讀環境變數--env-file .env
--restart重啟策略--restart unless-stopped
--rm結束後自動刪除容器(一次性任務)docker run --rm …
-it互動式終端機docker run -it ubuntu:24.04 bash
--network加入指定網路--network app-net
--network-alias在網路裡額外的 DNS 名稱--network-alias database
--add-host寫入容器的 /etc/hosts--add-host=host.docker.internal:host-gateway
--memory/--cpus限制資源--memory 512m --cpus 1.5
--user以指定使用者執行--user 1000:1000
-w/--workdir工作目錄-w /app
--entrypoint覆寫映像檔的 ENTRYPOINT--entrypoint sh
--init用 Docker 內建的 tini 當 PID 1處理訊號與殭屍程序
--hostname容器的主機名稱--hostname app01
--label加上標籤(方便篩選與清理)--label env=staging
--pull何時下載映像檔--pull always(每次都檢查新版)
--platform指定架構--platform linux/amd64
--stop-timeout/--stop-signal停止時等待秒數與送出的訊號--stop-timeout 30
--log-driver/--log-opt日誌驅動與選項--log-opt max-size=10m
--read-only根檔案系統唯讀搭配 --tmpfs 使用
--device把主機裝置給容器--device /dev/dri(硬體轉碼)
--gpus使用 NVIDIA GPU(需裝 NVIDIA Container Toolkit)--gpus all

⚠️ -p 3306:3306 會把埠開在主機的所有網卡上,而且 Docker 會自己改防火牆規則,不受 ufw 管控。資料庫這類只給本機用的服務,請寫成 -p 127.0.0.1:3306:3306。如果只是同一台主機上的其他容器要連,根本不需要 -p,放在同一個自訂網路裡用容器名稱連即可。

--restart 的選擇:

策略程式異常結束程式正常結束(0)手動 stop 後主機重開適用
no(預設)不重啟不重啟不啟動一次性任務
on-failure[:次數]重啟不重啟不啟動批次工作,失敗才重試
always重啟重啟會啟動一定要跑的服務
unless-stopped重啟重啟不啟動長駐服務(我最常用)

重啟不是無限快速重試:Docker 會以倍數拉長間隔(從 100 毫秒開始倍增,上限約 1 分鐘),容器穩定跑超過 10 秒後才重置計數。所以看到 Restarting (1) 40 seconds ago 代表它一直在啟動失敗,請直接看 docker logs。

-v 與 --mount 的差別

# 兩者等價
docker run -d -v db-data:/var/lib/postgresql/data postgres:17
docker run -d --mount type=volume,src=db-data,dst=/var/lib/postgresql/data postgres:17

# bind mount
docker run -d -v /srv/site:/usr/share/nginx/html:ro nginx:1.27
docker run -d --mount type=bind,src=/srv/site,dst=/usr/share/nginx/html,readonly nginx:1.27

關鍵差異:用 -v 掛載不存在的主機路徑時,Docker 會自動用 root 身分建立一個空資料夾,程式就默默讀到空目錄;--mount type=bind 遇到不存在的路徑則會直接報錯。寫腳本或正式環境我偏好 --mount,打字快速測試用 -v。另外打錯路徑把「檔案」掛成「資料夾」,也是常見的 -v 陷阱(例如主機上 nginx.conf 不存在,結果容器裡出現一個叫 nginx.conf 的空資料夾,nginx 啟動失敗)。

查看與操作

docker ps                         # 執行中的容器
docker ps -a                      # 包含已停止的
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker logs -f --tail 100 web     # 追蹤最近 100 行日誌
docker logs --since 30m web       # 最近 30 分鐘
docker exec -it web bash          # 進入容器(沒有 bash 的精簡映像檔改用 sh)
docker exec web nginx -t          # 在容器裡執行單一指令
docker stop web                   # 停止(先送 SIGTERM,10 秒後才強制)
docker start web
docker restart web
docker rm web                     # 刪除已停止的容器
docker rm -f web                  # ⚠️ 強制刪除執行中的容器
docker inspect web                # 完整設定(IP、掛載、環境變數、重啟次數)
docker inspect -f '{{.State.Status}} {{.RestartCount}}' web
docker stats                      # 即時 CPU、記憶體、網路、磁碟用量
docker stats --no-stream          # 只看一次
docker top web                    # 容器內的程序
docker cp web:/etc/nginx/nginx.conf ./nginx.conf   # 從容器複製檔案出來
docker cp ./index.html web:/usr/share/nginx/html/  # 複製檔案進容器
docker diff web                   # 容器啟動後改了哪些檔案

容器是「用完即丟」的設計:用 docker exec 進去改的東西,容器一刪就全部消失。要保留的資料放 volume,要改的設定寫進 Dockerfile 或用掛載的方式提供。

docker ps 的篩選與格式

docker ps -a --filter status=exited               # 已結束的
docker ps --filter health=unhealthy               # 健康檢查失敗的
docker ps --filter label=env=staging              # 有某個標籤的
docker ps --filter ancestor=nginx:1.27            # 用某個映像檔建立的
docker ps --filter name=web                       # 名稱包含 web(部分比對)
docker ps -a -q --filter status=exited            # 只要 ID,給其他指令用
docker ps -s                                      # 加上可寫層大小
docker ps -l                                      # 最近建立的那一個
docker ps --format '{{.Names}}\t{{.Label "com.docker.compose.project"}}'   # 看屬於哪個 Compose 專案
docker ps --format json                           # 一行一個 JSON,可搭配 jq

常用的格式欄位:.ID、.Names、.Image、.Status、.State、.Ports、.RunningFor、.CreatedAt、.Networks、.Mounts、.Size、.Label "鍵"。

docker logs 的讀法

docker logs -t web                       # 每行前面加時間戳記(UTC,RFC3339 格式)
docker logs --since 2026-10-30T09:00:00 --until 2026-10-30T10:00:00 web   # 指定時間區間
docker logs --since 10m web 2>&1 | grep -i error   # 注意:stderr 要轉進管線才 grep 得到
docker logs web > web.log 2>&1           # 存成檔案

docker logs 只看得到主程序寫到 stdout/stderr 的內容。如果程式把日誌寫到容器裡的檔案(例如 /var/log/app.log),docker logs 會是空的。官方 nginx 映像檔的做法是把 /var/log/nginx/access.log 做成指向 /dev/stdout 的符號連結,自己做映像檔時可以參考。另外 docker logs 會把容器的 stdout 和 stderr 分別送到你終端機的 stdout 和 stderr,所以直接 | grep 會漏掉 stderr,要先 2>&1。

docker exec 的常用選項

docker exec -it web sh                       # 互動 shell
docker exec -u root -it web sh               # 以 root 身分進去(映像檔用一般使用者時)
docker exec -w /app web ls                   # 指定工作目錄
docker exec -e DEBUG=1 web ./healthcheck.sh  # 帶環境變數
docker exec web sh -c 'echo $HOSTNAME > /tmp/x'   # 需要管線、轉向、變數展開時要包 sh -c

沒有 shell 的映像檔(distroless、scratch)無法 exec 進去,錯誤訊息是 exec: "sh": executable file not found in $PATH。這時可以借用其他容器的命名空間來除錯,見後面「除錯技巧」。

停止容器:訊號與寬限時間

docker stop 會先送 SIGTERM,等待寬限時間(預設 10 秒)後如果還沒結束,再送 SIGKILL 強制砍掉。程式能不能「優雅地」結束,取決於 PID 1 有沒有處理 SIGTERM。實測差異:

$ docker run -d --name t1 alpine:3.22 sleep 300
$ time docker stop -t 3 t1        # sleep 當 PID 1,不處理 SIGTERM
3.11s total
$ docker inspect -f '{{.State.ExitCode}}' t1
137                                # 等到逾時被 SIGKILL

$ docker run -d --init --name t2 alpine:3.22 sleep 300
$ time docker stop -t 3 t2        # 由 tini 當 PID 1,把訊號轉給 sleep
0.07s total
$ docker inspect -f '{{.State.ExitCode}}' t2
143                                # 收到 SIGTERM 立即結束

Linux 核心對 PID 1 有特殊處理:沒有註冊處理函式的訊號,對 PID 1 不會有預設的「結束」行為。所以一般程式在主機上收到 SIGTERM 會結束,當成容器的 PID 1 時卻毫無反應。解法是加 --init、在映像檔裡用 tini,或確保程式自己處理 SIGTERM。

docker stop -t 60 db                  # 資料庫給長一點的寬限時間
docker kill web                       # 直接送 SIGKILL
docker kill -s HUP nginx              # 送其他訊號,例如讓 nginx 重新載入設定
docker run -d --stop-signal SIGQUIT --stop-timeout 30 nginx:1.27   # 建立時指定

其他容器操作

docker rename web web-old                       # 改名(升級時保留舊容器很方便)
docker update --restart unless-stopped web      # 修改重啟策略,不需重建
docker update --memory 1g --memory-swap 1g web  # 調整記憶體上限
docker update --cpus 2 web
docker pause web && docker unpause web          # 凍結與解凍
docker wait job1                                # 等待容器結束並印出結束代碼(腳本用)
docker port web                                 # 埠對應
docker attach web                               # 接上主程序的 stdin/stdout(Ctrl-P Ctrl-Q 離開而不停止)
docker create --name web nginx:1.27             # 只建立不啟動

⚠️ docker attach 之後直接按 Ctrl-C,會把 SIGINT 送給主程序,等於把服務停掉。看日誌請用 docker logs -f,不要用 attach。

docker update 只能改資源限制與重啟策略;埠、掛載、環境變數、網路都要刪掉容器重建。這也是為什麼長期維護的服務最好寫成 Compose 檔:重建就是一行 docker compose up -d。

容器的結束代碼

docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' <容器>
代碼常見意義
0正常結束
1程式本身錯誤(看 docker logs)
2shell 內建指令用法錯誤,或程式自訂的錯誤代碼
125docker run 指令本身有問題(參數錯誤、daemon 錯誤)
126找到檔案但無法執行(沒有執行權限、執行的是目錄或一般檔案)
127找不到指令(ENTRYPOINT 或 CMD 寫錯、PATH 不對)
128+N被訊號 N 結束,例如 130=SIGINT(Ctrl-C)
137被 SIGKILL(128+9):常見是記憶體不足被砍(OOMKilled 會是 true),或 docker stop 等太久被強制結束
139Segmentation fault(128+11),常見於架構不符的二進位檔或原生函式庫問題
143收到 SIGTERM 正常結束(128+15,docker stop)

上面 125、126、127 我都實際測過:docker run --bogus alpine 回傳 125;把 /etc/passwd 當指令執行回傳 126;執行不存在的 nosuchcmd 回傳 127,錯誤訊息是 exec: "nosuchcmd": executable file not found in $PATH。看到 137 時,先用上面的 inspect 看 OOMKilled:true 是記憶體問題,false 多半是停止逾時。

資源限制與 OOM

預設情況下容器沒有任何資源限制,一個記憶體洩漏的容器可以把整台主機的記憶體吃光,連帶讓 sshd、資料庫一起被核心的 OOM killer 砍掉。正式環境建議每個容器都設上限。

參數意義說明
--memory 512m記憶體硬上限超過就被 OOM killer 結束(結束代碼 137)
--memory-swap 512m記憶體+swap 的總上限設成和 --memory 相同等於不准用 swap;不設的話預設可再用同樣大小的 swap
--memory-reservation 256m軟性下限主機記憶體吃緊時,核心會盡量把容器壓回這個值
--cpus 1.5最多使用 1.5 顆 CPU 的時間最常用的 CPU 限制方式
--cpuset-cpus 0-1只能在指定的 CPU 核心上執行綁核,避免和其他重要服務搶
--cpu-shares 512相對權重(預設 1024)只在 CPU 滿載時才有作用
--pids-limit 200程序/執行緒數上限防止 fork bomb 拖垮主機
--ulimit nofile=65536:65536檔案描述符上限高連線數的服務需要
--oom-score-adj調整被 OOM killer 選中的優先順序數值越高越先被砍

⚠️ --oom-kill-disable 看起來很誘人,但沒有同時設 --memory 的話,記憶體不足時核心會改砍主機上的其他程序,後果更糟。不建議使用。

實測 OOM

$ docker run --name oomtest --memory 32m --memory-swap 32m alpine:3.22 sh -c 'tail /dev/zero'
$ echo $?
137
$ docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' oomtest
137 true
$ docker rm oomtest

tail /dev/zero 會一直讀入沒有換行的資料,記憶體持續成長,碰到 32 MB 上限就被砍。在主機上可以用 journalctl -k | grep -i oom 或 dmesg -T | grep -i oom 看到核心的 OOM 紀錄,裡面會寫出被砍的程序與 cgroup。

看懂 docker stats

$ docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.PIDs}}'
NAME     CPU %     MEM USAGE / LIMIT     MEM %     PIDS
web      0.00%     1.176MiB / 31.29GiB   0.00%     1
  • CPU % 以「一顆 CPU」為 100%,4 核心機器上可能看到 380%。
  • LIMIT 如果顯示整台主機的記憶體(上例 31.29GiB),代表這個容器沒有設記憶體上限。
  • MEM USAGE 不含檔案快取中可回收的部分,所以和容器裡 free 看到的不一樣,以 stats 為準。
  • PIDS 持續成長通常是程式沒有回收子程序或執行緒洩漏。
  • BLOCK I/O 與 NET I/O 是容器啟動以來的累計值,不是速率。

不重建容器調整限制

docker update --memory 1g --memory-swap 1g --cpus 2 <容器>
docker inspect -f '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' <容器>   # 位元組、奈秒 CPU(1e9=1 顆)

注意 docker update 的修改只存在這個容器上,用 Compose 管理的服務下次 docker compose up -d 重建時會回到 compose 檔裡寫的值,所以最後還是要回頭改 compose 檔。

程式語言與容器記憶體

  • Java:JDK 10 之後預設會讀 cgroup 限制。建議用 -XX:MaxRAMPercentage=75 而不是寫死 -Xmx,留空間給 metaspace、執行緒堆疊與原生記憶體。
  • Node.js:較新版本會參考 cgroup 限制決定 heap 上限,但保守起見可以設 NODE_OPTIONS=--max-old-space-size=<MB>,約為容器上限的 70~75%。
  • Python(gunicorn、uvicorn):worker 數不要用 multiprocessing.cpu_count() 自動算,它回傳的是主機核心數;請依容器的 --cpus 手動設定。
  • Go:Go 1.25 起執行環境會依 cgroup 的 CPU 限制自動設定 GOMAXPROCS;記憶體可以用 GOMEMLIMIT 讓 GC 在接近上限時更積極回收。

資料保存:Volume 與 Bind Mount

docker volume create db-data
docker volume ls
docker volume inspect db-data         # 實際存放位置
docker run -d --name db -v db-data:/var/lib/mysql -e MYSQL_ROOT_PASSWORD_FILE=/run/secrets/pw mysql:8.4
docker volume rm db-data              # ⚠️ 刪除 volume=刪除資料
docker volume prune                   # ⚠️ 刪除沒被任何容器使用的「匿名」volume
docker volume prune -a                # ⚠️⚠️ 連沒被使用的 named volume 也刪除

⚠️ Docker 23 之後 docker volume prune 的行為改了:不加參數時只刪「匿名 volume」(名稱是一串 64 碼雜湊值的那種),有名字的 volume 要加 -a 才會被刪。我實測建立一個 named volume 和一個匿名 volume 後執行 docker volume prune -f,只有匿名的被刪掉。網路上很多舊文章還寫著「prune 會刪所有未使用的 volume」,指的是舊版行為;但反過來說,-a 才是真正會刪資料的那一個,請特別小心。

兩種掛載方式的選擇:

  • Named volume(-v db-data:/var/lib/mysql):由 Docker 管理,適合資料庫等資料。權限問題少,跨平台表現一致。
  • Bind mount(-v /srv/site:/usr/share/nginx/html):直接掛主機的資料夾,適合設定檔、原始碼、要用主機工具編輯或備份的檔案。要注意容器內程式的 UID 與主機檔案擁有者是否一致。
類型資料在哪適合注意事項
Named volume/var/lib/docker/volumes/<名稱>/_data資料庫、需要持久保存但不需要手動編輯的資料第一次掛載到空 volume 時,會把映像檔裡該路徑的內容複製進去
匿名 volume同上,名稱是隨機雜湊值映像檔用 VOLUME 宣告、但執行時沒指定 -v 時自動產生容器重建後會換一個新的,舊資料就「不見」了(其實還在,只是沒人掛它)
Bind mount你指定的主機路徑設定檔、原始碼、要被主機備份的檔案UID/權限、SELinux 標籤(:z/:Z)、Docker Desktop 上效能較差
tmpfs記憶體暫存檔、敏感的暫時資料容器停止就消失,會佔用記憶體上限

匿名 volume 的陷阱

很多資料庫的官方映像檔在 Dockerfile 裡寫了 VOLUME /var/lib/postgresql/data。如果你 docker run postgres:17 沒加 -v,資料會寫進一個匿名 volume。之後你 docker rm 再 docker run 一個新容器,新容器會拿到另一個全新的匿名 volume,看起來就像資料全部消失。舊資料其實還在舊的匿名 volume 裡,可以這樣找回來:

docker volume ls --filter dangling=true            # 沒被任何容器使用的 volume
docker run --rm -v <那串雜湊值>:/data alpine:3.22 ls -la /data   # 確認內容
# 確認是舊資料後,複製到正式的 named volume
docker run --rm -v <那串雜湊值>:/from:ro -v db-data:/to alpine:3.22 sh -c 'cp -a /from/. /to/'

所以資料庫一律要明確指定 named volume,也請記得 docker run --rm 會在容器結束時一併刪除它的匿名 volume。

volume 初始化的行為

當一個空的 named volume 第一次掛到容器的某個路徑,而映像檔在那個路徑已經有檔案時,Docker 會先把映像檔裡的檔案複製進 volume。這個特性很方便(例如設定檔有預設值),但也是個陷阱:volume 只會在「空的時候」初始化一次。映像檔升級後裡面的預設檔案更新了,volume 裡還是舊的。Bind mount 則完全沒有這個行為,主機資料夾會直接「蓋住」容器裡的路徑。

權限問題:UID 對不上

Bind mount 最常見的錯誤是 Permission denied。原因是 Linux 的檔案權限只看數字 UID/GID,不看名稱:容器裡的 node 使用者是 UID 1000,主機上的資料夾如果屬於 UID 1001 或 root,容器就寫不進去。

docker run --rm <映像檔> id                          # 容器預設以哪個 UID 執行
ls -ln /srv/app-data                                   # 主機資料夾的數字 UID/GID
sudo chown -R 1000:1000 /srv/app-data                  # 改成和容器一致
docker run --user "$(id -u):$(id -g)" -v "$PWD":/work -w /work <映像檔> …   # 或讓容器用你的 UID 執行

在 RHEL、Rocky、Fedora 這類啟用 SELinux 的系統上,即使 UID 正確也可能被擋,要在掛載後面加 :z(多個容器共用)或 :Z(只給這個容器)讓 Docker 重新標記。⚠️ 不要對 /home、/usr 這種系統目錄加 :Z,會改掉整個目錄的 SELinux 標籤。

備份與還原 volume

# 備份:用一個暫時的容器把 volume 打包到目前目錄
docker run --rm -v db-data:/data -v "$PWD":/backup ubuntu:24.04 tar czf /backup/db-data.tar.gz -C /data .
# 還原
docker run --rm -v db-data:/data -v "$PWD":/backup ubuntu:24.04 tar xzf /backup/db-data.tar.gz -C /data

改良版:備份時把 volume 掛成唯讀(:ro)避免誤寫;還原到全新的 volume,確認內容後再切換,不要直接覆蓋原本的 volume。我用 busybox 實測過「備份→還原到另一個 volume→讀出內容」整個流程:

docker run --rm -v db-data:/data:ro -v "$PWD":/backup busybox:1.37 \
  tar czf /backup/db-data-$(date +%F).tar.gz -C /data .
docker volume create db-data-restore
docker run --rm -v db-data-restore:/data -v "$PWD":/backup:ro busybox:1.37 \
  tar xzf /backup/db-data-2026-10-31.tar.gz -C /data

⚠️ 資料庫請優先用資料庫自己的工具備份(例如 docker exec db mysqldump …),直接打包執行中的資料庫檔案可能得到不一致的備份。如果一定要打包檔案,請先停止資料庫容器:

docker exec db sh -c 'mysqldump -uroot -p"$(cat /run/secrets/pw)" --single-transaction --all-databases' > all.sql
docker exec pg pg_dumpall -U postgres > all.sql               # PostgreSQL(不要加 -t,否則換行會變成 CRLF)
docker exec -i pg psql -U postgres < all.sql                 # 還原(注意是 -i 不是 -it)

匯出與還原都不要加 -t:-t 會配置虛擬終端機,匯出時換行會被轉成 CRLF、還混進終端機控制字元;還原時則把 stdin 的資料流當成鍵盤輸入處理,碰到大檔案或特殊字元會出問題。還原要用 -i(保持 stdin 開啟),不是 -it。

volume 驅動與 NFS volume

Volume 不一定要存在本機磁碟。內建的 local 驅動可以透過 mount 選項掛載 NFS、CIFS,第三方外掛還能接雲端儲存。NFS 的寫法:

docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=10.0.0.10,rw,nfsvers=4.1 \
  --opt device=:/export/app \
  app-nfs
docker volume inspect -f '{{json .Options}}' app-nfs
docker run --rm -v app-nfs:/data alpine:3.22 ls /data      # 第一次使用時才真正掛載

Compose 寫法:

volumes:
  app-nfs:
    driver: local
    driver_opts:
      type: nfs
      o: "addr=10.0.0.10,rw,nfsvers=4.1"
      device: ":/export/app"

幾個重點:

  • docker volume create 只會記錄設定,不會測試連線;設定錯誤要等到容器啟動、真正掛載時才會報錯(例如 mount: … connection refused)。我在本機驗證了建立與 inspect,實際掛載需要 NFS 伺服器,請在你的環境測試。
  • 主機要安裝 NFS 用戶端(Ubuntu 是 nfs-common),掛載動作由 Docker 主機執行,不是容器。
  • NFS 上跑資料庫要非常小心:檔案鎖定與 fsync 行為不同,SQLite、PostgreSQL 都可能出問題。NFS volume 比較適合放上傳檔案、媒體庫、備份。
  • 改了 driver_opts 不會套用到已存在的 volume,要先刪掉 volume 再重建(資料在 NFS 伺服器上,不會因此遺失)。

CIFS/SMB 的寫法類似:--opt type=cifs --opt device=//10.0.0.10/share --opt o=addr=10.0.0.10,username=<帳號>,password=<密碼>,uid=1000,gid=1000。⚠️ 這樣密碼會以明文存在 volume 設定裡,docker volume inspect 就看得到,建議改用 credentials=<檔案路徑> 選項指向只有 root 能讀的憑證檔。

網路

docker network ls
docker network create app-net
docker run -d --name api --network app-net myapi:1.0
docker run -d --name db  --network app-net mysql:8.4
docker network inspect app-net        # 哪些容器在這個網路、各自的 IP
docker network connect app-net web    # 把已存在的容器加入網路
docker network disconnect app-net web
docker network rm app-net
docker network prune                  # 刪除沒有容器使用的自訂網路

同一個自訂網路裡的容器,可以直接用容器名稱互相連線(例如 api 連資料庫用 db:3306),Docker 內建 DNS 會解析。預設的 bridge 網路沒有這個功能,所以多容器的服務建議都建自訂網路,或交給 Compose 自動處理。

實測:在自訂網路裡,容器的 /etc/resolv.conf 是 nameserver 127.0.0.11(Docker 內建 DNS),用容器名稱和 --network-alias 設定的別名都能解析;同樣的查詢在預設 bridge 網路裡會得到 bad address。

容器要連主機上的服務:Docker Desktop 用 host.docker.internal;Linux 上要在 run 時加 --add-host=host.docker.internal:host-gateway。注意主機上的服務必須監聽在容器連得到的位址:只聽 127.0.0.1 的服務,從容器是連不到的(容器的 127.0.0.1 是容器自己),要讓它監聽 Docker bridge 的閘道位址或 0.0.0.0(再用防火牆限制)。

網路模式

模式說明適用情境注意事項
bridge(預設)容器在一個虛擬交換器後面,透過 NAT 上網,用 -p 對外開埠絕大多數服務預設 bridge 沒有名稱解析,請用自訂 bridge
自訂 bridgedocker network create 建立的 bridge多容器應用有內建 DNS、可隨時 connect/disconnect
host直接使用主機的網路堆疊,沒有隔離需要大量埠(VoIP)、極致網路效能、需要收廣播封包的服務-p 無效;埠直接和主機衝突
none只有 loopback,完全不能連網處理敏感資料的批次工作實測只看得到 lo
macvlan容器拿到實體區網上的獨立 MAC 與 IP,像一台獨立設備需要被區網直接連到的服務(家用 DNS、IoT 整合)主機預設無法直接連到自己的 macvlan 容器;交換器要允許同一埠多個 MAC
ipvlan類似 macvlan 但共用主機的 MAC交換器限制 MAC 數量、或在雲端/Wi-Fi 環境同樣有主機互連的限制
container:<名稱>共用另一個容器的網路命名空間除錯、sidecar兩者的 localhost 是同一個

macvlan 範例

docker network create -d macvlan \
  --subnet 10.20.30.0/24 \
  --gateway 10.20.30.1 \
  --ip-range 10.20.30.192/27 \
  -o parent=eth0 \
  lan
docker run -d --name dns --network lan --ip 10.20.30.200 <映像檔>
  • --ip-range 限制 Docker 自動配發的範圍,請從路由器的 DHCP 範圍排除這一段,否則會 IP 衝突。
  • parent 是主機的實體網卡名稱(用 ip -br link 查);要接 VLAN 可以寫 eth0.30,Docker 會自動建立子介面。
  • 主機要連到 macvlan 容器,需在主機上另外建立一個 macvlan 子介面並設路由,這是 Linux macvlan 的設計限制,不是故障。
  • Docker Desktop(Mac/Windows)上 macvlan 不會接到你的實體區網,請在 Linux 主機上使用。

內部網路:禁止對外連線

docker network create --internal backend
docker run --rm --network backend busybox:1.37 wget -T 3 -qO- http://example.com
# wget: bad address 'example.com'(連不出去)

--internal 網路裡的容器彼此可以連線,但無法連到外部網路,也不能用 -p 對外開埠。很適合放資料庫:前端容器同時接 frontend 與 backend 兩個網路,資料庫只接 backend。

開埠與防火牆的實際運作

  • -p 8080:80 時,Docker 在 iptables(或 nftables)的 nat 表加入 DNAT 規則,封包在進入 INPUT 鏈之前就被轉走,所以 ufw 的 INPUT 規則管不到它。要用防火牆限制容器的埠,規則請寫在 DOCKER-USER 鏈。
  • 只想給本機用的服務,最簡單可靠的方法就是綁定 127.0.0.1。
  • 主機上執行 iptables -F、重新載入 firewalld 等動作會清掉 Docker 的規則,容器就連不出去也連不進來,sudo systemctl restart docker 會重建。
  • 開 IPv6 時,-p 也會同時綁在 IPv6 位址上,請一併檢查 IPv6 的防火牆。
sudo iptables -t nat -L DOCKER -n --line-numbers     # 看埠對應產生的 DNAT 規則
sudo iptables -L DOCKER-USER -n                     # 自訂的過濾規則放這裡
docker port <容器>                                  # 從 Docker 的角度看埠對應

日誌(Logging)

容器的 stdout/stderr 由「日誌驅動」決定送去哪裡。預設是 json-file:每個容器一個 JSON 檔,放在 /var/lib/docker/containers/<ID>/<ID>-json.log。

驅動特色docker logs 可用
json-file預設;簡單、通用,但預設不輪替可以
local壓縮過的二進位格式,預設就會輪替(每檔 20 MB、保留 5 檔),比 json-file 省空間可以
journald送進 systemd journal,可用 journalctl CONTAINER_NAME=web 查可以
syslog送到本機或遠端 syslog 伺服器只透過「雙重記錄」功能
fluentd、gelf、awslogs、gcplogs集中式日誌系統只透過「雙重記錄」功能
none完全不記錄不行

「雙重記錄(dual logging)」是 Docker 20.10 之後的功能:使用遠端驅動時,Docker 仍會在本機保留一份暫存,讓 docker logs 可以讀。如果完全關掉,會看到 configured logging driver does not support reading(我用 --log-driver none 實測就是這個錯誤)。

docker run -d --log-driver local --log-opt max-size=10m --log-opt max-file=5 nginx:1.27
docker run -d --log-opt max-size=10m --log-opt max-file=3 nginx:1.27      # json-file 加上輪替
docker inspect -f '{{.HostConfig.LogConfig.Type}} {{.LogPath}}' <容器>   # 用哪個驅動、檔案在哪
docker info --format '{{.LoggingDriver}}'                                 # daemon 預設驅動

Compose 寫法:

services:
  web:
    image: nginx:1.27
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

日誌已經長到好幾 GB、又不能重啟容器時,可以先清空檔案:sudo truncate -s 0 $(docker inspect -f '{{.LogPath}}' <容器>)。⚠️ 不要用 rm 刪日誌檔,Docker 還開著那個檔案,空間不會釋放,之後的日誌也寫不到新檔。根本解法還是設定輪替(見下一節的 daemon.json),然後重建容器讓設定生效。

daemon.json 常用設定

Docker daemon 的設定檔在 Linux 上是 /etc/docker/daemon.json(預設不存在,要自己建立),Docker Desktop 則在「Settings → Docker Engine」裡編輯。下面是我在 Linux 伺服器上常用的設定組合,已用 dockerd --validate 驗證過格式與欄位名稱:

{
  "data-root": "/srv/docker",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "registry-mirrors": ["https://mirror.example.com"],
  "insecure-registries": ["registry.example.com:5000"],
  "default-address-pools": [
    { "base": "10.200.0.0/16", "size": 24 }
  ],
  "bip": "10.199.0.1/24",
  "dns": ["10.0.0.53", "1.1.1.1"],
  "live-restore": true,
  "builder": { "gc": { "enabled": true, "defaultKeepStorage": "20GB" } },
  "default-ulimits": { "nofile": { "Name": "nofile", "Soft": 65536, "Hard": 65536 } },
  "userland-proxy": false,
  "max-concurrent-downloads": 6,
  "shutdown-timeout": 30
}

不需要的項目請刪掉,不要整份照抄(尤其是網段與 DNS)。JSON 不允許註解與結尾多餘的逗號。

設定用途注意事項
data-root把 /var/lib/docker 搬到別顆磁碟改了之後原本的映像檔、容器、volume 都「看不到」,要先搬資料(見下方)
log-driver/log-opts預設日誌驅動與輪替只對之後新建的容器生效,既有容器要重建
registry-mirrorsDocker Hub 的鏡像站(pull-through cache)只對 Docker Hub 有效,其他 registry 不會走鏡像站
insecure-registries允許用 HTTP 或自簽憑證連線的 registry⚠️ 傳輸不加密,只能用在受信任的內部網路
default-address-pools自訂網路(含 Compose 建立的網路)從哪個網段配發避免和公司網段衝突,見下方說明
bip預設 docker0 bridge 的 IP 與網段寫的是閘道 IP 加遮罩(10.199.0.1/24),不是網段位址
dns容器預設使用的 DNS公司內部網域要能解析的話,第一個請放內部 DNS
live-restoredaemon 重啟或升級時容器保持執行不支援 Swarm 模式;重大版本升級仍建議重啟容器
builder.gc自動清除建置快取建置主機(CI runner)特別需要
default-ulimits所有容器預設的 ulimit容器個別的 --ulimit 會覆蓋
userland-proxy關閉後改用 iptables 處理本機迴路的埠轉送可減少每個埠一個 docker-proxy 程序;少數舊環境需要保持開啟
max-concurrent-downloads同時下載的層數(預設 3)頻寬大時調高可加快 pull
shutdown-timeoutdaemon 關閉時等待容器結束的秒數資料庫多的主機可以調長

改完設定先驗證再重啟

sudo dockerd --validate --config-file /etc/docker/daemon.json     # 顯示 configuration OK 才重啟
sudo systemctl restart docker        # ⚠️ 會重啟所有容器(除非已開 live-restore)
docker info | grep -A3 -E 'Registry Mirrors|Logging Driver|Live Restore'   # 確認生效

驗證能抓到兩種常見錯誤,我都實際測過:

  • 打錯欄位名稱:the following directives don't match any configuration option: no-such-key
  • JSON 語法錯誤(例如多一個逗號):invalid character '}' looking for beginning of object key string

如果沒先驗證就重啟,daemon 會起不來,所有容器都停在那裡,journalctl -u docker 才看得到原因。另一個常見錯誤是同一個設定同時寫在 daemon.json 和 systemd 的啟動參數(例如 -H 或 --data-root),daemon 會拒絕啟動並提示 the following directives are specified both as a flag and in the configuration file。

default-address-pools:避免和公司網段衝突

Docker 預設從 172.17.0.0/16 開始,依序配發 172.18.0.0/16、172.19.0.0/16…給每個自訂網路,用完 172.16~31 之後還會用到 192.168.x.0/20。每個 Compose 專案都會建立至少一個網路,專案一多就會配到很多網段。

問題在於很多公司內網、VPN、雲端 VPC 也用 172.16~31 或 192.168 網段。一旦 Docker 配發的網段和公司某個網段重疊,主機上就會多出一條「這個網段走 Docker bridge」的路由,主機(甚至整台機器的 SSH)就連不到公司那個網段。症狀通常是「裝了 Docker 或多起一個 Compose 專案之後,某些內部系統突然連不上」。

解法是在 daemon.json 指定一段確定不會和任何內部網段衝突的範圍:

{
  "bip": "10.199.0.1/24",
  "default-address-pools": [
    { "base": "10.200.0.0/16", "size": 24 }
  ]
}

意思是預設 bridge 用 10.199.0.0/24,其他網路從 10.200.0.0/16 裡每次切一個 /24,最多 256 個網路。設定後要注意:

  • 既有的網路不會自動換網段,要 docker compose down 再 up(或刪除重建網路)才會用新的範圍。
  • Compose 檔裡如果有寫死 ipam.config.subnet,以 compose 檔為準,不受這個設定影響。
  • 選網段前先問網管或查公司的 IP 規劃文件,不要用「應該沒人用吧」的猜測。
docker network inspect -f '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' $(docker network ls -q)   # 列出每個網路用的網段
ip route | grep -E 'docker0|br-'                                                                        # 主機上 Docker 產生的路由

搬移 data-root 到另一顆磁碟

  1. 停止 Docker:sudo systemctl stop docker docker.socket containerd。
  2. 複製資料並保留權限與硬連結:sudo rsync -aHAX --info=progress2 /var/lib/docker/ /srv/docker/(注意兩邊結尾都有斜線)。
  3. 在 daemon.json 加上 "data-root": "/srv/docker",用 dockerd --validate 驗證。
  4. 啟動 Docker:sudo systemctl start docker,用 docker info --format '{{.DockerRootDir}}' 確認路徑,docker images、docker volume ls 確認資料都在。
  5. 確認所有服務正常一段時間後,才把舊的 /var/lib/docker 改名備份,最後再刪除。

⚠️ 新磁碟的檔案系統建議用 ext4 或 xfs(xfs 需要 ftype=1),NFS、CIFS 這類網路檔案系統不能當 data-root 使用。

registry-mirrors 與 Docker Hub 下載限制

Docker Hub 對未登入的下載有次數限制,CI 環境或多台主機共用一個對外 IP 時很容易撞到,錯誤訊息是 toomanyrequests: You have reached your pull rate limit。解法有幾種:用 docker login 登入(額度較高)、架設 pull-through cache(例如 registry:2 設定成 proxy 模式)並設成 registry-mirrors、或把常用映像檔複製到自己的私有 registry。

Dockerfile 寫法

指令總覽

指令用途會產生有內容的層嗎
FROM基底映像檔,可用 AS 名稱 命名階段(引入基底的層)
RUN執行指令會
COPY從 build context 或其他階段複製檔案會
ADD同 COPY,但會自動解壓本機 tar、可下載網址會
WORKDIR設定工作目錄(不存在會自動建立)不存在時會建立目錄
ENV環境變數(建置與執行時都有效)不會
ARG建置參數(只在建置時有效)不會
USER之後的指令與執行時使用的使用者不會
EXPOSE宣告服務使用的埠(只是文件,不會真的開埠)不會
VOLUME宣告資料目錄,執行時會自動產生匿名 volume不會
LABEL中繼資料,例如 org.opencontainers.image.source不會
ENTRYPOINT/CMD啟動時執行的程式與預設參數不會
HEALTHCHECK健康檢查不會
SHELL改變 RUN 字串格式使用的 shell不會
STOPSIGNALdocker stop 送出的訊號不會
ONBUILD延遲到「被別人當基底時」才執行的指令不會

Dockerfile 第一行建議寫 # syntax=docker/dockerfile:1,讓 BuildKit 使用最新的穩定版語法(支援 heredoc、--mount、COPY --chmod 等功能),不必等 Docker 本身升級。

一個完整的範例

# 第一階段:建置
FROM node:22-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# 第二階段:執行(只帶需要的檔案,映像檔小很多)
FROM node:22-bookworm-slim
ENV NODE_ENV=production TZ=Asia/Taipei
WORKDIR /app
RUN apt-get update \
 && apt-get install -y --no-install-recommends tini \
 && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*
COPY --from=build /app/package.json /app/package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["node", "dist/server.js"]

逐段說明:

  • 兩個階段都用同一個基底,確保建置時編出來的原生模組(例如 bcrypt、sharp)和執行環境的 glibc 版本一致。
  • 第一階段先只複製 package.json 與 lock 檔再 npm ci:只要相依沒變,這一層就會命中快取,改程式碼只會從 COPY . . 之後重跑。
  • 第二階段重新 npm ci --omit=dev,只裝正式環境的相依;dist 從第一階段複製過來,原始碼、測試、devDependencies 都不會進最終映像檔。
  • USER node 是官方 Node 映像檔內建的一般使用者(UID 1000)。
  • HEALTHCHECK 用 Node 內建的 fetch(Node 18 以後),不必為了健康檢查另外安裝 curl。
  • tini 當 PID 1,負責轉送訊號與回收殭屍程序。

重點整理

  • 選小的基底映像檔:-slim、alpine(體積最小,但用 musl 而不是 glibc,某些套件會有相容問題)、distroless(連 shell 都沒有,最安全,但除錯較麻煩)。
  • 善用建置快取:把「很少變動」的步驟放前面。上面先只 COPY package.json 再 npm ci,只要相依沒變,改程式碼時就不必重新安裝套件。
  • 多階段建置(multi-stage):編譯工具、原始碼、測試檔只留在第一階段,最終映像檔只放執行需要的東西。
  • 同一個 RUN 裡清理:就是本篇開頭的「必寫」,npm cache clean、pip install --no-cache-dir 也是同樣道理。
  • 不要用 root 執行:USER 指定一般使用者,容器被入侵時傷害比較小。
  • HEALTHCHECK:讓 Docker(和 Compose 的 depends_on: condition: service_healthy)知道服務是否真的可用,而不只是程序還活著。
  • 用 tini 或 --init:讓程式能正確收到停止訊號、回收殭屍程序,docker stop 才不會等到逾時被強制砍掉(結束代碼 137)。
  • 不要把密碼寫進 Dockerfile:ENV、ARG 的值都會留在映像檔的歷史紀錄裡,docker history 就看得到。執行時再用環境變數、secret 或掛載設定檔提供;建置時需要的憑證用 BuildKit 的 --mount=type=secret(後面有範例)。
  • 一個容器一個主要程序:不要在同一個容器裡用 supervisord 同時跑 nginx、PHP、cron、資料庫。拆成多個容器,各自獨立重啟、擴展、看日誌。
  • 加上 OCI 標籤:LABEL org.opencontainers.image.source="https://example.com/repo",日後看到映像檔就知道從哪裡來。

ENTRYPOINT 與 CMD

  • CMD:預設要執行的指令,docker run 映像檔 其他指令 時會被整個取代。
  • ENTRYPOINT:固定要執行的程式,docker run 後面接的參數會「附加」在它後面。
  • 兩者都請用 JSON 陣列格式(["node", "server.js"]),程式才會是 PID 1、直接收到停止訊號。字串格式會被包在 /bin/sh -c 裡,訊號送不到你的程式。

兩者搭配的結果(假設執行時沒有另外指定指令):

ENTRYPOINTCMD實際執行
(無)["nginx", "-g", "daemon off;"]nginx -g "daemon off;"
["/usr/bin/tini", "--"]["node", "server.js"]/usr/bin/tini -- node server.js
["python", "manage.py"]["runserver"]python manage.py runserver;docker run 映像檔 migrate 則變成 python manage.py migrate
python manage.py(字串格式)任何值/bin/sh -c "python manage.py",CMD 被忽略

需要在啟動前做一些準備(產生設定檔、等待資料庫、執行 migration)時,常見做法是寫一支 entrypoint 腳本,最後一行一定要用 exec "$@",讓真正的程式取代 shell 成為 PID 1:

#!/bin/sh
set -e
# 由環境變數產生設定檔
envsubst < /etc/app/config.tmpl > /etc/app/config.yaml
# 把控制權交給 CMD 指定的程式
exec "$@"
COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "dist/server.js"]

漏掉 exec 的話,shell 會一直當 PID 1,docker stop 的 SIGTERM 送不到你的程式,又變成等 10 秒被強制砍掉。在 Windows 編輯的腳本要注意換行字元,CRLF 會讓 shebang 變成 /bin/sh\r,錯誤訊息是讓人一頭霧水的 no such file or directory。

ARG 與 ENV

項目ARGENV
有效範圍只在建置時建置時與容器執行時
如何設定docker build --build-arg KEY=值Dockerfile 裡寫死;執行時可用 -e 覆蓋
多階段建置每個 FROM 之後要重新宣告才能使用只在宣告的階段與之後繼承它的階段有效
會留在映像檔裡嗎值會出現在 docker history(被 RUN 使用時)會留在映像檔設定,docker image inspect 看得到

常見用法是「用 ARG 接收版本號,再轉成 ENV 讓程式執行時也讀得到」:

# FROM 之前的 ARG 只能用在 FROM 那一行
ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-bookworm-slim

# FROM 之後要再宣告一次才能在這個階段使用
ARG APP_VERSION=0.0.0
ENV APP_VERSION=${APP_VERSION}
LABEL org.opencontainers.image.version=${APP_VERSION}

BuildKit 也內建一組自動提供的 ARG,寫跨架構 Dockerfile 時很好用:TARGETPLATFORM、TARGETOS、TARGETARCH、BUILDPLATFORM(例如建置在 linux/arm64、目標是 linux/amd64)。要用之前一樣要 ARG TARGETARCH 宣告。

COPY 與 ADD

  • 優先用 COPY:行為單純,就是複製。
  • ADD 本機.tar.gz /dest/ 會自動解壓縮,有時這是你要的,有時是意外(你只是想複製一個 tar 檔進去)。
  • ADD https://… 可以下載檔案,但沒有快取控制,網址內容變了也可能沿用舊快取;如果要用,搭配 --checksum=sha256:… 確保內容一致,或乾脆改在 RUN 裡用 curl 下載並驗證。
  • COPY --chown=app:app:複製時直接設定擁有者,不要事後再 RUN chown -R(那會把所有檔案再複製一份到新的層,映像檔變兩倍大)。
  • COPY --chmod=0755:同理,直接設定權限。
  • COPY --from=<階段或映像檔>:從前面的階段,甚至直接從別的映像檔複製檔案,例如 COPY --from=busybox:1.37 /bin/busybox /busybox。
  • COPY --link:讓這一層不依賴前面的層,換基底映像檔時可以不必重建這層,在多階段建置的最後階段特別有用。

SHELL 與 pipefail

RUN 的字串格式預設用 /bin/sh -c 執行。在管線裡,只有最後一個指令的結束代碼會被檢查,所以 RUN curl -fsSL https://example.com/install.sh | sh 在 curl 下載失敗時,sh 收到空輸入照樣回傳 0,建置會「成功」但什麼都沒裝。加上 pipefail 可以避免:

SHELL ["/bin/sh", "-eo", "pipefail", "-c"]
RUN curl -fsSL https://example.com/tool.tar.gz | tar xz -C /usr/local/bin

注意 pipefail 需要 shell 支援。Alpine 的 busybox ash 可以(我用 alpine:3.22 實際建置過上面的設定);但 Debian/Ubuntu 的 /bin/sh 是 dash,不支援 pipefail,我在 debian:bookworm-slim(dash 0.5.12)上實測會得到 Illegal option -o pipefail,建置直接失敗。Debian 系的映像檔請改用 bash:

SHELL ["/bin/bash", "-o", "pipefail", "-c"]

Heredoc:多行 RUN 與內嵌檔案

dockerfile 語法 1.4 之後支援 heredoc,長的 RUN 不用再寫滿反斜線,也可以直接在 Dockerfile 裡產生小檔案:

# syntax=docker/dockerfile:1
FROM alpine:3.22
RUN <<EOT
set -e
apk add --no-cache curl
echo "built at $(date)" > /build-info.txt
EOT

COPY --chmod=0755 <<'EOT' /usr/local/bin/hello
#!/bin/sh
echo "hello from $APP_VERSION"
EOT

heredoc 的 RUN 仍然是一層,所以「必寫」的原則一樣適用:安裝和清理放在同一個 heredoc 裡。分隔字加引號('EOT')時,內容裡的 $變數 不會在建置時展開。

ONBUILD:不建議使用

ONBUILD COPY . /app 的意思是「別人 FROM 我的時候才執行這行」。它讓下游的 Dockerfile 看起來很短,但行為不透明:看 Dockerfile 的人不知道建置時多做了什麼,出錯時也很難追。Docker 官方已經把語言映像檔的 -onbuild 版本停用多年,我的建議是不要用,把步驟明確寫在每個 Dockerfile 裡。

用 docker build --check 檢查寫法

BuildKit 內建 Dockerfile 檢查規則,不必真的建置就能找出常見問題:

$ docker build --check .
Check complete, 3 warnings have been found!
WARNING: FromAsCasing - …              # FROM 與 AS 大小寫不一致(from … as)
WARNING: SecretsUsedInArgOrEnv - …     # ARG/ENV 名稱看起來像密碼
WARNING: JSONArgsRecommended - …       # CMD/ENTRYPOINT 建議用 JSON 陣列格式

上面是我故意寫錯的測試 Dockerfile 檢查出來的結果。SecretsUsedInArgOrEnv 特別值得注意,它會在你寫 ENV DB_PASSWORD=… 時提醒你。CI 流水線裡可以加一步 docker build --check .,有警告就讓流程失敗。

.dockerignore

建置時 Docker 會把整個目錄(build context)送給 builder,沒排除的話 node_modules、.git、甚至 .env 都會被送進去,建置慢又可能把密碼包進映像檔:

.git
node_modules
dist
*.log
.env
.env.*
Dockerfile
docker-compose*.yml

補充幾個實用的寫法與觀念:

  • **/node_modules 可以排除所有子資料夾裡的 node_modules;! 開頭代表例外,例如排除 *.md 但保留 !README.md。
  • 建議也排除 compose*.yaml、.github、coverage、__pycache__、.venv、IDE 設定資料夾(.idea、.vscode)。
  • .dockerignore 要放在 build context 的根目錄。用 -f 指定別處的 Dockerfile 時,也可以放一個同名的 <Dockerfile 名稱>.dockerignore(例如 docker/api.Dockerfile.dockerignore),它會優先使用。
  • 建置輸出第一段 transferring context: 1.2GB 如果很大,就是 .dockerignore 沒寫好。
  • 就算排除了 .env,也不要依賴 .dockerignore 當作唯一的保護;機密本來就不該放在專案資料夾裡和程式碼混在一起。

更多 Dockerfile 範例

下面三個範例都在本機實際建置並執行過(Python 與 Go 有實際打健康檢查端點、PHP 有實際透過 nginx 執行 PHP 頁面)。

Python:venv + 多階段 + 一般使用者

# syntax=docker/dockerfile:1
FROM python:3.13-slim AS base
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /app

FROM base AS deps
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    python -m venv /opt/venv \
 && /opt/venv/bin/pip install -r requirements.txt

FROM base
RUN groupadd --system app && useradd --system --gid app --no-create-home app
COPY --from=deps /opt/venv /opt/venv
COPY --chown=app:app app.py .
ENV PATH="/opt/venv/bin:$PATH"
USER app
EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "app:app"]
  • PYTHONUNBUFFERED=1:讓 print 與日誌立刻輸出,否則 docker logs 會延遲好一陣子才出現內容,甚至容器當掉時最後幾行永遠看不到。
  • PYTHONDONTWRITEBYTECODE=1:不產生 .pyc,避免容器的可寫層多出一堆檔案。
  • 相依安裝在 /opt/venv,最後階段整包複製過去。需要編譯的套件(如 psycopg 非 binary 版)可以在 deps 階段安裝 build-essential,最後階段完全不會有編譯器。
  • pip 的下載快取用 --mount=type=cache 保存在 builder 裡,不會進映像檔,所以不需要 --no-cache-dir,重建時也不用重新下載。
  • gunicorn 的 --workers 明確指定,不要讓它依主機核心數自動計算(見前面資源限制一節)。

實測結果:映像檔 161 MB,docker exec … id 顯示 uid=999(app),健康檢查端點正常回應。

Go:靜態編譯 + distroless 或 scratch

Go 可以編成不依賴任何系統函式庫的靜態執行檔,最終映像檔只需要那一個檔案:

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build
ARG TARGETOS
ARG TARGETARCH
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -trimpath -ldflags="-s -w" -o /out/app .

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]
  • FROM --platform=$BUILDPLATFORM:編譯階段固定在建置主機的原生架構執行(不經模擬,快很多),再用 GOOS/GOARCH 交叉編譯成目標架構。我在 Apple 晶片上用 --platform linux/amd64 建置,產出的映像檔確認是 linux/amd64。
  • CGO_ENABLED=0:關閉 cgo,產生純靜態執行檔;如果程式用到 cgo(例如 SQLite 的某些驅動),就不能用 scratch,要改用 distroless/base 這類帶 glibc 的基底。
  • -trimpath -ldflags="-s -w":移除建置路徑與除錯符號,檔案更小。
  • 兩個 cache mount 分別保存模組下載與編譯快取,重建通常只要幾秒。
  • 專案沒有任何外部相依、還沒有 go.sum 時,COPY go.mod go.sum ./ 會因為找不到檔案而失敗,改成只 COPY go.mod ./ 即可。

distroless 和 scratch 的差別:

基底實測大小內容適合
scratch5.37 MB完全空白,只有你複製進去的檔案極簡;但沒有 CA 憑證、時區資料、/etc/passwd,要自己補
distroless/static-debian12:nonroot7.49 MBCA 憑證、tzdata、/etc/passwd(含 nonroot 使用者 65532)多數 Go 服務的首選

用 scratch 時,程式要呼叫 HTTPS API 就得自己複製 CA 憑證:COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/(alpine 的 golang 映像檔要先 apk add ca-certificates);要用時區就複製 /usr/share/zoneinfo,或在 Go 程式裡 import _ "time/tzdata" 把時區資料編進執行檔。

兩者都沒有 shell,docker exec -it … sh 會失敗。distroless 另外提供 :debug 標籤的版本,內含 busybox shell,可在除錯時暫時替換。

PHP-FPM + nginx

PHP 的典型架構是兩個容器:nginx 處理靜態檔案並把 .php 請求透過 FastCGI 轉給 PHP-FPM。

# syntax=docker/dockerfile:1
FROM php:8.4-fpm-alpine
RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS \
 && docker-php-ext-install -j"$(nproc)" pdo_mysql opcache \
 && apk del .build-deps
COPY docker/php.ini /usr/local/etc/php/conf.d/zz-app.ini
WORKDIR /var/www/html
COPY --chown=www-data:www-data public/ ./public/
USER www-data

docker/php.ini(正式環境的 opcache 設定):

opcache.enable=1
opcache.validate_timestamps=0
expose_php=Off
memory_limit=256M

docker/nginx/default.conf:

server {
    listen 80;
    root /var/www/html/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

compose.yaml:

services:
  php:
    build: .
    image: example.com/myapp/php:1.0
    volumes:
      - app-code:/var/www/html/public
  nginx:
    image: nginx:1.27-alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - app-code:/var/www/html/public:ro
    depends_on:
      - php
volumes:
  app-code:

重點與陷阱:

  • fastcgi_pass php:9000 的 php 是 Compose 服務名稱,靠內建 DNS 解析。
  • nginx 需要看得到靜態檔案,PHP-FPM 需要看得到 .php 檔案,而且兩邊的路徑必須相同(SCRIPT_FILENAME 是 nginx 算出來、交給 PHP-FPM 去開的路徑)。上面用一個 named volume 共用:volume 第一次建立時,會從 php 映像檔複製 public/ 的內容進去。
  • ⚠️ 這個共用 volume 的做法有個大坑:前面說過 volume 只在空的時候初始化一次。程式更新、重建映像檔後,volume 裡還是舊版程式碼。部署新版時要 docker compose down 後 docker volume rm <專案>_app-code 再 up;更好的做法是另外建一個 nginx 映像檔,用 COPY --from 把靜態檔案直接複製進去,完全不用共用 volume。
  • 官方 php 映像檔用 docker-php-ext-install 安裝擴充功能,編譯工具用 --virtual .build-deps 包起來,裝完立刻刪除——一樣是「必寫」的精神。
  • opcache.validate_timestamps=0 代表不檢查檔案是否變更,效能最好,但改程式碼必須重啟 PHP-FPM 容器;開發環境請設成 1。

實測:curl 打 nginx 回傳 php 8.4.x opcache=1 pdo_mysql=1,docker compose exec nginx nginx -t 顯示設定正確。

各語言的快取技巧整理

語言先複製的相依檔安裝指令cache mount 目標
Node.js(npm)package.json、package-lock.jsonnpm ci/root/.npm
Node.js(pnpm)package.json、pnpm-lock.yamlpnpm install --frozen-lockfilepnpm store 路徑(可用 pnpm store path 查)
Python(pip)requirements.txtpip install -r requirements.txt/root/.cache/pip
Python(uv)pyproject.toml、uv.lockuv sync --frozen --no-install-project/root/.cache/uv
Gogo.mod、go.sumgo mod download/go/pkg/mod、/root/.cache/go-build
Java(Maven)pom.xmlmvn dependency:go-offline/root/.m2
RustCargo.toml、Cargo.lockcargo build --release/usr/local/cargo/registry、/app/target
PHP(Composer)composer.json、composer.lockcomposer install --no-dev --no-scripts/tmp/cache 或 COMPOSER_CACHE_DIR
Debian apt—apt-get install/var/cache/apt、/var/lib/apt(要加 sharing=locked)

共通原則:lock 檔一定要提交到版本控制並複製進建置。沒有 lock 檔,每次建置拿到的相依版本都可能不同,「上週能建、今天建不起來」大多是這個原因。

cache mount 的路徑是以執行該 RUN 的使用者為準的:若前面已經 USER app,pip 的快取就會在 /home/app/.cache/pip,target 也要跟著改,否則快取不會生效。另外 Rust 把 target 放在 cache mount 裡時,編出來的執行檔也在快取裡、不在映像檔層中,要在同一個 RUN 裡把執行檔 cp 到其他路徑。

BuildKit 進階:cache、secret、ssh 掛載

--mount=type=cache:跨建置保存快取

一般的層快取是「全有或全無」:requirements.txt 只要改一行,整個 pip install 層就要重跑,所有套件重新下載。cache mount 則是把套件管理工具的下載快取目錄保存在 builder 裡,就算那一層要重跑,已經下載過的套件也不必重新下載,而且快取內容不會進入映像檔。

# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
# Debian 映像檔預設會在安裝後自動清掉 apt 快取,要用 cache mount 時先關掉這個行為
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
 && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates

這個寫法和開頭的「必寫」並不衝突:用 cache mount 時,/var/cache/apt 與 /var/lib/apt 根本不在映像檔層裡,所以不必再 rm -rf;沒有用 cache mount 的一般寫法,就一定要在同一個 RUN 裡清掉。sharing=locked 是因為 apt 不允許兩個程序同時使用同一個快取目錄,平行建置多個階段時要上鎖。

cache mount 存在 builder 的建置快取裡,docker builder prune 會把它清掉;CI 環境每次都是全新的 runner 時,它就沒有效果,要搭配後面講的 --cache-to/--cache-from(注意這兩個只匯出層快取,不包含 cache mount 的內容)。

--mount=type=secret:建置時使用密碼但不留在映像檔

建置時需要私有套件庫的 token、或下載內部檔案的憑證,最常見的錯誤是 ARG NPM_TOKEN 或 COPY .npmrc,這些都會留在映像檔或建置歷史裡。正確做法是 secret mount:

# syntax=docker/dockerfile:1
FROM alpine:3.22
# 以檔案形式提供,預設路徑 /run/secrets/<id>
RUN --mount=type=secret,id=api_token \
    wc -c < /run/secrets/api_token
# 也可以直接變成環境變數(只在這個 RUN 裡有效)
RUN --mount=type=secret,id=api_token,env=API_TOKEN \
    test -n "$API_TOKEN" && echo "token length: ${#API_TOKEN}"
docker build --secret id=api_token,src=./token.txt -t myapp:1.0 .      # 從檔案
docker build --secret id=api_token,env=API_TOKEN -t myapp:1.0 .        # 從建置主機的環境變數

我實測過:建置輸出顯示 token 長度正確,之後用 docker history --no-trunc 搜尋 token 內容,找不到任何一筆。npm 私有套件庫的實際用法是 RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci,把整個 .npmrc 當作 secret 掛到它該在的位置。

⚠️ secret mount 只保護「映像檔層」。如果你在 RUN 裡把 secret 的內容寫進其他檔案(例如 cp /run/secrets/api_token /app/config),它還是會被包進去。

--mount=type=ssh:用 SSH 金鑰拉私有 Git 儲存庫

# syntax=docker/dockerfile:1
FROM alpine:3.22
RUN apk add --no-cache git openssh-client \
 && mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh git clone git@github.com:<組織>/<私有儲存庫>.git /src
docker build --ssh default -t myapp:1.0 .     # 把本機的 ssh-agent 轉送給建置過程

私鑰從頭到尾都留在你的 ssh-agent 裡,不會被複製進建置環境。這個範例需要真正的私有儲存庫才能驗證,我只確認過 --ssh 參數存在,實際流程請在自己的環境測試。

docker init:自動產生起手檔案

docker init 是 Docker Desktop 內建的指令,在專案資料夾執行後,會問你幾個問題(語言、版本、啟動指令、監聽的埠),然後產生四個檔案:

  • Dockerfile:依語言產生的多階段建置範本,已經包含 cache mount、非 root 使用者等最佳實踐。
  • compose.yaml:一個服務的基本設定,常見的資料庫設定以註解形式附在裡面。
  • .dockerignore:該語言常見的排除清單。
  • README.Docker.md:建置與部署的說明。
cd my-project
docker init                     # 互動式問答
docker build -t myapp:dev .
docker compose up --build

支援的範本包含 Go、Python、Node、Rust、ASP.NET Core、PHP、Java,其他語言可以選「Other」產生通用範本。已經有 Dockerfile 的資料夾執行時會詢問是否覆蓋。我覺得它最大的價值是「看官方建議的寫法」:產生出來的 Dockerfile 很適合當作學習範本,再依專案調整。docker init 是互動式工具,我只在本機確認過指令存在,不同版本產生的內容可能略有差異。Linux 上的 Docker Engine 不一定附帶這個外掛,找不到指令時代表它沒有安裝。

建置映像檔

docker build -t myapp:1.0 .
docker build -t myapp:1.0 -f docker/Dockerfile .     # 指定 Dockerfile 位置
docker build --no-cache -t myapp:1.0 .               # 不使用快取(懷疑快取有問題時)
docker build --build-arg VERSION=1.0 -t myapp:1.0 .
docker build --target build -t myapp:build .         # 只建置到某一個階段(除錯用)
docker build --progress=plain -t myapp:1.0 .         # 顯示完整輸出

更多實用參數:

docker build -t myapp:1.4.2 -t myapp:latest .                # 一次加多個 tag
docker build --pull -t myapp:1.0 .                           # 強制檢查基底映像檔有沒有新版(定期重建時必加)
docker build --no-cache-filter deps -t myapp:1.0 .           # 只讓指定階段不用快取
docker build --label org.opencontainers.image.revision=$(git rev-parse --short HEAD) -t myapp:1.0 .
docker build --build-context shared=../shared -t myapp:1.0 . # 額外的 context,Dockerfile 用 COPY --from=shared
docker build -o type=local,dest=./out --target export .      # 不產生映像檔,把建置結果輸出到本機資料夾
docker build --check .                                        # 只做 Dockerfile 檢查
cat Dockerfile | docker build -t myapp:1.0 -f- .             # Dockerfile 從 stdin 讀入

看懂建置輸出

#8 [deps 2/2] RUN --mount=type=cache,target=/root/.cache/pip …
#8 CACHED
#10 [stage-2 3/4] COPY --chown=app:app app.py .
#10 DONE 0.0s
  • #8 是步驟編號,BuildKit 會平行執行沒有相依關係的步驟,所以編號不一定依序出現。
  • [deps 2/2] 是「階段名稱 第幾步/共幾步」,沒命名的階段顯示為 stage-N。
  • CACHED 代表命中快取;某一步沒有命中,它之後同一階段的所有步驟都會重跑。如果你發現「改了 README 也重裝所有套件」,就是 COPY 的順序或 .dockerignore 有問題。
  • 預設的精簡輸出看不到 RUN 的完整訊息,除錯時加 --progress=plain;想看 RUN 每次都真正執行的輸出,再加 --no-cache。
  • 錯誤時 BuildKit 會印出 Dockerfile 對應的行號與前後幾行,往上找 ERROR 那一段最直接。
docker buildx history ls                 # 最近的建置紀錄
docker buildx history inspect <建置ID>   # 某次建置的詳細資訊(耗時、快取命中、錯誤)

buildx:跨架構建置

docker buildx ls                                   # 可用的 builder 與支援的平台
docker buildx create --name multi --use            # 建立支援多平台的 builder
docker buildx build --platform linux/amd64,linux/arm64 -t myrepo/myapp:1.0 --push .   # 同時建兩種架構並推送
docker buildx build --platform linux/amd64 -t myapp:1.0 --load .                      # 只建 amd64 並載入本機

在 Apple 晶片的 Mac 上直接 docker build,產生的是 arm64 映像檔,丟到 x86 主機上會出現 exec format error。要部署到不同架構的主機,請用 --platform 指定。

builder 驅動的差別

驅動說明多平台映像檔匯出快取(--cache-to)
docker(預設)直接用 daemon 內建的 BuildKit,結果直接進本機映像檔傳統儲存驅動下不支援一次建多平台不支援(除非啟用 containerd 映像檔儲存區)
docker-container在容器裡跑一個獨立的 BuildKit支援支援
kubernetes在 Kubernetes 叢集裡跑 BuildKit支援支援
remote連到自己架設的 BuildKit 服務支援支援

這張表是我踩過的坑:用預設 builder 執行 --cache-to type=local,直接報錯 Cache export is not supported for the docker driver。建立一個 docker-container 驅動的 builder 之後就正常了:

docker buildx create --name ci --driver docker-container --bootstrap
docker buildx build --builder ci \
  --cache-to type=local,dest=/tmp/buildcache,mode=max \
  --cache-from type=local,src=/tmp/buildcache \
  -t myapp:1.0 --load .
docker buildx rm ci          # 移除 builder(連同它的建置快取)

用 docker-container 驅動時,建置結果預設只留在 builder 的快取裡,不會出現在 docker images,要加 --load(載入本機)或 --push(推到 registry)。忘了加時會看到警告 No output specified … build result will only remain in the build cache。

模擬與交叉編譯

跨架構建置有兩種方式:

  • QEMU 模擬:BuildKit 用模擬器執行另一個架構的 RUN 指令。什麼語言都能用、Dockerfile 不必改,但很慢,npm ci 或編譯 C 擴充可能慢上 5~20 倍。Docker Desktop 已內建;Linux 主機要先安裝 binfmt:docker run --privileged --rm tonistiigi/binfmt --install all(⚠️ 需要 privileged,會修改主機核心的 binfmt 設定)。
  • 交叉編譯:像前面 Go 範例那樣,編譯階段用 --platform=$BUILDPLATFORM 原生執行,只產出目標架構的檔案。快很多,但需要語言工具鏈支援(Go、Rust、.NET 都很好做)。

多架構 manifest

docker buildx build --platform linux/amd64,linux/arm64 --push 會把兩個架構的映像檔和一個 index 一起推上去。如果兩個架構是在不同機器上分別建置的(例如 CI 裡用原生的 arm64 runner 和 amd64 runner 各建一次,避免模擬),可以事後把它們合併成一個名稱:

# 兩台 runner 各自推送單一架構的映像檔
docker buildx build --platform linux/amd64 -t registry.example.com/myapp:1.0-amd64 --push .
docker buildx build --platform linux/arm64 -t registry.example.com/myapp:1.0-arm64 --push .
# 合併成一個多架構 tag(在 registry 上直接組合,不需要下載映像檔)
docker buildx imagetools create -t registry.example.com/myapp:1.0 \
  registry.example.com/myapp:1.0-amd64 \
  registry.example.com/myapp:1.0-arm64
docker buildx imagetools inspect registry.example.com/myapp:1.0     # 確認兩個平台都在

舊的 docker manifest create/docker manifest push 也能做到同樣的事,但 imagetools 支援 OCI 格式與 attestation,建議用新的。這段需要推送到 registry,我沒有在本機實際推送,只驗證了指令與參數存在,以及用 imagetools inspect 讀取公開映像檔的 index。

CI/CD 的建置快取:--cache-from 與 --cache-to

CI runner 每次都是乾淨的環境,沒有上次的層快取,所以每次建置都從頭來。解法是把快取匯出到外部,下次再匯入:

類型寫法適用
registry--cache-to type=registry,ref=registry.example.com/myapp:buildcache,mode=max、--cache-from type=registry,ref=registry.example.com/myapp:buildcache通用,任何 CI 都能用,快取存成 registry 上的一個獨立 tag
inline--cache-to type=inline把快取資訊寫進映像檔本身;只支援 mode=min,多階段建置的中間階段不會被快取
gha--cache-to type=gha,mode=max、--cache-from type=ghaGitHub Actions 專用的快取服務
local--cache-to type=local,dest=路徑自架 runner、可保存目錄的環境(本機已實測)
s3--cache-to type=s3,region=…,bucket=…AWS 環境

mode=min(預設)只匯出最終映像檔用到的層;mode=max 連中間階段(例如 deps、build 階段)的層都匯出,多階段建置一定要用 max,否則最花時間的相依安裝階段根本沒被快取。

GitHub Actions 的典型寫法(以官方 actions 為例,版本號請以官方最新為準):

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

這段是 GitHub Actions 的設定檔,我只檢查了 YAML 語法,沒有實際在 GitHub 上執行。setup-buildx-action 會自動建立 docker-container 驅動的 builder,所以快取匯出可以正常運作。密碼只透過 secrets 取得,不會寫在檔案裡。

建置後順便產生 SBOM 與來源證明(provenance),供應鏈安全掃描會用到:docker buildx build --sbom=true --provenance=mode=max -t … --push .。這些 attestation 就是前面 imagetools inspect 看到的 unknown/unknown 項目。

Docker Compose

Compose 用一個 YAML 檔描述多個容器(服務)、網路與 volume,讓整組服務可以一行指令建立、更新、刪除。檔名預設依序找 compose.yaml、compose.yml、docker-compose.yaml、docker-compose.yml,新專案建議用 compose.yaml。檔案開頭的 version: "3.8" 已經過時,Compose v2 會忽略它並顯示警告,可以直接刪掉。

compose.yaml 範例

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      api:
        condition: service_healthy
    restart: unless-stopped

  api:
    build: ./api
    env_file: .env
    environment:
      TZ: Asia/Taipei
      DB_HOST: db
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 3s
      retries: 3
    restart: unless-stopped

  db:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: app
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
    secrets:
      - db_root_password
    volumes:
      - db-data:/var/lib/mysql
    ports:
      - "127.0.0.1:3306:3306"
    restart: unless-stopped

volumes:
  db-data:

secrets:
  db_root_password:
    file: ./secrets/db_root_password.txt

Compose 會自動建立一個專案專用的網路,所以 api 用 db 這個名稱就能連到資料庫。密碼放在 secrets 或 .env 檔,並把它們加進 .gitignore,不要寫在 compose.yaml 裡一起進版本控制。

非 Swarm 模式下的 secrets,本質上是把檔案以唯讀 bind mount 掛到容器的 /run/secrets/<名稱>。它比環境變數安全的地方在於:不會出現在 docker inspect 的 Config.Env 裡,也不會被子程序繼承或在錯誤報告中被印出。所以 MySQL、PostgreSQL 等官方映像檔都支援 *_FILE 結尾的變數,從檔案讀取密碼。

專案名稱與資源命名

Compose 用「專案名稱」區分不同組服務,預設是 compose 檔所在的資料夾名稱。容器、網路、volume 都會加上這個前綴:

資源命名規則例子(專案 myapp)
容器<專案>-<服務>-<編號>myapp-api-1
網路<專案>_<網路>myapp_default
volume<專案>_<volume>myapp_db-data

⚠️ 這代表資料夾改名,專案名稱就變了,下次 up 會建立一組全新的容器和全新的空 volume,看起來資料全部消失(舊 volume 還在,只是名稱前綴不同)。正式環境建議在 compose 檔最上面寫死專案名稱:

name: myapp
services:
  …

也可以用 docker compose -p <專案名稱> 或環境變數 COMPOSE_PROJECT_NAME 指定。Compose 用容器上的標籤(com.docker.compose.project、com.docker.compose.service)辨識哪些容器屬於哪個專案,所以手動用 docker run 建立的容器,Compose 不會管理它。

常用指令

docker compose up -d                 # 建立並在背景啟動全部服務
docker compose up -d --build         # 先重新建置再啟動
docker compose ps                    # 各服務狀態
docker compose logs -f api           # 追蹤某個服務的日誌
docker compose exec api sh           # 進入某個服務的容器
docker compose restart api
docker compose stop                  # 停止但保留容器
docker compose down                  # 停止並刪除容器與網路(volume 保留)
docker compose down -v               # ⚠️ 連 volume 一起刪除=資料一起刪除
docker compose pull                  # 下載新版映像檔
docker compose up -d                 # 拉完新映像檔後再 up,只會重建有變動的服務
docker compose config                # 顯示合併、展開變數後的最終設定(排查設定錯誤很好用)
docker compose -f compose.yaml -f compose.prod.yaml up -d   # 疊加不同環境的設定

進階但常用的指令:

docker compose up -d --wait                  # 等到所有服務 healthy(或啟動完成)才返回,部署腳本必備
docker compose up -d --no-deps api           # 只重建 api,不動它依賴的服務
docker compose up -d --force-recreate api    # 設定沒變也強制重建
docker compose up -d --remove-orphans        # 刪除 compose 檔裡已經不存在的服務的容器
docker compose up -d --scale worker=3        # 同一個服務跑 3 個容器(不能有固定的主機埠)
docker compose run --rm api npm run migrate  # 用服務的設定跑一次性指令
docker compose run --rm --service-ports api  # run 預設不開 ports,要加這個才會
docker compose exec -T db pg_dump -U postgres app > app.sql   # -T 不配置終端機,輸出重新導向時必加
docker compose logs -f --tail 50 -t          # 所有服務最近 50 行並加時間戳記
docker compose logs --since 10m api
docker compose top                           # 各服務容器內的程序
docker compose images                        # 各服務實際使用的映像檔與 tag
docker compose ls                            # 這台主機上所有 Compose 專案與 compose 檔路徑
docker compose cp api:/app/logs ./logs       # 複製檔案
docker compose down --rmi local              # 一併刪除 build 出來的映像檔
docker compose config --services             # 列出所有服務名稱
docker compose config --images               # 列出所有會用到的映像檔
docker compose config --variables            # 列出 compose 檔用到的變數與預設值
docker compose --dry-run up -d               # 只顯示會做什麼,不實際執行

docker compose ls 很好用:主機上跑了一堆服務、忘了 compose 檔放在哪裡時,它會列出每個專案的狀態與設定檔路徑。另外 stop 與 down 的差別要分清楚:stop 只停容器,start 可以原樣再啟動;down 會刪容器與網路,下次 up 是重新建立(volume 預設保留)。

up -d 什麼時候會重建容器

Compose 會比較「compose 檔算出來的設定」和「現有容器的設定」,有差異才重建。會觸發重建的情況:映像檔 ID 變了(pull 到新版、重新 build)、environment/ports/volumes/command 等設定改了、引用的 env_file 內容改了。不會觸發重建的情況:bind mount 掛進去的設定檔內容改了(例如 nginx.conf)——檔案已經直接反映到容器裡,但程式不一定會重新讀取,需要 docker compose restart web 或送 reload 訊號(docker compose exec web nginx -s reload)。

環境變數插值規則

compose 檔裡可以用 ${變數} 引用變數,Compose 在解析檔案時就替換掉(這叫插值,interpolation),跟容器裡的環境變數是兩回事。

寫法變數未設定變數設為空字串用途
${VAR}空字串並顯示警告空字串一般引用
${VAR:-預設值}預設值預設值最常用
${VAR-預設值}預設值空字串允許刻意設為空
${VAR:?錯誤訊息}中止並顯示錯誤中止並顯示錯誤必填的變數
${VAR?錯誤訊息}中止並顯示錯誤空字串必須存在但可以是空的
${VAR:+替代值}空字串空字串有設定時才使用替代值
$$輸出一個字面上的 $,不做插值要把 $VAR 留給容器裡的 shell 展開時

實測必填變數沒設定時的錯誤訊息長這樣,會直接拒絕執行,比默默用空字串啟動安全很多:

$ docker compose config -q
error while interpolating services.api.image: required variable TAG is missing a value: 請在 .env 設定 TAG

$$ 的典型用途是健康檢查:test: ["CMD-SHELL", "pg_isready -U postgres -d $${POSTGRES_DB}"]。寫成單一個 $ 的話,Compose 會在解析時就用主機上的 POSTGRES_DB(通常不存在)替換成空字串;寫成 $$,才會留到容器裡由 shell 讀取容器自己的環境變數。

.env 與變數的優先順序

這是 Compose 最容易搞混的地方:「compose 檔插值用的變數」與「容器裡的環境變數」是兩套機制。

插值用的變數(${TAG} 這種)來源,優先順序由高到低:

  1. 執行 docker compose 時 shell 裡的環境變數(例如 TAG=9.9.9 docker compose up -d)。
  2. --env-file 指定的檔案(可指定多個,後面的覆蓋前面的)。
  3. 專案目錄下的 .env 檔(沒有指定 --env-file 時才讀)。

我實測過:.env 裡 TAG=1.4.2,執行 TAG=9.9.9 docker compose config --images 得到 api:9.9.9;改用 --env-file prod.env(內容 TAG=2.0.0)則得到 api:2.0.0。

容器裡的環境變數則由服務定義決定,優先順序由高到低:

  1. docker compose run -e KEY=值 指定的。
  2. 服務的 environment:。
  3. 服務的 env_file:。
  4. 映像檔 Dockerfile 裡的 ENV。

實測同一個變數 A 同時出現在 environment(from-environment)和 env_file(from-env-file),最後容器拿到的是 from-environment。

⚠️ 專案目錄的 .env 不會自動變成容器的環境變數,它只用於 compose 檔的插值。要讓容器讀到,必須在服務裡寫 env_file: .env,或在 environment 裡逐一引用 KEY: ${KEY}。很多人以為「放了 .env 容器就讀得到」,結果程式讀不到設定。

.env 檔的格式:一行一個 KEY=值,# 開頭是註解;值有空白或特殊字元時用引號包起來;單引號內不做插值,雙引號內會。這個檔案通常含有密碼,請加入 .gitignore,另外提交一份不含真實值的 .env.example 給其他人參考。

其他可以在 shell 或 .env 裡設定、影響 Compose 本身行為的變數:COMPOSE_PROJECT_NAME(專案名稱)、COMPOSE_FILE(要載入的 compose 檔,用冒號分隔,例如 compose.yaml:compose.prod.yaml)、COMPOSE_PROFILES(要啟用的 profile)。我實測過在 .env 以外用環境變數設定 COMPOSE_FILE 與 COMPOSE_PROFILES 都能生效,很適合用來讓正式主機「預設就載入正式環境的設定」。

override 檔:疊加不同環境的設定

同一個資料夾裡如果有 compose.override.yaml,執行 docker compose 時會自動和 compose.yaml 合併。常見分工:

  • compose.yaml:所有環境共用的基本定義。
  • compose.override.yaml:開發環境專用(開 debug 埠、掛原始碼、LOG_LEVEL: debug),不必每次指定就會載入。
  • compose.prod.yaml:正式環境專用,用 -f compose.yaml -f compose.prod.yaml 明確指定。
# compose.override.yaml(開發用)
services:
  api:
    environment:
      LOG_LEVEL: debug
    ports:
      - "127.0.0.1:3000:3000"

⚠️ 一旦用 -f 明確指定檔案,compose.override.yaml 就不會自動載入。我實測:不加 -f 時 LOG_LEVEL 是 override 檔裡的 debug;加上 -f compose.yaml -f compose.prod.yaml 後變回 info。這通常就是你要的行為(正式環境不想吃到開發設定),但要知道它的存在。

合併規則:單一值(image、command)後面覆蓋前面;environment、labels 這類對應表依鍵合併;ports、expose、dns 這類清單會附加而不是取代。想在 override 檔裡清掉基本檔的某個清單,可以用 !reset 標記,例如 ports: !reset [];想完整取代則用 !override。合併後的結果一律用 docker compose config 確認。

extends 與 include:重用設定

extends 讓一個服務繼承另一個服務(可以在別的檔案)的設定,適合多個服務共用日誌、時區、重啟策略:

# common.yaml
services:
  base-app:
    restart: unless-stopped
    environment:
      TZ: Asia/Taipei
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
# compose.yaml
services:
  api:
    image: example.com/myapp/api:1.0
    extends:
      file: common.yaml
      service: base-app

include 則是把整份 compose 檔(連同它的服務、網路、volume)引入,適合把大型專案拆成多個資料夾,各自維護:

include:
  - path: ./db/compose.yaml
services:
  app:
    image: example.com/myapp/app:1.0
    depends_on: [db]

兩者的差別我實測過:用 include 引入只放共用片段的 common.yaml 會失敗(service "base-app" has neither an image nor a build context specified),因為 include 會把裡面的服務當成真正的服務;共用片段請用 extends。另一個常用的重用方法是 YAML 錨點,搭配 x- 開頭的擴充欄位(Compose 會忽略 x- 開頭的頂層欄位):

x-healthcheck: &default-health
  interval: 10s
  timeout: 3s
  retries: 5
  start_period: 20s

services:
  db:
    image: postgres:17
    healthcheck:
      <<: *default-health
      test: ["CMD-SHELL", "pg_isready -U postgres"]

profiles:選擇性啟動的服務

有些服務只有特定時候需要(資料庫管理介面、除錯工具、一次性的資料匯入),可以放進 profile,預設不會啟動:

services:
  adminer:
    image: adminer:5
    profiles: ["debug"]
    ports:
      - "127.0.0.1:8081:8080"
docker compose up -d                       # 不會啟動 adminer
docker compose --profile debug up -d       # 一起啟動
COMPOSE_PROFILES=debug docker compose up -d
docker compose config --profiles           # 列出所有 profile

沒有設定 profiles 的服務永遠會啟動。直接指定服務名稱(docker compose up -d adminer)時,也會啟動它而不需要另外啟用 profile。⚠️ 注意 docker compose down 時如果沒有加 --profile,Compose 不會處理 profile 裡的服務。我實測用 --profile debug up -d 啟動後只打 docker compose down,profile 裡的容器還在跑,專案網路也因為 Resource is still in use 刪不掉;關閉時請帶上相同的 --profile。

depends_on 的條件

單純的 depends_on: [db] 只保證「db 容器先啟動」,不保證 db 已經可以連線。資料庫啟動到可以接受連線常常要好幾秒,api 搶先連線就失敗。用長格式指定條件:

condition意義適用
service_started容器已啟動(預設,等同短格式)沒有健康檢查的服務
service_healthy健康檢查回報 healthy資料庫、需要暖機的服務(被依賴的服務必須有 healthcheck)
service_completed_successfully容器執行完畢且結束代碼為 0migration、初始化這類一次性工作
services:
  api:
    depends_on:
      db:
        condition: service_healthy
        restart: true          # db 被 Compose 重啟時,api 也跟著重啟
      migrate:
        condition: service_completed_successfully
      cache:
        condition: service_started
        required: false        # cache 不存在或沒啟用(例如在 profile 裡)也沒關係

我用 busybox 實際跑過這三種條件的組合:docker compose up -d --wait 會先等 app 的健康檢查通過、job 執行完畢(Exited 0),才啟動依賴它們的 web。要注意 depends_on 只在 Compose 啟動時有作用:資料庫在執行途中重啟,Compose 不會幫你處理(restart: true 只處理 Compose 自己發起的重啟),程式本身仍然要有斷線重連的能力。

healthcheck 的寫法

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]   # 不經 shell,直接執行
  # test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/health || exit 1"]   # 經 sh -c,可用管線
  interval: 10s        # 多久檢查一次
  timeout: 3s          # 單次檢查逾時
  retries: 5           # 連續失敗幾次才判定 unhealthy
  start_period: 30s    # 啟動寬限期,這段時間內的失敗不計入 retries
  start_interval: 2s   # 寬限期內的檢查間隔(較新版本才支援)
  • 健康檢查是在容器裡執行,所以指令必須存在於映像檔中。精簡映像檔常常沒有 curl,可以改用 wget、語言本身(node -e、python -c),或程式自帶的健康檢查子指令。
  • 網址用 127.0.0.1,不要用 localhost:有些映像檔的 localhost 會先解析到 IPv6 的 ::1,而程式只監聽 IPv4,檢查就一直失敗。
  • 常用服務的檢查指令:PostgreSQL pg_isready -U postgres、MySQL mysqladmin ping -h 127.0.0.1、Redis redis-cli ping。
  • 健康狀態與最近幾次檢查的輸出:docker inspect -f '{{json .State.Health}}' <容器>,裡面的 Log 陣列有每次檢查的結束代碼與輸出,查「為什麼一直 unhealthy」很有用。
  • unhealthy 的容器 Docker 不會自動重啟(重啟策略只看程序有沒有結束)。它的作用是讓 depends_on、--wait、監控系統、反向代理(例如 Traefik)知道狀態。

資源限制:deploy.resources

services:
  api:
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M
          pids: 200
        reservations:
          memory: 256M

早期 deploy 只在 Swarm 模式有效,現在 Compose v2 一般模式也會套用 resources。我實測 limits.memory: 64M、cpus: "0.5" 建立出來的容器,docker inspect 看到 HostConfig.Memory 是 67108864、NanoCpus 是 500000000,確實生效。舊寫法 mem_limit、cpus、pids_limit 直接寫在服務底下也還能用,兩種擇一,不要混用。

watch:開發模式自動同步

docker compose watch 會監看本機檔案,有變更時依規則自動同步進容器或重建,比 bind mount 原始碼更接近正式環境,在 Docker Desktop 上也沒有 bind mount 的檔案系統效能問題:

services:
  api:
    build: ./api
    develop:
      watch:
        - action: sync           # 直接把檔案複製進容器(搭配會自動重新載入的開發伺服器)
          path: ./api/src
          target: /app/src
          ignore:
            - "*.test.js"
        - action: sync+restart   # 同步後重啟容器(設定檔類)
          path: ./api/config
          target: /app/config
        - action: rebuild        # 重新建置映像檔並重建容器(相依變動時)
          path: ./api/package.json
docker compose watch              # 啟動服務並開始監看
docker compose up --watch         # 同上,同時顯示日誌

上面的設定我用 docker compose config 驗證過語法。sync 需要容器裡的使用者對 target 目錄有寫入權限,否則同步會失敗。

從 docker run 轉成 Compose

一條越寫越長的 docker run,就是該改成 compose 檔的訊號。例如:

docker run -d --name uptime \
  --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-data:/app/data \
  -e TZ=Asia/Taipei \
  --memory 512m --cpus 1 \
  --log-opt max-size=10m --log-opt max-file=3 \
  --add-host=host.docker.internal:host-gateway \
  --network monitor \
  louislam/uptime-kuma:1

對應的 compose.yaml:

name: uptime
services:
  uptime:
    image: louislam/uptime-kuma:1
    container_name: uptime
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-data:/app/data
    environment:
      TZ: Asia/Taipei
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - monitor

volumes:
  uptime-data:
    external: true      # 沿用 docker run 時已經建立的 volume,不要讓 Compose 另外建一個

networks:
  monitor:
    external: true      # 沿用既有網路
docker runcompose.yaml
--namecontainer_name(設了就不能 --scale)
-pports
-v/--mountvolumes(named volume 要在頂層 volumes: 宣告)
-e/--env-fileenvironment/env_file
--restartrestart
--memory/--cpusdeploy.resources.limits
--log-driver/--log-optlogging
--add-hostextra_hosts
--networknetworks(既有網路要標 external: true)
--user/-w/--entrypointuser/working_dir/entrypoint
--cap-drop/--cap-add/--security-optcap_drop/cap_add/security_opt
--read-only/--tmpfsread_only/tmpfs
--initinit: true
--stop-timeoutstop_grace_period
映像檔後面的指令command

轉換時最重要的是 volume:如果 docker run 時用的 volume 叫 uptime-data,compose 檔裡沒標 external: true 的話,Compose 會建立一個新的 uptime_uptime-data,服務看起來就像資料全部不見。上面這份 compose 檔我用 docker compose config 驗證過語法;映像檔 louislam/uptime-kuma 只是舉例,請換成你實際使用的映像檔與版本。

一份比較完整的正式環境範例

把上面的功能組合起來,這份設定已用 docker compose config 驗證過(.env 裡需要有 TAG 與 DB_NAME):

name: myapp

x-healthcheck: &default-health
  interval: 10s
  timeout: 3s
  retries: 5
  start_period: 20s

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "${WEB_PORT:-8080}:80"
    depends_on:
      api:
        condition: service_healthy
        restart: true
    extends:
      file: common.yaml
      service: base-app

  api:
    image: example.com/myapp/api:${TAG:?請在 .env 設定 TAG}
    build:
      context: ./api
      target: runtime
      args:
        APP_VERSION: ${TAG}
    environment:
      DB_HOST: db
      DB_NAME: ${DB_NAME}
      LOG_LEVEL: ${LOG_LEVEL:-info}
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    healthcheck:
      <<: *default-health
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M
    extends:
      file: common.yaml
      service: base-app

  migrate:
    image: example.com/myapp/api:${TAG}
    command: ["node", "dist/migrate.js"]
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      <<: *default-health
      test: ["CMD-SHELL", "pg_isready -U postgres -d $${POSTGRES_DB}"]
    shm_size: 256m

  adminer:
    image: adminer:5
    profiles: ["debug"]
    ports:
      - "127.0.0.1:8081:8080"

volumes:
  db-data:

secrets:
  db_password:
    file: ./secrets/db_password.txt

幾個細節:image 與 build 同時寫時,docker compose build 會把建置結果標成 image 指定的名稱,docker compose push 就能推上 registry;migrate 沿用同一個映像檔、只換指令;PostgreSQL 的 shm_size 預設 64 MB 太小,複雜查詢會出現 could not resize shared memory segment,所以調大。

維運 SOP:更新、回滾、備份、遷移

更新服務的標準流程

  1. 修改 compose.yaml 裡的映像檔版本號(或 .env 裡的 TAG)。先看該版本的更新說明,有沒有需要手動處理的設定或資料庫變更。
  2. docker compose config -q 確認設定沒有語法錯誤。
  3. docker compose pull 先下載,避免下載期間服務中斷。
  4. 有資料庫的服務先備份(見下方)。
  5. docker compose up -d --wait:只會重建版本有變的服務,並等到健康檢查通過才返回。
  6. docker compose ps、docker compose logs -f <服務> 確認狀態與日誌。
  7. 確認穩定後再 docker image prune 清掉舊映像檔;有問題就把版本號改回來再 up -d 一次。

第 7 步的「確認穩定後再清」很重要:舊映像檔還在本機時,回滾只要幾秒;清掉之後要重新下載,如果剛好 registry 有問題或舊版已被下架,就回不去了。

回滾

docker compose images                               # 目前各服務用的映像檔與 tag
docker image ls example.com/myapp/api               # 本機還有哪些舊版
sed -i 's/^TAG=.*/TAG=1.4.1/' .env                  # 改回上一版(或直接編輯 compose 檔)
docker compose up -d --wait api                     # 只重建 api

⚠️ 回滾程式碼不等於回滾資料。如果新版已經執行過資料庫 migration(加欄位、改資料格式),舊版程式可能無法使用新的資料結構。這種版本更新前一定要先備份資料庫,必要時連資料一起還原。用 latest 的服務根本無從回滾,這是不要用 latest 的另一個理由。

定期備份

一個 Compose 專案要備份的東西有三類:

  • 設定:compose.yaml、override 檔、.env、bind mount 的設定檔。建議整個專案資料夾放版本控制(.env 與 secrets 除外,另外安全保存)。
  • 資料庫:用資料庫自己的匯出工具,搭配 cron 每天執行,並保留多個版本。
  • 其他 volume:上傳檔案、媒體等,用前面的 tar 方式或 rsync bind mount 的資料夾。
#!/bin/sh
# /srv/myapp/backup.sh,由 cron 每天執行
set -eu
cd /srv/myapp
STAMP=$(date +%F)
mkdir -p backup
docker compose exec -T db pg_dump -U postgres -Fc app > "backup/app-$STAMP.dump"
docker run --rm -v myapp_uploads:/data:ro -v "$PWD/backup":/backup busybox:1.37 \
  tar czf "/backup/uploads-$STAMP.tar.gz" -C /data .
find backup -type f -mtime +14 -delete      # 保留 14 天

備份沒有還原過就不算備份。請定期在測試機上實際還原一次,確認檔案完整、還原程序寫得清楚。

遷移到新主機

  1. 新主機安裝相同或較新版本的 Docker,若有 daemon.json 也一併複製(特別是 default-address-pools、日誌設定)。
  2. 把專案資料夾(compose 檔、.env、secrets、bind mount 的資料夾)用 rsync -aHAX 複製過去,保留權限與擁有者。
  3. 在舊主機停止服務:docker compose stop(先不要 down,萬一要回頭還能直接 start)。
  4. 匯出資料庫與 volume(資料庫用匯出工具,其他 volume 用 tar),複製到新主機。
  5. 新主機上先建立 volume 並還原資料,再 docker compose up -d --wait。專案名稱必須相同(建議 compose 檔裡寫死 name:),volume 名稱才會對得上。
  6. 確認服務正常後切換 DNS 或反向代理,觀察一段時間,才把舊主機的服務 down 掉。

架構不同時要特別注意:從 x86 主機搬到 ARM 主機(例如 Graviton、樹莓派),映像檔要有 arm64 版本;資料庫的二進位資料檔通常可以跨架構使用,但保險起見還是用匯出、匯入的方式搬。

例行維護清單

  • 每月:docker compose pull && docker compose up -d 拿到基底映像檔的安全修補;自己建置的映像檔用 docker build --pull 重建。
  • 每月:docker system df 看空間,清建置快取與舊映像檔。
  • 每季:實際還原一次備份。
  • 升級 Docker 本身之前:看官方 release notes 的「Breaking changes」與「Deprecated」段落,先在測試機升級。

清理空間

docker system df                     # 映像檔、容器、volume、建置快取各佔多少
docker system df -v                  # 詳細到每一個項目
docker container prune               # 刪除所有已停止的容器
docker image prune                   # 刪除懸空映像檔
docker image prune -a --filter "until=720h"   # 刪除 30 天以上、沒被使用的映像檔
docker builder prune                 # 清除建置快取(常常是最大宗)
docker system prune                  # 停止的容器+懸空映像檔+未使用網路+建置快取
docker system prune -a --volumes     # ⚠️⚠️ 全部清光,連沒被使用的匿名 volume 都會刪除

⚠️ docker system prune -a --volumes 很方便但很危險。Docker 23 之後,這裡的 --volumes 只會刪「匿名 volume」,不會刪 named volume(help 說明寫的是 Prune anonymous volumes);但前面講過,沒指定 -v 的資料庫容器,資料就是存在匿名 volume 裡,容器暫時停著的時候執行,那份資料就沒了。-a 則會刪掉所有沒有被容器使用的映像檔,停著的服務要重新下載。正式環境請分開清,volume 只在確定不要時手動 docker volume rm。

看懂 docker system df

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          21        2         13.84GB   11.81GB (85%)
Containers      2         2         5.452GB   0B (0%)
Local Volumes   0         0         0B        0B
Build Cache     129       0         372.9MB   288.8MB
  • ACTIVE:正在被容器使用的數量。
  • RECLAIMABLE:理論上可以清掉的空間。映像檔的可回收空間是「沒有被任何容器使用的映像檔」,包含你之後可能還要用的舊版。
  • Containers 的 SIZE 是所有容器可寫層的總和,數字很大代表有容器把資料寫在可寫層(應該改用 volume),可用 docker ps -s 找出是誰。
  • 這裡不包含容器日誌,日誌檔要另外用 du 看。

依標籤與時間篩選清理

docker image prune -a --filter "until=168h"                 # 7 天前建立的
docker image prune -a --filter "label=stage=ci"              # 有特定標籤的
docker container prune --filter "until=24h"
docker builder prune --filter "until=72h"                    # 3 天沒用到的建置快取
docker builder prune --max-used-space 10GB                   # 只保留最多 10 GB 的快取
docker buildx du --verbose | head -40                        # 看建置快取的明細

舊文章常見的 docker builder prune --keep-storage,在新版 buildx 已改成 --max-used-space、--reserved-space、--min-free-space 這組參數,打舊參數時以 docker builder prune --help 為準。CI 建置主機最好在 daemon.json 開啟 builder.gc,讓它自動清。

容器日誌

容器的日誌預設不會自動輪替,長期執行的容器日誌可能長到好幾 GB。建議在 /etc/docker/daemon.json 設定上限:

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}
sudo systemctl restart docker        # ⚠️ 會重啟所有容器;只對之後新建的容器生效

「只對之後新建的容器生效」的意思是:既有容器要 docker compose up -d --force-recreate(或刪除重建)才會套用新的日誌設定,單純 restart 容器沒有用。

Docker Desktop 的磁碟

Docker Desktop 的所有資料都放在虛擬機的一個磁碟映像檔裡。在容器裡刪除資料、prune 之後,這個檔案不一定會立刻變小。較新版本通常會自動回收(實際行為依版本與虛擬化設定而定);設定頁面的「Resources → Disk usage limit」可以調整上限。⚠️ 最後手段是「Troubleshoot → Clean / Purge data」,會刪掉所有映像檔、容器與 volume,執行前請確認沒有需要的資料。

Registry:推送與下載私有映像檔

docker login                                   # Docker Hub
docker login ghcr.io -u <GitHub 帳號>           # GitHub Container Registry(密碼用 Personal Access Token)
docker tag myapp:1.0 ghcr.io/<帳號>/myapp:1.0
docker push ghcr.io/<帳號>/myapp:1.0
docker logout ghcr.io

推送前 tag 的名稱必須包含 registry 位址,Docker 才知道要推去哪裡(沒有的話就是推到 Docker Hub)。一次推送同一個名稱的所有 tag:docker push --all-tags ghcr.io/<帳號>/myapp。GHCR 推上去的映像檔預設是私有的,要公開請到套件設定頁面修改。

AWS ECR

aws ecr get-login-password --region ap-northeast-1 \
  | docker login --username AWS --password-stdin <帳號ID>.dkr.ecr.ap-northeast-1.amazonaws.com
docker tag myapp:1.0 <帳號ID>.dkr.ecr.ap-northeast-1.amazonaws.com/myapp:1.0
docker push <帳號ID>.dkr.ecr.ap-northeast-1.amazonaws.com/myapp:1.0

密碼一律用 --password-stdin 從管線送進去,不要寫在 -p 參數上,否則會留在 shell 歷史紀錄。登入憑證存在 ~/.docker/config.json,那台機器不再需要時記得 docker logout。

ECR 的幾個常見狀況:登入權杖 12 小時就過期,長時間執行的腳本要重新登入;推送前 repository 必須已經存在(aws ecr create-repository --repository-name myapp),不像 Docker Hub 會自動建立;建議設定生命週期規則自動刪除舊映像檔,否則儲存費用會一直累積。

憑證存在哪裡

docker login 之後,~/.docker/config.json 的 auths 裡會有該 registry 的紀錄。如果有設定 credsStore(Docker Desktop 預設用 macOS 鑰匙圈或 Windows 認證管理員),密碼存在系統的安全儲存區;Linux 伺服器上沒有設定的話,帳密是以 base64 編碼(不是加密)直接存在這個檔案裡,任何能讀這個檔案的人都能還原。伺服器上可以安裝 docker-credential-pass 之類的憑證輔助程式,或者只在需要時登入、用完就 docker logout。

自架私有 registry(registry:2)

內網環境、離線部署、或想當作 Docker Hub 的快取時,可以用官方的 registry 映像檔自己架一台:

services:
  registry:
    image: registry:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:5000:5000"
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    volumes:
      - registry-data:/var/lib/registry
volumes:
  registry-data:
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0
curl -s http://localhost:5000/v2/_catalog                   # 列出所有 repository
curl -s http://localhost:5000/v2/myapp/tags/list            # 列出某個 repository 的 tag
  • Docker 預設只允許用 HTTPS 連 registry(localhost 例外)。從其他主機連線時,正確做法是在前面放一個有正式憑證的反向代理;暫時測試可以在用戶端的 daemon.json 加 insecure-registries(⚠️ 不加密,只限受信任的內網)。
  • registry:2 預設沒有任何認證,任何連得到的人都能推送與下載。對外提供時請設定 htpasswd 基本認證加 HTTPS,或放在只有內網能連的位置。
  • 官方映像檔目前也有 registry:3(distribution 3.x),設定格式有部分調整,新架設時可以評估。

私有 registry 的清理

registry 刪除映像檔分兩步:先用 API 刪除 manifest,再執行垃圾回收清掉沒有被引用的層。只刪 tag 不會釋放空間。

# 1. 取得 manifest 的 digest(要帶正確的 Accept 標頭)
curl -sI -H "Accept: application/vnd.oci.image.index.v1+json" \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/myapp/manifests/1.0 | grep -i docker-content-digest
# 2. 刪除 manifest(需要 REGISTRY_STORAGE_DELETE_ENABLED=true)
curl -X DELETE http://localhost:5000/v2/myapp/manifests/sha256:<digest>
# 3. 垃圾回收:先 dry-run 看會刪什麼
docker compose exec registry registry garbage-collect --dry-run /etc/docker/registry/config.yml
docker compose exec registry registry garbage-collect --delete-untagged /etc/docker/registry/config.yml

⚠️ 垃圾回收執行期間如果有人正在推送,可能把剛上傳、還沒被 manifest 引用的層刪掉,導致映像檔損壞。官方建議執行前先把 registry 設成唯讀或暫停服務。--delete-untagged 會刪除所有沒有 tag 的 manifest,多架構映像檔的子 manifest 在某些版本可能被誤刪,請先 dry-run 確認。

上面的 compose 檔與 garbage-collect 指令我在本機用 registry:2 確認過指令存在、_catalog API 可用;推送與刪除流程因為不在本機做推送測試,請在自己的環境先試。

docker scout:映像檔漏洞掃描

docker scout 會分析映像檔的 SBOM(裝了哪些套件、什麼版本),比對已知漏洞資料庫:

docker scout quickview <映像檔>                         # 摘要:各嚴重等級的漏洞數量、基底映像檔
docker scout cves <映像檔>                              # 列出所有漏洞
docker scout cves --only-severity critical,high <映像檔>
docker scout cves --only-fixed <映像檔>                 # 只看已經有修補版本的(最值得處理)
docker scout cves --ignore-base <映像檔>                # 排除基底映像檔帶來的,只看你自己加的
docker scout recommendations <映像檔>                   # 建議更新到哪個基底映像檔版本
docker scout compare <新映像檔> --to <舊映像檔>         # 比較兩個版本的漏洞差異
docker scout cves --exit-code --only-severity critical <映像檔>   # 有 critical 就回傳非 0,CI 用

讀報告的建議:不必追求零漏洞,很多漏洞存在於你根本沒用到的套件功能。優先處理「critical/high 且有修補版本」的,而最有效的方法通常是換新的基底映像檔並重建,而不是一個一個套件升級。Docker Desktop 已內建 scout;Linux 上需另外安裝外掛,且大部分功能需要登入 Docker 帳號。我只在本機確認過上述參數存在,沒有實際執行掃描。其他常用的開源掃描工具還有 Trivy、Grype,可以在不登入任何帳號的情況下離線掃描。

容器安全

基本原則

  • 不要用 --privileged,除非你非常清楚為什麼需要它;它幾乎等於把整台主機交給容器。實測一般容器的有效權限(CapEff)是 00000000a80425fb,加上 --privileged 後變成 000001ffffffffff(全部權限),還能存取主機所有裝置。
  • 不要把 /var/run/docker.sock 掛進容器(監控、CI 工具常會要求),拿到它就等於拿到主機 root 權限。真的需要,至少用唯讀代理限制可呼叫的 API。
  • 只用可信來源的映像檔:官方映像檔(Docker Official Images)、經驗證的發行者,或你自己建置的。
  • 定期重建映像檔:基底映像檔的安全修補,要重新 docker build/docker compose pull 才會套用,舊容器不會自己變安全。
  • 可以用 docker scout cves <映像檔>(Docker Desktop 內建)掃描映像檔裡已知的漏洞。
  • 以一般使用者執行容器(Dockerfile 的 USER 或 --user),並且對外只開必要的埠,管理介面綁 127.0.0.1。

Linux capabilities

Linux 把 root 的特權拆成幾十個 capability。Docker 預設只給容器一小部分(約 14 個),像 SYS_ADMIN、NET_ADMIN、SYS_TIME 這些危險的預設就不給。更嚴格的做法是全部拿掉,只加回需要的:

docker run --rm --cap-drop ALL alpine:3.22 chown nobody /etc/hostname
# chown: /etc/hostname: Operation not permitted(連 root 都不能改檔案擁有者了)
docker run -d --cap-drop ALL --cap-add CHOWN --cap-add SETUID --cap-add SETGID nginx:1.27
Capability允許的事什麼時候需要
CHOWN、SETUID、SETGID改檔案擁有者、切換使用者以 root 啟動後再降權的程式(官方 nginx、postgres 映像檔)
NET_BIND_SERVICE綁定 1024 以下的埠通常不需要(見下方說明)
NET_ADMIN修改網路設定、iptablesVPN(WireGuard)、網路工具
NET_RAW原始 socketping(預設有給,不需要的話建議拿掉)
SYS_ADMIN掛載檔案系統等大量管理操作幾乎等於 privileged,盡量避免
SYS_TIME修改系統時間NTP 伺服器

關於 NET_BIND_SERVICE:Docker 20.10 之後,容器預設把 net.ipv4.ip_unprivileged_port_start 設成 0(我實測容器裡讀到的值就是 0),所以一般使用者在容器裡也能直接監聽 80 埠,不需要這個 capability。例外是使用 --network host 時,這個核心參數屬於主機,就要依主機的設定。

唯讀根檔案系統與 tmpfs

docker run --rm --read-only --tmpfs /tmp alpine:3.22 sh -c 'touch /x; touch /tmp/ok && echo tmp-ok'
# touch: /x: Read-only file system
# tmp-ok

--read-only 讓容器的根檔案系統不可寫,攻擊者就算進入容器也很難植入檔案或修改程式。程式需要寫入的地方(暫存檔、PID 檔、快取)用 --tmpfs 或 volume 開放。第一次套用時通常要多試幾次,看日誌裡 Read-only file system 的錯誤補上需要寫入的路徑。nginx 常見的是 /var/cache/nginx 與 /var/run。

no-new-privileges、seccomp、AppArmor

docker run --rm --security-opt no-new-privileges alpine:3.22 grep NoNewPrivs /proc/self/status
# NoNewPrivs:	1
docker run --rm alpine:3.22 grep Seccomp: /proc/self/status
# Seccomp:	2(2 代表 seccomp 過濾模式啟用中)
  • no-new-privileges:禁止程序透過 setuid 程式(如 sudo、su)取得更高權限。對絕大多數服務沒有副作用,建議預設加上。
  • seccomp:限制容器可以使用的系統呼叫。Docker 預設的設定檔已經擋掉約 40 多個危險的系統呼叫(如 reboot、mount、核心模組載入)。⚠️ 不要隨便加 --security-opt seccomp=unconfined 關掉它;實測關掉後 Seccomp 欄位變成 0。
  • AppArmor/SELinux:Ubuntu 預設用 AppArmor 的 docker-default 設定檔,RHEL 系用 SELinux。docker info 的 Security Options 欄位可以看到目前啟用哪些。

把安全選項寫進 Compose

services:
  app:
    image: example.com/myapp/app:1.0
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    init: true
    deploy:
      resources:
        limits:
          memory: 512M
          pids: 200

這是我給一般 Web 服務的起始模板(已用 docker compose config 驗證語法),再依程式的需要逐一放寬。程序數上限寫在 deploy.resources.limits.pids:我原本寫成服務層的 pids_limit: 200 再加上 deploy.resources.limits.memory,docker compose config 直接報錯 can't set distinct values on 'pids_limit' and 'deploy.resources.limits.pids',這就是前面說「舊寫法和 deploy 寫法不要混用」的實例。

docker.sock 的風險

能存取 /var/run/docker.sock 就能呼叫 Docker API 建立任何容器,包括 --privileged 並掛載主機根目錄的容器,所以它等於主機的 root 權限。Traefik、Portainer、Watchtower、CI runner 這類工具常會要求掛載。降低風險的方法:

  • 掛載時加 :ro 沒有用:唯讀只是不能刪除或修改 socket 檔案本身,仍然可以透過它送出任何 API 請求。
  • 改用 socket 代理(例如社群常用的 docker-socket-proxy),只開放需要的 API(例如只允許讀取容器清單)。
  • CI 建置盡量改用 rootless 的 builder 或遠端 BuildKit,不要把主機的 socket 給 CI 工作。

rootless Docker

一般的 Docker daemon 以 root 執行,daemon 或容器逃逸漏洞都會直接變成主機 root。Rootless 模式讓 daemon 和容器都以一般使用者身分執行,搭配 user namespace,容器裡的 root 在主機上只是你這個一般使用者。

# Ubuntu:需要 uidmap 套件,且使用者在 /etc/subuid、/etc/subgid 有配置的範圍
sudo apt-get install -y uidmap
dockerd-rootless-setuptool.sh install           # 以一般使用者身分執行(不要加 sudo)
systemctl --user enable --now docker
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
docker context use rootless                     # 安裝程式會建立名為 rootless 的 context
sudo loginctl enable-linger $USER               # 讓使用者登出後 daemon 仍然執行

Rootless 的限制要先知道:

  • 預設不能綁定 1024 以下的主機埠(可調整主機的 net.ipv4.ip_unprivileged_port_start,或在前面放反向代理)。
  • 網路效能較差(預設透過使用者空間的網路堆疊),也不支援 macvlan 這類需要特權的網路。
  • --memory、--cpus 等 cgroup 限制需要 cgroup v2 與 systemd 委派設定。
  • 資料目錄在 ~/.local/share/docker,和 root 模式的映像檔、容器完全分開。
  • bind mount 的檔案擁有者會經過 UID 對應,容器裡的 UID 1000 在主機上是 subuid 範圍裡的某個數字,權限問題更容易出現。

這段是依官方文件整理,我沒有在本機(macOS)上實際安裝 rootless 模式,請在測試機上先試。另一個折衷方案是 daemon 的 userns-remap 設定:daemon 仍以 root 執行,但容器裡的 root 對應到主機上的非特權 UID。

除錯技巧

docker inspect --format 速查

docker inspect 的 --format(-f)使用 Go template 語法,能從長長的 JSON 裡只取出需要的欄位:

想知道指令
狀態、結束代碼、是否 OOMdocker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}' <容器>
啟動時間、重啟次數docker inspect -f '{{.State.StartedAt}} {{.RestartCount}}' <容器>
各網路的 IPdocker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}={{$v.IPAddress}} {{end}}' <容器>
掛載(JSON)docker inspect -f '{{json .Mounts}}' <容器>
環境變數(一行一個)docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' <容器>
重啟策略docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <容器>
記憶體與 CPU 限制docker inspect -f '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' <容器>
健康檢查紀錄docker inspect -f '{{json .State.Health}}' <容器>
屬於哪個 Compose 專案docker inspect -f '{{index .Config.Labels "com.docker.compose.project"}}' <容器>
日誌檔位置docker inspect -f '{{.LogPath}}' <容器>
用哪個映像檔docker inspect -f '{{.Config.Image}} {{.Image}}' <容器>

小技巧:

  • {{json .X}} 把物件轉成 JSON,再接 | jq 就能排版或進一步篩選:docker inspect <容器> | jq '.[0].Mounts'。
  • 鍵名含有點號或斜線的標籤,要用 index 函式取,不能直接寫 .Config.Labels.com.docker…。
  • 在 zsh/bash 裡請用單引號包住 template,避免 $ 被 shell 展開。
  • 以上這些格式我都在本機對測試容器實際執行過。

docker events:即時看發生了什麼事

docker events                                          # 即時串流所有事件(Ctrl-C 結束)
docker events --filter container=web                   # 只看某個容器
docker events --filter event=die --filter event=oom    # 只看結束與 OOM
docker events --filter type=network                    # 網路的建立、連接
docker events --since 1h --until 10m                   # 查過去一段時間(不會持續等待)
docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.Attributes.name}}'

一個容器從建立到刪除的實測事件順序是 create → attach → start → die → destroy。排查「容器半夜一直重啟」時,docker events --since 12h --filter container=<名稱> --filter event=die 搭配日誌,可以知道每次結束的時間點與結束代碼(事件的 exitCode 屬性)。注意 daemon 只保留最近一部分的事件,太久以前的查不到。

借用命名空間除錯精簡容器

distroless、scratch 映像檔沒有 shell 和任何工具,可以另外啟動一個工具容器,共用目標容器的網路或程序命名空間:

docker run --rm -it --network container:<目標容器> busybox:1.37 sh    # 共用網路:localhost 就是目標容器
docker run --rm --network container:<目標容器> busybox:1.37 netstat -tln   # 看目標容器監聽了哪些埠
docker run --rm --pid container:<目標容器> busybox:1.37 ps              # 看目標容器的程序

我實測用這個方法對一個只跑 httpd 的容器執行 netstat -tln,看得到它的 8080 埠;ps 看得到它的 PID 1。網路除錯可以換成內建大量工具(curl、dig、tcpdump)的社群映像檔,但請先確認來源可信。新版 Docker Desktop 另外提供 docker debug 指令,功能類似。

docker context:管理多台主機

docker context ls                                                     # 列出所有 context,* 是目前使用中
docker context create prod --docker "host=ssh://deploy@prod.example.com"
docker context use prod                                               # 之後的 docker 指令都對 prod 執行
docker --context prod ps                                              # 只有這一次對 prod 執行
docker context use default                                            # 切回本機
DOCKER_CONTEXT=prod docker compose up -d                              # 用環境變數指定

透過 SSH 的 context 不需要把 Docker API 開在網路上,只要能 SSH 登入、該帳號有 Docker 權限即可。⚠️ 切換 context 之後很容易忘記自己在操作哪一台,曾經有人以為在本機而對正式機 docker compose down -v。建議在 shell 提示字元顯示目前的 context,或養成用 --context 明確指定的習慣。⚠️ 也不要為了方便把 daemon 開在 TCP 2375 埠(沒有加密與認證),那等於把主機 root 權限公開在網路上。

其他好用的查詢

docker system info --format '{{.ContainersRunning}}/{{.Containers}} running'
docker ps -q | xargs docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}}'   # 每個容器的重啟策略
docker ps -q | xargs docker inspect -f '{{.Name}} {{.HostConfig.LogConfig.Config}}'     # 檢查哪些容器沒設日誌輪替
docker network inspect -f '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{println}}{{end}}' <網路>

Docker Desktop 與 Linux 的差異

項目Linux(Docker Engine)Docker Desktop(Mac/Windows)
daemon 在哪裡主機本身Docker Desktop 管理的 Linux 虛擬機
容器 IP主機可以直接連到容器的 bridge IP主機連不到容器 IP,只能透過 -p 開埠
連回主機要加 --add-host=host.docker.internal:host-gatewayhost.docker.internal 直接可用
--network host完全使用主機網路使用的是虛擬機的網路;新版提供實驗性的主機網路支援,行為與 Linux 不完全相同
macvlan可接上實體區網無法接到你的實體區網
bind mount 效能原生速度要跨虛擬機同步,大量小檔案(node_modules)時明顯較慢
檔案擁有者直接對應 UID,常有權限問題Desktop 會自動轉換,權限問題較少(但上線到 Linux 時才會冒出來)
資源上限整台主機設定頁面指定給虛擬機的 CPU、記憶體、磁碟
daemon.json/etc/docker/daemon.jsonSettings → Docker Engine
CPU 架構主機架構Apple 晶片是 arm64,可透過模擬執行 amd64
授權開源大型企業商業使用需要付費訂閱

實務上最常踩的是「在 Mac 上一切正常,部署到 Linux 就權限錯誤或 exec format error」。所以 CI 一定要在 Linux 上建置與測試,部署到哪個架構就建置哪個架構。Mac 上 bind mount 很慢時,可以把 node_modules 這類目錄改用 named volume,或改用 docker compose watch 的 sync。

我在 Mac 上用 --add-host=host.docker.internal:host-gateway 啟動容器時,/etc/hosts 裡同時出現 IPv4 與 IPv6 兩筆紀錄,可見 Desktop 上 host-gateway 一樣能用,Compose 檔寫上這行就能同時相容兩種環境。

常見問題排查

遇到問題時,我的查詢順序固定是:docker ps -a(狀態與結束代碼)→ docker logs(程式說了什麼)→ docker inspect(設定是不是我以為的那樣)→ docker events(發生了什麼事)→ 主機的 journalctl -u docker(daemon 本身的問題)。

permission denied while trying to connect to the Docker daemon socket

目前使用者不在 docker 群組:sudo usermod -aG docker $USER 後重新登入,或暫時用 sudo docker …。加入群組後要重新登入(或 newgrp docker)才會生效,用 id 確認群組清單裡有 docker。

Cannot connect to the Docker daemon. Is the docker daemon running?

  1. Linux:systemctl status docker 看 daemon 有沒有在跑,沒有的話 journalctl -u docker -n 100 --no-pager 看原因,最常見的是 daemon.json 寫錯。
  2. Mac/Windows:Docker Desktop 有沒有開啟、虛擬機是否啟動完成。
  3. docker context ls 確認目前的 context 指到哪裡;環境變數 DOCKER_HOST 會覆蓋 context 設定,echo $DOCKER_HOST 檢查一下。

Bind for 0.0.0.0:8080 failed: port is already allocated

主機上的埠已經被佔用:sudo ss -tlnp | grep 8080 或 docker ps --format "{{.Names}} {{.Ports}}" 找出是誰,換一個埠或先停掉它。Mac 上用 lsof -nP -iTCP:8080 -sTCP:LISTEN。如果找不到任何程式在用,可能是已停止但尚未刪除的容器,或 Compose 專案改名後舊專案的容器還在,用 docker ps -a 與 docker compose ls -a 找找看。

容器一啟動就結束

  1. docker ps -a 看狀態與結束代碼。
  2. docker logs <容器> 看錯誤訊息。
  3. 前景程式結束容器就會結束,背景執行的服務要用前景模式啟動(例如 nginx 要 daemon off;)。
  4. 改用互動模式進去手動執行看看:docker run -it --rm --entrypoint sh <映像檔>。
  5. 用 docker inspect -f '{{.Config.Entrypoint}} {{.Config.Cmd}}' <映像檔> 確認實際要執行的指令,常見錯誤是 compose 的 command 把映像檔預設的 CMD 蓋掉了。
  6. 看看是不是缺環境變數:很多官方映像檔(MySQL、PostgreSQL)沒有設定密碼相關變數時會直接結束,日誌裡會寫明。

容器一直 Restarting

docker ps 看到 Restarting (1) 5 seconds ago 代表程式不斷啟動失敗、被重啟策略拉起來。括號裡是上次的結束代碼。docker logs --tail 50 <容器> 看最後一次的錯誤;如果程式太快結束來不及看,可以先把重啟策略關掉(docker update --restart no <容器>)再手動 docker start -a <容器> 觀察輸出。

exec format error

映像檔的 CPU 架構和主機不同(例如在 Apple 晶片 Mac 上建置的 arm64 映像檔,跑在 x86 主機上)。用 docker buildx build --platform linux/amd64 重新建置。另一個可能是 entrypoint 腳本第一行的 shebang 寫錯或檔案是 CRLF 換行,用 file <腳本> 檢查,若顯示 with CRLF line terminators 就用 dos2unix 轉換,並在 .gitattributes 加 *.sh text eol=lf。

容器裡連不到外網或 DNS 解析失敗

  1. docker run --rm busybox nslookup google.com 測 DNS。
  2. docker run --rm busybox ping -c 3 1.1.1.1 測 IP 連線:IP 通但名稱不通是 DNS 問題,兩個都不通是路由或防火牆問題。
  3. 公司網路或 VPN 環境常擋掉 Docker 預設使用的 DNS,可以在 daemon.json 加 "dns": ["8.8.8.8", "1.1.1.1"];需要解析公司內部網域的話,第一個要放內部 DNS。
  4. 主機防火牆(nftables)規則被其他工具清掉時,Docker 的 NAT 規則也會不見,sudo systemctl restart docker 會重建。
  5. 主機的 IP 轉送被關掉:sysctl net.ipv4.ip_forward 應該是 1。
  6. 主機上的 /etc/resolv.conf 指向 127.0.0.53(systemd-resolved)時,Docker 會自動改用 resolved 背後真正的上游 DNS;如果上游也是內部 DNS 而容器網路到不了,就需要手動設定 dns。

裝了 Docker 之後,主機連不到公司某些網段

這幾乎都是網段衝突:Docker 配發的 bridge 網段(172.17~31 或 192.168)和公司網段重疊,主機的路由表把那些流量導進了 Docker bridge。用 ip route 找出衝突的 br-xxxx,docker network ls 對照是哪個網路,刪掉之後在 daemon.json 設定 default-address-pools 與 bip(見前面的說明),再重建網路。

容器之間連不到

  1. 兩個容器在不在同一個網路:docker inspect -f '{{json .NetworkSettings.Networks}}' <容器>。不同 Compose 專案預設各自一個網路,彼此不通,要共用一個 external 網路。
  2. 用的是容器名稱或服務名稱,而不是 localhost:容器裡的 localhost 是它自己。
  3. 連的是容器內部的埠(例如 db 的 5432),不是 -p 對應到主機的埠。
  4. 目標程式是否監聽 0.0.0.0:只監聽 127.0.0.1 的程式,同網路的其他容器也連不到。
  5. 是不是預設的 bridge 網路:那裡沒有名稱解析。

Permission denied(bind mount)

見前面「權限問題:UID 對不上」。快速確認:docker exec <容器> id 看容器以哪個 UID 執行,主機上 ls -ln <資料夾> 看擁有者的數字 UID,兩者要能對上(或資料夾權限允許)。SELinux 系統再加上 :z。

磁碟被 Docker 吃光

  1. docker system df 看是映像檔、建置快取還是 volume。
  2. sudo du -sh /var/lib/docker/containers/*/*-json.log | sort -h | tail:容器日誌是不是太大。
  3. 依序 docker builder prune、docker image prune -a、清日誌,最後才考慮 volume。
  4. docker ps -s 看是不是有容器把大量資料寫在可寫層。
  5. sudo du -sh /var/lib/docker/* 看各子目錄的大小,對照前面「/var/lib/docker 裡有什麼」的表格。

⚠️ 磁碟完全滿的時候,daemon 可能無法正常執行 prune,甚至資料庫容器會損壞資料。先手動刪掉一些主機上可以刪的檔案(舊日誌、暫存檔)騰出一點空間,再用 Docker 指令清理。

容器時間不對

多數映像檔預設是 UTC。加上 -e TZ=Asia/Taipei(映像檔要有 tzdata),或掛載主機時區 -v /etc/localtime:/etc/localtime:ro。實測在 debian:bookworm-slim 加上 TZ=Asia/Taipei 時區會變成 CST,但在沒有 tzdata 的 alpine:3.22 上仍然是 UTC,要先 apk add --no-cache tzdata。注意容器的時鐘本身和主機是同一個(共用核心),時間「快慢」不準要修主機的 NTP,容器裡無法單獨調整。

toomanyrequests: You have reached your pull rate limit

撞到 Docker Hub 的下載次數限制。docker login 登入後額度較高;長期解法是架 pull-through cache 或把常用映像檔放到自己的 registry(見前面 registry-mirrors 一節)。

no space left on device(但 df 顯示還有空間)

可能是 inode 用完:df -i /var/lib/docker。大量小檔案的映像檔(例如 node_modules 很大的映像檔)會快速消耗 inode。清理舊映像檔與建置快取通常就能解決;若經常發生,建立檔案系統時要配置較多的 inode,或改用 xfs。

建置時 COPY 找不到檔案

錯誤是 failed to compute cache key: … not found。原因不外乎:檔案被 .dockerignore 排除了;路徑是相對於 build context(docker build 最後那個 .)而不是 Dockerfile 所在的位置;或試圖 COPY context 以外的檔案(COPY ../shared . 不允許,要改用 --build-context)。

建置每次都從頭來、快取沒有命中

  1. 用 --progress=plain 找出第一個沒有 CACHED 的步驟,它前面那個 COPY 就是元兇。
  2. 檢查 .dockerignore 是否排除了會一直變的檔案(.git、日誌、建置輸出)。
  3. 用了 ARG 而且每次傳不同的值(例如建置時間):ARG 的值改變會讓第一個使用它的步驟以及之後全部失效,這種 ARG 請放在 Dockerfile 越後面越好。
  4. CI 上沒有匯入快取:見前面 --cache-from/--cache-to。

Compose:變數沒有被替換、或替換成空白

用 docker compose config 看展開後的結果,搭配 docker compose config --variables 看每個變數有沒有值。常見原因:.env 不在專案目錄(它是相對於專案目錄,不是你目前的工作目錄)、用 -f 指定了其他資料夾的 compose 檔、shell 裡有同名的舊環境變數覆蓋了 .env(env | grep <變數> 檢查)。

Compose:改了設定但容器沒有更新

改的是 bind mount 的檔案內容時,Compose 不會重建容器(見前面「up -d 什麼時候會重建容器」);改的是 build 的程式碼時,要 docker compose up -d --build,單純 up -d 不會重新建置已經存在的映像檔。

速查表

容器

想做的事指令
執行中的容器docker ps
全部容器docker ps -a
背景啟動容器docker run -d --name 名稱 -p 主機埠:容器埠 映像檔:版本
一次性執行並自動刪除docker run --rm -it 映像檔 sh
看日誌docker logs -f --tail 100 容器
進入容器docker exec -it 容器 sh
以 root 進入容器docker exec -u root -it 容器 sh
資源用量docker stats --no-stream
為什麼結束docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' 容器
健康檢查紀錄docker inspect -f '{{json .State.Health}}' 容器
容器的 IPdocker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' 容器
不重建調整記憶體docker update --memory 1g --memory-swap 1g 容器
改了哪些檔案docker diff 容器
即時事件docker events --filter container=容器
除錯沒有 shell 的容器docker run --rm -it --network container:容器 busybox:1.37 sh

映像檔與建置

想做的事指令
建置映像檔docker build -t 名稱:版本 .
建置並更新基底映像檔docker build --pull -t 名稱:版本 .
檢查 Dockerfile 寫法docker build --check .
跨架構建置docker buildx build --platform linux/amd64 -t 名稱:版本 --load .
多架構建置並推送docker buildx build --platform linux/amd64,linux/arm64 -t 名稱:版本 --push .
建置時使用密碼docker build --secret id=token,src=token.txt …+RUN --mount=type=secret,id=token
映像檔哪一層最大docker history 映像檔
映像檔的 digestdocker image ls --digests
看多架構清單docker buildx imagetools inspect 映像檔
匯出/匯入映像檔docker save -o x.tar 映像檔/docker load -i x.tar
漏洞掃描docker scout cves --only-fixed 映像檔
Dockerfile 安裝套件apt-get install -y --no-install-recommends … && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/*

Compose

想做的事指令
啟動 Compose 專案docker compose up -d
啟動並等到健康docker compose up -d --wait
更新 Compose 服務docker compose pull && docker compose up -d
重新建置並啟動docker compose up -d --build
只重建單一服務docker compose up -d --no-deps 服務
停止並移除docker compose down
檢查 Compose 設定docker compose config
看變數與預設值docker compose config --variables
啟用 profiledocker compose --profile debug up -d
一次性指令docker compose run --rm 服務 指令
匯出資料庫(不配置終端機)docker compose exec -T db pg_dump -U postgres app > app.sql
主機上所有專案docker compose ls
開發模式自動同步docker compose watch

空間、網路與系統

想做的事指令
空間用量docker system df
清建置快取docker builder prune
清 30 天以上未使用的映像檔docker image prune -a --filter "until=720h"
清空太大的日誌sudo truncate -s 0 $(docker inspect -f '{{.LogPath}}' 容器)
建立自訂網路docker network create 網路
禁止對外的內部網路docker network create --internal 網路
各網路的網段docker network inspect -f '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' $(docker network ls -q)
備份 volumedocker run --rm -v 名稱:/data:ro -v "$PWD":/backup busybox:1.37 tar czf /backup/名稱.tar.gz -C /data .
驗證 daemon.jsonsudo dockerd --validate --config-file /etc/docker/daemon.json
daemon 日誌journalctl -u docker -n 100 --no-pager
切換到遠端主機docker context use 名稱

⚠️ 會刪資料的指令

指令會刪什麼
docker compose down -v專案的所有 volume(資料)
docker volume rm 名稱該 volume 的資料
docker volume prune所有未使用的匿名 volume
docker volume prune -a所有未使用的 volume,包含 named volume
docker system prune -a --volumes未使用的映像檔、容器、網路、建置快取與匿名 volume
docker rm -f 容器容器與它的可寫層(以 -v 參數執行時也刪匿名 volume)
docker run --rm …容器結束時刪除容器與它的匿名 volume

這篇會持續更新,遇到新的常用指令或踩到新的坑,就會補進來。

Read more

雲端架構延遲問題:為什麼AP與DB不能放太遠?

雲端與地端的架構差異認知不足導致的效能陷阱 前言 許多企業在上雲初期,經常基於成本考量或錯誤認知,將應用程式伺服器(AP)與資料庫(DB)部署在不同區域。這種做法在地端環境中影響較小,但在雲端環境中卻會造成嚴重的效能問題。本文透過台北-東京的實際案例,說明距離對雲端架構的致命影響。 核心問題: * 地端思維:同個機房內不同區域延遲可忽略 * 雲端現實:跨區域延遲可達數十毫秒 * 結果:連線建立時間從毫秒級暴增到秒級 1. 地端 vs 雲端的延遲差異 1.1 地端環境的延遲特性 傳統地端機房: 同機房不同機櫃:RTT < 1ms 同城市不同機房:RTT < 5ms 同國家不同城市:RTT < 20ms 地端架構師的經驗: * AP和DB分別放在不同機櫃:幾乎無延遲影響 * 災備機房放在不同城市:RTT約10-15ms,可接受 * 習慣性認為「網路延遲不是問題」

By Albert Yu
常用指令-MAC

常用指令-MAC

這篇整理我在 Mac 上最常用的終端機指令:Homebrew 套件管理、系統資訊與更新、網路診斷、檔案與 Finder、磁碟與備份、電源與排程、效能與日誌、SSH 與鑰匙圈、隱私權與安全性,以及一些很實用但不常被提到的 macOS 專屬指令。內容以 Apple 晶片(M 系列)的 Mac、近年的 macOS 版本為準,Intel Mac 大多也適用,差異的地方會特別標註。文中的指令我都在自己的 Mac(Apple 晶片、macOS 27、zsh、Homebrew 7)上確認過指令與參數存在;少數因為需要管理員權限、會改動系統、或本機沒有安裝而無法實際驗證的部分,會在旁邊註明「本機未驗證」。 這篇文章很長,建議把它當成工具書:先看目錄式的章節標題,

By Albert Yu
常用指令-ubuntu

常用指令-ubuntu

這篇是我平常維運 Ubuntu 主機時最常用的指令整理,從系統更新、套件管理、服務管理、磁碟與網路,到憑證、資料庫、效能分析、排程、SSH、安全加固與疑難排解,盡量把「指令本身」和「什麼時候用、輸出怎麼讀、要注意什麼」放在一起。內容以 Ubuntu 24.04 LTS 為準,大部分指令在 22.04 也一樣能用;遇到版本差異的地方會另外註明。 這篇很長,建議當成工具書使用:先看目錄找到需要的章節,或直接跳到文末的「常見情境 SOP」與「速查表」。文中的指令、參數與設定檔範例,都在乾淨的 Ubuntu 24.04 環境裡實際跑過或用工具檢查過語法;少數需要實體硬體或完整 systemd 才能驗證的部分,我會在旁邊說明。

By Albert Yu

2021ironman 13th – DevOps – Day04 – Amazon ECS Anywhere 基礎說明與建置(下)

先前將主機已經註冊上去了 那接下來就是進到『Task Definitions』開始來建立服務 點選『Create new Task Definition』 因為我們是要建立ECS Anywhere 點選『EXTERNAL』再來 Next Step Task definition name 輸入服務名稱,我這邊只是先建立一個apache測試環境所以名稱直接用『apache』 Network mode 記得保持預設 輸入這個Task所需的記憶體及CPU數量 記憶體單位是M CPU1024是代表1 vCPU 建立容器『Add container』 Container name 輸入名稱 Image 這邊看要抓取的 Image 位置及版本,我這個寫法因為沒有URL 所以會直接跟docker Hub拉 Port mappings 這個數值很重要 是外部要跟Container要對應的Port,看您包的Container是需要哪個Port就使用那個Port 點選『Create』

By Albert Yu