Docker Compose build 與 image:VPS 差異與更新方法
了解 Docker Compose 的 image 與 build 在 VPS 上如何運作,以及為何修改 Dockerfile 後執行 docker compose up 仍使用舊映像檔,並掌握正確修正方式。
Docker Compose build 與 image:簡短說明
在 Docker Compose 檔案中,image: 用來指定要使用的映像檔,包括本機映像檔、標籤或 digest 參照;build: 則告訴 Compose 如何從原始碼建置映像檔。只設定 image: 時,Compose 會依 pull_policy 使用或拉取映像檔。只設定 build: 時,Compose 會使用已設定的 builder 建置映像檔,並以專案名稱和服務名稱衍生出映像檔名稱。兩者都設定時,pull_policy 會決定 Compose 要拉取還是建置;建置時,Compose 會使用 image: 中的名稱標記結果。這就是以自訂名稱建置映像檔並推送映像檔的方式。builder 可以在本機或遠端 Docker host 上執行。
這就是兩者的全部差異。以下內容說明它們在伺服器上的實際運作方式。本節假設 Docker Engine 和 Compose plugin 已經安裝完成;在 VPS 上執行 Docker 涵蓋這部分。
完整介紹 3 種形式
使用已發佈的 tag。若該 tag 不存在,則依預設的 pull policy 拉取。整個過程不會使用 Dockerfile。
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"從專案目錄中的 Dockerfile 建置。建置過程也可以拉取映像檔,並下載 Dockerfile 所需的相依項目。
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"建置結果並以 docker compose build 加上 tag;若未明確指定 pull policy,up 會在建置前嘗試拉取此映像檔。接著,docker compose push 可以將該確切 tag 推送至 registry。
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context 是傳送給 builder 的目錄。dockerfile 會以該 context 為基準解析,因此使用 context: . 搭配 dockerfile: docker/prod.Dockerfile 是正常且正確的作法。執行 docker compose images,查看每個服務容器背後的映像檔名稱與映像檔 ID;檢查 Compose 檔案,確認服務使用 image:、build:,或兩者皆使用。
為什麼修改 Dockerfile 後,執行 docker compose up 不會重新建置?
因為一般的 up 會重複使用現有映像檔,除非您明確要求建置,或設定必須建置的原則。
當 Compose 啟動只有 build: 區段的服務時,只要現有映像檔可用,就會使用該映像檔。它不會讀取您的 Dockerfile、比較來源檔案,也不會檢查任何時間戳記。若同時設定 image: 與 build:,且未明確指定 pull_policy,Compose 會先嘗試拉取映像檔;只有在 registry 或平台快取中找不到映像檔時,才會進行建置。只要映像檔存在,就會被視為可用。
因此,您修改 app.py 後執行 docker compose up -d,看到 Compose 回報容器正在執行,但實際提供的仍是舊程式碼。過程中沒有失敗,因此也不會顯示警告。判斷線索是 Compose 顯示在容器名稱旁的狀態文字:Compose 重新建立的容器會顯示 recreated 或 started,而 Compose 決定保留不變的容器會顯示 running。
兩項檢查即可確認。docker compose images 會列出每個容器使用的映像檔 ID,請在部署前記下該 ID,並在部署後比較。docker image ls 會顯示 CREATED 欄位,但由於快取建置與可重現的時間戳記,單靠該日期無法證明是否已使用最新來源進行建置。
哪些旗標會強制重新建置
docker compose up -d --build會先進行建置,接著重新建立映像檔已變更的容器。這是多數人要找的旗標。docker compose build web會建置一項服務,但不啟動任何服務。搭配docker compose up --no-deps -d web使用,即可只替換該容器,讓堆疊的其餘部分繼續執行。docker compose build --no-cache web會略過快取層,重新建置該服務。docker compose build --pull會嘗試在FROM中提取較新版的基礎映像檔,因此像node:22這類會變動的標籤,會取得目前內容,而不是你在 3 月下載的副本。docker compose up -d --force-recreate會強制重新建立容器,即使設定與映像檔都沒有變更。此旗標本身不會要求建置,但當映像檔不存在,或提取原則要求建置時,up仍可能進行建置。原本想使用--build卻改用這個旗標,是常見的錯誤方向。
你也可以將這項決策放入檔案中。根據 Compose 規格的定義,pull_policy: build 表示由 Compose 建置映像檔;如果映像檔已存在,也會重新建置。每次執行 up 都會付出建置成本。這適合在筆記型電腦上使用,但在伺服器上通常不適合。
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: build還有一項值得注意的互動行為。docker compose pull 也會嘗試提取具有 build 區段的服務映像檔;如果提取失敗,便會告知你必須改為建置映像檔。傳入 --ignore-buildable 可安靜地略過這些服務。
建置快取如何決定部署時間
當 Dockerfile 指令及其輸入未變更時,建置器會檢查每個指令是否有可重複使用的快取結果。對於 COPY 而言,輸入包括檔案內容與中繼資料,但不包括修改時間。只要其中一個層未命中快取,後續依賴該層的步驟就會重新建置。
這項規則會決定部署只需數秒,還是需要數分鐘。請依照變更頻率由低至高排列 Dockerfile,將很少變更的內容放在前面,經常隨每次 commit 變更的內容放在後面。
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci 位於 COPY . . 之上,因此編輯來源檔案時,安裝層仍會保留在快取中,建置會從 copy 步驟繼續。若交換這兩行,單一字元的變更就會重新安裝所有相依套件,因為 COPY . . 會使 npm ci 所依賴的層失效。相同的結構也適用於 pip install -r requirements.txt 與 go mod download。
當你懷疑有過時的層遮蔽修正內容時,--no-cache 是適合使用的工具。但不應將它作為預設選項,因為它會捨棄 Dockerfile 排序所帶來的重複使用效益。
映像檔設定與 Compose 都能覆寫其中一項設定:Dockerfile 的 CMD 是映像檔預設執行的內容,而服務中的 command: 鍵會取代它。command 與 entrypoint 如何互動 在此很重要,因為 Compose 覆寫設定可能讓剛建置的映像檔表現得完全像舊映像檔。
建置內容與 .dockerignore
context: . 會將專案目錄提供給建置器。若未設定排除項目,其中也會包含 .git 以及您可能放在原始碼旁的任何資料目錄;不過 BuildKit 會略過未使用的檔案,並以增量方式傳輸變更。若專案沒有其他變更,建置卻在傳輸內容步驟停滯,表示內容過大。
在內容根目錄建立 .dockerignore 檔案,即可從傳輸中排除路徑。其語法接近 .gitignore。
.git
node_modules
*.log
data/
.env這有兩項好處。傳輸內容會縮小,因此傳送這些檔案所需的時間也會減少。此外,COPY . . 將無法再把 .env 複製到映像中,因而避免任何拉取該映像的人讀取其中內容。
會隨時間變慢的建置案例是 bind mount。具名 volume 位於專案目錄之外,但例如 ./data:/var/lib/postgresql/data 這類 bind mount 位於建置內容內,因此資料庫持續增長時,建置速度會逐週變慢。在 .dockerignore 中加入一行即可修正。對具名 volume 使用 bind mount 說明更廣泛的取捨。
建置引數也有較小版本的相同風險。透過 args: 傳入的值可能保留在映像歷程或 provenance metadata 中,因此應放入版本號,絕不要放入 token。除非在 Dockerfile 中明確參照,否則預先定義的 proxy 引數預設會從建置快取和 docker history 中排除。Compose 中的環境檔與 secrets 說明憑證應改放在何處。
應在 VPS 上建置,還是在其他地方建置後再拉取?
在提供網路流量服務的主機上建置是預設做法,因為路徑最短:git pull,接著執行 docker compose up -d --build。對於目前尚未有人依賴的小型伺服器,這樣做沒有問題。但有兩個可量測的原因,以及一個只會在狀況不佳時出現的原因,會讓這種做法不再適用。
記憶體。 建置會在正式執行中的應用程式旁執行編譯器與 bundler,而這通常是多數技術堆疊中最耗用記憶體的部分。JavaScript bundler 或 Rust 編譯可能耗盡 1 GB VPS 可用的記憶體。記憶體耗盡時,kernel 會根據記憶體使用量、配置情境與 oom_score_adj 計算的 badness score 選擇 OOM 受害程序;它不會單純終止佔用記憶體最多的程序。建置可能以 Killed 停止並回傳結束狀態 137,也可能改為終止資料庫,導致網站在部署途中停止服務。dmesg -T | grep -i oom 會在 kernel log 中搜尋 OOM 訊息;存取該 log 需要具備讀取權限。
磁碟。 建置會留下 image layer 與 build cache。docker system df 會顯示其磁碟用量;BuildKit 的定期 garbage collection 會依照已設定的政策回收 cache。使用 docker image prune 回收 dangling image,使用 docker builder prune 回收 cached layer。磁碟已滿時,受影響的不只是建置。資料庫也會停止寫入,而這項故障造成的損失遠高於部署速度變慢。
可重現性。 如果沒有推送或匯出,在伺服器上建置的 image 只存在於該伺服器。舊 image 不再可用時,回復版本就必須切換至舊 commit 並重新建置;但這次建置不保證會產生原本的結果,因為 base tag 可能已變更,套件 mirror 也可能隨之變更。在其他地方建置並推送 tag,則可將回復版本轉為編輯操作:將 image: 指向先前的 tag,再執行 docker compose up -d。
能長期維持的配置很簡單。持續整合環境執行建置並推送 registry.example.com/acme/web:<git-sha>,而 VPS 上的 Compose 檔案則攜帶 image:,完全不包含 build: key。如此一來,部署只需執行兩個幾乎不需要記憶體的命令。
docker compose pull
docker compose up -d在伺服器上執行 docker login registry.example.com,儲存拉取 private tag 所需的認證資訊。
保留建置區段供開發使用,不要刪除;請放在自行命名的檔案中。
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --build將該檔案命名為 compose.dev.yaml,不要命名為 compose.override.yaml。Compose 只要發現 override 檔案存在,就會自動載入;因此,若有遺留的 override 檔案被複製到伺服器,伺服器就會再次在背景中開始建置。分層使用多個 Compose 檔案說明合併時如何解析各個 key。
在其他環境建置時的架構陷阱
單一平台映像檔會帶有建置時使用的 CPU 架構。在 Apple Silicon 筆記型電腦上建置 ARM 映像檔並推送後,若再於 x86_64 VPS 上使用該映像檔,Docker 在建立容器時,若使用不相容且未明確指定平台的快取映像檔,就會發出警告。未使用模擬器時,程序會因 exec format error 而失敗。這看起來像二進位檔損毀,但實際上並不是。請明確指定目標架構進行建置:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .如果筆記型電腦使用 x86,而您執行的是 ARM VPS,而非 x86 VPS,也會發生相反的架構不相容問題。讓 CI 在實際部署所用的架構上建置,即可排除這項疑問。多平台映像檔也能解決此問題:Docker 會在提取映像檔時選取相符的變體。
部署後應檢查的項目
docker compose images會列出每個執行中容器所使用的映像與標籤。映像 ID 已變更,即可證明新建置版本已投入服務。docker compose config會在變數替換後列出合併的檔案內容。執行任何操作前,即可讀取 Compose 最終使用的映像名稱。docker compose logs -f web在切換後的前 30 秒內持續監控。如果容器啟動後反覆結束,只有在其 restart policy 要求時才會自動重新啟動;請檢查日誌以找出原因。docker image ls會顯示 CREATED 欄位。也請檢查建置輸出與已部署映像 ID,因為建立時間戳記本身無法證明是否執行過重新建置。
如果您仍在組合這些檢查所使用的檔案,VPS 上 Compose 檔案的基本內容涵蓋相關鍵值,而Compose 指令速查表則列出其餘子命令。
FAQ
可以在同一個服務中同時使用 build 和 image 嗎?
可以,這是自行建置專案時的標準設定。Compose 會根據 build: 區段進行建置,並使用 image: 的值為結果加上標籤;若未明確設定 pull_policy,up 會先嘗試拉取映像。這個標籤就是 docker compose push 推送至 registry 時使用的標籤,也是其他機器拉取的目標。若未設定 image: 索引鍵,Compose 仍會建置,但會依專案名稱和服務名稱命名映像,並警告缺少該屬性,因此無法推送映像。
為什麼 docker compose up 沒有套用我的 Dockerfile 變更?
因為一般的 up 會重複使用現有映像,除非你要求建置,或設定需要建置的原則。它不會比較該映像與 Dockerfile 或原始檔案,以判斷是否需要重新建置。請執行 docker compose up -d --build;若只要替換單一服務,則執行 docker compose build web,接著執行 docker compose up --no-deps -d web。在服務上設定 pull_policy: build 後,每次執行 up 都會重新建置,適合開發機器使用。
--build 和 --force-recreate 有什麼差異?
--build 會重新建置映像,然後重新建立映像已變更的容器。--force-recreate 會強制重新建立容器,即使設定和映像都未變更;它本身不會要求建置。若變更位於原始碼或 Dockerfile,應使用 --build 旗標。--force-recreate 用於重設容器本身,例如在保留相同映像的情況下清除其可寫入層。
應該在 VPS 上建置 Docker 映像,還是在其他地方建置?
請在其他地方建置,待該主機也提供網路流量服務後,再拉取標籤。建置會與應用程式爭用記憶體;記憶體耗盡時,核心會使用可調整的 OOM 分數選擇終止對象,可能選中建置程序或資料庫。建置也會在磁碟上留下快取,但 BuildKit 會依據垃圾回收原則自動回收快取。若是沒有使用者的小型專案,直接在伺服器上建置仍可接受;只要將 build: 區段保留在僅供開發使用的 Compose 檔案中,日後移轉的成本就不高。
如何避免 Docker 建置快取填滿磁碟?
執行 docker system df,查看映像與建置快取各自占用多少空間。docker builder prune 會移除快取層,docker image prune 會移除先前建置留下的懸空映像。分別加入 -a 後,會移除所有未使用的建置快取,或所有未被容器參照的映像;但這不保證下一次建置會完全從零開始。請勿在伺服器上排程執行 docker system prune -af --volumes,因為它會移除已停止的容器與未使用的匿名 volume;維護期間,這可能使儲存在匿名 volume 中的資料庫資料面臨遺失風險。