Compose 建置規格

建置是 Compose 規格的選用部分。它告訴 Compose 如何從原始碼（重新）建置應用程式，並讓您以可攜式方式在 Compose 檔案中定義建置流程。 build 可以指定為定義上下文路徑的單個字串，也可以指定為詳細的建置定義。

在前一種情況下，整個路徑會被用作 Docker 上下文來執行 Docker 建置，並在目錄的根目錄尋找標準的 Dockerfile。路徑可以是絕對路徑或相對路徑。如果是相對路徑，則會從包含 Compose 檔案的目錄解析。如果是絕對路徑，則該路徑會導致 Compose 檔案無法攜帶，因此 Compose 會顯示警告。

在後一種情況下，可以指定建置參數，包括替代的 Dockerfile 位置。路徑可以是絕對路徑或相對路徑。如果是相對路徑，則會從包含 Compose 檔案的目錄解析。如果是絕對路徑，則該路徑會導致 Compose 檔案無法攜帶，因此 Compose 會顯示警告。

使用 `build` 和 `image`

當 Compose 同時遇到服務的 build 子區段和 image 屬性時，它會遵循 pull_policy 屬性定義的規則。

如果服務定義中缺少 pull_policy，Compose 會先嘗試拉取映像檔，如果在登錄或平台快取中找不到映像檔，則會從原始碼建置。

發佈建置的映像檔

支援 build 的 Compose 提供將建置的映像檔推送至登錄的選項。執行此操作時，它不會嘗試推送沒有 image 屬性的服務映像檔。Compose 會針對缺少 image 屬性發出警告，這會阻止映像檔被推送。

說明範例

以下範例說明了 Compose 建置規格的概念，並提供了一個具體的範例應用程式。此範例不具規範性。

services:
  frontend:
    image: example/webapp
    build: ./webapp

  backend:
    image: example/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom

當用於從原始碼建置服務映像檔時，Compose 檔案會建立三個 Docker 映像檔

example/webapp：使用 Compose 檔案父資料夾中的 webapp 子目錄作為 Docker 建置上下文來建置 Docker 映像檔。如果此資料夾中缺少 Dockerfile，則會擲出錯誤。
example/database：使用 Compose 檔案父資料夾中的 backend 子目錄來建置 Docker 映像檔。使用 backend.Dockerfile 檔案來定義建置步驟，此檔案會相對於上下文路徑搜尋，這表示 .. 解析為 Compose 檔案的父資料夾，因此 backend.Dockerfile 是一個同級檔案。
Docker 映像檔是使用 custom 目錄建構的，並以使用者的 HOME 作為 Docker 建置上下文。Compose 會顯示一則關於建構映像檔時使用非可攜式路徑的警告。

推送時，example/webapp 和 example/database Docker 映像檔都會被推送到預設的 registry。custom 服務映像檔會被略過，因為沒有設定 image 屬性，Compose 會顯示一則關於缺少此屬性的警告。

屬性

build 子區段定義了 Compose 用來從原始碼建構 Docker 映像檔的設定選項。build 可以指定為包含建置上下文路徑的字串，或者指定為詳細的結構。

使用字串語法時，只能將建置上下文設定為以下其中一種：

Compose 檔案父資料夾的相對路徑。此路徑必須是一個目錄，並且必須包含一個 Dockerfile。
services: webapp: build: ./dir
Git 儲存庫 URL。Git URL 接受在其片段區段中以冒號 (:) 分隔的上下文設定。第一部分表示 Git 簽出的參考，可以是分支、標籤或遠端參考。第二部分表示儲存庫內用作建置上下文的一個子目錄。
services: webapp: build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory

或者，build 可以是一個物件，其欄位定義如下：

additional_contexts（額外上下文）

Docker Compose 版本 2.17.0 引入

additional_contexts 定義映像檔建構器在映像檔建構期間應使用的具名上下文清單。

additional_contexts 可以是映射或清單。

build:
  context: .
  additional_contexts:
    - resources=/path/to/resources
    - app=docker-image://my-app:latest
    - source=https://github.com/myuser/project.git

build:
  context: .
  additional_contexts:
    resources: /path/to/resources
    app: docker-image://my-app:latest
    source: https://github.com/myuser/project.git

當用作清單時，語法遵循 NAME=VALUE 格式，其中 VALUE 是一個字串。除此之外的驗證由映像檔建構器負責（並且是建構器特定的）。Compose 至少支援目錄的絕對和相對路徑以及 Git 儲存庫 URL，就像 context 一樣。其他上下文類型必須加上前綴以避免與 type:// 前綴混淆。

如果映像檔建構器不支援額外的上下文，Compose 會發出警告，並可能列出未使用的上下文。

可以在這裡找到 Buildx 中如何使用它的說明範例。

args（參數）

args 定義建構參數，即 Dockerfile ARG 值。

使用以下 Dockerfile 作為範例：

ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"

可以在 Compose 檔案的 build 鍵下設定 args 來定義 GIT_COMMIT。args 可以設定為映射或清單。

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19

build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

在指定建構參數時可以省略值，在這種情況下，其建構時的值必須通過使用者互動獲得，否則在建構 Docker 映像檔時將不會設定建構參數。

args:
  - GIT_COMMIT

context（上下文）

context 定義包含 Dockerfile 的目錄的路徑，或 Git 儲存庫的 URL。

當提供的值是相對路徑時，它會被解釋為相對於專案目錄。Compose 會針對用於定義建置上下文的絕對路徑發出警告，因為這些路徑會導致 Compose 檔案無法攜帶。

build:
  context: ./dir

services:
  webapp:
    build: https://github.com/mycompany/webapp.git

如果未明確設定，context 預設為專案目錄 (.)。

cache_from（快取來源）

cache_from 定義映像檔建構器應使用來解析快取的來源清單。

快取位置語法遵循全域格式 [NAME|type=TYPE[,KEY=VALUE]]。簡單的 NAME 實際上是 type=registry,ref=NAME 的簡寫表示法。

Compose Build 實作可能支援自定義類型，Compose 規範定義了必須支援的標準類型：

registry 從由鍵 ref 設定的 OCI 映像檔中檢索建構快取。

build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

不支援的快取會被忽略，並且不會阻止您建構映像檔。

cache_to（快取目標）

cache_to 定義用於與未來建構共享建構快取的匯出位置清單。

build:
  context: .
  cache_to:
   - user/app:cache
   - type=local,dest=path/to/cache

快取目標使用 cache_from 定義的相同 type=TYPE[,KEY=VALUE] 語法定義。

不支援的快取會被忽略，並且不會阻止您建構映像檔。

dockerfile（Dockerfile）

dockerfile 設定替代的 Dockerfile。相對路徑會從建置上下文中解析。Compose 會針對用於定義 Dockerfile 的絕對路徑發出警告，因為它會導致 Compose 檔案無法攜帶。

設定時，不允許使用 dockerfile_inline 屬性，Compose 會拒絕同時設定兩者的任何 Compose 檔案。

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline (嵌入式 Dockerfile)

Docker Compose 版本 2.17.0 引入

dockerfile_inline 將 Dockerfile 內容定義為 Compose 檔案中的內嵌字串。設定時，不允許使用 dockerfile 屬性，Compose 會拒絕同時設定兩者的任何 Compose 檔案。

建議使用 YAML 多行字串語法來定義 Dockerfile 內容。

build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN some command

entitlements (權利)

Docker Compose 版本 2.27.1 引入

entitlements 定義在建構期間允許的額外權限。

entitlements:
  - network.host
  - security.insecure

extra_hosts (額外主機)

extra_hosts 在建構時新增主機名稱映射。使用與 extra_hosts 相同的語法。

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"

Compose 在容器的網路設定中使用 IP 位址和主機名稱建立相符的項目，這表示對於 Linux，/etc/hosts 將會新增額外的行。

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

isolation (隔離)

isolation 指定建構的容器隔離技術。與 isolation 相同，支援的值因平台而異。

labels (標籤)

labels 將中繼資料新增至產生的映像檔。labels 可以設定為陣列或映射。

建議您使用反向 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"

network (網路)

設定建構期間 RUN 指令連線到的網路容器。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

使用 none 在建構期間停用網路。

build:
  context: .
  network: none

no_cache (不使用快取)

no_cache 會停用映像檔建構器快取，並強制從來源完整重建所有映像檔層。這僅適用於 Dockerfile 中宣告的層，只要 registry 上的標籤已更新，就可以從本機映像檔儲存區中檢索參考映像檔（請參閱 pull）。

platforms (平台)

platforms 定義目標平台的清單。

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"

當省略 platforms 屬性時，Compose 會將服務的平台包含在預設建構目標平台清單中。

當定義了 platforms 屬性時，Compose 會包含服務的平台，否則使用者將無法運行他們構建的映像檔。

在下列情況下，Compose 會回報錯誤：

當列表包含多個平台，但實作無法儲存多平台映像檔時。

當列表包含不受支援的平台時。

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "unsupported/unsupported"

當列表非空且不包含服務的平台時。

services:
  frontend:
    platform: "linux/amd64"
    build:
      context: "."
      platforms:
        - "linux/arm64"

privileged (特權模式)

Docker Compose 版本 2.15.0 引入

privileged 設定服務映像檔以提升的權限進行構建。支援程度和實際影響因平台而異。

build:
  context: .
  privileged: true

pull (拉取映像檔)

pull 要求映像檔構建器提取參考的映像檔（FROM Dockerfile 指令），即使這些映像檔已存在於本機映像檔儲存庫中。

secrets (Secrets)

secrets 允許在每個服務構建的基礎上，授予對由 secrets 定義的敏感資料的存取權。支援兩種不同的語法變體：簡短語法和完整語法。

如果 Compose 檔案的 secrets 區段中未定義 secret，Compose 將回報錯誤。

簡短語法

簡短語法變體僅指定 secret 名稱。這將授予容器存取 secret 的權限，並將其作為唯讀檔案掛載到容器內的 /run/secrets/<secret_name>。來源名稱和目標掛載點都設定為 secret 名稱。

以下範例使用簡短語法授予 frontend 服務構建對 server-certificate secret 的存取權。server-certificate 的值設定為檔案 ./server.cert 的內容。

services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

完整語法

完整語法在服務容器內建立 secret 的方式上提供了更細緻的控制。

source：secret 在平台上的名稱。
target：要掛載到服務工作容器中 /run/secrets/ 的檔案名稱。如果未指定，則預設為 source。
uid 和 gid：在服務工作容器中 /run/secrets/ 內擁有該檔案的數值 UID 或 GID。預設值是執行容器的使用者。
mode：要掛載到服務工作容器中 /run/secrets/ 的檔案權限，以八進位表示法表示。預設值是世界可讀權限（模式 0444）。如果設定了可寫位元，則必須忽略它。可執行位元可以設定。

以下範例將容器內 server-certificate secret 檔案的名稱設定為 server.crt，將模式設定為 0440（群組可讀），并将使用者和群組設定為 103。server-certificate secret 的值由平台透過查詢提供，secret 的生命週期不由 Compose 直接管理。

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: server.cert
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true

可以授予服務構建對多個 secret 的存取權。長短語法可以在同一個 Compose 檔案中使用。在頂層 secrets 中定義 secret 並不意味著授予任何服務構建對它的存取權。此類授予必須在服務規範中作為 secrets 服務元素明確指定。

ssh (SSH)

ssh 定義映像檔構建器在映像檔構建期間應使用的 SSH 驗證（例如，複製私有儲存庫）。

ssh 屬性語法可以是：

default：讓構建器連接到 SSH 代理。
ID=path：ID 和關聯路徑的鍵/值定義。它可以是 PEM 檔案，或是 ssh 代理程式通訊端的路径。

build:
  context: .
  ssh:
    - default   # mount the default SSH agent

或

build:
  context: .
  ssh: ["default"]   # mount the default SSH agent

使用自訂 ID myproject 和本機 SSH 金鑰的路徑

build:
  context: .
  ssh:
    - myproject=~/.ssh/myproject.pem

映像檔構建器可以依靠它在構建期間掛載 SSH 金鑰。

例如，SSH 掛載可用於掛載由 ID 設定的 SSH 金鑰並存取受保護的資源。

RUN --mount=type=ssh,id=myproject git clone ...

shm_size (共享記憶體大小)

shm_size 設定分配用於構建 Docker 映像檔的共享記憶體大小（Linux 上的 /dev/shm 分割區）。指定為表示位元組數的整數值或表示位元組值的字串。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

tags (標籤)

tags 定義必須與構建映像檔關聯的標籤映射列表。此列表是服務區段中定義的映像檔屬性的補充。

tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"

target (目標)

target 定義要在多階段 Dockerfile 中構建的階段。

build:
  context: .
  target: prod

ulimits (資源限制)

Docker Compose 版本 2.23.1 引入

ulimits 覆蓋容器的預設 ulimits。它指定為單一限制的整數或軟/硬限制的映射。

services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000