环境 ​

简介 ​

您可能已经注意到，项目本身不包含太多信息或资源。所有部署和调用的命令都存储在环境中。每个项目可以拥有任意数量的环境。

通常，您将有一个用于“生产”的环境，以及一个用于测试应用程序的“暂存”环境。但是，不要害怕创建更多环境来测试新功能，而不会中断您的主要暂存环境。

创建环境 ​

可以使用 env Vapor CLI 命令创建环境

vapor env my-environment

此命令将在您的项目的 vapor.yml 文件中添加一个新的环境条目，您可以在准备好时进行部署

id: 2
name: vapor-laravel-app
environments:
    production:
        build:
            - 'composer install --no-dev'
    my-environment:
        build:
            - 'composer install --no-dev'

除了我们的原生运行时之外，Vapor 还支持 Docker 镜像部署。如果您希望环境使用 Docker 镜像运行时而不是默认的 Vapor 运行时，请在创建环境时使用 --docker 选项

vapor env my-environment --docker

此命令将在您的应用程序的根目录中创建一个 my-environment.Dockerfile 文件。

打开环境 ​

可以使用 Vapor CLI 的 open 命令在默认浏览器中打开环境

vapor open my-environment

默认环境 ​

执行 Vapor CLI 命令时，Vapor CLI 默认使用 staging 环境

vapor open // Opens the `staging` environment in your default browser...

vapor open production // Opens the `production` environment in your default browser...

但是，在您的应用程序的vapor.yml文件中，您可以定义一个default-environment选项来更改项目的默认环境。

id: 2
name: vapor-laravel-app
default-environment: production
environments:
    production:
        build:
            - 'composer install --no-dev'
    my-environment:
        build:
            - 'composer install --no-dev'

环境变量 ​

每个环境都包含一组环境变量，这些变量在执行期间为您的应用程序提供关键信息，就像您应用程序的本地.env文件中的变量一样。

Vapor 的默认环境变量 ​

Vapor 会根据您环境配置的缓存、数据库等自动注入各种环境变量。例如，通过在您的vapor.yml文件中添加cache或database键，Vapor 将注入必要的CACHE_*和DB_*环境变量。

以下是 Vapor 在您的环境中注入的环境变量的完整列表

使用 Vapor CLI 或 Vapor UI 管理环境时，您将看不到这些环境变量，并且您手动定义的任何变量都将覆盖 Vapor 自动注入的变量。

更新环境变量 ​

您可以通过 Vapor UI 或使用env:pull和env:push CLI 命令来更新环境的变量。env:pull命令可用于为给定环境下拉环境文件。

vapor env:pull production

执行此命令后，将在应用程序的根目录中放置一个.env.{environment}文件。要更新环境变量，只需打开并编辑此文件即可。编辑完变量后，使用env:push命令将变量推送到 Vapor

vapor env:push production

如果您使用 DotEnv 库的变量嵌套功能来引用 Vapor 注入的默认环境变量，则应将这些引用替换为字面值。由于 Vapor 注入的环境变量不属于环境文件，因此无法使用嵌套功能引用它们。

保留的环境变量 ​

以下环境变量是保留的，不能添加到您的环境中

• _HANDLER
• AWS_ACCESS_KEY_ID
• AWS_DEFAULT_REGION
• AWS_EXECUTION_ENV
• AWS_LAMBDA_FUNCTION_MEMORY_SIZE
• AWS_LAMBDA_FUNCTION_NAME
• AWS_LAMBDA_FUNCTION_VERSION
• AWS_LAMBDA_LOG_GROUP_NAME
• AWS_LAMBDA_LOG_STREAM_NAME
• AWS_LAMBDA_RUNTIME_API
• AWS_REGION
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN
• LAMBDA_RUNTIME_DIR
• LAMBDA_TASK_ROOT
• TZ

此外，环境变量的名称中不应包含AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY或AWS_SESSION_TOKEN。例如：MY_SERVICE_AWS_SECRET_ACCESS_KEY。

加密的环境文件 ​

Vapor 内置支持 Laravel 的加密环境文件。如果 Vapor 在启动应用程序时发现加密的环境文件，它将自动尝试解密它并将生成的变量注入到运行时。

要利用此功能，您必须首先确保在部署期间应用程序的根目录中存在加密的环境文件。例如，部署production环境需要在应用程序的根目录中存在一个名为.env.production.encrypted的文件。

此外，您应该确保解密密钥在运行时可用，方法是通过 Vapor UI 或 CLI 将其定义为 LARAVEL_ENV_ENCRYPTION_KEY 环境变量。

Passport 密钥 ​

您可以使用 env:passport CLI 命令轻松地将项目的 Passport 密钥添加到加密的环境文件中。

vapor env:passport production

env:passport 命令会将本地 Passport 密钥的内容追加到您的 .env.production 文件中。命令完成后，您应该使用 Laravel 的 env:encrypt 命令重新加密环境文件，并重新部署项目以使更改生效。

维护模式 ​

在使用传统 VPS（如由 Laravel Forge 管理的 VPS）部署 Laravel 应用程序时，您可能已经使用过 php artisan down 命令将应用程序置于“维护模式”。要将 Vapor 环境置于维护模式，您可以使用 Vapor UI 或 down CLI 命令。

vapor down production

要将环境从维护模式中移除，您可以使用 up 命令。

vapor up production

自定义维护模式屏幕 ​

您可以通过将 503.html 文件放在应用程序的根目录中来自定义应用程序的维护模式启动画面。此外，您还可以将 503.json 文件放在应用程序的根目录中，用于请求 JSON 响应。

绕过维护模式 ​

您可能希望在维护模式下通过自定义域名而不是虚拟域名访问您的网站。为此，您可以在调用 `down` 命令时提供一个密钥。

vapor down --secret="example-secret"

然后，您可以使用密钥作为 URL 路径访问您的应用程序。

https://example.com/example-secret

命令 ​

命令允许您对环境执行任意 Artisan 命令。您可以通过 Vapor UI 或使用 `command` CLI 命令发出命令。`command` 命令将提示您输入要运行的 Artisan 命令。

vapor command production

vapor command production --command="php artisan inspire"

默认情况下，您的命令将在 1 分钟后超时。您可以使用 `vapor.yml` 文件中的 `cli-timeout` 选项配置 CLI 命令的超时时间。此选项允许您指定 CLI 命令允许运行的最大秒数。

id: 2
name: vapor-laravel-app
environments:
    production:
        cli-timeout: 20
        build:
            - 'composer install --no-dev'

有时您可能需要再次运行上一个命令。为此，您可以使用 Vapor UI 或 `command:again` CLI 命令。

# Run the previous command again...
vapor command:again

# Run a specific command again using the command's ID...
vapor command:again 50

内存 ​

Vapor（通过 AWS Lambda）根据为应用程序配置的内存量，按比例为您的 Lambda 函数分配 CPU 能力。您可以使用环境 `vapor.yml` 配置中的 `memory` 选项增加或减少配置的内存。

id: 2
name: vapor-laravel-app
environments:
    production:
        memory: 1024
        build:
            - 'composer install --no-dev'

并发 ​

默认情况下，Vapor 允许您的应用程序以最大并发量处理 Web 请求，这通常是 1,000 个请求在任何给定时间点在您给定区域的所有 AWS Lambda 函数中同时执行。如果您想降低最大 Web 并发量，您可以在环境 `vapor.yml` 配置中定义 `concurrency` 选项。此外，如果您需要超过 1,000 个并发请求，您可以在 AWS Support Center 控制台中提交限制增加请求。

虽然最大性能无疑很有吸引力，但在某些情况下，将此值设置为您的特定应用程序合理预期的最大并发性可能更有意义。否则，针对您的应用程序的 DDoS 攻击可能会导致比预期更大的 AWS 成本。

id: 2
name: vapor-laravel-app
environments:
    production:
        concurrency: 50
        build:
            - 'composer install --no-dev'

预热 ​

默认情况下，当部署环境时，它收到的第一个请求可能会遇到“冷启动”。这些请求通常会产生几秒钟的延迟，因为 AWS 需要加载无服务器容器来处理请求。一旦容器处理了请求，它通常会保持“热”状态，以便在没有延迟的情况下处理后续请求。

为了减轻新部署后的“冷启动”，Vapor 允许您在 vapor.yml 文件中为环境定义一个 warm 配置值。warm 值表示 Vapor 将通过对新部署的应用程序进行并发请求来“预热”多少个无服务器容器，**在它被激活供公众访问之前**。Vapor 将继续每 5 分钟预热这么多容器，直到应用程序部署完成，这样指定的容器数量始终准备处理请求。

id: 2
name: vapor-laravel-app
environments:
    production:
        warm: 10
        build:
            - 'composer install --no-dev'

防火墙 ​

您可以指示 Vapor 自动配置一个防火墙，该防火墙提供针对针对您环境的拒绝服务攻击的基本保护，以及针对可能消耗您环境资源的普遍的机器人流量的保护。

在开始之前，请记住，Vapor 的托管防火墙使用来自 Web 请求来源的 IP 地址检查请求。因此，此功能仅应在请求尚未通过 Cloudflare 等服务进行反向代理的情况下使用。**如果您已经在使用反向代理，则不应使用此功能**。

您可以通过在应用程序的 vapor.yml 文件中定义 firewall 配置选项来使用 Vapor 的托管防火墙。

id: 2
name: vapor-laravel-app
environments:
    production:
        build:
            - 'composer install --no-dev'
        firewall:
            rate-limit: 1000
            bot-control:
                - CategorySearchEngine
                - CategorySocialMedia
                - CategoryScrapingFramework

rate-limit ​

当使用 rate-limit 选项时，Vapor 的托管防火墙会跟踪每个源 IP 地址的请求速率，并阻止请求速率超过给定 rate-limit 值的 IP 地址。在上面的示例中，如果某个 IP 地址的请求计数在任何 5 分钟时间段内超过 1,000 次，则防火墙将使用 403 Forbidden HTTP 状态码暂时阻止来自该 IP 地址的请求。

bot-control ​

当使用 bot-control 选项时，Vapor 的托管防火墙会阻止来自普遍存在的机器人的请求，例如抓取工具或搜索引擎。您可以通过在应用程序的 vapor.yml 文件中提供一个 array 类别来自定义 bot-control 应该阻止的请求“类别”。

firewall:
    bot-control:
        - CategoryAdvertising
        - CategoryArchiver
        - SignalNonBrowserUserAgent

以下是您可以使用的可用类别列表。

在幕后，Vapor 的托管防火墙使用 **Amazon WAF**，为每个 Vapor 环境创建一个 Web ACL，其中包含一个基于速率的规则。请随时查看 AWS WAF 文档以获取有关 WAF 及其定价的更多信息。

超时 ​

默认情况下，Vapor 会将 Web 请求执行时间限制为 10 秒。如果您想更改超时值，可以在环境配置中添加一个 timeout 值（以秒为单位）。API Gateway 的最大超时时间为 30 秒。如果您需要更长的请求持续时间，可以使用 负载均衡器。请注意，AWS 不允许 Lambda 执行超过 15 分钟。

id: 2
name: vapor-laravel-app
environments:
    production:
        timeout: 20
        build:
            - 'composer install --no-dev'

调度程序 ​

Vapor 会自动配置 Laravel 的任务调度程序，并指示它使用 DynamoDB 缓存驱动程序来避免任务重叠，因此无需进行其他配置即可开始利用 Laravel 的计划任务功能。

如果您想禁用调度程序，可以将环境的 scheduler 选项设置为 false。

id: 2
name: vapor-laravel-app
environments:
    production:
        scheduler: false
        build:
            - 'composer install --no-dev'

亚分钟计划任务 ​

由于 AWS 的限制，无法保证调度器会在任何给定分钟的开始时被调用。因此，您可能会发现，默认情况下，在 `schedule:run` 进程早期安排的亚分钟任务不会按预期运行，而那些在调度中运行较晚的任务可能不会在预期时间开始。例如，当使用 `everyThirtySeconds` 调度命令并假设调度器在 12:00:10 由 AWS 调用时，您应该期望您的命令在 12:00:10 和 12:00:40 运行。

为了解决亚分钟任务的这些限制，您可以在应用程序的 `vapor.yml` 文件中添加 `scheduler: sub-minute` 来启用 Vapor 自身的调度器引擎。

id: 2
name: vapor-laravel-app
environments:
    production:
        scheduler: sub-minute
        cli-timeout: 120

当启用 Vapor 的亚分钟调度器时，Vapor 会运行它自己的调度器命令，该命令会在每分钟开始时等待，然后调用 `schedule:run`。因此，在启用此选项时，您还应确保您的 `cli-timeout` >= 120，以留出足够的时间来调用 Laravel 的调度器并允许它完成所有亚分钟任务。您还应确保 `cli-concurrency` >= 2，以允许 Vapor 调度器的重叠调用。

此外，`runInBackground` 选项在 Vapor 上不受支持；因此，如果您发现某些任务被阻止运行，则可能是因为前一个任务运行时间超过预期。

邮件 ​

Laravel 提供了一个干净、简单的电子邮件 API。默认情况下，Vapor 会自动配置您的环境以使用 Amazon SES 作为默认邮件驱动程序，方法是在部署期间注入适当的 Laravel 环境变量。当然，您可以通过为 `MAIL_MAILER` 环境变量定义不同的值来更改默认邮件驱动程序。

如果您计划使用 Amazon SES 作为应用程序的邮件服务，您应该首先确保 `MAIL_MAILER` 环境变量已设置，并且它包含值 `ses`。接下来，您应该 将域附加 到您的环境。附加并部署后，Vapor 会自动更新域的 DNS 记录，以便 Amazon SES 可以验证域并配置 DKIM。这些 DNS 记录对于保护您作为发件人的声誉是必要的。

默认情况下，Vapor 使用 `[email protected]` 和 `Your Project Name` 分别配置“发件人地址”和“发件人名称” Laravel 配置设置。当然，您可以通过为 `MAIL_FROM_ADDRESS` 和 `MAIL_FROM_NAME` 环境变量定义新值来修改这些值。

最后，如果您以前从未使用过 Amazon SES，您的 SES 帐户将处于“沙盒”模式。沙盒模式只允许您将电子邮件发送到手动验证的域。要退出 SES 沙盒模式，请按照以下说明操作：https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html。

指标 ​

您可以在 Vapor UI 或使用 metrics CLI 命令中找到各种环境性能指标

vapor metrics production
vapor metrics production 5m
vapor metrics production 30m
vapor metrics production 1h
vapor metrics production 8h
vapor metrics production 1d
vapor metrics production 3d
vapor metrics production 7d
vapor metrics production 1M

警报 ​

您可以使用 Vapor UI 为所有环境指标配置警报。当警报的配置阈值被打破以及当警报恢复时，这些警报将通过您选择的通知方式通知您。

运行时 ​

runtime 配置选项允许您指定给定环境运行的运行时。

原生运行时 ​

当前支持的原生运行时为 php-8.1:al2、php-8.2:al2、php-8.2:al2-arm、php-8.3:al2 和 php-8.3:al2-arm。以 al2 为后缀的运行时使用 Amazon Linux 2，而没有后缀的运行时使用 Amazon Linux 1。没有 -arm 后缀的运行时在 x86 架构上运行，而以 -arm 为后缀的运行时在 Arm 架构上运行。与 x86 等效产品相比，Arm 提供了性能优势和成本节约

id: 2
name: vapor-laravel-app
environments:
    production:
        runtime: 'php-8.2:al2'
        build:
            - 'composer install --no-dev'

以下限制适用于 Vapor 原生运行时

• 应用程序大小（包括运行时本身）不得超过 250MB。
• 无法安装额外的 PHP 扩展或库（例如 imagick）。

自定义核心 php.ini 指令 ​

要在我们的原生运行时上自定义核心 php.ini 指令，请在项目的 php/conf.d 目录中创建一个 php.ini 文件，其中包含所需的指令。例如，要更改 upload_max_filesize，请将以下行添加到应用程序的 php.ini 文件中

upload_max_filesize = 4M

部署后，新指令将在您的 Vapor 环境中生效。

Docker 运行时 ​

基于 Docker 的运行时允许您打包和部署大小高达 10GB 的应用程序，并允许您通过更新环境的相应 .Dockerfile 来安装额外的 PHP 扩展或库。对于每个新的基于 Docker 的环境，Vapor 都会在您的应用程序中创建一个 .Dockerfile 文件，该文件使用 Vapor 的基本镜像之一作为构建镜像的起点。所有 Vapor 的 Docker 镜像都基于 Alpine Linux

FROM laravelphp/vapor:php82

COPY . /var/task

Vapor 的 Docker 运行时也支持 Arm 架构，这可以提高性能并节省成本。如果您想利用 Arm 架构，您应该按照以下步骤更新您的基础镜像。

FROM laravelphp/vapor:php82-arm

COPY . /var/task

如果您想使用 Docker 镜像而不是 Vapor 原生运行时，您应该将您的 vapor.yml 配置文件的 runtime 选项设置为 docker（对于 x86 架构）或 docker-arm（对于 Arm 架构）。

# x86
id: 2
name: vapor-laravel-app
environments:
    production:
        runtime: docker
        build:
            - 'composer install --no-dev'

# Arm
id: 2
name: vapor-laravel-app
environments:
    production:
        runtime: docker-arm
        build:
            - 'composer install --no-dev'

如果您想重命名 Dockerfile 或在多个环境中使用共享 Dockerfile，您可以在 vapor.yml 文件中定义一个 dockerfile 选项。

id: 2
name: vapor-laravel-app
environments:
    production:
        runtime: docker
        dockerfile: vapor.Dockerfile
        build:
            - 'composer install --no-dev'

Vapor 会在您部署期间构建、标记和发布您环境的镜像；因此，您应该确保您已在本地机器上安装了 Docker。Vapor 的基础 Docker 镜像是

• laravelphp/vapor:php74
• laravelphp/vapor:php80
• laravelphp/vapor:php81
• laravelphp/vapor:php82
• laravelphp/vapor:php82-arm
• laravelphp/vapor:php83
• laravelphp/vapor:php83-arm

当然，您可以随意修改环境的 Dockerfile 以安装额外的依赖项或 PHP 扩展。以下是一些示例

FROM laravelphp/vapor:php81

# Add the `ffmpeg` library...
RUN apk --update add ffmpeg

# Add the `mysql` client...
RUN apk --update add mysql-client

# Add the `gmp` PHP extension...
RUN apk --update add gmp gmp-dev
RUN docker-php-ext-install gmp

# Place application in Lambda application directory...
COPY . /var/task

自定义核心 php.ini 指令 ​

要在我们的 Docker 运行时上自定义核心 php.ini 指令，请在项目的**根目录**中创建一个包含所需指令的 php.ini 文件。例如，要更改 upload_max_filesize 指令，请将以下行添加到您的 php.ini 文件中

upload_max_filesize = 4M

接下来，在您的 Dockerfile 中，包含一个新的 COPY 命令，该命令将本地 php.ini 文件复制到 Docker 镜像中

FROM laravelphp/vapor:php81

COPY ./php.ini /usr/local/etc/php/conf.d/overrides.ini

COPY . /var/task

部署后，新指令将在您的 Vapor 环境中生效。

Docker 构建参数 ​

在使用 Docker 时，通常会在 .Dockerfile 文件中使用 ARG 指令来定义构建时变量。

ARG VERSION=php81

FROM laravelphp/vapor:${VERSION}

COPY . /var/task

您可以通过应用程序 vapor.yml 文件中的 docker-build-args 配置选项设置 Docker 构建参数。

id: 2
name: vapor-laravel-app
environments:
    production:
        runtime: docker
        docker-build-args:
            VERSION: php81
        build:
            - 'composer install --no-dev'

或者，您可以向 deploy Vapor CLI 命令提供一个或多个 --build-arg 选项来指定构建参数的值。

vapor deploy --build-arg VERSION=php74 --build-arg KEY=value

Octane ​

默认情况下，当 Lambda 接收 HTTP 请求时，Vapor 会使用 FastCGI 协议将这些请求同步发送到 PHP-FPM。这意味着每个传入请求都会生成一个 PHP-FPM 工作进程并启动您的应用程序。这种方法确保 Vapor 的行为与传统 Web 服务器完全一致。

如果您希望减少使用 PHP-FPM 所涉及的开销，您可以选择在 Vapor 上启用 **Laravel Octane** 支持。Octane 可以通过一次启动您的应用程序，将其保留在内存中，然后在接收到请求时将这些请求馈送到同一个应用程序实例来提高您的应用程序的性能。

要开始使用，请在您的项目中 安装 Laravel Octane。安装 Octane 后，请务必查看重要的 Octane 文档 主题，例如 依赖注入 和 内存泄漏管理。

最后，您可以通过在应用程序的 vapor.yml 文件中设置 octane 配置选项来指示 Vapor 使用 Octane。

id: 1
name: my-application
environments:
    staging:
        memory: 1024
        runtime: 'php-8.2:al2'
        octane: true

此外，如果您的项目使用数据库，您可以使用 octane-database-session-persist 和 octane-database-session-ttl 选项来指示 Octane 在请求之间重用数据库连接。

database: my-database
        octane: true
        octane-database-session-persist: true
        octane-database-session-ttl: 10

• octane-database-session-persist 选项指示数据库连接应在请求之间持久化。此选项的主要目的是减少每次请求创建数据库连接所涉及的开销。
• octane-database-session-ttl 选项允许指定 Lambda 容器在未被使用时应保持连接到数据库的时间（以秒为单位）。此选项仅适用于 MySQL 固定大小数据库。

我们建议您指定一个octane-database-session-ttl值；否则，Lambda 容器将保持连接到您的数据库，直到 Lambda 容器被销毁。这可能需要几分钟，并可能导致您的数据库被大量活动连接淹没。

网关版本 ​

默认情况下，Vapor 使用 AWS API Gateway v1（REST API）将 HTTP 流量路由到您的无服务器应用程序。您的应用程序可以在 API Gateway v1（REST API）或 API Gateway v2（HTTP API）上运行。默认情况下，应用程序使用 API Gateway v1 部署，因为它提供了更全面的功能集，例如 Vapor 的托管防火墙等等。

但是，API Gateway v2 为您的应用程序每百万次请求提供成本降低（每百万次请求 1.00 美元，而 API Gateway v1 为每百万次请求 3.50 美元）。如果您想使用 API Gateway v2，您可以在 vapor.yml 文件中为给定环境指定 gateway-version 配置选项。

id: 2
name: vapor-laravel-app
environments:
    production:
        gateway-version: 2
        build:
            - 'composer install --no-dev'

使用 API Gateway v2 进行 HTTP 到 HTTPS 重定向 ​

如果您选择使用 API Gateway v2 并希望支持 HTTP 到 HTTPS 重定向，我们目前建议使用 Cloudflare 作为您的 Vapor 应用程序的外部 DNS 提供商。Cloudflare 不仅提供 DNS，还充当您应用程序的反向代理，并提供自动 HTTP 到 HTTPS 重定向选项。

Vapor 部署完成后，Vapor 将为您提供与您的环境关联的域名的 CNAME 记录。这些记录将指向您的 Lambda 应用程序的域名。您应该在 Cloudflare DNS 仪表板中手动添加这些值作为 CNAME 记录。

此外，在使用 Cloudflare 时，您应该将 Cloudflare SSL/TLS 模式设置为“完整”。“始终使用 HTTPS”配置选项可以在 SSL/TLS 菜单的“边缘证书”选项卡中找到。

自定义 VPC ​

如果您想将您的 Lambda 函数放置在 Vapor 未管理的 VPC 中，您可以在 vapor.yml 文件中为给定环境指定 subnets 和 security-groups 配置选项。

id: 2
name: vapor-laravel-app
environments:
    production:
        subnets:
            - subnet-08aczain4man8bba7
            - subnet-08acr4nd0mbba7
        security-groups:
            - sg-0cr4and0m45b7e0

删除环境 ​

可以通过 Vapor UI 或使用 env:delete CLI 命令删除环境。

vapor env:delete testing