Docker Compose配置文件詳解（V3）

Docker Compose配置文件是Docker Compose的核心，用於定義服務、網絡和數據卷。格式為YAML，默認路徑為./docker-compose.yml，可以使用.yml或.yaml擴展名，目前Compose配置文件格式的最新版本為V3。Compose配置文件中涉及的配置項也比較多，但大部分配置項的含義跟docker run命令相關選項是類似的。

本文主要參考官方文檔對目前最新的V3版Compose配置文件進行一個總結。都是一些概念性的內容，不涉及具體操作。

一、Compose配置文件版本

這里主要對Compose配置文件的版本的相關要點進行一個簡單的總結。至於每個版本具體的變化和升級信息可以參考官方的Compose配置文件版本與升級指南。

1.Compose配置文件格式的版本概述

當前有三種版本的Compose配置文件格式：

• Version 1：

  • 舊版格式，通過省略YAML的根配置項version來指定。
  • 未聲明版本的Compose配置文件都被視為V1版，所有的服務都作為根選項在Compose配置文件中聲明。
  • 支持V1的Compose最高到1.6.x，再高版本的Compose不推薦使用V1版Compose配置文件。
  • 不支持數據卷、網絡和構建參數配置。
  • V1的Compose不會利用網絡優勢，每個容器都位於默認的bridge網絡上，並且可以從其他容器的IP地址訪問，需要使用links來啟用容器之間的發現。

• Version 2.x：

  • 通過YAML的根配置項version來指定，具體配置如version: '2'或version: '2.1'等。
  • 必須在Compose配置文件根選項指定版本號，並且主版本數字為2，且所有服務必須在services配置項下聲明。
  • 1.6.0+版本的Compose都支持V2，Docker Engine的版本需要1.10.0+版本。
  • 支持數據卷和網絡的配置。
  • 默認情況下，每個容器都加入了應用范圍的默認網絡，並且可以在與服務名稱相同的主機名下發現。很大程度上links不是必要的。
  • V2中加入了環境變量替換。

• Version 3.x：

  • 最新版本，也是推薦使用版本，推出該版的目的是為了在Compose和Docker Engine的swarm模式之間形成交叉兼容。
  • 通過YAML的根配置項version來指定，具體配置如version: '3'或version: '3.1'等。
  • V3刪除了多個配置項，但也新增了更多配置項。

關於Compose配置文件版本的常見注意事項：

• 在聲明V2和V3版本時需注意：

  • 在指定Compose配置文件要使用的版本時，需同時指定主版本數字和次版本數字。如果未給定次版本數字，則默認使用0而不是最新版本，因此將不支持再更高版本中才加入的新功能。比如version: '3'，使用的是3.0版本而不是目前最新的3.8版本。

• 在使用多Compose配置文件時需注意：

  • 使用多個Compose配置文件擴展服務時，每個文件必須為相同的版本。

2.Compose配置文件格式版本與Docker的兼容性關系

Compose配置文件格式具有多種版本。其中Compose配置文件格式版本與Docker的兼容性關系如下表所示：

Compose配置文件格式版本 Docker Engine版本
3.8 19.03.0+
3.7 18.06.0+
3.6 18.02.0+
3.5 17.12.0+
3.4 17.09.0+
3.3 17.06.0+
3.2 17.04.0+
3.1 1.13.1+
3.0 1.13.0+
2.4 17.12.0+
2.3 17.06.0+
2.2 1.13.0+
2.1 1.12.0+
2.0 1.10.0+
1.0 1.9.1.+

如果使用的較舊版本的Docker，可以參考官方的Compose版本發布列表。其中的每組發行說明都詳細說明了支持的Docker Engine版本和兼容的Compose配置文件格式版本。

3.兼容模式

在1.20.0版本，Compose在docker-compose命令中引入了一個新的選項--compatibility，目的在於幫助開發人員更輕松地過渡到V3版。啟用該選項后，docker-compose命令會讀取每個服務定義的deploy部分，並嘗試將其轉換為等效的V2配置項。目前，以下deploy下的配置項已被轉換：

• resources下的limits和reservations下的memory
• replicas
• restart_policy下的 condition 和max_attempts

所有的其他配置項都將被忽略，如果這些被忽略的配置項存在則會發出一個警告。可以使用帶--compatibility的Config命令查看將用於deploy的配置。

注意請勿在生成環境使用兼容模式！
建議不要在生產環境中使用--compatibility選項。由於使用非Swarm模式屬性生成的配置僅是近似值，因此可能會產生意外的結果。

二、Compose配置文件結構

Docker Compose配置文件是一個用於定義服務、網絡和數據卷的YAML文件。其中服務定義了該服務啟動的每個容器的配置，就像將命令行參數傳遞給docker run一樣，網絡和數據卷的定義類似於docker network create和docker volume create。跟docker run一樣，如果在Dockerfile中通過諸如CMD、EXPOSE、VOLUME和ENV這些指令指定了相關選項，那么在默認情況下，不需要在docker-compose.yml中再次指定它們。下面是從官網引過來的一個Compose配置文件的示例，可以先大致了解一下它的結構：

version: "3.8"
services:

  redis:
    image: redis:alpine
    ports:
      - "6379"
    networks:
      - frontend
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints:
          - "node.role==manager"

  vote:
    image: dockersamples/examplevotingapp_vote:before
    ports:
      - "5000:80"
    networks:
      - frontend
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
      restart_policy:
        condition: on-failure

  result:
    image: dockersamples/examplevotingapp_result:before
    ports:
      - "5001:80"
    networks:
      - backend
    depends_on:
      - db
    deploy:
      replicas: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 1
      labels: [APP=VOTING]
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
        window: 120s
      placement:
        constraints:
          - "node.role==manager"

  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    stop_grace_period: 1m30s
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints:
          - "node.role==manager"

networks:
  frontend:
  backend:

volumes:
  db-data:

頂層的version、services、networks和volumes將Compose配置文件分為四個部分，其中version指定Compose配置文件的版本，services定義服務，networks定義網絡，volumes定義數據卷。

三、服務配置

服務定義了該服務啟動的每個容器的配置，就像將命令行參數傳遞給docker run一樣。比如以下配置：

services:
  redis:
    image: redis:alpine

services下的redis是用戶自定義的服務名稱，redis下的image只是眾多服務配置項中的其中一個，意思是指定鏡像名稱或id。下面就對服務的相關配置項進行一個總結。

1.build

在構建時應用的配置項。一般直接指定Dockerfile所在文件夾路徑，可以是絕對路徑，或者相對於Compose配置文件的路徑。可以指定為包含構建上下文（context）路徑的字符串。例如：

version: "3.8"
services:
  webapp:
    build: ./dir

也可以使用context指定上下文路徑，使用dockerfile基於上下文路徑指定Dockerfile文件，使用args指定構建參數。例如：

version: "3.8"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

如果同時指定了build和image。例如：

build: ./dir
image: webapp:tag

Compose會在./dir目錄下構建一個名為webapp，標簽為tag的鏡像。

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，build配置項被忽略。因為docker stack命令不會在部署之前構建鏡像。

(1)context

指定包含Dockerfile的目錄路徑或git倉庫url。該目錄是發送給Docker守護進程（Daemon）的構建上下文（context）。當配置的值是相對路徑時，它將被解釋為相對於Compose配置文件的路徑。例如：

build:
  context: ./dir

指定上下文為Compose配置文件目錄下的dir目錄。

(2)dockerfile

指定Dockerfile文件。Compose會使用指定的Dockerfile文件構建鏡像，但必須要指定構建上下文路徑。例如：

build:
  context: .
  dockerfile: Dockerfile-alternate

Compose會使用Compose配置文件所在目錄下名為Dockerfile-alternate的Dockerfile文件構建鏡像。

(3)args

添加構建參數，這些只能在構建過程中訪問的環境變量。首先在Dockerfile文件中指定參數：

ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

然后build中指定參數，以下兩種寫法都可以：

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

這時構建過程中使用的參數的值為args指定的值。在指定構建參數時也可以不指定值，在這種情況下，構建過程中使用的參數的值為運行Compose的環境中的值。例如：

args:
  - buildno
  - gitcommithash

使用布爾值時的注意事項：YMAL中布爾類型的值（"true"、"false"、"yes"、"no"、"on"、"off"）必須用引號引起來，以便解析器將它們解釋為字符串。

(4)cache_from

在3.2版的配置文件格式中加入

指定緩存解析鏡像列表。例如：

build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14

(5)labels

在3.3版的配置文件格式中加入

將元數據以標簽的形式添加到生成的鏡像中。可以使用數組或字典兩種格式。推薦使用反向DNS寫法以避免和其他應用的標簽沖突。例如：

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

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

(6)network

在3.4版的配置文件格式中加入

設置容器網絡連接以獲取構建過程中的RUN指令。例如：

build:
  context: .
  network: custom_network_1

設置為none可以在構建期間禁用網絡連接。例如：

build:
  context: .
  network: none

(7)shm_size

在3.5版的配置文件格式中加入

指定容器的/dev/shm分區大小。指定的值為表示字節數的整數值或表示字節值的字符串。例如：

build:
  context: .
  shm_size: 10000000

build:
  context: .
  shm_size: '2gb'

(8)target

在3.4版的配置文件格式中加入

指定在Dockerfile中定義的構建階段，即鏡像只構建到指定階段就停止構建。例如：

build:
  context: .
  target: prod

指定構建階段為prod，即鏡像只構建到prod階段，prod階段之后的內容不會被構建。

2.cap_add、cap_drop

添加或刪除容器內核能力（capability）。完整的capability列表可查看man 7 capabilities。例如，讓容器擁有所有內核能力：

cap_add:
  - ALL

例如，刪除NET_ADMIN和SYS_ADMIN能力：

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，cap_add和cap_drop配置項將被忽略。

3.cgroup_parent

為容器指定一個可選的父控制組。例如：

cgroup_parent: m-executor-abcd

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，cgroup_parent配置項將被忽略。

4.command

覆蓋容器啟動后默認執行的命令。可以寫成字符串形式。例如：

command: bundle exec thin -p 3000

也可以寫成JSON數組形式。例如：

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

5.configs

在3.3版的配置文件格式中加入

為每個服務授予對配置（configs）的訪問權限。支持short和long兩種格式的語法。更多configs信息，參考configs。

注意：該配置（config）必須已存在或者在堆棧文件頂層configs配置項中定義，否則堆棧部署將失敗。

short語法僅指定config名稱來授予容器訪問config的權限並將其掛載到容器的/<config_name>上。source名稱和目標掛載點都設置為config名稱。例如以下示例，授予了redis服務對configs的my_config和my_other_config的訪問權限，其中my_config的值設置到文件./my_config.txt的內容中，my_other_config定義為外部資源，這意味着它已經在Docker中通過運行docker config create命令或其他堆棧部署進行定義，如果外部config不存在，堆棧部署將會失敗並顯示config not found錯誤：

version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

long語法提供了在服務的任務容器內如何創建config的更多粒度：

• source：Docker中存在的config名稱。
• target：指定要掛載到服務的任務容器的文件的路徑加名稱。如果未指定，默認為/。
• uid和gid：指定服務的任務容器所擁有的該文件的UID或GID。如果在LInux中未指定，兩者都默認為0。不支持Windows。
• mode：以八進制表示法指定要掛載到服務的任務容器的文件權限。例如，0444代表可讀。默認值就為0444。config內容已掛載到臨時文件系統中，所以不可寫，如果設置了可寫位將被忽略。可以設置可執行位。如果不熟悉UNIX文件權限模式，可以使用權限計算器 。

例如以下示例，指定config名稱為my_config，授予redis服務對my_config的訪問權限，指定要掛載到redis服務的任務容器的路徑加文件名稱為/redis_config，指定UID和GID均為103，指定要掛載到服務的任務容器的文件權限為0440（group-readable），但該redis服務沒有訪問my_other_config的權限：

version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

可以授予服務訪問多個config的權限，並且可以混合long和short語法。定義config並不意味着授予服務對其的訪問權限。

6.container_name

指定自定義容器的名稱，而不是使用默認名稱。例如：

container_name: my-web-container

因為Docker容器的名稱必須唯一，所以為一個服務指定了自定義容器名稱后，該服務不能進行擴展。如果嘗試為該服務擴容將會導致錯誤。

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，container_name配置項將被忽略。

7.credential_spec

在3.3版的配置文件格式中加入
在3.8或更高版本文件格式中支持將組托管服務帳戶（GMSA）配置與Compose配置文件一起使用。

配置托管服務帳戶的憑據規格（credential spec）。此選項僅用於使用Windows容器的服務。credential_spec配置必須采用file:// 或registry:// 格式。使用file:時，引用的文件必須存在於Docker數據目錄的CredentialSpecs子目錄中，在Windows上，Docker數據目錄默認為C:\ProgramData\Docker\。以下示例從名為C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json的文件加載憑證規格：

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憑據規格時，只需用config指定憑據規格。例如：

version: "3.8"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

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

8.depends_on

指定服務之間的依賴關系，解決服務啟動先后順序問題。指定服務之間的依賴關系，將會導致以下行為：

• docker-compose up以依賴順序啟動服務。
• docker-compose up SERVICE會自動包含SERVICE的依賴項。
• docker-compose stop以依賴順序停止服務。

例如以下示例：

version: "3.8"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

啟動時會先啟動db和redis，最后才啟動web。在使用docker-compose up web啟動web時，也會啟動db和redis，因為在web服務中指定了依賴關系。在停止時也在web之前先停止db和redis。

使用depends_on時的注意事項：

• 服務不會等待該服務所依賴的服務完全啟動之后才啟動。例如上例，web不會等到db和redis完全啟動之后才啟動。
• V3版不再支持的condition形式的depends_on。
• V3版中，在swarm mode下部署堆棧時，depends_on配置項將被忽略。

9.deploy

在3版的配置文件格式中加入

指定部署和運行服務的相關配置。該配置僅在swarm mode下生效，並只能通過docker stack deploy命令部署，docker-compose up和docker-compose run命令將被忽略。例如：

version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

deploy配置項中包含endpoint_mode、labels、mode、placement、replicas、resources、restart_policy、update_config等子配置項。

(1)endpoint_mode

在3.2版的配置文件格式中加入

為外部客戶端連接到swarm指定服務發現方式：

• endpoint_mode: vip：Docker為服務分配了一個前端的虛擬IP，客戶端通過該虛擬IP訪問網絡上的服務。Docker在客戶端和服務的可用工作節點之間進行路由請求，而無須關系有多少節點正在參與該服務或這些節點的IP地址或者端口。這是默認設置。
• endpoint_mode: dnsrr：DNS輪詢（DNSRR），Docker設置服務的DNS條目，以便對服務名稱的DNS查詢返回IP地址列表，並且客戶端通過輪詢的方式直接連接到其中之一。

例如：

version: "3.8"
services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

(2)labels

指定服務的標簽。這些標簽僅在服務上設置，而不在服務的任何容器上設置。例如：

version: "3.8"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

(3)mode

指定服務的容器副本模式。可以為：

• global：每個swarm節點只有一個該服務容器。
• replicated：整個集群中存在指定份數的服務容器副本，為默認值。

例如，指定容器副本模式為global：

version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global

(4)placement

指定constraints和preferences。constraints可以指定只有符合要求的節點上才能運行該服務容器，preferences可以指定容器分配策略。例如，指定集群中只有滿足node.rolemanager和engine.labels.operatingsystemubuntu 18.04條件的節點上能運行db服務容器，並且在滿足node.labels.zone的節點上均勻分配：

version: "3.8"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone

(5)max_replicas_per_node

在3.8版的配置文件格式中加入

如果服務的容器副本模式為replicated（默認），可以指定每個節點上運行的最大容器副本數量。當指定的容器副本數量大於最大容器副本數量時，將引發no suitable node (max replicas per node limit exceed)錯誤。例如：

version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1

(6)replicas

如果服務的容器副本模式為replicated（默認），指定運行的容器副本數量。例如：

version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

(7)resources

配置資源限制。例如，指定redis服務使用的cpu份額為25%到50%，內存為20M到50M：

version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M

在V3版Compose配置文件中的改變：resources取代了V3版之前的Compose配置文件中舊的資源限制的配置項，包括cpu_shares、cpu_quota、cpuset、mem_limit、memswap_limit、mem_swappiness。
在非swarm mode容器上設置資源限制：此處的resources配置項只有用於deploy配置項之下和swarm mode。如果要在非swarm mode部署中設置資源限制，需使用V2版Compose配置文件中CPU、memory和其他資源的配置項。

(8)restart_policy

指定容器的重啟策略。代替restart。有以下配置選項：

• condition：重啟策略。值可以為none、on-failure或any，默認為any。
• delay：嘗試重啟的等待時間。指定為持續時間（durations）。默認值為0。
• max_attempts：重啟最多嘗試的次數，超過該次數將放棄。默認為永不放棄。如果在window配置的時間之內未成功重啟，則此次嘗試不計入max_attempts的值。
• window：在決定重啟是否成功之前的等待時間。指定為持續時間（durations）。默認值為立即決定。

例如，指定重啟策略為失敗時重啟，等待5s，重啟最多嘗試3次，決定重啟是否成功前的等待時間為120s：

version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

(9)rollback_config

在3.7版的配置文件格式中加入

配置在更新失敗的情況下如何回滾服務。有以下配置選項：

• parallelism：一次回滾的容器數量。如果設置為0，則所有容器同時回滾。
• delay：每個容器組之間的回滾所等待的時間。默認值為0s。
• failure_action：回滾失敗后的行為。有continue和pause兩種，默認值為pause。
• monitor：每次任務更新后監視失敗的時間（ns|us|ms|s|m|h）。默認值為0s。
• max_failure_ratio：在回滾期間能夠容忍的最大失敗率。默認值為0。
• order：設置回滾順序。stop-first為在開啟新任務之前停止舊任務，start-first為首先啟動新任務，和正在運行任務短暫重疊，默認值為stop-first。

(10)update_config

配置如何更新服務。該配置對滾動更新很有用。有以下配置選項：

• parallelism：一次更新的容器數量。
• delay：更新一組容器之間的等待時間。
• failure_action：更新失敗后的行為。有continue、rollback和pause三種，默認值為pause。
• monitor：每次任務更新后監視失敗的時間（ns|us|ms|s|m|h）。默認值為0s。
• max_failure_ratio：在更新期間能夠容忍的最大失敗率。
• order：設置更新順序。stop-first為在開啟新任務之前停止舊任務，start-first為首先啟動新任務，和正在運行任務短暫重疊，默認值為stop-first。注意該配置項在3.4版的配置文件格式中加入，僅支持3.4或更高版本。

例如，指定每次更新2個容器，更新等待時間10s，更新順序為先停止舊任務再開啟新任務：

version: "3.8"
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
        order: stop-first

(11)不支持docker stack deploy的配置項

以下為支持docker-compose up和docker-compose run，不支持docker stack deploy或deploy配置項的配置項：

• build
• cgroup_parent
• container_name
• devices
• tmpfs
• external_links
• links
• network_mode
• restart
• security_opt
• userns_mode

10.devices

指定設備映射列表。與Docker客戶端create的--device選項類似。例如：

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，devices配置選項將被忽略。

11.dns

自定義DNS服務器。可以是一個值或一個列表。例如：

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

12.dns_search

自定義DNS搜索域。可以是一個值或一個列表。例如：

dns_search: example.com

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

13.entrypoint

覆蓋默認的入口命令。注意設置entrypoint會覆蓋所有在服務鏡像上使用Dockerfile的ENTRYPOINT指令設置的默認入口命令，並清除掉服務鏡像上任何使用Dockerfile的CMD指令設置的啟動容器時默認執行的命令。可以寫成字符串形式，例如：

entrypoint: /code/entrypoint.sh

也可以寫成JSON數組形式，例如：

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

14.env_file

從文件中獲取環境變量。可以是一個值或一個列表。例如：

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env

如果指定了Compose配置文件，env_file路徑為相對於該文件所在目錄的路徑。如果環境文件中設置有與environment選項同名的變量，將以后者為准，無論這些變量的值是空還是未定義。其中環境文件每行都以VAR=VAL格式聲明環境變量，以#開頭的行被解析為注釋，和空行一樣將被忽略。環境文件示例如下：

# Set Rails/Rack environment
RACK_ENV=development

如果變量的值被引號引起來（通常是shell變量），則引號也包含在傳遞給Compose的值中。如果以列表的形式同時指定了多個環境文件，列表中文件的順序對於給多次出現的環境變量確定值十分重要，且列表中的文件是從上到下處理的。如果指定了多個環境文件且有至少兩個文件聲明了相同名稱但不同值的環境變量，那么指定列表中順序靠下的文件將覆蓋順序靠上的文件中的相同名稱的環境變量的值。例如：

services:
  some-service:
    env_file:
      - a.env
      - b.env

如果a.env中有VAR=1，b.env中有VAR=2，則最終$VAR=2。

注意：這里所說的環境變量是針對宿主機的Compose而言的，如果在服務中指定了build配置項，那么這些變量並不會進入構建過程中，如果要定義構建時用的環境變量首選build的arg子選項。

15.environment

設置環境變量。可以使用數組或字典兩種格式。任何布爾類型的值都必須用引號引起來，以便解析器將它們解釋為字符串。值設置了鍵沒設置值的環境變量可以在運行Compose的主機環境中解析它們的值，這對於使用密鑰和特定於主機的值用處很大。例如：

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

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

注意：這里所說的環境變量是針對宿主機的Compose而言的，如果在服務中指定了build配置項，那么這些變量並不會進入構建過程中，如果要定義構建時用的環境變量首選build的arg子選項。

16.expose

暴露指定端口，但不映射到宿主機，只被連接的服務訪問。只能指定內部端口。例如：

expose:
  - "3000"
  - "8000"

17.external_links

鏈接到docker-compose.yml外部的容器，甚至並非Compose管理的外部容器，特別是對於提供共享或公共服務的容器。在同時指定容器名稱和鏈接別名（CONTAINER:ALIAS）時，external_links與舊版本中的配置項links有類似的語義。例如：

external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql

注意：Compose項目里面的容器連接到外部容器的前提條件是外部容器中必須至少有一個容器連接到與項目內的服務的同一個網絡里面。建議使用networks代替舊版本中的配置項Links。

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，external_links配置項將被忽略。

18.extra_hosts

添加主機名到IP的映射。使用和Docker客戶端中的--add-host的參數一樣的值。例如：

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

會在啟動后的服務容器中的/etc/hosts文件中添加如下兩條具有主機名和IP地址的條目：

162.242.195.82  somehost
50.31.209.229   otherhost

19.healthcheck

配置運行檢查以確定服務容器是否健康。支持以下配置選項：

• test：指定健康檢測的方法。
• interval：啟動容器到進行健康檢查的間隔時間以及兩次健康檢查的間隔時間。
• timeout：單次健康檢查的超時時間，超過該時間該次健康檢查失敗。
• retries：健康檢查失敗后的最大重試次數，重試了最大次數依然失敗，容器將被視為unhealthy。
• start_period：為需要時間引導的容器提供的初始化時間，在此期間檢查失敗將不計入最大重試次數，但是如果在啟動期間健康檢查成功，則會將容器視為已啟動，並且所有連續失敗將計入最大重試次數。

其中interval、timeout和start_period都被指定為持續時間（durations）。start_period是在3.4版的配置文件格式中加入。test必須是字符串或JSON數組格式。如果是JSON數組格式，第一項必須是NONE、CMD或CMD-SHELL其中之一。如果是字符串格式，則等效於指定CMD-SHELL后跟該字符串的JSON數組格式。

例如以下示例，指定檢測方法為訪問http://localhost，健康檢查間隔時間為1m30s，健康檢查超時時間為10s，重試次數為3，啟動容器后等待健康檢查的初始化時間為40s：

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

例如以下示例，兩種形式等效：

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

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

使用disable: true可以設置鏡像禁用所有健康檢查，相對於test: ["NONE"]。例如：

healthcheck:
  disable: true

20.image

指定要從中啟動容器的鏡像。可以寫倉庫/標簽（repository/tag）或鏡像ID。示例如下：

image: redis

image: ubuntu:18.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

如果鏡像不存在，Compose會自動拉取鏡像，除非指定了build，這種情況下會使用指定選項構建鏡像並給鏡像打上指定標簽。

21.init

在3.7版的配置文件格式中加入

在容器內運行一個初始化程序以轉發信號並獲取進程。設置為true即可為服務啟動此功能。例如：

version: "3.8"
services:
  web:
    image: alpine:latest
    init: true

注意：默認使用的初始化二進制文件是Tini，並安裝在主機守護進程的/usr/libexec/docker-init。可以通過Daemon configuration file中的init-path將守護進程配置為使用自定義的初始化二進制文件 。

22.isolation

指定容器的隔離技術。Linux上只支持default值。Windows上支持default、process和hyperv這三個值。

23.labels

將元數據以標簽的形式添加到容器中。可以使用數組或字典兩種格式。例如：

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"

24.links

警告：--link是Docker的遺留功能。它最終可能會被刪除。建議您使用用戶自定義網絡代替--link來進行兩個容器間的通信。用戶自定義的網絡不支持--link在容器之間共享的環境變量的功能。但是可以使用例如數據卷之類的其他機制以更可控的方式在容器之間共享環境變量。

鏈接到其他服務中的容器。可以使用"SERVICE:ALIAS"或"SERVICE"的格式，其中SERVICE為服務名稱，ALIAS為鏈接別名。例如：

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

鏈接服務的容器可以通過與別名相同的主機名訪問，如果未指定別名，則可以使用服務名。默認情況下，不需要鏈接即可使服務進行通信，任何服務都可以使用該服務的名稱訪問任何其他服務。鏈接也可以和depends_on一樣表示服務之間的依賴關系 ，因此可以確定服務啟動的順序。

注意：如果同時定義鏈接和網絡，則它們之間具有鏈接的服務必須共享至少一個公共網絡才能進行通信。

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，links配置項將被忽略。

25.logging

服務的日志配置。例如：

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

driver配置項指定服務容器的日志驅動，與docker run中的--log-driver選項一樣。默認值為json-file，這里列舉三種日志驅動類型：

driver: "json-file"

driver: "syslog"

driver: "none"

使用options配置項為日志驅動指定日志記錄選項，與docker run中的--log-opt選項一樣。例如：

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

默認日志驅動json-file具有限制日志存儲量的選項。例如以下示例，max-size設置最大存儲大小為200k，max-file設置存儲的最大文件數為10，隨着日志超過最大限制，將刪除較舊的日志文件以允許存儲新日志：

options:
  max-size: "200k"
  max-file: "10"

26.network_mode

設置網絡模式。使用和Docker客戶端中的--network的參數一樣的值，格式為service:[service name]。可以指定使用服務或者容器的網絡。示例如下：

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]"

network_mode: "container:[container name/id]"

注意事項：

• 在swarm mode下部署堆棧時，該選項將被忽略。
• network_mode: "host"不能與links配置項混用。

27.networks

指定所加入的網絡。需要在頂層networks配置項中引入具體的網絡信息。例如：

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

networks:
  some-network:
  other-network:

(1)aliases

指定服務在此網絡上的別名（備用主機名）。同一網絡上的其他容器可以使用服務名稱或此別名來連接到服務的任何一個容器。由於aliases屬於網絡范圍，因此同一服務在不同的網絡上可以具有不同的別名。例如：

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

在以下示例中，提供了web、worker和db三個服務，以及new和legacy兩個網絡：

version: "3.8"
services:
  web:
    image: "nginx:alpine"
    networks:
      - new
  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy
  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

在該例中，可以通過主機名db或database在new網絡上訪問db服務，通過db或mysql在legacy網絡上訪問db服務。

注意：網絡范圍內的別名可以被多個容器甚至多個服務共享。 如果是這樣，則不能保證名稱恰好解析到哪一個容器。

(2)ipv4_address、ipv6_address

加入網絡后，為此服務的容器指定一個靜態IP地址。在頂層networks配置項中的相應網絡配置必須有子網配置覆蓋每個靜態地址的ipam配置。例如：

version: "3.8"
services:
  app:
    image: nginx:alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

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

注意：如果需要IPv6尋址，則必須使用V2.x版本的Compose配置文件並設置頂層networks配置項下的enable_ipv6選項。在當前swarm mode下IPv6選項不會起作用。

28.pid

跟主機系統共享進程命名空間。

pid: "host"

將PID模式設置為主機PID模式，打開該選項的容器之間，以及容器和宿主機操作系統之間可以通過進程ID來相互訪問和操作。

29.ports

暴露端口。注意端口映射與network_mode: host不兼容。支持short和long兩種格式的語法。short語法可以使用HOST:CONTAINER的格式指定端口映射，也可以指定容器端口，宿主機會隨機選擇臨時端口進行映射。例如：

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

注意：當使用HOST:CONTAINE格式來映射端口時，如果使用的容器端口小於60可能會得到錯誤得結果，因為YAML將會解析xx:yy這種數字格式為60進制，因此建議始終采用字符串格式來指定端口映射。

long語法支持配置short語法中不支持的附加字段。這些附加字段如下：

• target：指定容器內的端口。
• published：指定公開的端口。
• protocol：指定端口協議（tcp或udp）。
• mode：使用host在每個節點公開一個主機端口，或使用ingress對swarm mode端口進行負載均衡。

示例如下：

ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

long語法在3.2版的配置文件格式中加入

30.restart

指定重啟策略。例如想要在容器退出時總是會重啟容器，指定以下重啟策略：

restart: always

一共支持以下重啟策略：

• no：在任何情況下都不會重啟容器。默認的重啟策略。
• always：在容器退出時總是重啟容器。
• on-failure：在容器以非0狀態碼退出時才會重啟。
• unless-stopped：在容器退出時總是重啟容器，但是不考慮在Docker守護進程啟動時就已經停止了的容器。

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，restart配置項將被忽略。

31.secrets

為每個服務授予對保密數據（secrets）的訪問權限。支持short和long兩種格式的語法。更多secrets信息，參考secrets。

使用docker stack deploy時的注意事項：該保密數據（secret）必須已存在或者在Compose配置文件頂層secrets配置項中定義，否則堆棧部署將失敗。

short語法僅指定secret名稱來授予容器訪問secret數據的權限並將其掛載到容器的/run/secrets/<secret_name>上。source名稱和目標掛載點都設置為secret名稱。例如以下示例，授予了redis服務對secrets的my_secret和my_other_secret的訪問權限，其中my_secret的值設置到文件./my_secret.txt的內容中，my_other_secret定義為外部資源，這意味着它已經在Docker中通過運行docker secret create命令或其他堆棧部署進行定義，如果外部secret不存在，堆棧部署將會失敗並顯示secret not found錯誤：

version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

long語法提供了在服務的任務容器內如何創建secret的更多粒度：

• source：Docker中存在的secret名稱。
• target：指定要掛載到服務的任務容器的/run/secrets/中的文件名稱。如果未指定，默認為source的值。
• uid和gid：指定服務的任務容器的/run/secrets/中所擁有的該文件的UID或GID。如果未指定，兩者都默認為0。
• mode：以八進制表示法指定要掛載到服務的任務容器的/run/secrets/中的文件權限。例如，0444代表可讀。默認值在Docker 1.13.1為0000，在較新版本為0444。secret內容已掛載到臨時文件系統中，所以不可寫，如果設置了可寫位將被忽略。可以設置可執行位。如果不熟悉UNIX文件權限模式，可以使用權限計算器 。

例如以下示例，指定secret名稱為my_secret，授予redis服務對my_secret的訪問權限，指定要掛載到redis服務的任務容器的/run/secrets/中的文件名稱為redis_secret，指定UID和GID均為103，指定要掛載到服務的任務容器的/run/secrets/中的文件權限為0440（group-readable），但該redis服務沒有訪問my_other_secret的權限：

version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

可以授予服務訪問多個secret的權限，並且可以混合long和short語法。定義secret並不意味着授予服務對其的訪問權限。

32.security_opt

為每個容器覆蓋默認的標簽（label）。例如配置標簽中的用戶名和角色名：

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

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，security_opt配置項將被忽略。

33.stop_grace_period

指定在發送SIGKILL之前，如果容器無法處理SIGTERM或使用stop_signal指定的任何停止信號時，試圖停止該容器所需要的等待時間。默認情況下，stop在發送SIGKILL之前等待10秒以退出容器。時間指定為duration。具體示例如下：

stop_grace_period: 1s

stop_grace_period: 1m30s

34.stop_signal

設置停止容器的信號。默認使用SIGTERM停止容器。例如指定SIGUSR1信號：

stop_signal: SIGUSR1

35.sysctls

在容器中設置的內核參數。可以使用數組或字典兩種格式。例如指定連接數為1024和開啟TCP的syncookies：

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

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

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，sysctls配置項要求Docker Engine 19.03或以上。

36.tmpfs

在3.6版的配置文件格式中加入

掛載一個臨時文件系統到容器內部。可以是一個值或一個列表。例如：

tmpfs: /run

tmpfs:
  - /run
  - /tmp

在容器內掛載一個臨時文件系統。Size可以指定掛載的tmpfs大小，以字節為單位。 默認情況下不受限制。例如：

 - type: tmpfs
     target: /app
     tmpfs:
       size: 1000

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時使用3至3.5版本的Compose配置文件，tmpfs配置項將被忽略。

37.ulimits

覆蓋容器的默認ulimit值。可以單一地將限制值設為一個整數，也可以將soft/hard限制指定為映射。例如，指定最大進程數為65535，指定文件句柄數，其中軟限制為20000，系統硬限制為40000，軟限制應用可以隨時修改，不能超過硬限制，硬限制只能root用戶提高：

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

38.userns_mode

指定用戶命名空間模式。如果Docker守護進程配置了用戶名稱空間，則禁用此服務的用戶名稱空間。以下是使用主機上的用戶命名空間的配置示例：

userns_mode: "host"

使用docker stack deploy時的注意事項：在swarm mode下部署堆棧時，userns_mode配置項將被忽略。

39.volumes

指定所掛載的主機路徑或數據卷名稱。支持short和long兩種格式的語法。可以將主機路徑作為單個服務的一部分進行掛載，而無需在頂層volumes配置項中定義。但是如果想要在多個服務之間重用數據卷，需要在頂層volumes配置項中定義一個數據卷名稱。

在3版的配置文件格式中的變化：在頂層volumes配置項中定義了數據卷名稱並從每個服務的volumes列表中引用了該數據卷。這將替代早期版本的Compose配置文件格式中的volumes_from配置項。

short語法使用通用的[SOURCE:]TARGET[:MODE]格式，SOURCE可以是主機路徑或數據卷名稱，TARGET為掛載數據卷的容器路徑，MODE可以為ro只讀模式或rw讀寫模式（默認）。可以在主機上掛載相對路徑，該路徑相對於正在使用的Compose配置文件的目錄進行擴展，相對路徑應始終以.或..開頭。例如：

volumes:
  #只指定一個路徑，Docker會自動在創建一個數據卷（這個路徑是容器內部的）
  - /var/lib/mysql
  #使用絕對路徑掛載數據卷
  - /opt/data:/var/lib/mysql
  #使用基於Compose配置文件的相對路徑作為數據卷掛載到容器
  - ./cache:/tmp/cache
  #使用基於root用戶的相對路徑作為數據卷掛載到容器
  - ~/configs:/etc/configs/:ro
  #使用已經存在命名的數據卷掛載到容器
  - datavolume:/var/lib/mysql

long語法支持配置以下short語法中不支持的附加字段：

• type：掛載類型，可以為volume、bind、tmpfs或npipe。
• source：掛載源，在主機上用於綁定掛載的路徑或定義在頂層volumes配置項中的數據卷名稱。不適用於tmpfs掛載類型。
• target：數據卷掛載在容器中的路徑。
• read_only：設置數據卷為只讀。
• bind：配置額外的bind選項。
  • propagation：用於綁定的傳播模式。
• volume：配置額外的volume選項。
  • nocopy：創建數據卷時禁止從容器復制數據。
• tmpfs：配置額外的tmpfs選項。
  • size：tmpfs掛載的大小，以字節為單位。
• consistency：掛載的一致性要求，可以為consistent、cached或delegated。其中consistent表示主機和容器具有相同視圖。cached表示讀取緩存，主機視圖是權威的。delegated表示讀寫緩存，容器視圖是權威的。

例如：

version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:

40.其他配置項

此外，還有domainname、hostname、ipc、mac_address、privileged、read_only、shm_size、stdin_open、tty、user和working_dir這些配置項。它們都是單值配置，和docker run中的對應選項類似。注意mac_address是舊版本配置項。例如：

#指定容器中運行應用的用戶名
user: postgresql
#指定容器的工作目錄
working_dir: /code
#指定容器中的搜索域名
domainname: foo.com
#指定容器中的主機名
hostname: foo
ipc: host
#指定容器中的mac地址
mac_address: 02:42:ac:11:65:43
#指定容器為特權容器
privileged: true
#指定以只讀模式掛載容器的root文件系統，不能對容器內容進行修改
read_only: true
#設置/dev/shm分區的大小
shm_size: 64M
#打開標准輸入，可以接受外部輸入
stdin_open: true
#分配tty設備用來支持終端登錄
tty: true

四、數據卷配置

雖然可以聲明即時生效的數據卷作為服務聲明的一部分，但這部分可以通過頂層volumes配置項定義一個數據卷以實現在多個服務之間重用，並且可以使用docker命令行或API輕松進行檢索和檢查。例如以下示例，數據庫的數據目錄作為數據卷與另一個服務共享以便定期備份：

version: "3.8"
services:
  db:
    image: db
    volumes:
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:

頂層volumes配置項下的條目可以為空，這種情況下配置的默認驅動，默認驅動在大多數情況下為local驅動。下面就對數據卷的相關配置項進行一個總結。

1.driver

指定該數據卷所要使用的數據卷驅動。默認為Docker Engine中配置使用的無論哪種驅動，大多數情況下為local驅動。如果驅動不可用，則引擎會在docker-compose up嘗試創建數據卷時返回一個錯誤。以下為指定數據卷驅動的示例：

driver: foobar

2.driver_opts

以鍵值對的形式指定用來傳遞給該數據卷所使用的數據卷驅動的列表選項。這些選項取決於數據卷驅動，可以參考數據卷驅動程序文檔。例如：

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

3.external

指定該數據卷是否是外部數據卷。如果設置為true，則指定該數據卷是在Compose外部創建的。由於docker-compose up不會嘗試創建該數據卷，如果該數據卷不存在則會引發錯誤。在3.3及以下版本的Compose配置文件格式中，external配置項不能與包括driver、driver_opts和labels在內的其他數據卷配置項同時使用，在3.4及以上版本中則沒有此限制。例如以下示例，Compose不會嘗試創建一個名為[projectname]_data的數據卷，而是查找一個現存的被簡單稱為data的數據卷並將其掛載到db服務的容器中：

version: "3.8"
services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true

通過external配置項下的name配置項可以指定數據卷的名稱，該名稱與Compose配置文件中用於引用數據卷的名稱區分開來。例如：

volumes:
  data:
    external:
      name: actual-name-of-volume

不過external配置項下的name配置項在3.4版的配置文件格式中就已經被棄用了，可以用name配置項替代。

使用docker stack deploy時的注意事項：如果使用docker stack deploy代替docker-compose up以swarm mode啟動應用，則會創建不存在的外部數據卷。在swarm mode下，服務定義數據卷后將自動創建該卷。由於服務任務已在新節點上安排，因此SwarmKit將在本地節點上創建數據卷。

4.labels

將元數據以標簽的形式添加到容器中。可以使用數組或字典兩種格式。例如：

labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"

5.name

在3.4版的配置文件格式中加入

為該數據卷設置一個自定義名稱。例如：

version: "3.8"
volumes:
  data:
    name: my-app-data

可以和external配置項一起使用。例如：

version: "3.8"
volumes:
  data:
    external: true
    name: my-app-data

五、網絡配置

通過頂層networks配置項可以指定要創建的網絡。下面就對網絡的相關配置項進行一個總結。

1.driver

指定該網絡所要使用的驅動。默認驅動取決於所使用的Docker Engine的配置方式，但是在大多數情況下，單個主機上用的bridge，Swarm上用的overlay。

• bridge：表示橋接，Docker在單個主機上默認使用bridge網絡。
• overlay：overlay驅動在一個swarm中的多個節點之間創建一個命名網絡。

如果驅動不可用，則Docker Engine會返回一個錯誤。以下為指定卷驅動的示例：

driver: overlay

如果想要使用主機的網絡堆棧，或者不使用網絡。這相當於docker run --net = host或docker run --net = none。僅在使用docker stack命令時使用。如果使用docker-compose命令，需使用服務配置中的network_mode配置項。如果要在相同構建版本的容器上使用特定網絡，需要在服務配置的build下的network配置項中設置。例如：

services:
  web:
    build:
      network: host
      context: .

使用諸如host和none的內置網絡的語法有所不同。定義一個名為host或none的外部網絡以及Compose可以使用的別名，然后使用該別名向該網絡授予服務訪問權限，而且該外部網絡在Docker中已經自動創建。例如以下示例，定義了名為host的外部網絡，Compose中可以使用的別名為hostnet：

version: "3.8"
services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host

例如以下示例，定義了名為none的外部網絡，Compose中可以使用的別名為nonet：

services:
  web:
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

2.driver_opts

以鍵值對的形式指定用來傳遞給該網絡所使用的驅動的列表選項。這些選項取決於驅動，可以參考驅動程序文檔。例如：

driver_opts:
  foo: "bar"
  baz: 1

3.attachable

在3.2版的配置文件格式中加入

指定是否允許除服務之外的獨立容器連接到該網絡。僅在driver設置為overlay時使用。如果設置為true，則除了服務之外的獨立容器也可以連接到該網絡。如果獨立容器連接到了overlay網絡，那它可以與那些也從其他Docker守護進程連接到overlay網絡的服務和獨立容器進行通信。例如：

networks:
  mynet1:
    driver: overlay
    attachable: true

4.enable_ipv6

在該網絡上啟用IPv6網絡。

不支持V3版Compose配置文件：如果要使用enable_ipv6配置項，則需要使用V2版Compose配置文件，因為swarm mode尚不支持該配置項。

5.ipam

指定自定義IPAM配置。有以下配置選項：

• driver：自定義IPAM驅動以代替默認驅動。
• config：包含零個或多個配置塊的列表，每個配置塊可以有以下配置選項。
  • subnet：設置表示網段的CIDR格式的子網。

以下為指定自定義IPAM配置的示例：

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16

注意：目前，例如gateway等其他IPAM配置僅適用於V2版Compose配置文件。

6.internal

指定是否創建一個與外部隔離的overlay網絡。默認情況下，Docker也會將橋接網絡連接到它以提供外部連接。如果要創建一個與外部隔離的overlay網絡，需將此配置項設置為true。

7.labels

將元數據以標簽的形式添加到容器中。可以使用數組或字典兩種格式。例如：

labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

8.external

指定該網絡是否是外部網絡。如果設置為true，則指定該網絡是在Compose外部創建的。由於docker-compose up不會嘗試創建該網絡，如果該網絡不存在則會引發錯誤。在3.3及以下版本的Compose配置文件格式中，external配置項不能與包括driver、driver_opts、ipam和internal等在內的其他網絡配置項同時使用，在3.4及以上版本中則沒有此限制。例如以下示例，proxy是通往外界的網關，Compose不會嘗試創建一個名為[projectname] _outside的網絡，而是查找一個現存的被簡單稱為的outside網絡並將proxy服務的容器連接到該網絡：

version: "3.8"
services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

通過external配置項下的name配置項可以指定網絡的名稱，該名稱與Compose配置文件中用於引用網絡的名稱區分開來。例如：

networks:
  outside:
    external:
      name: actual-name-of-network

不過external配置項下的name配置項在3.5版的配置文件格式中就已經被棄用了，可以用name配置項替代。

9.name

在3.5版的配置文件格式中加入

為該網絡設置一個自定義名稱。例如：

version: "3.8"
networks:
  network1:
    name: my-app-net

可以和external配置項一起使用。例如：

version: "3.8"
networks:
  network1:
    external: true
    name: my-app-net

六、configs配置

頂層configs配置項定義或引用了授予此堆棧中的服務的configs，config來源於file或external。下面就對configs的相關配置項進行一個簡單總結。

• file：通過指定路徑中的文件內容創建config。
• external：如果設置為true，則指定該config已經創建。Docker不會嘗試創建它，如果它不存在，會發生config not found錯誤。
• name：指定Docker中config的名稱。在3.5版的配置文件格式中加入。
• driver和driver_opts：自定義secret驅動的名稱，和以鍵值對的形式指定用來傳遞給特定驅動的選項。這兩個配置項均在3.8版的配置文件格式中加入，僅在使用docker stack時受支持。
• template_driver：指定要使用的模板驅動的名稱，它控制是否以及如何將secret有效負載作為模板進行評估。如果未設置驅動，則不使用任何模板。當前僅支持使用Go語言的golang驅動。該配置項在3.8版的配置文件格式中加入，僅在使用docker stack時受支持。

七、secrets配置

頂層secrets配置項定義或引用了授予此堆棧中的服務的secrets，secret來源於file或external。下面就對secrets的相關配置項進行一個簡單總結。

• file：通過指定路徑中的文件內容創建secret。
• external：如果設置為true，則指定該secret已經創建。Docker不會嘗試創建它，如果它不存在，會發生secretg not found錯誤。
• name：指定Docker中secret的名稱。在3.5版的配置文件格式中加入。
• template_driver：指定要使用的模板驅動的名稱，它控制是否以及如何將secret有效負載作為模板進行評估。如果未設置驅動，則不使用任何模板。當前僅支持使用Go語言的golang驅動。該配置項在3.8版的配置文件格式中加入，僅在使用docker stack時受支持。

八、擴展字段

在3.4版的配置文件格式中加入

可以使用擴展字段來定義可重用的配置片段。這些特殊字段只要位於Compose配置文件的最頂（root）層，可以為任何格式，它們的名稱以x-開頭。

注意：從3.7版（對於3.x系列）和2.4版（對於2.x系列）的配置文件格式開始，擴展字段可以位於服務、數據卷、網絡、config和 secret定義部分的root層。

例如以下示例，通過擴展字段x-custom定義一個可重用的配置片段：

version: '3.4'
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"

這些擴展字段內容將被Compose忽略，但是可以通過YAML錨點來引用擴展字段內容。例如以下日志記錄配置，希望被多個服務引用：

logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

可以通過&開頭的字符串在擴展字段x-logging定義的日志記錄配置片段中設置錨點，然后在需要引用該日志記錄配置片段的服務中以*加上錨點名進行引用：

version: '3.4'
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging

也可以通過YAML合並來部分覆蓋擴展字段中的值。例如：

version: '3.4'
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local

九、其他內容

1.指定持續時間（durations）

某些配置項如healthcheck配置項的子配置項interval和timeout接受以類似如下格式的字符串表示的持續時間（durations）：

2.5s
10s
1m30s
2h32m
5h34m56s

支持的單位有us、ms、s、m和h。

2.指定字節值

某些配置項如build配置項的子配置項shm_size接受以類似如下格式的字符串表示的字節值：

2b
1024kb
2048k
300m
1gb

支持的單位有b、k或kb、m或mb、g或gb。目前不支持十進制。

3.變量替換

配置項中的值可以包含環境變量，Compose會使用運行docker-compose時所在的shell中的環境變量值來替換Compose配置文件中的環境變量，\({VARIABLE}和\)VARIABLE這兩種語法都支持。例如以下示例，假設shell中有POSTGRES_VERSION=9.3這個環境變量，則配置中的${POSTGRES_VERSION}將被替換為9.3：

db:
  image: "postgres:${POSTGRES_VERSION}"

如果未設置環境變量，則Compose會將配置文件中的環境變量替換為空字符串。如果上例中的POSTGRES_VERSION未設置，則image的值為postgres:。可以使用.env環境文件為環境變量設置默認值，不過shell中的環境變量值會覆蓋.env環境文件中設置的值。

使用docker stack deploy時的注意事項：.env環境文件僅在使用docker-compose up命令時有效，不適用於docker stack deploy。

此外，可以使用典型的shell語法提供內聯默認值，支持以下兩種語法：

• ${VARIABLE:-default}：如果VARIABLE未設置或為空，則會應用default的值。
• ${VARIABLE-default}：僅當VARIABLE未設置時才會應用default的值。

同樣，也可以使用以下兩種語法來強制要求變量必須賦值：

• ${VARIABLE:?err}：如果VARIABLE未設置或為空，退出並輸出一條包含err的錯誤信息。
• ${VARIABLE?err}：如果VARIABLE未設置，退出並輸出一條包含err的錯誤信息。

當配置中需要\(符號時，可以使用\)\(符號。也可以防止Compose插值，因此\)$ 可以引用不想由Compose處理的環境變量。例如以下示例，就算設置了環境變量VAR_NOT_INTERPOLATED_BY_COMPOSE，Compose配置文件中的VAR_NOT_INTERPOLATED_BY_COMPOSE也不會被替換：

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

如果少指定了一個\(，也就是只使用單個\)符號，則Compose會將值解釋為環境變量，並出現一個類似The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.這樣的警告。