Compose 模板檔案
模板檔案是使用 Compose 的核心,涉及到的指令關鍵字也比較多。但大家不用擔心,這裡面大部分指令跟 docker run 相關參數的含義都是類似的。
預設的模板檔名稱為 compose.yaml(也相容 docker-compose.yml 等歷史檔案名),格式為 YAML。
name: docker-practice
services:
web:
image: nginx:1.28-alpine
ports:
- "8080:80"
restart: unless-stopped注意每個服務都必須透過 image 指令指定映像檔或 build 指令(需要 Dockerfile)等來自動建立產生映像檔。
如果使用 build 指令,在 Dockerfile 中設定的選項(例如:CMD、EXPOSE、VOLUME、ENV 等)將會自動被取得,無需在 Compose 檔案中重複設定。
下面分別介紹各個指令的用法。
build
指定 Dockerfile 所在資料夾的路徑(可以是絕對路徑,或者相對 Compose 檔案的路徑)。Compose 將會利用它自動建立這個映像檔,然後使用這個映像檔。
services:
webapp:
build: ./dir你也可以使用 context 指令指定 Dockerfile 所在資料夾的路徑。
使用 dockerfile 指令指定 Dockerfile 檔案名。
使用 arg 指令指定建立映像檔時的變數。
使用 cache_from 指定建立映像檔的快取
cap_add, cap_drop
指定容器的核心能力 (capability) 分配。
例如,讓容器擁有所有能力可以指定為:
去掉 NET_ADMIN 能力可以指定為:
command
覆蓋容器啟動後預設執行的命令。
configs
configs 來自 Compose Specification。它在 Swarm 中是原生物件;在本地 docker compose 模式下通常以檔案掛載的形式實作,具體能力取決於 Compose 版本與執行平台。
cgroup_parent
指定父 cgroup 組,意味著將繼承該組的資源限制。
例如,建立了一個 cgroup 組名稱為 cgroups_1。
container_name
指定容器名稱。預設將會使用 專案名稱_服務名稱_序號 這樣的格式。
注意:指定容器名稱後,該服務將無法進行擴展 (scale),因為 Docker 不允許有多個容器具有相同的名稱。
deploy
deploy 用於描述副本數、更新策略、資源限制等部署參數。該欄位在 Swarm 中支援最完整;在本地 docker compose up 場景下通常只有部分欄位生效。
devices
指定裝置映射關係。
depends_on
解決容器的依賴、啟動先後的問題。以下例子中會先啟動 redis db 再啟動 web
注意:上述簡寫形式中,
web服務不會等待redisdb「完全啟動」之後才啟動。
如果需要等待依賴服務就緒,可以使用 condition 欄位配合 healthcheck:
condition 支援三個值:
service_started:容器啟動即滿足(預設)。service_healthy:容器的healthcheck狀態為 healthy 時滿足。service_completed_successfully:容器成功退出(退出碼為 0)時滿足,適用於初始化任務等一次性容器。
dns
自訂 DNS 伺服器。可以是一個值,也可以是一個列表。
dns_search
設定 DNS 搜尋域。可以是一個值,也可以是一個列表。
tmpfs
掛載一個 tmpfs 檔案系統到容器。
env_file
從檔案中取得環境變數,可以為單獨的檔案路徑或列表。
如果透過 docker compose -f FILE 方式來指定 Compose 模板檔案,則 env_file 中變數的路徑會基於模板檔案路徑。
如果有變數名稱與 environment 指令衝突,則按照慣例,以後者為準。
環境變數檔案中每一行必須符合格式,支援 # 開頭的註解行。
environment
設定環境變數。你可以使用陣列或字典兩種格式。
只給定名稱的變數會自動取得執行 Compose 主機上對應變數的值,可以用來防止洩露不必要的資料。
如果變數名稱或者值中用到 true|false,yes|no 等表達布林含義的詞彙,最好放到引號裡,避免 YAML 自動解析某些內容為對應的布林語義。這些特定詞彙,包括
expose
暴露埠號,但不映射到宿主機,只被連線的服務存取。
僅可以指定內部埠號為參數
external_links
注意:不建議使用該指令。
連結到 Compose 檔案外部的容器,甚至並非 Compose 管理的外部容器。
extra_hosts
類似 Docker 中的 --add-host 參數,指定額外的 host 名稱映射資訊。
會在啟動後的服務容器中 /etc/hosts 檔案中新增如下兩條條目。
healthcheck
透過命令檢查容器是否健康執行。
image
指定為映像檔名稱或映像檔 ID。如果映像檔在本地不存在,Compose 將會嘗試拉取這個映像檔。
labels
為容器新增 Docker 中繼資料 (metadata) 資訊。例如可以為容器新增輔助說明資訊。
links
注意:不推薦使用該指令。容器之間應透過 Docker 網路 (networks) 進行互聯。
logging
設定日誌選項。
Docker 支援十餘種日誌驅動(json-file、local、syslog、journald、gelf、fluentd、awslogs、splunk、gcplogs、none 等,預設為 json-file),完整清單見官方文件。下面是幾個常見取值:
options 設定日誌驅動的相關參數。
network_mode
設定網路模式。使用和 docker run 的 --network 參數一樣的值。
networks
設定容器連線的網路。
pid
跟主機系統共享程式命名空間。開啟該選項的容器之間,以及容器和宿主機系統之間可以透過程式 ID 來相互存取和操作。
ports
暴露埠號資訊。
使用宿主埠號:容器埠號 (HOST:CONTAINER) 格式,或者僅僅指定容器的埠號(宿主將會隨機選擇埠號)都可以。
注意:當使用 HOST:CONTAINER 格式來映射埠號時,如果你使用的容器埠號小於 60 並且沒放到引號裡,可能會得到錯誤結果,因為 YAML 會自動解析 xx:yy 這種數字格式為 60 進位。為避免出現這種問題,建議數字串都採用引號包括起來的字串格式。
secrets
儲存敏感資料,例如 mysql 服務密碼。
security_opt
指定容器模板標籤 (label) 機制的預設屬性(使用者、角色、型別、級別等)。例如設定標籤的使用者名稱和角色名。
stop_signal
設定另一個訊號來停止容器。在預設情況下使用的是 SIGTERM 停止容器。
sysctls
設定容器核心參數。
ulimits
指定容器的 ulimits 限制值。
例如,指定最大程式數為 65535,指定檔案控制代碼數為 20000(軟限制,應用可以隨時修改,不能超過硬限制)和 40000(系統硬限制,只能 root 使用者提高)。
volumes
資料卷所掛載路徑設定。可以設定為宿主機路徑 (HOST:CONTAINER) 或者資料卷名稱 (VOLUME:CONTAINER),並且可以設定存取模式 (HOST:CONTAINER:ro)。
該指令中路徑支援相對路徑。
如果路徑為資料卷名稱,必須在檔案中設定資料卷。
其他指令
此外,還有包括 domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir 等指令,基本跟 docker run 中對應參數的功能一致。
指定服務容器啟動後執行的入口檔案。
指定容器中執行應用的使用者名稱。
指定容器中工作目錄。
指定容器中搜尋域名、主機名、mac 位址等。
允許容器中執行一些特權命令。privileged: true 會顯著擴大容器對宿主機裝置和 Linux capability 的存取範圍,生產環境應優先使用更窄的 cap_add、devices 或只讀掛載;更多說明見 核心能力機制。
指定容器退出後的重啟策略。該命令對保持服務始終執行十分有效,在生產環境中推薦設定為 always 或者 unless-stopped。
no
預設值,不自動重啟
always
無論退出碼如何,始終重啟;Docker 守護程式啟動時也會重啟
on-failure[:max-retries]
僅在非零退出碼時重啟,可指定最大重試次數
unless-stopped
類似 always,但手動停止的容器在守護程式重啟後不會自動啟動
以只讀模式掛載容器的 root 檔案系統,意味著不能對容器內容進行修改。
開啟標準輸入,可以接受外部輸入。
模擬一個偽終端。
profiles
profiles 用於按場景選擇性啟動服務。未指定 profiles 的服務預設始終啟動;標記了 profiles 的服務僅在啟用對應 profile 時才啟動。
啟動時透過 --profile 啟用:
也可以透過環境變數啟用:
如果在命令列裡顯式指定某個帶 profile 的服務,Compose 會自動啟動這個目標服務及其宣告的依賴;但不會自動啟動同一 profile 下的其他服務,除非也顯式指定或透過 --profile / COMPOSE_PROFILES 啟用。
讀取變數
Compose 模板檔案支援動態讀取主機的系統環境變數和目前目錄下的 .env 檔案中的變數。
例如,下面的 Compose 檔案將從執行它的環境中讀取變數 ${MONGO_VERSION} 的值,並寫入執行的指令中。
如果執行 MONGO_VERSION=3.2 docker compose up 則會啟動一個 mongo:3.2 映像檔的容器;如果執行 MONGO_VERSION=2.8 docker compose up 則會啟動一個 mongo:2.8 映像檔的容器。
若目前目錄存在 .env 檔案,執行 docker compose 命令時將從該檔案中讀取變數。
在目前目錄新建 .env 檔案並寫入以下內容。
執行 docker compose up 則會啟動一個 mongo:3.6 映像檔的容器。
最後更新於