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

# 扩展 Elastic Beanstalk Linux 平台
<a name="platforms-linux-extend"></a>

本主题介绍如何使用您自己的命令、脚本、软件和配置来扩展您的 Linux 平台。您可能需要扩展您的平台才能更改默认代理服务器和配置。或者，您可能需要自定义平台如何构建或启动您的应用程序。

**Topics**
+ [Buildfile 和 Procfile](platforms-linux-extend.build-proc.md)
+ [平台挂钩](platforms-linux-extend.hooks.md)
+ [配置文件](platforms-linux-extend.config-files.md)
+ [反向代理配置](platforms-linux-extend.proxy.md)
+ [带扩展功能的应用程序示例](platforms-linux-extend.example.md)

# Buildfile 和 Procfile
<a name="platforms-linux-extend.build-proc"></a>

某些平台允许您自定义如何构建或准备应用程序，并指定运行应用程序的进程。如果平台支持 *Buildfile and/or *Proc* file*，则每个单独的平台主题都会特别提及它们。在 [Elastic Beanstalk 平台](concepts-all-platforms.md) 下查找您的特定平台。

对于所有支持的平台，语法和语义是相同的，如本页所述。各个平台主题都提到了这些文件在以各自的语言构建和运行应用程序时的特定用法。

## Buildfile
<a name="platforms-linux-extend.build"></a>

要为应用程序指定自定义构建和配置命令，请将名为 `Buildfile` 的文件放置在应用程序源的根目录中。文件名区分大小写。`Buildfile` 使用以下语法。

```
<process_name>: <command>
```

`Buildfile` 中的命令必须符合以下正则表达式：`^[A-Za-z0-9_-]+:\s*[^\s].*$`

Elastic Beanstalk 不会监控通过 `Buildfile` 运行的应用程序。对于短期运行并在完成任务后终止的命令，请使用 `Buildfile`。对于长期运行、不应退出的应用程序进程，请使用 [Procfile](#platforms-linux-extend.proc)。

`Buildfile` 中的所有路径都是源包根目录的相对路径。在下面的 `Buildfile` 示例中，`build.sh` 是位于源包根目录的 Shell 脚本。

**Example Buildfile**  

```
make: ./build.sh
```

如果您想提供自定义构建步骤，我们建议您将 `predeploy` 平台挂钩用于除最简单的命令之外的任何内容，而不是 `Buildfile`。通过平台挂钩可以使用更丰富的脚本，并且能更好地进行错误处理。平台挂钩将在下一节中介绍。

## Procfile
<a name="platforms-linux-extend.proc"></a>

要指定自定义命令以便启动和运行应用程序，请将名为 `Procfile` 的文件放置在应用程序源的根目录中。文件名区分大小写。`Procfile` 使用以下语法。您可以指定一个或多个命令。

```
<process_name1>: <command1>
<process_name2>: <command2>
...
```

`Procfile` 中的每一行都必须符合以下正则表达式：`^[A-Za-z0-9_-]+:\s*[^\s].*$`

对于长期运行、不应退出的应用程序进程，请使用 `Procfile`。Elastic Beanstalk 希望从 `Procfile` 运行的进程一直运行。Elastic Beanstalk 会监控这些进程并重启所有终止的进程。对于短期运行的进程，请使用 [Buildfile](#platforms-linux-extend.build)。

`Procfile` 中的所有路径都是源包根目录的相对路径。以下示例 `Procfile` 定义了三个进程。第一个进程在该示例中称为 `web`，它是*主要 Web 应用程序*。

**Example Procfile**  

```
web: bin/myserver
cache: bin/mycache
foo: bin/fooapp
```

Elastic Beanstalk 将代理服务器配置为将请求转发到端口 5000 上的主 Web 应用程序，并且您可以配置此端口号。`Procfile` 的常见用途是将此端口号作为命令参数传递给应用程序。有关代理配置的详细信息，请参阅 [反向代理配置](platforms-linux-extend.proxy.md)。

Elastic Beanstalk 将 `Procfile` 进程的标准输出和错误流捕获到日志文件中。Elastic Beanstalk 根据进程名称命名日志文件并将其存储在 `/var/log` 中。例如，上例中的 `web` 进程分别为 `web-1.log` 和 `web-1.error.log` 生成名为 `stdout` 和 `stderr` 的日志。

# 平台挂钩
<a name="platforms-linux-extend.hooks"></a>

平台挂钩是专为扩展您的环境平台而设计的。这些自定义脚本和其他可执行文件部署为应用程序源代码的一部分，并由 Elastic Beanstalk 在不同的实例预置阶段运行。

**注意**  
Amazon Linux AMI 平台版本（Amazon Linux 2 之前的版本）不支持平台挂钩。

## 应用程序部署平台挂钩
<a name="platforms-linux-extend.hooks.appdeploy"></a>

当您提供新的源包进行部署时，或者当您进行的配置更改要求终止和重新创建所有环境实例时，将发生*应用程序部署*。

要提供在应用程序部署期间运行的平台挂钩，请将文件放在源包中的 `.platform/hooks` 目录下（位于以下子目录之一中）。
+ `prebuild` – 此处的文件在 Elastic Beanstalk 平台引擎下载和提取应用程序源包之后且在设置和配置应用程序和 Web 服务器之前运行。

  `prebuild` 文件在运行任何配置文件的 [commands](customize-containers-ec2.md#linux-commands) 部分中的命令之后且在运行 `Buildfile` 命令之前运行。
+ `predeploy` – 此处的文件在 Elastic Beanstalk 平台引擎设置和配置应用程序及 Web 服务器之后且在将它们部署到其最终运行时位置之前运行。

  `predeploy` 文件在运行任何配置文件的 [container\$1commands](customize-containers-ec2.md#linux-container-commands) 部分中的命令之后且在运行 `Procfile` 命令之前运行。
+ `postdeploy` – 此处的文件在 Elastic Beanstalk 平台引擎部署应用程序和代理服务器之后运行。

  这是最后一个部署工作流步骤。

## 配置部署平台挂钩
<a name="platforms-linux-extend.hooks.configdeploy"></a>

如果您进行的配置更改仅更新环境实例而不重新创建环境实例，则会发生*配置部署*。以下选项更新会导致配置更新。
+ [环境属性和特定于平台的设置](environments-cfg-softwaresettings.md)
+ [静态文件](environment-cfg-staticfiles.md)
+ [AWS X-Ray 守护程序](environment-configuration-debugging.md)
+ [日志存储和流式处理](environments-cfg-logging.md)
+ 应用程序端口（有关详细信息，请参阅 [反向代理配置](platforms-linux-extend.proxy.md)）

要提供在配置部署期间运行的挂钩，请将它们放在源包中的 `.platform/confighooks` 目录下。应用与应用程序部署挂钩相同的三个子目录。

## 有关平台挂钩的更多信息
<a name="platforms-linux-extend.hooks.more"></a>

挂钩文件可以是二进制文件，也可以是以包含其解释器路径的 `#!` 行开头的脚本文件，例如 `#!/bin/bash`。所有文件都必须具有执行权限。使用 `chmod +x` 对挂钩文件设置执行权限。对于 2022 年 4 月 29 日或之后发布的所有基于 Amazon Linux 2023 和 Amazon Linux 2 的平台版本，Elastic Beanstalk 会自动向所有平台挂钩脚本授予执行权限。在这种情况下，您无需手动授予执行权限。有关这些平台版本的列表，请参阅《*AWS Elastic Beanstalk 发布说明指南*》中的 [2022 年 4 月 29 日 ](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2022-04-29-linux.html#release-2022-04-29-linux.platforms) Linux 发布说明。

Elastic Beanstalk 按照文件名的字母表顺序运行上述每个目录中的文件。所有文件都以 `root` 用户身份运行。平台挂钩的当前工作目录 (cwd) 是应用程序的根目录。对于 `prebuild` 和 `predeploy` 文件，该目录是应用程序暂存目录，对于 `postdeploy` 文件，该目录是当前应用程序目录。如果其中一个文件失败（以非零退出代码退出），则部署中止并失败。

如果平台挂钩文本脚本包含 Windows *回车符/换行符* (CRLF) 换行符，则该脚本可能会失败。如果某文件保存在 Windows 主机中，然后传输到 Linux 服务器，则它可能包含 Windows CRLF 换行符。对于 [2022 年 12 月 29 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2022-12-29-linux.html)当天或之后发布的平台，Elastic Beanstalk 会自动将 Windows CRLF 字符转换为平台挂钩文本文件中的 Linux *换行符* (LF) 换行符。如果应用程序在此日期之前发布的任何 Amazon Linux 2 平台上运行，则需要将 Windows CRLF 字符转换为 Linux LF 字符。实现此目的的一种方法是在 Linux 主机上创建并保存脚本文件。互联网上也提供了转换这些字符的工具。

挂钩文件可以访问您在应用程序选项中定义的所有环境属性和系统环境变量 `HOME`、`PATH` 和 `PORT`。

要将环境变量和其他配置选项的值添加到平台挂钩脚本中，您可以使用 Elastic Beanstalk 在环境实例上提供的 `get-config` 实用程序。有关更多信息，请参阅 [适用于 Elastic Beanstalk 环境的平台脚本工具](custom-platforms-scripts.md)。

# 配置文件
<a name="platforms-linux-extend.config-files"></a>

您可以将[配置文件](ebextensions.md)添加到应用程序源代码的 `.ebextensions` 目录中，以配置 Elastic Beanstalk 环境的各个方面。此外，配置文件还允许您自定义环境实例上的软件和其他文件，并在实例上运行初始化命令。有关更多信息，请参阅 [自定义 Linux 服务器上的软件](customize-containers-ec2.md)。

您还可以使用配置文件设置[配置选项](command-options.md)。许多选项控制平台行为，其中的某些选项是[平台特定选项](command-options-specific.md)。

对于基于 Amazon Linux 2 和 Amazon Linux 2023 的平台，我们建议在实例预置期间使用 *Buildfile*、*Procfile* 和*平台挂钩*在环境实例上配置和运行自定义代码。本页上前面的部分中描述了这些机制。您仍可以在 `.ebextensions` 配置文件中使用命令和容器命令，但这并不简单。例如，从语法角度而言，在 YAML 文件中编写命令脚本可能面临挑战。对于任何需要引用 AWS CloudFormation 资源的脚本，您仍然需要使用`.ebextensions`配置文件。

# 反向代理配置
<a name="platforms-linux-extend.proxy"></a>

所有 Amazon Linux 2 和 Amazon Linux 2023 平台版本都使用 nginx 作为其默认的反向代理服务器。Tomcat、Node.js、PHP 和 Python 平台也支持将 Apache HTTPD 作为替代方案。要在这些平台上选择 Apache，请将 `aws:elasticbeanstalk:environment:proxy` 命名空间中的 `ProxyServer` 选项设置为 `apache`。所有平台都以一致的方式启用代理服务器配置，如本节所述。

**注意**  
在 Amazon Linux AMI 平台版本（Amazon Linux 2 之前的版本），您需要以不同的方式配置代理服务器。您可以在本指南中的[相应平台主题](concepts-all-platforms.md)下找到这些旧的详细信息。

Elastic Beanstalk 在环境实例上将代理服务器配置为向环境根 URL 的主要 Web 应用程序转发 Web 流量；例如，`http://my-env.elasticbeanstalk.com`。

默认情况下，Elastic Beanstalk 将代理配置为通过端口 5000 向主要 Web 应用程序转发 80 端口上的传入请求。通过使用配置文件中的 [aws:elasticbeanstalk:application:environment](command-options-general.md#command-options-general-elasticbeanstalkapplicationenvironment) 命名空间来设置 `PORT` 环境属性，您可以配置此端口号，如以下示例所示。

```
option_settings:
  - namespace:  aws:elasticbeanstalk:application:environment
    option_name:  PORT
    value:  <main_port_number>
```

有关设置应用程序环境变量的更多信息，请参阅[选项设置](ebextensions-optionsettings.md)。

您的应用程序应侦听代理中为其配置的端口。如果使用 `PORT` 环境属性更改默认端口，代码可以通过读取 `PORT` 环境变量的值来访问该端口。例如，在 Go 中调用 `os.Getenv("PORT")`，或者在 Java 中调用 `System.getenv("PORT")`。如果您将代理配置为向多个应用程序进程发送流量，则可以配置多个环境属性，并在代理配置和应用程序代码中使用它们的值。另一种选择是将端口值作为 `Procfile` 中的命令参数传递给进程。有关更多信息，请参阅 [Buildfile 和 Procfile](platforms-linux-extend.build-proc.md)。

## 配置 nginx
<a name="platforms-linux-extend.proxy.nginx"></a>

Elastic Beanstalk 使用 nginx 作为默认反向代理，将应用程序映射到 Elastic Load Balancing 负载均衡器。Elastic Beanstalk 提供一个默认 nginx 配置，您可以扩展该配置，或者将其完全替换为您自己的配置。

**注意**  
添加或编辑 nginx `.conf` 配置文件时，请务必将其编码为 UTF-8。

要扩展 Elastic Beanstalk 的默认 nginx 配置，请将 `.conf` 配置文件添加到您的应用程序源包的 `.platform/nginx/conf.d/` 文件夹中。Elastic Beanstalk nginx 配置自动在此文件夹中包括 `.conf` 文件。

```
~/workspace/my-app/
|-- .platform
|   `-- nginx
|       `-- conf.d
|           `-- myconf.conf
`-- other source files
```

`.platform/nginx/conf.d/` 中的配置文件包含在 nginx 配置的 `http` 块中。请将全局适用的配置存储在此位置。

若要扩展默认的 nginx `server` 块配置，请将 `.conf` 配置文件添加到您应用程序源捆绑包中名为 `.platform/nginx/conf.d/elasticbeanstalk/` 的文件夹中。Elastic Beanstalk nginx 配置包含 `server` 块中此文件夹中的 `.conf` 文件。

```
~/workspace/my-app/
|-- .platform
|   `-- nginx
|       `-- conf.d
|           `-- elasticbeanstalk
|               `-- server.conf
`-- other source files
```

使用此位置添加服务器特定的配置，例如其他位置块、自定义错误页面或服务器级指令。以下示例添加了一个自定义位置块。

**Example 。 platform/nginx/conf.d/elasticbeanstalk/server.conf**  

```
location /test {
    return 200 "Hello World!";
    add_header Content-Type text/plain;
}
```

要完全覆盖 Elastic Beanstalk 默认 nginx 配置，请在您的源包的 `.platform/nginx/nginx.conf` 处包含一个配置：

```
~/workspace/my-app/
|-- .platform
|   `-- nginx
|       `-- nginx.conf
`-- other source files
```

如果要覆盖 Elastic Beanstalk nginx 配置，请将以下行添加到 `nginx.conf`，以便加入适用于 [Elastic Beanstalk 中的增强型运行状况报告和监控](health-enhanced.md)、自动应用程序映射和静态文件的 Elastic Beanstalk 配置。

```
 include conf.d/elasticbeanstalk/*.conf;
```

## 配置 Apache HTTPD
<a name="platforms-linux-extend.proxy.httpd"></a>

Tomcat、Node.js、PHP 和 Python 平台允许您选择 Apache HTTPD 代理服务器作为 nginx 的替代方案。这不是默认值。以下示例将 Elastic Beanstalk 配置为使用 Apache HTTPD。

**Example .ebextensions/httpd-proxy.config**  

```
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: apache
```
您可以使用其他配置文件扩展 Elastic Beanstalk 默认 Apache 配置。也可以完全覆盖 Elastic Beanstalk 默认 Apache 配置。  
要扩展 Elastic Beanstalk 默认 Apache 配置，请将 `.conf` 配置文件添加到应用程序源包中名为 `.platform/httpd/conf.d` 的文件夹中。Elastic Beanstalk Apache 配置自动在此文件夹中包括 `.conf` 文件。  

```
~/workspace/my-app/
|-- .ebextensions
|   -- httpd-proxy.config
|-- .platform
|   -- httpd
|      -- conf.d
|         -- port5000.conf
|         -- ssl.conf
-- index.jsp
```
例如，以下 Apache 2.4 配置将在端口 5000 上添加一个监听器。  

**Example 。 platform/httpd/conf.d/port5000.conf**  

```
listen 5000
<VirtualHost *:5000>
  <Proxy *>
    Require all granted
  </Proxy>
  ProxyPass / http://localhost:8080/ retry=0
  ProxyPassReverse / http://localhost:8080/
  ProxyPreserveHost on

  ErrorLog /var/log/httpd/elasticbeanstalk-error_log
</VirtualHost>
```
要完全覆盖 Elastic Beanstalk 默认 Apache 配置，请在源包的 `.platform/httpd/conf/httpd.conf` 处包括一个配置。  

```
~/workspace/my-app/
|-- .ebextensions
|   -- httpd-proxy.config
|-- .platform
|   `-- httpd
|       `-- conf
|           `-- httpd.conf
`-- index.jsp
```
如果要覆盖 Elastic Beanstalk Apache 配置，请将以下行添加到 `httpd.conf`，以便加入适用于 [Elastic Beanstalk 中的增强型运行状况报告和监控](health-enhanced.md)、自动应用程序映射和静态文件的 Elastic Beanstalk 配置。  

```
IncludeOptional conf.d/elasticbeanstalk/*.conf
```

# 带扩展功能的应用程序示例
<a name="platforms-linux-extend.example"></a>

以下示例演示一个应用程序源包，其中包含 Elastic Beanstalk Amazon Linux 2 和 Amazon Linux 2023 平台支持的多个可扩展性功能：`Procfile`、`.ebextensions` 配置文件、自定义挂钩和代理配置文件。

```
~/my-app/
|-- web.jar
|-- Procfile
|-- readme.md
|-- .ebextensions/
|   |-- options.config        # Option settings
|   `-- cloudwatch.config     # Other .ebextensions sections, for example files and container commands
`-- .platform/
    |-- nginx/                # Proxy configuration
    |   |-- nginx.conf
    |   `-- conf.d/
    |       |-- custom.conf
    |       `-- elasticbeanstalk/
    |           `-- server.conf
    |-- hooks/                # Application deployment hooks
    |   |-- prebuild/
    |   |   |-- 01_set_secrets.sh
    |   |   `-- 12_update_permissions.sh
    |   |-- predeploy/
    |   |   `-- 01_some_service_stop.sh
    |   `-- postdeploy/
    |       |-- 01_set_tmp_file_permissions.sh
    |       |-- 50_run_something_after_app_deployment.sh
    |       `-- 99_some_service_start.sh
    `-- confighooks/          # Configuration deployment hooks
        |-- prebuild/
        |   `-- 01_set_secrets.sh
        |-- predeploy/
        |   `-- 01_some_service_stop.sh
        `-- postdeploy/
            |-- 01_run_something_after_config_deployment.sh
            `-- 99_some_service_start.sh
```

**注意**  
Amazon Linux AMI 平台版本（Amazon Linux 2 以前的版本）不支持其中一些扩展。