在 Docker Compose 中定義服務

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

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

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

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

示例

簡單示例

以下示例演示瞭如何定義兩個簡單服務，設定它們的映象，對映埠，並使用 Docker Compose 配置基本的環境變數。

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb

高階示例

在以下示例中，proxy 服務使用 Nginx 映象，將本地 Nginx 配置檔案掛載到容器中，暴露埠 80 並依賴於 backend 服務。

backend 服務從 backend 目錄中位於 builder 階段的 Dockerfile 構建映象。

services:
  proxy:
    image: nginx
    volumes:
      - type: bind
        source: ./proxy/nginx.conf
        target: /etc/nginx/conf.d/default.conf
        read_only: true
    ports:
      - 80:80
    depends_on:
      - backend

  backend:
    build:
      context: backend
      target: builder

有關更多 Compose 檔案示例，請瀏覽 Awesome Compose 示例。

屬性

annotations

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

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

attach

當定義 attach 並將其設定為 false 時，Compose 不會收集服務日誌，直到您明確請求。

預設服務配置為 attach: true。

build

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

blkio_config

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

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_count

cpu_count 定義服務容器可用的 CPU 數量。

cpu_percent

cpu_percent 定義可用 CPU 的可用百分比。

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

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

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

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

注意

與 Dockerfile 中的 CMD 指令不同，command 欄位不會自動在映象中定義的 SHELL 指令的上下文中執行。如果您的 command 依賴於 shell 特定的功能，例如環境變數擴充套件，您需要明確地在 shell 中執行它。例如

command: /bin/sh -c 'echo "hello $$HOSTNAME"'

該值也可以是列表，類似於 Dockerfile 使用的 exec-form 語法。

configs

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 容器，則可以將 file: 和 registry: 協議用於 credential_spec。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: 指定在啟動依賴服務之前，依賴項應處於“健康”狀態（由 healthcheck 指示）。
  • 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 Deploy 規範中所定義。

develop

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"

devices 還可以依賴 CDI 語法，讓容器執行時選擇裝置

devices:
  - "vendor1.com/device=gpu"

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

driver_opts 指定要傳遞給驅動程式的鍵值對選項列表。這些選項依賴於驅動程式。

services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.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

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

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

env_file 也可以是列表。列表中的檔案從上到下處理。對於在兩個環境變數檔案中指定的同一變數，列表中的最後一個檔案中的值有效。

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

格式

format 屬性允許您為 env_file 使用備用檔案格式。如果未設定，env_file 將根據 Env_file 格式中概述的 Compose 規則進行解析。

raw 格式允許您使用包含 key=value 項的 env_file，但 Compose 不會嘗試解析該值進行插值。這允許您按原樣傳遞值，包括引號和 $ 符號。

env_file:
  - path: ./default.env
    format: raw

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、networks、configs、secrets、links、volumes_from 或 depends_on 等屬性顯式定義。或者，依賴項可以在名稱空間宣告（如 ipc、pid 或 network_mode）中使用 service:{name} 語法引用另一個服務。

Compose 不會自動將這些引用的資源匯入到擴充套件模型中。您有責任確保所有必需的資源都在依賴 extends 的模型中明確宣告。

不支援 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 形式設定附加主機的主機名和 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 可以設定為主機名和 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

gpus

gpus 指定要為容器使用分配的 GPU 裝置。這等同於具有隱式 gpu 功能的 裝置請求。

services:
  model:
    gpus:
      - driver: 3dfx
        count: 2

gpus 也可以設定為字串 all，以將所有可用的 GPU 裝置分配給容器。

services:
  model:
    gpus: all

group_add

group_add 指定使用者在容器內必須是其成員的額外組（按名稱或編號）。

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

services:
  myservice:
    image: alpine
    group_add:
      - mail

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

healthcheck

healthcheck 屬性宣告一個檢查，用於確定服務容器是否“健康”。它的工作方式與 HEALTHCHECK Dockerfile 指令相同，並且具有與 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 必須遵循開放容器規範 可定址映象格式，格式為 [<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 部分，就可以從 Compose 檔案中省略 image。如果您不使用 Compose 構建規範，如果 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 檔案中指定帶有此字首的標籤會導致執行時錯誤。

label_file

label_file 屬性允許您從外部檔案或檔案列表載入服務的標籤。這提供了一種方便的方式來管理多個標籤，而無需使 Compose 檔案混亂。

該檔案使用鍵值格式，類似於 env_file。您可以將多個檔案指定為列表。當使用多個檔案時，它們按照在列表中出現的順序進行處理。如果在多個檔案中定義了相同的標籤，則列表中最後一個檔案中的值將覆蓋較早的值。

services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels

如果標籤在 label_file 和 labels 屬性中都定義，則 labels 中的值優先。

links

links 定義到另一個服務中容器的網路連結。既可以指定服務名稱和連結別名 (SERVICE:ALIAS)，也可以只指定服務名稱。

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

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

不需要連結即可使服務進行通訊。當未設定特定網路配置時，任何服務都可以在 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，則容器被允許使用無限量的交換，直至主機系統上可用的量。

models

models 定義服務在執行時應使用的 AI 模型。每個引用的模型必須在 models 頂級元素下定義。

services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

當服務連結到模型時，Docker Compose 會注入環境變數，以將連線詳細資訊和模型識別符號傳遞給容器。這允許應用程式在執行時動態定位並與模型通訊，而無需硬編碼值。

長語法

長語法讓您可以更好地控制環境變數名稱。

• endpoint_var 設定儲存模型執行器 URL 的環境變數的名稱。
• model_var 設定儲存模型識別符號的環境變數的名稱。

如果兩者之一被省略，Compose 會根據模型鍵使用以下規則自動生成環境變數名稱

• 將模型鍵轉換為大寫
• 將所有 '-' 字元替換為 '_'
• 為端點變數附加 _URL

network_mode

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

• none: 關閉所有容器網路。
• host: 授予容器對主機網路介面的原始訪問許可權。
• service:{name}: 授予容器透過引用其服務名稱訪問指定容器的許可權。
• container:{name}: 授予容器透過引用其容器 ID 訪問指定容器的許可權。

有關容器網路的更多資訊，請參閱 Docker Engine 文件。

    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 頂級元素的更多資訊，請參閱 網路。

隱式預設網路

如果 networks 在 Compose 檔案中為空或缺失，Compose 會為服務定義一個隱式定義，即連線到 default 網路

services:
  some-service:
    image: foo

此示例實際上等同於

services:
  some-service:
    image: foo
    networks:
      default: {}

如果您希望服務不連線到網路，則必須設定 network_mode: none。

別名

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: {}

interface_name

interface_name 允許您指定用於將服務連線到給定網路的網路介面的名稱。這確保了跨服務和網路的一致且可預測的介面命名。

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

執行示例 Compose 應用程式顯示

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

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

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

driver_opts

driver_opts 指定一個選項列表，作為鍵值對傳遞給驅動程式。這些選項是驅動程式特定的。請查閱驅動程式的文件以獲取更多資訊。

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

gw_priority

具有最高 gw_priority 的網路被選為服務容器的預設閘道器。如果未指定，預設值為 0。

在以下示例中，app_net_2 將被選為預設閘道器。

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

priority

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

如果容器執行時接受服務級別的 mac_address 屬性，則它將應用於具有最高 priority 的網路。在其他情況下，請使用屬性 networks.mac_address。

priority 不影響哪個網路被選為預設閘道器。請改用 gw_priority 屬性。

priority 不控制網路連線新增到容器的順序，它不能用於確定容器中的裝置名稱 (eth0 等)。

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 調整容器的 PID 限制。設定為 -1 表示無限 PID。

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 一起使用。這樣做會導致執行時錯誤，因為 network_mode: host 已經直接將容器埠暴露給主機網路，因此不需要埠對映。

短語法

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

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

• HOST 是 [IP:](port | range)（可選）。如果未設定，它將繫結到所有網路介面 (0.0.0.0)。
• CONTAINER 是 port | range。
• PROTOCOL 將埠限制為指定協議 tcp 或 udp（可選）。預設為 tcp。

埠可以是單個值或範圍。HOST 和 CONTAINER 必須使用等效的範圍。

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

HOST:CONTAINER 應始終指定為（帶引號的）字串，以避免與 YAML base-60 float 衝突。

IPv6 地址可以括在方括號中。

示例

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"
  - "::1:6000:6000"
  - "[::1]:6001:6001"
  - "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：指定埠在 Swarm 設定中如何釋出。如果設定為 host，則在 Swarm 中的每個節點上釋出埠。如果設定為 ingress，則允許在 Swarm 中的節點之間進行負載均衡。預設為 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

post_start

post_start 定義容器啟動後執行的一系列生命週期鉤子。命令執行的確切時間不作保證。

• command：指定容器啟動後要執行的命令。此屬性是必需的，您可以選擇使用 shell 形式或 exec 形式。
• user：執行命令的使用者。如果未設定，則命令以與主服務命令相同的使用者身份執行。
• privileged：允許 post_start 命令以特權訪問執行。
• working_dir：執行命令的工作目錄。如果未設定，則在與主服務命令相同的工作目錄中執行。
• environment：專門為 post_start 命令設定環境變數。雖然該命令繼承了為服務主命令定義的環境變數，但此部分允許您新增新變數或覆蓋現有變數。

services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

有關更多資訊，請參閱 使用生命週期鉤子。

pre_stop

pre_stop 定義容器停止前執行的一系列生命週期鉤子。如果容器自行停止或突然終止，這些鉤子將不會執行。

配置等同於 post_start。

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

provider

provider 可用於定義 Compose 不直接管理的服務。Compose 將服務生命週期委託給專用或第三方元件。

  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        foo: bar
  app:
    image: myapp
    depends_on:
       - database

當 Compose 執行應用程式時，awesomecloud 二進位制檔案用於管理 database 服務的設定。依賴服務 app 接收以服務名稱為字首的額外環境變數，以便它可以訪問資源。

為了說明，假設 awesomecloud 執行產生了變數 URL 和 API_KEY，則 app 服務使用環境變數 DATABASE_URL 和 DATABASE_API_KEY 執行。

當 Compose 停止應用程式時，awesomecloud 二進位制檔案用於管理 database 服務的拆卸。

Compose 將服務生命週期委託給外部二進位制檔案的機制在此處描述：here。

有關使用 provider 屬性的更多資訊，請參閱 使用提供程式服務。

type

type 屬性是必需的。它定義了 Compose 用於管理設定和拆卸生命週期事件的外部元件。

options

options 特定於所選提供程式，並且未經驗證 Compose 規範

pull_policy

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

• always：Compose 始終從登錄檔拉取映象。
• never：Compose 不從登錄檔拉取映象，並依賴平臺快取的映象。如果沒有快取的映象，則報告失敗。
• missing：Compose 僅在平臺快取中不可用時才拉取映象。如果您不使用 Compose 構建規範，這是預設選項。if_not_present 被視為此值的別名以實現向後相容性。
• build：Compose 構建映象。如果映象已存在，Compose 會重建映象。
• daily：如果上次拉取發生在 24 小時之前，Compose 會檢查登錄檔是否有映象更新。
• weekly：如果上次拉取發生在 7 天之前，Compose 會檢查登錄檔是否有映象更新。
• every_<duration>：如果上次拉取發生在 <duration> 之前，Compose 會檢查登錄檔是否有映象更新。持續時間可以用周 (w)、天 (d)、小時 (h)、分鐘 (m)、秒 (s) 或它們的組合表示。

services:
  test:
    image: nginx
    pull_policy: every_12h

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 執行參考頁面的 重啟策略 (--restart) 部分找到有關重啟策略的更詳細資訊。

runtime

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

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

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

預設值為 runc。要使用不同的執行時，請參閱 備用執行時。

scale

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

secrets

secrets 屬性以每個服務為基礎授予對由 secrets 頂級元素定義的敏感資料的訪問許可權。服務可以被授予對多個 secrets 的訪問許可權。

支援兩種不同的語法變體；短語法和長語法。secrets 的長短語法可以在同一個 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：秘密在平臺上存在的名稱。
• target：要掛載到服務任務容器中 /run/secrets/ 的檔名，如果需要備用位置，則為檔案的絕對路徑。如果未指定，預設為 source。
• uid 和 gid：擁有服務任務容器中 /run/secrets/ 檔案數值 uid 或 gid。預設值為 USER。
• mode：要掛載到服務任務容器中 /run/secrets/ 檔案的 許可權，採用八進位制表示法。預設值是全域性可讀許可權（模式 0444）。如果設定了可寫位，則必須忽略它。可執行位可以設定。

請注意，當 secret 的來源是 file 時，Docker Compose 不支援 uid、gid 和 mode 屬性。這是因為底層使用的繫結掛載不允許 uid 重新對映。

以下示例將 server-certificate 秘密檔案的名稱設定為容器中的 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: 0o440
secrets:
  server-certificate:
    file: ./server.cert

security_opt

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

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

有關您可以覆蓋的更多預設標籤方案，請參閱 安全配置。

shm_size

shm_size 配置服務容器允許的共享記憶體大小（Linux 上的 /dev/shm 分割槽）。它以 位元組值 指定。

stdin_open

stdin_open 配置服務容器以分配的 stdin 執行。這與使用 -i 標誌執行容器相同。有關更多資訊，請參閱 保持 stdin 開啟。

支援的值為 true 或 false。

stop_grace_period

stop_grace_period 指定當容器不處理 SIGTERM（或使用 stop_signal 指定的任何停止訊號）時，Compose 在傳送 SIGKILL 之前應等待多長時間。它以 持續時間 指定。

    stop_grace_period: 1s
    stop_grace_period: 1m30s

預設值是容器在傳送 SIGKILL 之前退出需要等待 10 秒。

stop_signal

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

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)。

tmpfs

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

tmpfs:
 - <path>
 - <path>:<options>

• path：tmpfs 將掛載到容器內的路徑。
• options：tmpfs 掛載選項的逗號分隔列表。

可用選項

• mode：設定檔案系統許可權。
• uid：設定擁有掛載 tmpfs 的使用者 ID。
• gid：設定擁有掛載 tmpfs 的組 ID。

services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

tty

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

支援的值為 true 或 false。

ulimits

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

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

use_api_socket

當設定 use_api_socket 時，容器能夠透過 API socket 與底層容器引擎進行互動。您的憑據被掛載到容器內部，因此容器作為您的命令的純粹委託，與容器引擎相關。通常，容器執行的命令可以 pull 和 push 到您的登錄檔。

user

user 覆蓋用於執行容器程序的使用者。預設由映象設定，例如 Dockerfile USER。如果未設定，則為 root。

userns_mode

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

userns_mode: "host"

uts

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 檔案並報錯。為避免與命名卷產生歧義，相對路徑應始終以 . 或 .. 開頭。

注意

對於繫結掛載，如果源路徑在主機上不存在，短語法會在該路徑建立目錄。這是為了向後相容舊版 docker-compose。透過使用長語法並將 create_host_path 設定為 false 可以防止這種情況。

長語法

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

• type：掛載型別。可以是 volume、bind、tmpfs、image、npipe 或 cluster
• source：掛載的來源，對於繫結掛載是主機上的路徑，對於映象掛載是 Docker 映象引用，或者是 頂級 volumes 鍵 中定義的卷名稱。不適用於 tmpfs 掛載。
• target：卷在容器中掛載的路徑。
• read_only：將卷設定為只讀的標誌。
• bind：用於配置額外的繫結選項
  • propagation：繫結使用的傳播模式。
  • create_host_path：如果主機上沒有內容，則在源路徑建立目錄。預設為 true。
  • selinux：SELinux 重新標記選項 z（共享）或 Z（私有）
• volume：配置額外的卷選項
  • nocopy：停用在建立卷時從容器複製資料的標誌。
  • subpath：要掛載的卷內的路徑，而不是卷根目錄。
• tmpfs：配置額外的 tmpfs 選項
  • size：tmpfs 掛載的大小（以位元組為單位，可以是數字或位元組單位）。在 Docker Compose 2.14.0 版本中引入。
  • mode：tmpfs 掛載的檔案模式，作為八進位制數字的 Unix 許可權位。在 Docker Compose 2.14.0 版本中引入。
• image：配置額外的映象選項
  • subpath：要掛載的源映象內的路徑，而不是映象根目錄。在 Docker Compose 版本 2.35.0 中可用
• consistency：掛載的一致性要求。可用值是平臺特定的。

提示

是否正在使用大型倉庫或 monorepos，或者檔案系統不再與您的程式碼庫一起擴充套件？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。