本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 配置 Elastic Beanstalk Docker 环境
<a name="create_deploy_docker.container.console"></a>

本章介绍所有受支持的 Docker 平台分支（包括 ECS 托管 Docker 平台分支）的附加配置信息。除非某节中确定了特定平台分支或平台分支组件，否则它适用于运行受支持的 Docker 和 ECS 管理的 Docker 平台的所有环境。

**注意**  
如果您的 Elastic Beanstalk 环境使用 Amazon Linux AMI Docker 平台版本（在 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. 在导航窗格中，选择 **Environments**（环境），然后从列表中选择环境的名称。

1. 在导航窗格中，选择 **Configuration**（配置）。

1. 在 **Updates, monitoring, and logging**（更新、监控和日志记录）配置类别中，选择 **Edit**（编辑）。

1. 进行必要的配置更改。

1. 要保存更改，请选择页面底部的 **Apply**（应用）。

有关在任何环境中配置软件设置的信息，请参阅[环境变量和其他软件设置](environments-cfg-softwaresettings.md)。以下各部分介绍特定于 Docker 的信息。

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

**容器选项**部分具有特定于平台的选项。对于 Docker 环境，它允许您选择您的环境是否包含 NGINX 代理服务器。

**使用 Docker Compose 的环境**  
如果您使用 Docker Compose 管理 Docker 环境，Elastic Beanstalk 假定您将代理服务器作为容器运行。因此，对于**代理服务器**设置，它默认为**无**，Elastic Beanstalk 不提供 NGINX 配置。

**注意**  
即使您选择 **NGINX** 作为代理服务器，也会在使用 Docker Compose 的环境中忽略此设置。**代理服务器**设置仍默认为**无**。

由于对于使用 Docker Compose 的 Amazon Linux 2 平台上的 Docker 已禁用 NGINX Web 服务器代理，因此您必须按照为增强型运行状况报告生成日志的说明操作。有关更多信息，请参阅 [利用 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 Systems Manager 引 AWS Secrets Manager 用和参数存储数据的功能。此功能可以让您的应用程序安全地原生访问这些服务存储的密钥和参数，无需管理对这些密钥和参数的 API 调用。只有 [2025 年 3 月 26 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2025-03-26-windows.html)当天或之后发布的 Elastic Beanstalk Docker 和 ECS 托管 Docker 平台，才支持此功能。有关使用环境变量来引用密钥的更多信息，请参阅[为 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>

*Docker Amazon Linux 2* 平台分支从 [2023 年 7 月 28 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2023-07-28-al2.html)平台版本发布起，提供 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 服务器代理作为容器运行。因此，对于运行 Docker Compose 的 Docker 环境禁用 NGINX Web 服务器代理。您必须将服务器配置为以 Elastic Beanstalk 运行状况代理所使用的位置和格式写入日志。这样就可以充分利用增强型运行状况报告，即使禁用了 Web 服务器代理也是如此。

有关如何执行此操作的说明，请参阅[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` 是 *<service name>* 
   +  `/var/log/nginx` 是 *<log directory inside container>* 

   ```
   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`) 进行进一步限定。

对于仅使用 Docker 平台的环境，您还可以在创建环境期间使用 Dockerfile 构建自己的映像。有关更多信息，请参阅 [使用 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 (UTC) 启用次版本更新和修补版本更新，从而允许跨 Docker 版本的托管更新：

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

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

对于运行 Docker 平台版本 2.9.0 或更早版本的环境，在新平台版本包括新 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 的代理服务的更多信息，请参阅 [容器选项](#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 环境中的映像存储预配置了第二个 12GB 的卷（名为 `xvdcz`）。

如果您需要为 Docker 映像增加存储空间或者提高 IOPS，可以使用 [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)。