服務頂級元素

服務是應用程式中計算資源的抽象定義，可以獨立於其他元件進行擴充套件或替換。服務由一組容器支援，這些容器由平臺根據複製要求和放置約束執行。由於服務由容器支援，因此它們由 Docker 映象和一組執行時引數定義。服務中的所有容器都使用這些引數以相同的方式建立。

Compose 檔案必須宣告一個services頂級元素作為對映，其鍵是服務名稱的字串表示形式，其值是服務定義。服務定義包含應用於每個服務容器的配置。

每個服務也可以包含一個build部分，該部分定義如何建立服務的 Docker 映象。Compose 支援使用此服務定義構建 Docker 映象。如果未使用，則build部分將被忽略，Compose 檔案仍被視為有效。構建支援是 Compose 規範的可選方面，在Compose 構建規範文件中進行了詳細描述。

每個服務定義執行時約束和要求以執行其容器。deploy部分對這些約束進行分組，並允許平臺調整部署策略以最佳方式匹配容器的需求和可用資源。部署支援是 Compose 規範的可選方面，在Compose 部署規範文件中進行了詳細描述。如果未實現，則deploy部分將被忽略，Compose 檔案仍被視為有效。

屬性

annotations

annotations定義容器的註釋。annotations可以使用陣列或對映。

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

attach

在 Docker Compose 版本2.20.0中引入

當attach被定義並設定為false時，Compose 不會收集服務日誌，除非你明確要求它。

預設服務配置是attach: true。

build

build指定從原始碼建立容器映象的構建配置，如Compose 構建規範中定義。

blkio_config

blkio_config定義一組配置選項，用於設定服務的塊 IO 限制。

services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30

device_read_bps，device_write_bps

為給定裝置上的讀/寫操作設定每秒位元組限制。列表中的每個專案都必須有兩個鍵

path：定義受影響裝置的符號路徑。
rate：可以是表示位元組數的整數，也可以是表示位元組值的字串。

device_read_iops，device_write_iops

為給定裝置上的讀/寫操作設定每秒操作限制。列表中的每個專案都必須有兩個鍵

path：定義受影響裝置的符號路徑。
rate：表示每秒允許操作次數的整數。

weight

修改分配給服務的頻寬比例，相對於其他服務。取值為 10 到 1000 之間的整數，預設值為 500。

weight_device

透過裝置微調頻寬分配。列表中的每個專案都必須有兩個鍵

path：定義受影響裝置的符號路徑。
weight：10 到 1000 之間的整數。

cpu_shares

cpu_shares定義服務容器相對於其他容器的相對 CPU 權重，以整數形式表示。

cpu_period

cpu_period在平臺基於 Linux 核心時配置 CPU CFS（完全公平排程程式）週期。

cpu_quota

cpu_quota在平臺基於 Linux 核心時配置 CPU CFS（完全公平排程程式）配額。

cpu_rt_runtime

cpu_rt_runtime為支援即時排程程式的平臺配置 CPU 分配引數。它可以是使用微秒作為單位的整數，也可以是持續時間。

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period為支援即時排程程式的平臺配置 CPU 分配引數。它可以是使用微秒作為單位的整數，也可以是持續時間。

 cpu_rt_period: '1400us'
 cpu_rt_period: 11000`

cpus

cpus定義分配給服務容器的（可能是虛擬的）CPU 數量。這是一個小數。0.000 表示沒有限制。

當設定cpus時，它必須與部署規範中的cpus屬性一致。

cpuset

cpuset定義允許執行的顯式 CPU。可以是範圍0-3或列表0,1

cap_add

cap_add指定額外的容器功能作為字串。

cap_add:
  - ALL

cap_drop

cap_drop指定容器功能作為字串。

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

在 Docker Compose 版本2.15.0中引入

cgroup指定要加入的 cgroup 名稱空間。未設定時，容器執行時將決定選擇哪個 cgroup 名稱空間（如果支援）。

host：在容器執行時 cgroup 名稱空間中執行容器。
private：在容器的私有 cgroup 名稱空間中執行容器。

cgroup_parent

cgroup_parent指定容器的可選父cgroup。

cgroup_parent: m-executor-abcd

command

command覆蓋容器映象宣告的預設命令，例如 Dockerfile 的CMD。

command: bundle exec thin -p 3000

該值也可以是列表，方式類似於Dockerfile

command: [ "bundle", "exec", "thin", "-p", "3000" ]

如果該值為null，則使用映象的預設命令。

如果該值為[]（空列表）或''（空字串），則忽略映象宣告的預設命令，即被覆蓋為空。

configs

配置允許服務在無需重新構建 Docker 映象的情況下調整其行為。服務只能在configs屬性明確授予許可權時才能訪問配置。支援兩種不同的語法變體。

如果config在平臺上不存在或未在 Compose 檔案的configs頂級元素中定義，Compose 會報告錯誤。

為配置定義了兩種語法：簡短語法和長語法。

您可以授予服務對多個配置的訪問許可權，並且可以混合使用長語法和短語法。

簡短語法

簡短語法變體只指定配置名稱。這授予容器對配置的訪問許可權，並將它作為檔案掛載到服務的容器檔案系統中。掛載點在容器內的位置預設在 Linux 容器中為/<config_name>，在 Windows 容器中為C:\<config-name>。

以下示例使用簡短語法來授予redis服務對my_config和my_other_config配置的訪問許可權。my_config的值設定為檔案./my_config.txt的內容，my_other_config被定義為外部資源，這意味著它已經在平臺中定義。如果外部配置不存在，則部署將失敗。

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

長語法

長語法提供了更多關於如何在服務的任務容器中建立配置的粒度。

source：配置在平臺中存在的名稱。
target：要掛載到服務的任務容器中的檔案路徑和名稱。如果未指定，則預設為/<source>。
uid和gid：在服務的任務容器中擁有已掛載的配置檔案的數字 UID 或 GID。未指定時的預設值是執行容器的 USER。
mode：在服務的任務容器中掛載的檔案的許可權，以八進位制表示。預設值為世界可讀（0444）。可寫位必須被忽略。可執行位可以設定。

以下示例將my_config的名稱在容器內設定為redis_config，將模式設定為0440（組可讀），並將使用者和組設定為103。redis服務無法訪問my_other_config配置。

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

container_name

container_name是一個字串，它指定自定義容器名稱，而不是預設生成的名稱。

container_name: my-web-container

如果 Compose 檔案指定了container_name，Compose 不會將服務擴充套件到一個容器之外。嘗試這樣做會導致錯誤。

container_name 遵循 [a-zA-Z0-9][a-zA-Z0-9_.-]+ 的正則表示式格式。

credential_spec

credential_spec 配置託管服務帳戶的憑據規範。

如果您有使用 Windows 容器的服務，則可以對 credential_spec 使用 file: 和 registry: 協議。Compose 還支援針對自定義用例的附加協議。

credential_spec 必須採用 file://<filename> 或 registry://<value-name> 格式。

credential_spec:
  file: my-credential-spec.json

當使用 registry: 時，憑據規範將從守護程式主機上的 Windows 登錄檔中讀取。必須在以下位置找到具有給定名稱的登錄檔值：

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

以下示例從登錄檔中名為 my-credential-spec 的值載入憑據規範

credential_spec:
  registry: my-credential-spec

gMSA 配置示例

在為服務配置 gMSA 憑據規範時，您只需要使用 config 指定憑據規範，如下例所示

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

使用 depends_on 屬性，您可以控制服務的啟動和關閉順序。如果服務緊密耦合，並且啟動順序會影響應用程式的功能，這將很有用。

簡短語法

簡短語法變體僅指定依賴項的服務名稱。服務依賴項會導致以下行為

Compose 按照依賴項順序建立服務。在以下示例中，db 和 redis 在 web 之前建立。
Compose 按照依賴項順序刪除服務。在以下示例中，web 在 db 和 redis 之前刪除。

簡單示例

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Compose 保證在啟動依賴服務之前啟動依賴服務。Compose 會等待依賴服務“就緒”，然後再啟動依賴服務。

長語法

長格式語法支援配置簡短格式無法表達的附加欄位。

restart：當設定為 true 時，Compose 會在更新依賴服務後重啟此服務。這適用於由 Compose 操作控制的顯式重啟，不包括容器在宕機後由容器執行時自動重啟。在 Docker Compose 版本 2.17.0 中引入。
condition：設定依賴項被認為已滿足的條件
- service_started：相當於上述簡短語法
- service_healthy：指定依賴項應在啟動依賴服務之前“健康”（如健康檢查所示）。
- service_completed_successfully：指定依賴項應在啟動依賴服務之前成功完成執行。
required：當設定為 false 時，Compose 只會在依賴服務未啟動或不可用時發出警告。如果未定義，required 的預設值為 true。在 Docker Compose 版本 2.20.0 中引入。

服務依賴項會導致以下行為

Compose 按照依賴項順序建立服務。在以下示例中，db 和 redis 在 web 之前建立。
Compose 會等待標記為 service_healthy 的依賴項上的健康檢查透過。在以下示例中，預計 db 在建立 web 之前是“健康的”。
Compose 按照依賴項順序刪除服務。在以下示例中，web 在 db 和 redis 之前刪除。

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres

Compose 保證在啟動依賴服務之前啟動依賴服務。Compose 保證標記為 service_healthy 的依賴服務在啟動依賴服務之前是“健康的”。

deploy

deploy 指定服務的部署和生命週期的配置，如 Compose 部署規範中所定義。

develop

在 Docker Compose 版本 2.22.0 中引入

develop 指定用於將容器與原始碼同步的開發配置，如開發部分中所定義。

device_cgroup_rules

device_cgroup_rules 定義此容器的裝置 cgroup 規則列表。格式與 Linux 核心在控制組裝置白名單控制器中指定的相同格式。

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

devices 以 HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS] 的形式定義建立的容器的裝置對映列表。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

dns

dns 定義要設定在容器網路介面配置上的自定義 DNS 伺服器。它可以是單個值或列表。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt 列出要傳遞給容器 DNS 解析器（Linux 上的 /etc/resolv.conf 檔案）的自定義 DNS 選項。

dns_opt:
  - use-vc
  - no-tld-query

dns_search

dns_search 定義要設定在容器網路介面配置上的自定義 DNS 搜尋域。它可以是單個值或列表。

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname 宣告要用於服務容器的自定義域名。它必須是有效的 RFC 1123 主機名。

driver_opts

在 Docker Compose 版本 2.27.1 中引入

driver_opts 指定要傳遞給驅動程式的鍵值對選項列表。這些選項取決於驅動程式。有關更多資訊，請參閱驅動程式的文件。

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

entrypoint

entrypoint 宣告服務容器的預設入口點。這會覆蓋服務 Dockerfile 中的 ENTRYPOINT 指令。

如果 entrypoint 非空，Compose 將忽略影像中的任何預設命令，例如 Dockerfile 中的 CMD 指令。

另請參閱 command 以設定或覆蓋由入口點程序執行的預設命令。

在簡短形式中，值可以定義為字串

entrypoint: /code/entrypoint.sh

或者，值也可以是列表，方式類似於 Dockerfile 中的定義。

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

如果值為 null，則使用影像中的預設入口點。

如果值為 []（空列表）或 ''（空字串），則會忽略影像宣告的預設入口點，即將其覆蓋為空。

env_file

env_file 屬性用於指定一個或多個包含要傳遞給容器的環境變數的檔案。

env_file: .env

env_file 也可以是列表。列表中的檔案將從上到下處理。對於在兩個 env 檔案中指定的相同變數，將使用列表中最後一個檔案的值。

env_file:
  - ./a.env
  - ./b.env

列表元素也可以宣告為對映，這樣您就可以設定一個額外的屬性 required。這預設為 true。當 required 設定為 false 且 .env 檔案不存在時，Compose 會靜默忽略該條目。

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

required 屬性適用於 Docker Compose 版本 2.24.0 或更高版本。

相對路徑將從 Compose 檔案的父資料夾解析。由於絕對路徑會阻止 Compose 檔案的可移植性，因此 Compose 會在使用此類路徑設定 env_file 時發出警告。

在 environment 部分中宣告的環境變數會覆蓋這些值。即使這些值為空或未定義，也是如此。

Env_file 格式

.env 檔案中的每一行都必須採用 VAR[=[VAL]] 格式。以下語法規則適用

以 # 開頭的行將被視為註釋並被忽略。
空行將被忽略。
未加引號和雙引號 (") 值將應用插值。
每一行代表一個鍵值對。值可以可選地加引號。
- VAR=VAL -> VAL
- VAR="VAL" -> VAL
- VAR='VAL' -> VAL
未加引號值的內聯註釋必須以空格開頭。
- VAR=VAL # comment -> VAL
- VAR=VAL# not a comment -> VAL# not a comment
加引號值的內聯註釋必須跟在結束引號之後。
- VAR="VAL # not a comment" -> VAL # not a comment
- VAR="VAL" # comment -> VAL
單引號 (') 值將按字面使用。
- VAR='$OTHER' -> $OTHER
- VAR='${OTHER}' -> ${OTHER}
引號可以使用 \ 轉義。
- VAR='Let\'s go!' -> Let's go!
- VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
常見的 shell 轉義序列（包括 \n、\r、\t 和 \\）在雙引號值中受支援。
- VAR="some\tvalue" -> some value
- VAR='some\tvalue' -> some\tvalue
- VAR=some\tvalue -> some\tvalue

可以省略 VAL，在這種情況下，變數值為空字串。可以省略 =VAL，在這種情況下，變數將被取消設定。

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

environment 屬性定義在容器中設定的環境變數。environment 可以使用陣列或對映。任何布林值；true、false、yes、no 應包含在引號中，以確保它們不會被 YAML 解析器轉換為 True 或 False。

環境變數可以透過單個鍵（沒有值等於符號）宣告。在這種情況下，Compose 依賴於您來解析值。如果值未解析，則變數將被取消設定並從服務容器環境中刪除。

對映語法

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

陣列語法

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

當為服務同時設定 env_file 和 environment 時，environment 設定的值具有優先順序。

expose

expose 定義 Compose 從容器中公開的（傳入）埠或埠範圍。這些埠必須可供連結的服務訪問，不應釋出到主機。只能指定內部容器埠。

語法是 <portnum>/[<proto>] 或 <startport-endport>/[<proto>]（用於埠範圍）。如果未顯式設定，則使用 tcp 協議。

expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp"

注意
如果影像的 Dockerfile 已經公開埠，那麼即使在 Compose 檔案中未設定 expose，它也對網路上的其他容器可見。

extends

extends 允許您在不同的檔案中共享通用配置，甚至可以在不同的專案之間共享。使用 extends，您可以在一個地方定義一組通用的服務選項，並從任何地方引用它。您可以引用另一個 Compose 檔案並選擇您想在自己的應用程式中使用的服務，並且能夠根據自己的需求覆蓋某些屬性。

您可以在任何服務上使用 extends，以及其他配置鍵。extends 值必須是使用必填 service 和可選 file 鍵定義的對映。

extends:
  file: common.yml
  service: webapp

service：定義被引用為基礎的服務的名稱，例如 web 或 database。
file：定義該服務的 Compose 配置檔案的位置。

當服務使用 extends 時，它也可以指定對其他資源的依賴關係，例如顯式 volumes 宣告。但是，請注意，extends 不會自動將目標卷定義合併到擴充套件的 Compose 檔案中。相反，您有責任確保擴充套件服務存在等效的資源以保持一致性。Docker Compose 會驗證 Compose 模型中是否存在具有所引用 ID 的資源。

extends 目標中對其他資源的依賴關係可以是

透過 volumes、networks、configs、secrets、links、volumes_from 或 depends_on 的顯式引用
在名稱空間宣告（ipc、pid、network_mode）中使用 service:{name} 語法對其他服務的引用

不支援使用 extends 進行迴圈引用，Compose 在檢測到迴圈引用時會返回錯誤。

查詢引用服務

file 值可以是

不存在。這表明正在引用同一個 Compose 檔案中的另一個服務。
檔案路徑，可以是
- 相對路徑。此路徑被視為相對於主 Compose 檔案的位置。
- 絕對路徑。

由 service 表示的服務必須存在於識別的引用 Compose 檔案中。如果 Compose 返回錯誤，則

未找到由 service 表示的服務。
未找到由 file 表示的 Compose 檔案。

合併服務定義

兩個服務定義，一個是當前 Compose 檔案中的主要定義，另一個是由 extends 指定的引用定義，以以下方式合併

對映：主要服務定義中的對映鍵會覆蓋引用服務定義中的對映鍵。未被覆蓋的鍵將原樣包含在內。
序列：將專案合併到一個新的序列中。元素的順序保持不變，引用項在前面，主項在後面。
標量：主要服務定義中的鍵優先於引用服務定義中的鍵。

以下鍵應被視為對映：annotations、build.args、build.labels、build.extra_hosts、deploy.labels、deploy.update_config、deploy.rollback_config、deploy.restart_policy、deploy.resources.limits、environment、healthcheck、labels、logging.options、sysctls、storage_opt、extra_hosts、ulimits。

適用於 healthcheck 的一個例外是，主要對映不能指定 disable: true，除非引用對映也指定 disable: true。在這種情況下，Compose 會返回錯誤。

例如，以下輸入

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

為 cli 服務生成以下配置。如果使用陣列語法，也會生成相同的輸出。

environment:
  PORT: 8080
  TZ: utc
image: busybox

blkio_config.device_read_bps、blkio_config.device_read_iops、blkio_config.device_write_bps、blkio_config.device_write_iops、devices 和 volumes 下的專案也被視為對映，其中鍵是容器內的目標路徑。

例如，以下輸入

services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro

為 cli 服務生成以下配置。請注意，現在掛載的路徑指向新的卷名，並且應用了 ro 標誌。

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

如果引用服務定義包含 extends 對映，則該對映下的專案將直接複製到新的合併定義中。然後再次啟動合併過程，直到沒有 extends 鍵為止。

例如，以下輸入

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

為 cli 服務生成以下配置。在這裡，cli 服務從 common 服務獲取 user 鍵，而 common 服務又從 base 服務獲取此鍵。

image: busybox
user: root

序列

以下鍵應被視為序列：cap_add、cap_drop、configs、deploy.placement.constraints、deploy.placement.preferences、deploy.reservations.generic_resources、device_cgroup_rules、expose、external_links、ports、secrets、security_opt。合併產生的任何重複項都會被移除，因此序列中只包含唯一元素。

例如，以下輸入

services:
  common:
    image: busybox
    security_opt:
      - label:role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label:user:USER

為 cli 服務生成以下配置。

image: busybox
security_opt:
- label:role:ROLE
- label:user:USER

如果使用列表語法，以下鍵也應被視為序列：dns、dns_search、env_file、tmpfs。與上面提到的序列欄位不同，合併產生的重複項不會被移除。

標量

服務定義中任何其他允許的鍵都應被視為標量。

external_links

external_links 將服務容器連結到 Compose 應用程式外部管理的服務。external_links 定義了使用平臺查詢機制檢索的現有服務的名稱。可以指定 SERVICE:ALIAS 形式的別名。

external_links:
  - redis
  - database:mysql
  - database:postgresql

extra_hosts

extra_hosts 將主機名對映新增到容器網路介面配置（Linux 的 /etc/hosts）。

簡短語法

簡短語法在列表中使用純字串。值必須以 HOSTNAME=IP 的形式設定附加主機的 hostname 和 IP 地址。

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 地址可以括在方括號中，例如

extra_hosts:
  - "myhostv6=[::1]"

分隔符 = 是首選，但也可以使用 :。在 Docker Compose 版本 2.24.1 中引入。例如

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

長語法

或者，可以將 extra_hosts 設定為 hostname 和 IP 之間的對映

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose 在容器的網路配置中建立具有 IP 地址和主機名的匹配條目，這意味著對於 Linux /etc/hosts，將獲得額外的行

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

group_add

group_add 指定容器內使用者必須屬於的額外組，按名稱或編號指定。

此功能在多個容器（以不同使用者身份執行）需要在共享捲上讀取或寫入同一個檔案時非常有用。該檔案可以由所有容器共享的組擁有，並在 group_add 中指定。

services:
  myservice:
    image: alpine
    group_add:
      - mail

在建立的容器內執行 id 必須顯示使用者屬於 mail 組，如果沒有宣告 group_add，則不會出現這種情況。

healthcheck

healthcheck 屬性宣告一個檢查，該檢查用於確定服務容器是否“健康”。它的工作原理相同，並且具有與服務 Docker 映象設定的 HEALTHCHECK Dockerfile 指令集相同的預設值。您的 Compose 檔案可以覆蓋 Dockerfile 中設定的值。

有關 HEALTHCHECK 的更多資訊，請參閱 Dockerfile 參考。

healthcheck:
  test: ["CMD", "curl", "-f", "https://"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

interval、timeout、start_period 和 start_interval 以持續時間指定。在 Docker Compose 版本 2.20.2 中引入

test 定義 Compose 執行的命令以檢查容器健康狀況。它可以是字串或列表。如果它是列表，第一個專案必須是 NONE、CMD 或 CMD-SHELL。如果它是字串，則等效於指定 CMD-SHELL，後面跟著該字串。

# Hit the local web app
test: ["CMD", "curl", "-f", "https://"]

使用 CMD-SHELL 使用容器的預設 shell（Linux 的 /bin/sh）執行配置為字串的命令。以下兩種形式是等效的

test: ["CMD-SHELL", "curl -f https:// || exit 1"]

test: curl -f https:// || exit 1

NONE 停用健康檢查，主要用於停用服務 Docker 映象設定的 Healthcheck Dockerfile 指令集。或者，可以透過設定 disable: true 來停用映象設定的健康檢查

healthcheck:
  disable: true

hostname

hostname 宣告一個用於服務容器的自定義主機名。它必須是一個有效的 RFC 1123 主機名。

image

image 指定要從中啟動容器的映象。image 必須遵循 Open Container Specification 可定址映象格式，如 [<registry>/][<project>/]<image>[:<tag>|@<digest>]。

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

如果平臺上不存在映象，Compose 會根據 pull_policy 嘗試拉取它。如果您也使用 Compose Build Specification，則有其他選項可用於控制拉取優先順序，而不是從原始碼構建映象，但是拉取映象是預設行為。

只要聲明瞭 build 部分，就可以從 Compose 檔案中省略 image。如果您未使用 Compose Build Specification，如果 Compose 檔案中缺少 image，Compose 將無法正常工作。

init

init 在容器內執行一個 init 程序（PID 1），該程序轉發訊號並回收程序。將此選項設定為 true 以為服務啟用此功能。

services:
  web:
    image: alpine:latest
    init: true

使用的 init 二進位制檔案是特定於平臺的。

ipc

ipc 配置服務容器設定的 IPC 隔離模式。

shareable：為容器提供自己的私有 IPC 名稱空間，並有可能與其他容器共享。
service:{name}：使容器加入另一個容器的（shareable）IPC 名稱空間。

    ipc: "shareable"
    ipc: "service:[service name]"

isolation

isolation 指定容器的隔離技術。支援的值是特定於平臺的。

labels

labels 向容器新增元資料。您可以使用陣列或對映。

建議您使用反向 DNS 符號來防止您的標籤與其他軟體使用的標籤衝突。

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose 建立具有規範標籤的容器

com.docker.compose.project 設定在 Compose 建立的所有資源上，設定為使用者專案名稱
com.docker.compose.service 設定在服務容器上，使用 Compose 檔案中定義的服務名稱

com.docker.compose 標籤字首是保留的。在 Compose 檔案中指定帶有此字首的標籤會導致執行時錯誤。

links

links 定義對另一個服務中容器的網路連結。指定服務名稱和連結別名（SERVICE:ALIAS）或只指定服務名稱。

web:
  links:
    - db
    - db:database
    - redis

連結服務的容器可以透過與別名相同的 hostname 訪問，或者如果未指定別名，則透過服務名稱訪問。

不需要連結來啟用服務之間的通訊。當未設定特定的網路配置時，任何服務都可以透過 default 網路上的服務名稱訪問任何其他服務。如果服務確實聲明瞭它們連線到的網路，則 links 不會覆蓋網路配置，未連線到共享網路的服務將無法通訊。Compose 不會警告您配置不匹配。

連結還以與 depends_on 相同的方式表達服務之間的隱式依賴關係，因此它們決定服務的啟動順序。

logging

logging 定義服務的日誌記錄配置。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver 名稱指定服務容器的日誌記錄驅動程式。預設值和可用值是特定於平臺的。可以使用 options 作為鍵值對來設定特定於驅動程式的選項。

mac_address

在 Docker Compose 版本 2.24.0 及更高版本中可用。

mac_address 為服務容器設定 MAC 地址。

注意容器執行時可能會拒絕此值（例如 Docker Engine >= v25.0）。在這種情況下，您應該改用 networks.mac_address。

mem_limit

mem_limit 配置容器可以分配的記憶體量的限制，以表示位元組值的字串形式設定。

設定後，mem_limit 必須與部署規範中的 limits.memory 屬性一致。

mem_reservation

mem_reservation 配置容器可以分配的記憶體量的預留量，以表示位元組值的字串形式設定。

設定後，mem_reservation 必須與部署規範中的 reservations.memory 屬性一致。

mem_swappiness

mem_swappiness 定義為一個百分比，一個介於 0 和 100 之間的值，用於主機核心交換容器使用的匿名記憶體頁。

0：關閉匿名頁交換。
100：將所有匿名頁設定為可交換。

預設值是特定於平臺的。

memswap_limit

memswap_limit 定義容器允許交換到磁碟的記憶體量。這是一個修飾符屬性，只有在也設定了 memory 時才有意義。使用交換可以讓容器在容器耗盡所有可用記憶體時將多餘的記憶體需求寫入磁碟。對於經常將記憶體交換到磁碟的應用程式來說，存在效能損失。

如果 memswap_limit 設定為正整數，那麼 memory 和 memswap_limit 都必須設定。memswap_limit 表示可以使用的記憶體和交換總量，memory 控制非交換記憶體使用的量。因此，如果 memory="300m" 且 memswap_limit="1g"，則容器可以使用 300m 記憶體和 700m (1g - 300m) 交換。
如果 memswap_limit 設定為 0，則忽略該設定，該值將被視為未設定。
如果 memswap_limit 設定為與 memory 相同的值，並且 memory 設定為正整數，則容器將無法訪問交換。
如果 memswap_limit 未設定，並且 memory 已設定，則如果主機容器已配置交換記憶體，則容器可以使用與 memory 設定一樣多的交換。例如，如果 memory="300m" 並且 memswap_limit 未設定，則容器總共可以使用 600m 記憶體和交換。
如果 memswap_limit 顯式設定為 -1，則容器允許使用無限交換，直到主機系統上可用的量。

network_mode

network_mode 設定服務容器的網路模式。

none：關閉所有容器網路。
host：讓容器直接訪問主機的網路介面。
service:{name}：讓容器僅訪問指定的服務。有關更多資訊，請參閱容器網路。

    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

設定後，將不允許使用 networks 屬性，Compose 會拒絕任何包含這兩個屬性的 Compose 檔案。

networks

networks 屬性定義服務容器連線到的網路，引用 networks 頂級元素下的條目。networks 屬性有助於管理容器的網路方面，提供對服務在 Docker 環境中如何分段和互動的控制。這用於指定該服務的容器應該連線到哪些網路。這對於定義容器如何相互通訊以及與外部通訊非常重要。

services:
  some-service:
    networks:
      - some-network
      - other-network

有關 networks 頂級元素的更多資訊，請參閱網路。

別名

aliases 為網路上的服務宣告備用主機名。同一網路上的其他容器可以使用服務名稱或別名來連線到服務的某個容器。

由於 aliases 是網路範圍的，因此同一服務可以在不同的網路上擁有不同的別名。

注意網路範圍的別名可以由多個容器共享，甚至可以由多個服務共享。如果是這樣，則無法保證名稱解析到哪個容器。

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

在以下示例中，服務 frontend 能夠在 back-tier 網路上以主機名 backend 或 database 訪問 backend 服務。服務 monitoring 能夠在 admin 網路上以 backend 或 mysql 訪問相同的 backend 服務。

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier:
  back-tier:
  admin:

ipv4_address、ipv6_address

在加入網路時，為服務容器指定一個靜態 IP 地址。

在頂級網路部分中的對應網路配置必須具有一個 ipam 屬性，其中包含覆蓋每個靜態地址的子網配置。

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips

link_local_ips 指定一個連結本地 IP 列表。連結本地 IP 是特殊的 IP，它們屬於一個眾所周知的子網，並且完全由操作員管理，通常取決於它們部署的架構。

示例

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

mac_address

在 Docker Compose 版本 2.23.2 中引入

mac_address 設定服務容器在連線到此特定網路時使用的 MAC 地址。

優先順序

priority 指示 Compose 按什麼順序將服務的容器連線到其網路。如果未指定，則預設值為 0。

在以下示例中，app 服務首先連線到 app_net_1，因為它具有最高優先順序。然後，它連線到 app_net_3，然後連線到 app_net_2，它使用預設優先順序值 0。

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

oom_kill_disable

如果設定了 oom_kill_disable，Compose 會配置平臺，以便在記憶體不足的情況下不會殺死容器。

oom_score_adj

oom_score_adj 調整在記憶體不足的情況下，平臺殺死容器的偏好。值必須在 -1000、1000 範圍內。

pid

pid 設定 Compose 建立的容器的 PID 模式。支援的值是特定於平臺的。

pids_limit

pids_limit 調整容器的 PIDs 限制。設定為 -1 表示無限 PIDs。

pids_limit: 10

設定後，pids_limit 必須與部署規範中的 pids 屬性一致。

platform

platform 定義服務容器執行的目標平臺。它使用 os[/arch[/variant]] 語法。

os、arch 和 variant 的值必須符合 OCI 映象規範中使用的約定。

Compose 使用此屬性來確定要拉取哪個版本的映象，以及在哪個平臺上執行服務的構建。

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

ports

ports 用於定義主機和容器之間的埠對映。這對於允許外部訪問容器中執行的服務至關重要。它可以使用簡短語法定義簡單埠對映，也可以使用長語法定義，其中包含其他選項，例如協議型別和網路模式。

注意
埠對映不能與 network_mode: host 一起使用，否則會發生執行時錯誤。

簡短語法

簡短語法是用冒號分隔的字串，用於設定主機 IP、主機埠和容器埠，形式為

[HOST:]CONTAINER[/PROTOCOL]，其中

HOST 是 [IP:](port | range)
CONTAINER 是 port | range
PROTOCOL 用於將埠限制為指定協議。tcp 和 udp 值由規範定義，Compose 提供對平臺特定協議名稱的支援。

如果未設定主機 IP，則它繫結到所有網路介面。埠可以是單個值或範圍。主機和容器必須使用等效的範圍。

可以指定兩個埠（HOST:CONTAINER），也可以只指定容器埠。在後一種情況下，容器執行時會自動分配主機上的任何未分配埠。

HOST:CONTAINER 應始終指定為（引用的）字串，以避免與 yaml 基數-60 浮點數衝突。

示例

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"

注意
如果容器引擎不支援主機 IP 對映，Compose 會拒絕 Compose 檔案並忽略指定的主機 IP。

長語法

長形式語法允許配置在簡短形式中無法表達的其他欄位。

target：容器埠
published：公開的埠。它定義為一個字串，可以使用語法 start-end 設定為一個範圍。這意味著實際埠被分配了一個剩餘的可用埠，該埠在設定的範圍內。
host_ip：主機 IP 對映，未指定表示所有網路介面（0.0.0.0）。
protocol：埠協議（tcp 或 udp）。預設為 tcp。
app_protocol：此埠用於的應用程式協議（TCP/IP 第 4 層/OSI 第 7 層）。這是可選的，可以用作提示，以便 Compose 為其理解的協議提供更豐富的行為。在 Docker Compose 版本 2.26.0 中引入。
mode：host：在每個節點上釋出主機埠，或 ingress 使埠負載平衡。預設為 ingress。
name：埠的人類可讀名稱，用於記錄其在服務中的使用情況。

ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host

privileged

privileged 配置服務容器以提升的許可權執行。支援和實際影響是特定於平臺的。

profiles

profiles 定義服務要啟用的命名配置檔案列表。如果沒有分配，則始終啟動服務，但如果分配了，則僅在啟用配置檔案時啟動服務。

如果存在，profiles 遵循 [a-zA-Z0-9][a-zA-Z0-9_.-]+ 的正則表示式格式。

services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

pull_policy

pull_policy 定義 Compose 在開始拉取映象時做出的決定。可能的值是

always：Compose 始終從登錄檔拉取映象。
never：Compose 不會從登錄檔拉取映象，而是依賴於平臺快取的映象。如果沒有快取的映象，則會報告錯誤。
missing：Compose 僅在平臺快取中沒有映象時才會拉取映象。如果您沒有使用 Compose 構建規範，這是預設選項。if_not_present 被認為是此值的別名，為了向後相容。
build：Compose 構建映象。如果映象已經存在，Compose 會重建映象。

read_only

read_only 配置服務容器以只讀檔案系統建立。

restart

restart 定義平臺在容器終止時應用的策略。

no：預設重啟策略。它在任何情況下都不會重啟容器。
always：此策略始終重啟容器，直到將其刪除。
on-failure[:max-retries]：如果退出程式碼表示錯誤，則此策略會重啟容器。可選地，限制 Docker 守護程序嘗試的重啟重試次數。
unless-stopped：此策略會重啟容器，無論退出程式碼如何，但當服務停止或刪除時停止重啟。

    restart: "no"
    restart: always
    restart: on-failure
    restart: on-failure:3
    restart: unless-stopped

您可以在 Docker run 參考頁面重啟策略（--restart）部分找到有關重啟策略的更詳細的資訊。

runtime

runtime 指定用於服務的容器的執行時。

例如，runtime 可以是 OCI 執行時規範的實現的名稱，例如 "runc"。

web:
  image: busybox:latest
  command: true
  runtime: runc

預設值為 runc。要使用其他執行時，請參閱替代執行時。

scale

scale 指定為該服務部署的容器的預設數量。當兩者都設定時，scale 必須與部署規範中的 replicas 屬性一致。

secrets

secrets 屬性允許服務訪問由 Compose 檔案頂級元素定義的敏感資料。服務可以被授權訪問多個 secrets。

Compose 支援兩種不同的語法變體：短語法和長語法。Compose 檔案中可以同時使用長語法和短語法。

如果 secret 在平臺上不存在或未在 Compose 檔案的 secrets 頂級部分中定義，Compose 會報告錯誤。

在頂級 secrets 中定義一個 secret 並不意味著授權任何服務訪問它。這種授權必須在服務規範中作為 secrets 服務元素明確指定。

簡短語法

短語法變體只指定 secret 名稱。這會授予容器訪問 secret 的許可權，並將它以只讀方式掛載到容器中的 /run/secrets/<secret_name>。源名稱和目標掛載點都設定為 secret 名稱。

以下示例使用短語法授予 frontend 服務訪問 server-certificate secret 的許可權。server-certificate 的值設定為檔案 ./server.cert 的內容。

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

長語法

長語法提供更細粒度的控制，可以自定義 secret 在服務容器中的建立方式。

source：secret 在平臺上的名稱。
target：在服務任務容器的 /run/secrets/ 中掛載的檔名，或者如果需要使用其他位置，則為檔案的絕對路徑。如果未指定，則預設為 source。
uid 和 gid：在服務任務容器的 /run/secrets/ 中擁有該檔案的數字 UID 或 GID。預設值為執行容器的 USER。
mode：在服務任務容器的 /run/secrets/ 中掛載檔案的許可權，以八進位制表示。預設值為世界可讀許可權（模式 0444）。如果設定了可寫位，則必須忽略它。可以設定可執行位。

以下示例將 server-certificate secret 檔案的名稱設定為容器中的 server.cert，將模式設定為 0440（組可讀），並將使用者和組設定為 103。server-certificate 的值設定為檔案 ./server.cert 的內容。

services:
  frontend:
    image: example/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0440
secrets:
  server-certificate:
    file: ./server.cert

security_opt

security_opt 覆蓋每個容器的預設標籤方案。

security_opt:
  - label:user:USER
  - label:role:ROLE

有關可以覆蓋的其他預設標籤方案，請參閱安全配置.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

預設值為 10 秒，容器在傳送 SIGKILL 之前退出。

stop_signal

stop_signal 定義 Compose 用於停止服務容器的訊號。如果未設定，Compose 透過傳送 SIGTERM 停止容器。

stop_signal: SIGUSR1

storage_opt

storage_opt 定義服務的儲存驅動程式選項。

storage_opt:
  size: '1G'

sysctls

sysctls 定義要在容器中設定的核心引數。sysctls 可以使用陣列或對映。

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

你只能使用核心中已名稱空間的 sysctls。Docker 不支援更改容器內的 sysctls，這些 sysctls 也會修改主機系統。有關支援的 sysctls 的概述，請參閱在執行時配置名稱空間核心引數 (sysctls).

tmpfs

tmpfs 在容器內掛載一個臨時檔案系統。它可以是單個值或列表。

tmpfs: /run

tmpfs:
  - /run
  - /tmp

tty

tty 配置服務容器以使用 TTY 執行。這與使用 -t 或 --tty 標誌執行容器相同。有關更多資訊，請參閱分配偽終端.

支援的值為 true 或 false。

ulimits

ulimits 覆蓋容器的預設 ulimits。它以整數形式指定單個限制，或者以對映形式指定軟限制/硬限制。

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

user

user 覆蓋用於執行容器程序的使用者。預設值由映像設定（例如 Dockerfile 的 USER）。如果沒有設定，則為 root。

userns_mode

userns_mode 設定服務的使用者名稱空間。支援的值特定於平臺，可能取決於平臺配置。

userns_mode: "host"

uts

在 Docker Compose 版本 2.15.1 中引入。

uts 配置為服務容器設定的 UTS 名稱空間模式。當未指定時，如果支援，則由執行時決定是否分配 UTS 名稱空間。可用值為

'host'：導致容器使用與主機相同的 UTS 名稱空間。

    uts: "host"

volumes

volumes 屬性定義服務容器可以訪問的掛載主機路徑或命名卷。可以使用 volumes 定義多種型別的掛載：volume、bind、tmpfs 或 npipe。

如果掛載是主機路徑，並且只被單個服務使用，則可以將其宣告為服務定義的一部分。要跨多個服務重用卷，必須在 volumes 頂級元素中宣告命名卷。

以下示例展示了 backend 服務使用的命名卷 (db-data)，以及為單個服務定義的繫結掛載。

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

有關 volumes 頂級元素的更多資訊，請參閱卷.

簡短語法

短語法使用帶冒號分隔值的單個字串來指定卷掛載 (VOLUME:CONTAINER_PATH)，或訪問模式 (VOLUME:CONTAINER_PATH:ACCESS_MODE)。

VOLUME：可以是託管容器的平臺上的主機路徑（繫結掛載）或卷名稱。
CONTAINER_PATH：在容器中掛載卷的路徑。
ACCESS_MODE：用逗號分隔的 , 選項列表
- rw：讀寫訪問。如果未指定，則為預設值。
- ro：只讀訪問。
- z：SELinux 選項，指示繫結掛載主機內容在多個容器之間共享。
- Z：SELinux 選項，指示繫結掛載主機內容是私有的，不與其他容器共享。

注意
SELinux 重新標記繫結掛載選項在沒有 SELinux 的平臺上會被忽略。

注意相對主機路徑只受部署到本地容器執行時的 Compose 支援。這是因為相對路徑是從 Compose 檔案的父目錄解析的，這僅適用於本地情況。當 Compose 部署到非本地平臺時，它會拒絕使用相對主機路徑的 Compose 檔案，並顯示錯誤。為了避免與命名卷的歧義，相對路徑應始終以 . 或 .. 開頭。

長語法

長形式語法允許配置在簡短形式中無法表達的其他欄位。

type：掛載型別。可以是 volume、bind、tmpfs、npipe 或 cluster
source：掛載的來源，對於繫結掛載，是主機上的路徑，或者是在頂級 volumes 鍵中定義的卷的名稱。不適用於 tmpfs 掛載。
target：在容器中掛載卷的路徑。
read_only：將卷設定為只讀的標誌。
bind：用於配置其他繫結選項
- propagation：用於繫結的傳播模式。
- create_host_path：如果主機上的源路徑不存在，則建立一個目錄。如果路徑上存在內容，Compose 不會執行任何操作。為了向後相容 docker-compose 遺留，這由短語法自動隱式實現。
- selinux：SELinux 重新標記選項 z（共享）或 Z（私有）
volume：配置其他卷選項
- nocopy：標誌，用於在建立卷時停用從容器複製資料。
- subpath：卷內的路徑，用於掛載，而不是卷的根目錄。
tmpfs：配置其他 tmpfs 選項
- size：tmpfs 掛載的大小，以位元組為單位（可以是數字或位元組單位）。
- mode：tmpfs 掛載的檔案模式，以 Unix 許可權位表示，用八進位制數表示。在 Docker Compose 版本 2.14.0 中引入。
consistency：掛載的一致性要求。可用值特定於平臺。

提示
使用大型倉庫或單體倉庫，或者使用不再隨著程式碼庫擴充套件的虛擬檔案系統？Compose 現在利用了同步檔案共享，並自動為繫結掛載建立檔案共享。確保你已使用付費訂閱登入 Docker，並在 Docker Desktop 的設定中啟用“訪問實驗性功能”和“使用 Compose 管理同步檔案共享”。

volumes_from

volumes_from 掛載來自另一個服務或容器的所有卷。可以選擇指定只讀訪問 ro 或讀寫訪問 rw。如果未指定訪問級別，則使用讀寫訪問。

你還可以使用 container: 字首從 Compose 不管理的容器中掛載卷。

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir 覆蓋容器的工作目錄，該目錄由映像指定，例如 Dockerfile 的 WORKDIR。