本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定 Elastic Beanstalk Docker 環境
<a name="create_deploy_docker.container.console"></a>

本章說明所有支援的 Docker 平台分支的其他組態資訊，包括 ECS 受管 Docker 平台分支。除非在區段中識別特定平台分支或平台分支元件，否則它適用於執行支援 Docker 和 ECS 受管 Docker 平台的所有環境。

**注意**  
如果您的 Elastic Beanstalk 環境使用 Amazon Linux AMI 平台版本 (Amazon Linux 2 之前的版本)，請閱讀 [Amazon Linux AMI (Amazon Linux 2 之前的版本) 上的 Docker 組態](#docker-alami) 中的其他資訊。

**Topics**
+ [在 Docker 環境中設定軟體](#docker-software-config)
+ [在容器中參考環境變數](#docker-env-cfg.env-variables)
+ [搭配 Docker Compose 使用環境變數的插補功能](#docker-env-cfg.env-variables-dc-interpolate)
+ [使用 Docker Compose 產生增強型運作狀態報告的日誌](#docker-env-cfg.healthd-logging)
+ [使用 Docker Compose 的 Docker 容器自訂記錄](#docker-env-cfg.dc-customized-logging)
+ [Docker 影像](#docker-images)
+ [為 Docker 環境設定受管更新](#docker-managed-updates)
+ [Docker 組態命名空間](#docker-namespaces)
+ [Amazon Linux AMI (Amazon Linux 2 之前的版本) 上的 Docker 組態](#docker-alami)

## 在 Docker 環境中設定軟體
<a name="docker-software-config"></a>

您可使用 Elastic Beanstalk 主控台來設定於您環境的執行個體上執行的軟體。

**在 Elastic Beanstalk 主控台中設定 Docker 環境**

1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)，然後在**區域**清單中選取您的 AWS 區域。

1. 在導覽窗格中，選擇**環境**，然後在清單中選擇您環境的名稱。

1. 在導覽窗格中，選擇**組態**。

1. 在**更新、監控和日誌記錄**組態類別中，選擇**編輯**。

1. 進行必要的組態變更。

1. 若要儲存變更，請選擇頁面底部的**儲存變更**。

如需有關在任何環境中配置軟體設定的資訊，請參閱 [環境變數和其他軟體設定](environments-cfg-softwaresettings.md)。以下各節介紹 Docker 的特定資訊。

### 容器選項
<a name="docker-software-config.container"></a>

**Container options (容器選項)** 區段具有平台特定選項。對於 Docker 環境而言，它可讓您選擇您的環境是否包含 NGINX 代理伺服器。

**使用 Docker Compose 的環境**  
如果您使用 Docker Compose 來管理 Docker 環境，則 Elastic Beanstalk 會假定您以容器身分來執行代理伺服器。因此，對於 **Proxy server (代理伺服器)** 設定，其預設為 **None (無)**，而且 Elastic Beanstalk 不會提供 NGINX 組態。

**注意**  
即使您選取 **NGINX** 做為代理伺服器，在使用 Docker Compose 的環境中也會忽略此設定。**Proxy server (代理伺服器)** 設定仍預設為 **None (無)**。

由於使用 Docker Compose 的 Amazon Linux 2 平台上的 Docker 已停用 NGINX Web 伺服器 Proxy，因此，您必須依照指示產生增強型運作狀態報告的日誌。如需詳細資訊，請參閱[使用 Docker Compose 產生增強型運作狀態報告的日誌](#docker-env-cfg.healthd-logging)。

### 環境屬性 （環境變數）
<a name="docker-software-config.env"></a>

您可以使用環境屬性 （也稱為環境變數） 將值、端點、偵錯設定和其他資訊傳遞至應用程式。主控台**的環境變數**區段可讓您在執行應用程式的 EC2 執行個體上指定環境變數。環境變數會以索引鍵/值對的形式傳入應用程式。

您在容器中執行的應用程式的程式碼，可以依名稱參照環境變數並讀取其值。讀取這些環境變數的原始程式碼會因程式設計語言而有所不同。您可以在個別平台主題中，找到在 Elastic Beanstalk 受管平台支援之程式設計語言中讀取環境變數值的指示。如需這些主題的連結清單，請參閱 [環境變數和其他軟體設定](environments-cfg-softwaresettings.md)。

**Elastic Beanstalk 環境變數中的秘密和參數**  
Elastic Beanstalk 提供在環境變數中參考 AWS Secrets Manager 和 AWS Systems Manager 參數存放區資料的功能。這是您的應用程式可以原生存取這些服務所存放之秘密和參數的安全選項，而不必管理對它們的 API 呼叫。您的 Elastic Beanstalk Docker 和 ECS 受管 Docker 平台必須是 [2025 年 3 月 26 日當天或之後發行的版本，](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2025-03-26-windows.html)才能支援此功能。如需使用環境變數參考秘密的詳細資訊，請參閱 [擷取 Elastic Beanstalk 環境變數的秘密和參數](AWSHowTo.secrets.env-vars.md)。

**使用 Docker Compose 的環境**  
如果您使用 Docker Compose 來管理 Docker 環境，您必須進行一些額外的設定，以擷取容器中的環境變數。若要讓容器中執行的可執行檔存取這些環境變數，您必須在 `docker-compose.yml` 中參考這些變數。如需詳細資訊，請參閱 [在容器中參考環境變數](#docker-env-cfg.env-variables)。

## 在容器中參考環境變數
<a name="docker-env-cfg.env-variables"></a>

如果您在 Amazon Linux 2 Docker 平台上使用 Docker Compose 工具，Elastic Beanstalk 會在應用程式專案的根目錄中產生名為 `.env` 的 Docker Compose 環境。此檔案會存放針對 Elastic Beanstalk 設定的環境變數。

**注意**  
 如果您在應用程式套件中加入 `.env` 檔案，Elastic Beanstalk 將不會產生 `.env` 檔案。

為了讓容器參考您在 Elastic Beanstalk 中定義的環境變數，您必須遵循其中一種或兩種設定方法。
+ 將 Elastic Beanstalk 產生的 `.env` 檔案新增至 `env_file` 檔案中的 `docker-compose.yml` 組態選項。
+ 直接定義 `docker-compose.yml` 檔案中的環境變數。

以下檔案提供範例。範例 `docker-compose.yml` 檔案會示範這兩種方法。
+ 如果您定義環境屬性 `DEBUG_LEVEL=1` 和 `LOG_LEVEL=error`，Elastic Beanstalk 會為您產生以下 `.env` 檔案：

  ```
  DEBUG_LEVEL=1
  LOG_LEVEL=error
  ```
+ 在此 `docker-compose.yml` 檔案中，`env_file` 組態選項會指向 `.env` 檔案，而且它也會在 `DEBUG=1` 檔案中直接定義環境變數 `docker-compose.yml`。

  ```
  services:
    web:
      build: .
      environment:
        - DEBUG=1
      env_file:
        - .env
  ```

**備註**  
如果您在兩個檔案中設定相同的環境變數，則 `docker-compose.yml` 檔案中定義之變數的優先順序高於 `.env` 檔案中定義的變數。
請小心不要在等號 (=) 和指派給變數的值之間留下空格，以防止空格加入字串中。

若要進一步了解 Docker Compose 中的環境變數，請參閱 [Compose 中的環境變數](https://docs.docker.com/compose/environment-variables/) 

## 搭配 Docker Compose 使用環境變數的插補功能
<a name="docker-env-cfg.env-variables-dc-interpolate"></a>

從 [2023 年 7 月 28 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2023-07-28-al2.html)的平台發行開始，*Docker Amazon Linux 2* 平台分支提供 Docker Compose *插補*功能。使用此功能，Compose 檔案中的值可由變數設定，並在執行期進行插補。如需有關此功能的詳細資訊，請參閱 Docker 文件網站上的[插補](https://docs.docker.com/compose/compose-file/12-interpolation/)。

**重要**  
如果想搭配使用此功能與您的應用程式，請注意，您需要實作使用平台勾點的方法。  
這是必要的，因為我們在平台引擎中實作了緩解措施。這種緩解措施可讓不知道新插補功能，且擁有使用環境變數搭配 `$` 字元之現有應用程式的客戶確保回溯相容性。預設情況下，更新後的平台引擎透過將 `$` 字元取代為 `$$` 字元來轉義插補。

以下是平台勾點指令碼範例，您可以將其設定為允許使用插補功能。

```
#!/bin/bash

: '
example data format in .env file
key1=value1
key2=value2
'
envfile="/var/app/staging/.env"
tempfile=$(mktemp)

while IFS= read -r line; do
  # split each env var string at '='
  split_str=(${line//=/ })
  if [ ${#split_str[@]} -eq 2 ]; then
    # replace '$$' with '$'
    replaced_str=${split_str[1]//\$\$/\$}
    # update the value of env var using ${replaced_str}
    line="${split_str[0]}=${replaced_str}"
  fi
  # append the updated env var to the tempfile
  echo "${line}" ≫"${tempfile}"
done < "${envfile}"
# replace the original .env file with the tempfile
mv "${tempfile}" "${envfile}"
```

將平台勾點放在這兩個目錄下：
+ `.platform/confighooks/predeploy/`
+ `.platform/hooks/predeploy/`

如需詳細資訊，請參閱本指南的*擴充 Linux 平台*主題中的 [平台勾點](platforms-linux-extend.hooks.md)。

## 使用 Docker Compose 產生增強型運作狀態報告的日誌
<a name="docker-env-cfg.healthd-logging"></a>

 [Elastic Beanstalk 運作狀態代理程式](health-enhanced.md#health-enhanced-agent)提供 Elastic Beanstalk 環境的作業系統和應用程式運作狀態指標。其依賴以特定格式轉送資訊的 Web 伺服器日誌格式。

Elastic Beanstalk 假設您以容器身分來執行 Web 伺服器 Proxy。因此，針對執行 Docker Compose 的 Docker 環境，已停用 NGINX Web 伺服器 Proxy。您必須將伺服器設為以 Elastic Beanstalk 運作狀態代理程式所使用的位置和格式來寫入日誌。這麼做可讓您即使在已停用 Web 伺服器 Proxy 的狀態下，也能充分利用增強型運作狀態報告。

如需如何執行此動作的詳細資訊，請參閱 [Web 伺服器日誌組態](health-enhanced-serverlogs.md#health-enhanced-serverlogs.configure) 

## 使用 Docker Compose 的 Docker 容器自訂記錄
<a name="docker-env-cfg.dc-customized-logging"></a>

為了有效疑難排解問題，並監控您的容器化服務，您可以透過環境管理主控台或 EB CLI，從 Elastic Beanstalk [要求執行個體日誌](using-features.logging.md)。執行個體日誌由套件日誌和結尾日誌組成，經過組合和封裝，可讓您以有效且直接的方式，檢視日誌和最近的事件。

 Elastic Beanstalk 會在容器執行個體上建立日誌目錄，針對 `docker-compose.yml` 檔案中定義的每個服務建立一個日誌目錄，位置是 `/var/log/eb-docker/containers/<service name>`。如果您在 Amazon Linux 2 Docker 平台上使用 Docker Compose 功能，您可以將這些目錄掛載到容器檔案結構中寫入日誌的位置。當您掛載日誌目錄以寫入日誌資料時，Elastic Beanstalk 可從這些目錄收集日誌資料。

**將服務的日誌檔案設定為可擷取的尾部檔案和套件日誌**

1. 編輯 `docker-compose.yml` 檔案。

1. 在您服務的 `volumes` 金鑰下，將綁定掛載新增至以下內容：

    ` "${EB_LOG_BASE_DIR}/<service name>:<log directory inside container> ` 

   在以下範例 `docker-compose.yml` 檔案中：
   +  `nginx-proxy` 是 *<服務名稱>* 
   +  `/var/log/nginx` 是 *<容器內的日誌目錄>* 

   ```
   services:
     nginx-proxy:
       image: "nginx"
       volumes:
         - "${EB_LOG_BASE_DIR}/nginx-proxy:/var/log/nginx"
   ```


+  `var/log/nginx` 目錄包含容器中 *nginx-proxy* 服務的日誌，其將映射至主機上的 `/var/log/eb-docker/containers/nginx-proxy` 目錄。
+  此目錄中的所有日誌現在可以透過 Elastic Beanstalk 的[請求執行個體日誌](using-features.logging.md)功能，以套件和結尾日誌的形式擷取。



**備註**  
*\$1\$1EB\$1LOG\$1BASE\$1DIR\$1* 是 Elastic Beanstalk 設定的環境變數，具有數值 `/var/log/eb-docker/containers`。
Elastic Beanstalk 會針對 `/var/log/eb-docker/containers/<service name>` 檔案中的每個服務，自動建立 `docker-compose.yml` 目錄。

## Docker 影像
<a name="docker-images"></a>

Elastic Beanstalk 的 Docker 和 ECS 受管 Docker 平台分支可支援使用存放於公有或私有線上映像儲存庫的 Docker 影像。

根據 `Dockerrun.aws.json` 中的名稱來指定映像。請注意這些慣例：
+ Docker Hub 上官方儲存庫中的映像，使用的是單一名稱 (例如，`ubuntu` 或 `mongo`)。
+ Docker Hub 上的其他儲存庫中的映像要求使用組織名稱 (例如，`amazon/amazon-ecs-agent`)。
+ 其他線上儲存庫中的映像更進一步要求使用網域名稱 (例如，`quay.io/assemblyline/ubuntu` 或 `account-id.dkr.ecr.us-east-2.amazonaws.com/ubuntu:trusty`)。

您也可以在環境建立期間，使用 Dockerfile 建置自己的映像。這僅適用於使用 Docker 平台的環境。如需詳細資訊，請參閱「[透過 Dockerfile 建置自訂映像](single-container-docker-configuration.md#single-container-docker-configuration.dockerfile)」。ECS 受管 Docker 平台不支援此功能。

## 為 Docker 環境設定受管更新
<a name="docker-managed-updates"></a>

使用[受管平台更新](environment-platform-update-managed.md)，您可以設定環境，根據排程自動更新至平台的最新版本。

如果是 Docker 環境，您可能會要決定自動平台更新是否應跨 Docker 版本實施 — 當新的平台版本包含新的 Docker 版本時。當從執行 2.9.0 版本以上的 Docker 平台版本的環境更新時，Elastic Beanstalk 支援跨 Docker 版本的受管理平台更新。當新的平台版本包含新版本的 Docker 時，Elastic Beanstalk 便會增加小型更新版本的號碼。因此，要允許跨 Docker 版本的受管平台更新，啟用次要和修補程式版本更新的受管平台更新。要避免跨 Docker 版本的受管平台更新，僅啟用修補程式版本更新的受管平台更新。

例如，以下[組態檔案](ebextensions.md)可讓受管平台於每個星期二的 9:00 AM UTC 為次要與修補程試版本更新，進而允許跨 Docker 版本的受管更新：

**Example .ebextensions/managed-platform-update.config**  

```
option_settings:
  aws:elasticbeanstalk:managedactions:
    ManagedActionsEnabled: true
    PreferredStartTime: "Tue:09:00"
  aws:elasticbeanstalk:managedactions:platformupdate:
    UpdateLevel: minor
```

針對執行 2.9.0 或更早版本 Docker 平台的環境，若新的平台版本包含新的 Docker 版本，則 Elastic Beanstalk 永遠不會執行受管平台更新。

## Docker 組態命名空間
<a name="docker-namespaces"></a>

您可以使用[組態檔案](ebextensions.md)來設定組態選項，並在部署期間執行其他的執行個體設定工作。組態選項可以是[平台特定](command-options-specific.md)選項，也可以套用至 Elastic Beanstalk 服務整體中的所有[平台](command-options-general.md)。組態選項會組織成*命名空間*。

**注意**  
 此資訊僅適用於未執行 Docker Compose 的 Docker 環境。此選項與執行 Docker Compose 的 Docker 環境有不同的行為。如需使用 Docker Compose 之 Proxy 服務的詳細資訊，請參閱 [容器選項](#docker-software-config.container)。

除了[適用於所有 Elastic Beanstalk 環境的支援選項](command-options-general.md)之外，Docker 也支援使用下列命名空間的選項：
+ `aws:elasticbeanstalk:environment:proxy` – 選擇適用於您環境的代理伺服器。Docker 支援執行 Nginx 或沒有代理伺服器。

下列範例配置檔案會將 Docker 環境設定為在沒有代理伺服器的情況下運作。

**Example .ebextensions/docker-settings.config**  

```
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: none
```

## Amazon Linux AMI (Amazon Linux 2 之前的版本) 上的 Docker 組態
<a name="docker-alami"></a>

如果您的 Elastic Beanstalk Docker 環境使用 Amazon Linux AMI 平台版本 (之前的 Amazon Linux 2)，請閱讀本節中的其他資訊。

### 使用私有儲存庫的身分驗證檔案
<a name="docker-alami.images-private"></a>

如果您要[使用私有儲存庫的映像](docker-configuration.remote-repo.md)，則此資訊與您相關。自 Docker 版本 1.7 起，**docker login** 命令會變更身分驗證檔案的名稱和檔案格式。Amazon Linux AMI Docker 平台版本 (Amazon Linux 2 之前的版本) 需要較舊的 `~/.dockercfg` 格式組態檔案。

若使用 Docker 版本 1.7 和更新版本，**docker login** 命令會於 `~/.docker/config.json` 建立身分驗證檔案，格式如下。

```
{
    "auths":{
      "server":{
        "auth":"key"
      }
    }
  }
```

若使用 Docker 版本 1.6.2 和更早版本，**docker login** 命令會於 `~/.dockercfg` 建立身分驗證檔案，格式如下。

```
{
    "server" :
    {
      "auth" : "auth_token",
      "email" : "email"
    }
  }
```

欲轉換 `config.json` 檔案，請移除外部 `auths` 金鑰、新增 `email` 金鑰並平展 JSON 文件，以符合舊的格式。

在 Amazon Linux 2 Docker 平台版本上，Elastic Beanstalk 會使用較新的身分驗證檔案名稱和格式。如果您使用的是 Amazon Linux 2 Docker 平台版本，則可以使用 **docker login** 命令建立的身分驗證檔案，而無需進行任何轉換。

### 設定其他儲存磁碟區
<a name="docker-alami.volumes"></a>

為了提高 Amazon Linux AMI 的效能，Elastic Beanstalk 為您 Docker 環境的 Amazon EC2 執行個體設定兩個 Amazon EBS 儲存磁碟區。除了所有 Elastic Beanstalk 環境佈建的根磁碟區，Docker 環境會佈建第二個名為 `xvdcz` 的 12GB 磁碟區供映像儲存使用。

若您需要更多儲存空間或增加 IOPS 供 Docker 影像使用，您可於 [aws:autoscaling:launchconfiguration](command-options-general.md#command-options-general-autoscalinglaunchconfiguration) 命名空間使用 `BlockDeviceMapping` 組態選項，藉此自訂映像儲存磁碟區。

例如，下列[組態檔案](ebextensions.md)會將儲存磁碟區的大小提高為 100 GB，而佈建 IOPS 為 500：

**Example .ebextensions/blockdevice-xvdcz.config**  

```
option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:100::io1:500
```

若您使用 `BlockDeviceMappings` 選項來設定您應用程式的其他磁碟區，您應該納入 `xvdcz` 的映射，以確保該磁碟區已建立。下列範例設定兩個磁碟區，一個為使用預設設定的映像儲存磁碟區 `xvdcz`，另一個則是名為 `sdh` 的額外 24 GB 應用程式磁碟區：

**Example .ebextensions/blockdevice-sdh.config**  

```
option_settings:
  aws:autoscaling:launchconfiguration:
    BlockDeviceMappings: /dev/xvdcz=:12:true:gp2,/dev/sdh=:24
```

**注意**  
當於此命名空間變更設定時，Elastic Beanstalk 會將您環境中的所有執行個體，替換為執行新組態的執行個體。如需詳細資訊，請參閱「[組態變更](environments-updating.md)」。