扩展 Elastic Beanstalk Linux 平台
Amazon Elastic Beanstalk Linux 平台提供了许多开箱即用的功能,以支持您的应用程序的开发和运行。您可以根据需要通过多种方式扩展平台,以配置选项、安装软件、添加文件和启动命令、提供构建和运行时说明,以及添加在环境 Amazon Elastic Compute Cloud (Amazon EC2) 实例的不同预配置阶段运行的初始化脚本。
某些平台允许您自定义如何构建或准备应用程序,并指定运行应用程序的进程。每个平台主题都特别提到 Buildfile 和/或 Procfile(如果平台支持)。在 Elastic Beanstalk 平台 下查找您的特定平台。
对于所有支持的平台,语法和语义是相同的,如本页所述。各个平台主题都提到了这些文件在以各自的语言构建和运行应用程序时的特定用法。
Buildfile
要为应用程序指定自定义构建和配置命令,请将名为 Buildfile
的文件放置在应用程序源的根目录中。文件名区分大小写。Buildfile
使用以下语法。
<process_name>
: <command>
Buildfile
中的命令必须符合以下正则表达式:^[A-Za-z0-9_-]+:\s*[^\s].*$
Elastic Beanstalk 不会监控通过 Buildfile
运行的应用程序。对于短期运行并在完成任务后终止的命令,请使用 Buildfile
。对于长期运行、不应退出的应用程序进程,请使用 Procfile。
Buildfile
中的所有路径都是源包根目录的相对路径。在下面的 Buildfile
示例中,build.sh
是位于源包根目录的 Shell 脚本。
例 Buildfile
make: ./build.sh
如果您想提供自定义构建步骤,我们建议您将 predeploy
平台挂钩用于除最简单的命令之外的任何内容,而不是 Buildfile
。通过平台挂钩可以使用更丰富的脚本,并且能更好地进行错误处理。平台挂钩将在下一节中介绍。
Procfile
要指定自定义命令以便启动和运行应用程序,请将名为 Procfile
的文件放置在应用程序源的根目录中。文件名区分大小写。Procfile
使用以下语法。您可以指定一个或多个命令。
<process_name1>
: <command1>
<process_name2>
: <command2>
...
Procfile
中的每一行都必须符合以下正则表达式:^[A-Za-z0-9_-]+:\s*[^\s].*$
对于长期运行、不应退出的应用程序进程,请使用 Procfile
。Elastic Beanstalk 希望从 Procfile
运行的进程一直运行。Elastic Beanstalk 会监控这些进程并重启所有终止的进程。对于短期运行的进程,请使用 Buildfile。
Procfile
中的所有路径都是源包根目录的相对路径。以下示例 Procfile
定义了三个进程。第一个进程在该示例中称为 web
,它是主要 Web 应用程序。
例 Procfile
web: bin/myserver
cache: bin/mycache
foo: bin/fooapp
Elastic Beanstalk 将代理服务器配置为将请求转发到端口 5000 上的主 Web 应用程序,并且您可以配置此端口号。Procfile
的常见用途是将此端口号作为命令参数传递给应用程序。有关代理配置的详细信息,请展开此页上的反向代理配置部分。
Elastic Beanstalk 将 Procfile
进程的标准输出和错误流捕获到日志文件中。Elastic Beanstalk 根据进程名称命名日志文件并将其存储在 /var/log
中。例如,上例中的 web
进程分别为 web-1.log
和 web-1.error.log
生成名为 stdout
和 stderr
的日志。
平台挂钩是专为扩展您的环境平台而设计的。这些自定义脚本和其他可执行文件部署为应用程序源代码的一部分,并由 Elastic Beanstalk 在不同的实例预置阶段运行。
注意
Amazon Linux AMI 平台版本(Amazon Linux 2 之前的版本)不支持平台挂钩。
应用程序部署平台挂钩
当您提供新的源包进行部署时,或者当您进行的配置更改要求终止和重新创建所有环境实例时,将发生应用程序部署。
要提供在应用程序部署期间运行的平台挂钩,请将文件放在源包中的 .platform/hooks
目录下(位于以下子目录之一中)。
-
prebuild
– 此处的文件在 Elastic Beanstalk 平台引擎下载和提取应用程序源包之后且在设置和配置应用程序和 Web 服务器之前运行。prebuild
文件在运行任何配置文件的 commands 部分中的命令之后且在运行Buildfile
命令之前运行。 -
predeploy
– 此处的文件在 Elastic Beanstalk 平台引擎设置和配置应用程序及 Web 服务器之后且在将它们部署到其最终运行时位置之前运行。predeploy
文件在运行任何配置文件的 container_commands 部分中的命令之后且在运行Procfile
命令之前运行。 -
postdeploy
– 此处的文件在 Elastic Beanstalk 平台引擎部署应用程序和代理服务器之后运行。这是最后一个部署工作流步骤。
配置部署平台挂钩
如果您进行的配置更改仅更新环境实例而不重新创建环境实例,则会发生配置部署。以下选项更新会导致配置更新。
-
应用程序端口(有关详细信息,请展开此页上的反向代理配置部分)
要提供在配置部署期间运行的挂钩,请将它们放在源包中的 .platform/confighooks
目录下。应用与应用程序部署挂钩相同的三个子目录。
有关平台挂钩的更多信息
挂钩文件可以是二进制文件,也可以是以包含其解释器路径的 #!
行开头的脚本文件,例如 #!/bin/bash
。所有文件都必须具有执行权限。使用 chmod +x
对挂钩文件设置执行权限。对于 2022 年 4 月 29 日或之后发布的所有基于 Amazon Linux 2 的平台版本,Elastic Beanstalk 会自动向所有平台挂钩脚本授予执行权限。在这种情况下,您无需手动授予执行权限。有关这些平台版本的列表,请参阅《Amazon Elastic Beanstalk 发布说明指南》中的 2022 年 4 月 29 日 Linux 发布说明。
Elastic Beanstalk 按照文件名的字母表顺序运行上述每个目录中的文件。所有文件都以 root
用户身份运行。平台挂钩的当前工作目录 (cwd) 是应用程序的根目录。对于 prebuild
和 predeploy
文件,该目录是应用程序暂存目录,对于 postdeploy
文件,该目录是当前应用程序目录。如果其中一个文件失败(以非零退出代码退出),则部署中止并失败。
如果平台挂钩文本脚本包含 Windows 回车符/换行符 (CRLF) 换行符,则该脚本可能会失败。如果某文件保存在 Windows 主机中,然后传输到 Linux 服务器,则它可能包含 Windows CRLF 换行符。对于 2022 年 12 月 29 日当天或之后发布的平台,Elastic Beanstalk 会自动将 Windows CRLF 字符转换为平台挂钩文本文件中的 Linux 换行符 (LF) 换行符。如果应用程序在此日期之前发布的任何 Amazon Linux 2 平台上运行,则需要将 Windows CRLF 字符转换为 Linux LF 字符。实现此目的的一种方法是在 Linux 主机上创建并保存脚本文件。互联网上也提供了转换这些字符的工具。
挂钩文件可以访问您在应用程序选项中定义的所有环境属性和系统环境变量 HOME
、PATH
和 PORT
。
要将环境变量和其他配置选项的值添加到平台挂钩脚本中,您可以使用 Elastic Beanstalk 在环境实例上提供的 get-config
实用程序。有关详细信息,请参阅 平台脚本工具。
您可以将配置文件添加到应用程序源代码的 .ebextensions
目录中,以配置 Elastic Beanstalk 环境的各个方面。此外,配置文件还允许您自定义环境实例上的软件和其他文件,并在实例上运行初始化命令。有关更多信息,请参阅自定义 Linux 服务器上的软件。
您还可以使用配置文件设置配置选项。许多选项控制平台行为,其中的某些选项是平台特定选项。
在 Amazon Linux 2 平台上,我们建议在实例预置期间使用 Buildfile、Procfile 和平台挂钩在环境实例上配置和运行自定义代码。本页上前面的部分中描述了这些机制。您仍可以在 .ebextensions
配置文件中使用命令和容器命令,但这并不简单。例如,从语法角度而言,在 YAML 文件中编写命令脚本可能面临挑战。对于需要引用 Amazon CloudFormation 资源的任何脚本,您仍需要使用 .ebextensions
配置文件。
所有 Amazon Linux 2 平台版本都使用 nginx 作为其默认的反向代理服务器。Tomcat、Node.js、PHP 和 Python 平台也支持将 Apache HTTPD 作为替代方案。要在这些平台上选择 Apache,请将 aws:elasticbeanstalk:environment:proxy
命名空间中的 ProxyServer
选项设置为 apache
。所有平台都以一致的方式启用代理服务器配置,如本节所述。
注意
在 Amazon Linux AMI 平台版本(Amazon Linux 2 之前的版本),您需要以不同的方式配置代理服务器。您可以在本指南中的相应平台主题下找到这些旧的详细信息。
Elastic Beanstalk 在环境实例上将代理服务器配置为向环境根 URL 的主要 Web 应用程序转发 Web 流量;例如,http://my-env.elasticbeanstalk.com
。
默认情况下,Elastic Beanstalk 将代理配置为通过端口 5000 向主要 Web 应用程序转发 80 端口上的传入请求。通过使用配置文件中的 aws:elasticbeanstalk:application:environment 命名空间来设置 PORT
环境属性,您可以配置此端口号,如以下示例所示。
option_settings:
- namespace: aws:elasticbeanstalk:application:environment
option_name: PORT
value: <main_port_number>
有关设置应用程序环境变量的更多信息,请参阅选项设置。
您的应用程序应侦听代理中为其配置的端口。如果使用 PORT
环境属性更改默认端口,代码可以通过读取 PORT
环境变量的值来访问该端口。例如,在 Go 中调用 os.Getenv("PORT")
,或者在 Java 中调用 System.getenv("PORT")
。如果您将代理配置为向多个应用程序进程发送流量,则可以配置多个环境属性,并在代理配置和应用程序代码中使用它们的值。另一种选择是将端口值作为 Procfile
中的命令参数传递给进程。有关详细信息,请展开此页上的 Buildfile 和 Procfile 部分。
配置 nginx
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
要完全覆盖 Elastic Beanstalk 默认 nginx 配置,请在您的源包的 .platform/nginx/nginx.conf
处包含一个配置:
~/workspace/my-app/
|-- .platform
| `-- nginx
| `-- nginx.conf
`-- other source files
如果要覆盖 Elastic Beanstalk nginx 配置,请将以下行添加到 nginx.conf
,以便加入适用于 增强型运行状况报告和监控、自动应用程序映射和静态文件的 Elastic Beanstalk 配置。
include conf.d/elasticbeanstalk/*.conf;
配置 Apache HTTPD
Tomcat、Node.js、PHP 和 Python 平台允许您选择 Apache HTTPD 代理服务器作为 nginx 的替代方案。这不是默认值。以下示例将 Elastic Beanstalk 配置为使用 Apache HTTPD。
例 .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 上添加一个监听器。
例 .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 配置。
IncludeOptional conf.d/elasticbeanstalk/*.conf
注意
如果您要将 Elastic Beanstalk 应用程序迁移到 Amazon Linux 2 平台,请务必阅读将 Elastic Beanstalk Linux 应用程序迁移到 Amazon Linux 2 中的信息。
带扩展功能的应用程序示例
以下示例演示一个应用程序源包,其中包含 Elastic Beanstalk Amazon Linux 2 平台支持的多个可扩展性功能: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
|-- 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 以前的版本)不支持其中一些扩展。
实例部署工作流
注意
本节信息不适用于在 Amazon Linux 2 上运行的 ECS 平台分支。有关更多信息,请参阅下一部分在 Amazon Linux 2 上运行的 ECS 的实例部署工作流。
有多种扩展环境平台的方法,对于了解 Elastic Beanstalk 在预配置实例或向实例运行部署时会发生什么情况非常有用。下图显示了整个部署工作流程。它描述了部署中的不同阶段以及 Elastic Beanstalk 在每个阶段中采取的步骤。
注意
-
该图不代表 Elastic Beanstalk 在部署期间对环境实例采取的完整步骤集。我们提供此图作为说明,为您提供执行自定义项的顺序和上下文。
-
为简单起见,图中仅提及
.platform/hooks/*
挂钩子目录(用于应用程序部署),而不提及.platform/confighooks/*
挂钩子目录(用于配置部署)。后面子目录中的挂钩运行的步骤与图中显示的相应子目录中的挂钩运行的步骤完全相同。

以下列表详细介绍了部署阶段和步骤。
-
初始步骤
Elastic Beanstalk 下载并提取您的应用程序。在上述每个步骤之后,Elastic Beanstalk 会运行一个可扩展性步骤。
-
运行任何配置文件的 commands: 部分中的命令。
-
运行在源包的
.platform/hooks/prebuild
目录中找到的任何可执行文件(.platform/confighooks/prebuild
用于配置部署)。
-
-
配置
Elastic Beanstalk 配置您的应用程序和代理服务器。
-
运行源包
Buildfile
中的命令。 -
如果源包
.platform/nginx
目录中包含任何自定义代理配置文件,请将其复制到其运行时位置。 -
运行任何配置文件的 container_commands: 部分中的命令。
-
运行在源包的
.platform/hooks/predeploy
目录中找到的任何可执行文件(.platform/confighooks/predeploy
用于配置部署)。
-
-
部署
Elastic Beanstalk 部署并运行您的应用程序和代理服务器。
-
运行源包
Procfile
文件中的命令。 -
使用您的自定义代理配置文件(如果有)运行或重新运行代理服务器。
-
运行在源包的
.platform/hooks/postdeploy
目录中找到的任何可执行文件(.platform/confighooks/postdeploy
用于配置部署)。
-
在 Amazon Linux 2 上运行的 ECS 的实例部署工作流
上一节介绍了应用程序部署工作流各个阶段支持的可扩展性功能。Docker 平台分支在 Amazon Linux 2 上运行的 ECS有一些不同之处。本节介绍这些概念如何应用于此特定平台分支。
有多种扩展环境平台的方法,对于了解 Elastic Beanstalk 在预配置实例或向实例运行部署时会发生什么情况非常有用。下图显示了基于在 Amazon Linux 2 上运行的 ECS 平台分支的环境的整个部署工作流。它描述了部署中的不同阶段以及 Elastic Beanstalk 在每个阶段中采取的步骤。
与上一节中描述的工作流不同,部署配置阶段不支持以下可扩展性功能:Buildfile
命令、Procfile
命令、反向代理配置。
注意
-
该图不代表 Elastic Beanstalk 在部署期间对环境实例采取的完整步骤集。我们提供此图作为说明,为您提供执行自定义项的顺序和上下文。
-
为简单起见,图中仅提及
.platform/hooks/*
挂钩子目录(用于应用程序部署),而不提及.platform/confighooks/*
挂钩子目录(用于配置部署)。后面子目录中的挂钩运行的步骤与图中显示的相应子目录中的挂钩运行的步骤完全相同。

以下列表详细介绍了部署工作流步骤。
-
运行
EBhooksDir
下appdeploy/pre
目录中找到的任何可执行文件。 -
运行在源包的
.platform/hooks/prebuild
目录中找到的任何可执行文件(.platform/confighooks/prebuild
用于配置部署)。 -
运行在源包的
.platform/hooks/predeploy
目录中找到的任何可执行文件(.platform/confighooks/predeploy
用于配置部署)。 -
运行
EBhooksDir
下appdeploy/enact
目录中找到的任何可执行文件。 -
运行
EBhooksDir
下appdeploy/post
目录中找到的任何可执行文件。 -
运行在源包的
.platform/hooks/postdeploy
目录中找到的任何可执行文件(.platform/confighooks/postdeploy
用于配置部署)。
对 EBhooksDir
的引用表示平台挂钩目录的路径。要检索目录路径名,请使用环境实例命令行上的 get-config 脚本工具,如下所示:
$
/opt/elasticbeanstalk/bin/get-config platformconfig -k EBhooksDir