常用指令-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/Ubuntu | apt-get update && apt-get install -y --no-install-recommends … && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* | 本篇的重點寫法 |
| Alpine | apk add --no-cache … | --no-cache 不會留下索引檔,不需要再清 |
| Alpine(編譯用的暫時套件) | apk add --no-cache --virtual .build-deps gcc musl-dev && … && apk del .build-deps | 用虛擬套件名稱把編譯工具包起來,用完一次刪掉 |
| RHEL/Rocky/Fedora | dnf install -y --setopt=install_weak_deps=False … && dnf clean all | install_weak_deps=False 相當於 apt 的不裝建議套件 |
| Python | pip install --no-cache-dir -r requirements.txt | 或改用 BuildKit 的快取掛載(後面會講) |
| Node.js | npm 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 對應到主機上的一般使用者 |
| cgroup | cgroup 階層視角 | 容器只看得到自己的 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 100000cpu.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 versiondocker info 的輸出很長,我最常看的是這幾行:
| 欄位 | 看什麼 |
|---|---|
Server Version | daemon 版本(docker version 裡 Client 與 Server 版本可以不同,以 Server 為準) |
Storage Driver | 應該是 overlay2;如果是 vfs,代表核心或檔案系統不支援 overlay,效能和空間都會很差 |
Logging Driver | 預設日誌驅動,正式環境建議確認有設輪替 |
Cgroup Driver/Cgroup Version | systemd/2 是目前主流 |
Docker Root Dir | 資料目錄,磁碟滿的時候要看的就是這裡 |
Registry Mirrors/Insecure Registries | 確認 daemon.json 設定有生效 |
Live Restore Enabled | daemon 重啟時容器是否保持執行 |
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.27docker 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) |
| 2 | shell 內建指令用法錯誤,或程式自訂的錯誤代碼 |
| 125 | docker run 指令本身有問題(參數錯誤、daemon 錯誤) |
| 126 | 找到檔案但無法執行(沒有執行權限、執行的是目錄或一般檔案) |
| 127 | 找不到指令(ENTRYPOINT 或 CMD 寫錯、PATH 不對) |
| 128+N | 被訊號 N 結束,例如 130=SIGINT(Ctrl-C) |
| 137 | 被 SIGKILL(128+9):常見是記憶體不足被砍(OOMKilled 會是 true),或 docker stop 等太久被強制結束 |
| 139 | Segmentation 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 oomtesttail /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% 1CPU %以「一顆 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 |
| 自訂 bridge | docker 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-mirrors | Docker 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-restore | daemon 重啟或升級時容器保持執行 | 不支援 Swarm 模式;重大版本升級仍建議重啟容器 |
builder.gc | 自動清除建置快取 | 建置主機(CI runner)特別需要 |
default-ulimits | 所有容器預設的 ulimit | 容器個別的 --ulimit 會覆蓋 |
userland-proxy | 關閉後改用 iptables 處理本機迴路的埠轉送 | 可減少每個埠一個 docker-proxy 程序;少數舊環境需要保持開啟 |
max-concurrent-downloads | 同時下載的層數(預設 3) | 頻寬大時調高可加快 pull |
shutdown-timeout | daemon 關閉時等待容器結束的秒數 | 資料庫多的主機可以調長 |
改完設定先驗證再重啟
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 到另一顆磁碟
- 停止 Docker:
sudo systemctl stop docker docker.socket containerd。 - 複製資料並保留權限與硬連結:
sudo rsync -aHAX --info=progress2 /var/lib/docker/ /srv/docker/(注意兩邊結尾都有斜線)。 - 在
daemon.json加上"data-root": "/srv/docker",用dockerd --validate驗證。 - 啟動 Docker:
sudo systemctl start docker,用docker info --format '{{.DockerRootDir}}'確認路徑,docker images、docker volume ls確認資料都在。 - 確認所有服務正常一段時間後,才把舊的
/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 | 不會 |
STOPSIGNAL | docker 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裡,訊號送不到你的程式。
兩者搭配的結果(假設執行時沒有另外指定指令):
| ENTRYPOINT | CMD | 實際執行 |
|---|---|---|
| (無) | ["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
| 項目 | ARG | ENV |
|---|---|---|
| 有效範圍 | 只在建置時 | 建置時與容器執行時 |
| 如何設定 | 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"
EOTheredoc 的 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 的差別:
| 基底 | 實測大小 | 內容 | 適合 |
|---|---|---|---|
scratch | 5.37 MB | 完全空白,只有你複製進去的檔案 | 極簡;但沒有 CA 憑證、時區資料、/etc/passwd,要自己補 |
distroless/static-debian12:nonroot | 7.49 MB | CA 憑證、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-datadocker/php.ini(正式環境的 opcache 設定):
opcache.enable=1
opcache.validate_timestamps=0
expose_php=Off
memory_limit=256Mdocker/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.json | npm ci | /root/.npm |
| Node.js(pnpm) | package.json、pnpm-lock.yaml | pnpm install --frozen-lockfile | pnpm store 路徑(可用 pnpm store path 查) |
| Python(pip) | requirements.txt | pip install -r requirements.txt | /root/.cache/pip |
| Python(uv) | pyproject.toml、uv.lock | uv sync --frozen --no-install-project | /root/.cache/uv |
| Go | go.mod、go.sum | go mod download | /go/pkg/mod、/root/.cache/go-build |
| Java(Maven) | pom.xml | mvn dependency:go-offline | /root/.m2 |
| Rust | Cargo.toml、Cargo.lock | cargo build --release | /usr/local/cargo/registry、/app/target |
| PHP(Composer) | composer.json、composer.lock | composer 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 /srcdocker 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=gha | GitHub 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.txtCompose 會自動建立一個專案專用的網路,所以 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} 這種)來源,優先順序由高到低:
- 執行
docker compose時 shell 裡的環境變數(例如TAG=9.9.9 docker compose up -d)。 --env-file指定的檔案(可指定多個,後面的覆蓋前面的)。- 專案目錄下的
.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。
容器裡的環境變數則由服務定義決定,優先順序由高到低:
docker compose run -e KEY=值指定的。- 服務的
environment:。 - 服務的
env_file:。 - 映像檔 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-appinclude 則是把整份 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 | 容器執行完畢且結束代碼為 0 | migration、初始化這類一次性工作 |
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、MySQLmysqladmin ping -h 127.0.0.1、Redisredis-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.jsondocker 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 run | compose.yaml |
|---|---|
--name | container_name(設了就不能 --scale) |
-p | ports |
-v/--mount | volumes(named volume 要在頂層 volumes: 宣告) |
-e/--env-file | environment/env_file |
--restart | restart |
--memory/--cpus | deploy.resources.limits |
--log-driver/--log-opt | logging |
--add-host | extra_hosts |
--network | networks(既有網路要標 external: true) |
--user/-w/--entrypoint | user/working_dir/entrypoint |
--cap-drop/--cap-add/--security-opt | cap_drop/cap_add/security_opt |
--read-only/--tmpfs | read_only/tmpfs |
--init | init: true |
--stop-timeout | stop_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:更新、回滾、備份、遷移
更新服務的標準流程
- 修改 compose.yaml 裡的映像檔版本號(或
.env裡的TAG)。先看該版本的更新說明,有沒有需要手動處理的設定或資料庫變更。 docker compose config -q確認設定沒有語法錯誤。docker compose pull先下載,避免下載期間服務中斷。- 有資料庫的服務先備份(見下方)。
docker compose up -d --wait:只會重建版本有變的服務,並等到健康檢查通過才返回。docker compose ps、docker compose logs -f <服務>確認狀態與日誌。- 確認穩定後再
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 天備份沒有還原過就不算備份。請定期在測試機上實際還原一次,確認檔案完整、還原程序寫得清楚。
遷移到新主機
- 新主機安裝相同或較新版本的 Docker,若有
daemon.json也一併複製(特別是default-address-pools、日誌設定)。 - 把專案資料夾(compose 檔、
.env、secrets、bind mount 的資料夾)用rsync -aHAX複製過去,保留權限與擁有者。 - 在舊主機停止服務:
docker compose stop(先不要down,萬一要回頭還能直接 start)。 - 匯出資料庫與 volume(資料庫用匯出工具,其他 volume 用 tar),複製到新主機。
- 新主機上先建立 volume 並還原資料,再
docker compose up -d --wait。專案名稱必須相同(建議 compose 檔裡寫死name:),volume 名稱才會對得上。 - 確認服務正常後切換 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.8MBACTIVE:正在被容器使用的數量。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 | 修改網路設定、iptables | VPN(WireGuard)、網路工具 |
NET_RAW | 原始 socket | ping(預設有給,不需要的話建議拿掉) |
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 裡只取出需要的欄位:
| 想知道 | 指令 |
|---|---|
| 狀態、結束代碼、是否 OOM | docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}' <容器> |
| 啟動時間、重啟次數 | docker inspect -f '{{.State.StartedAt}} {{.RestartCount}}' <容器> |
| 各網路的 IP | docker 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-gateway | host.docker.internal 直接可用 |
--network host | 完全使用主機網路 | 使用的是虛擬機的網路;新版提供實驗性的主機網路支援,行為與 Linux 不完全相同 |
| macvlan | 可接上實體區網 | 無法接到你的實體區網 |
| bind mount 效能 | 原生速度 | 要跨虛擬機同步,大量小檔案(node_modules)時明顯較慢 |
| 檔案擁有者 | 直接對應 UID,常有權限問題 | Desktop 會自動轉換,權限問題較少(但上線到 Linux 時才會冒出來) |
| 資源上限 | 整台主機 | 設定頁面指定給虛擬機的 CPU、記憶體、磁碟 |
| daemon.json | /etc/docker/daemon.json | Settings → 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?
- Linux:
systemctl status docker看 daemon 有沒有在跑,沒有的話journalctl -u docker -n 100 --no-pager看原因,最常見的是daemon.json寫錯。 - Mac/Windows:Docker Desktop 有沒有開啟、虛擬機是否啟動完成。
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 找找看。
容器一啟動就結束
docker ps -a看狀態與結束代碼。docker logs <容器>看錯誤訊息。- 前景程式結束容器就會結束,背景執行的服務要用前景模式啟動(例如 nginx 要
daemon off;)。 - 改用互動模式進去手動執行看看:
docker run -it --rm --entrypoint sh <映像檔>。 - 用
docker inspect -f '{{.Config.Entrypoint}} {{.Config.Cmd}}' <映像檔>確認實際要執行的指令,常見錯誤是 compose 的command把映像檔預設的 CMD 蓋掉了。 - 看看是不是缺環境變數:很多官方映像檔(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 解析失敗
docker run --rm busybox nslookup google.com測 DNS。docker run --rm busybox ping -c 3 1.1.1.1測 IP 連線:IP 通但名稱不通是 DNS 問題,兩個都不通是路由或防火牆問題。- 公司網路或 VPN 環境常擋掉 Docker 預設使用的 DNS,可以在
daemon.json加"dns": ["8.8.8.8", "1.1.1.1"];需要解析公司內部網域的話,第一個要放內部 DNS。 - 主機防火牆(nftables)規則被其他工具清掉時,Docker 的 NAT 規則也會不見,
sudo systemctl restart docker會重建。 - 主機的 IP 轉送被關掉:
sysctl net.ipv4.ip_forward應該是 1。 - 主機上的
/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(見前面的說明),再重建網路。
容器之間連不到
- 兩個容器在不在同一個網路:
docker inspect -f '{{json .NetworkSettings.Networks}}' <容器>。不同 Compose 專案預設各自一個網路,彼此不通,要共用一個external網路。 - 用的是容器名稱或服務名稱,而不是
localhost:容器裡的 localhost 是它自己。 - 連的是容器內部的埠(例如 db 的 5432),不是
-p對應到主機的埠。 - 目標程式是否監聽
0.0.0.0:只監聽127.0.0.1的程式,同網路的其他容器也連不到。 - 是不是預設的
bridge網路:那裡沒有名稱解析。
Permission denied(bind mount)
見前面「權限問題:UID 對不上」。快速確認:docker exec <容器> id 看容器以哪個 UID 執行,主機上 ls -ln <資料夾> 看擁有者的數字 UID,兩者要能對上(或資料夾權限允許)。SELinux 系統再加上 :z。
磁碟被 Docker 吃光
docker system df看是映像檔、建置快取還是 volume。sudo du -sh /var/lib/docker/containers/*/*-json.log | sort -h | tail:容器日誌是不是太大。- 依序
docker builder prune、docker image prune -a、清日誌,最後才考慮 volume。 docker ps -s看是不是有容器把大量資料寫在可寫層。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)。
建置每次都從頭來、快取沒有命中
- 用
--progress=plain找出第一個沒有CACHED的步驟,它前面那個 COPY 就是元兇。 - 檢查 .dockerignore 是否排除了會一直變的檔案(
.git、日誌、建置輸出)。 - 用了
ARG而且每次傳不同的值(例如建置時間):ARG 的值改變會讓第一個使用它的步驟以及之後全部失效,這種 ARG 請放在 Dockerfile 越後面越好。 - 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}}' 容器 |
| 容器的 IP | docker 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 映像檔 |
| 映像檔的 digest | docker 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 |
| 啟用 profile | docker 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) |
| 備份 volume | docker run --rm -v 名稱:/data:ro -v "$PWD":/backup busybox:1.37 tar czf /backup/名稱.tar.gz -C /data . |
| 驗證 daemon.json | sudo 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 |
這篇會持續更新,遇到新的常用指令或踩到新的坑,就會補進來。