Laravel Octane – 乌鸦嘴文档中心

介绍

Laravel Octane (opens in a new tab) 通过使用高性能的应用服务器（包括FrankenPHP (opens in a new tab)、Open Swoole (opens in a new tab)、Swoole (opens in a new tab) 和RoadRunner (opens in a new tab)）来提升您的应用程序性能。Octane 会一次性启动您的应用程序，将其保持在内存中，然后以超音速的速度为其提供请求。

安装

Octane 可以通过 Composer 包管理器进行安装：

composer require laravel/octane

安装 Octane 后，您可以执行 octane:install Artisan 命令，该命令会将 Octane 的配置文件安装到您的应用程序中：

php artisan octane:install

服务器前提条件

[!警告]
Laravel Octane 需要 PHP 8.1 及以上版本 (opens in a new tab)。

FrankenPHP

FrankenPHP (opens in a new tab) 是一个用 Go 编写的 PHP 应用服务器，支持现代网络功能，如早期提示、Brotli 和 Zstandard 压缩。当您安装 Octane 并选择 FrankenPHP 作为您的服务器时，Octane 会自动为您下载并安装 FrankenPHP 二进制文件。

通过 Laravel Sail 使用 FrankenPHP

如果您计划使用 Laravel Sail 开发您的应用程序，您应该运行以下命令来安装 Octane 和 FrankenPHP：

./vendor/bin/sail up
 
./vendor/bin/sail composer require laravel/octane

接下来，您应该使用 octane:install Artisan 命令来安装 FrankenPHP 二进制文件：

./vendor/bin/sail artisan octane:install --server=frankenphp

最后，在您的应用程序的 docker-compose.yml 文件中的 laravel.test 服务定义中添加一个 SUPERVISOR_PHP_COMMAND 环境变量。这个环境变量将包含 Sail 将用于使用 Octane 而不是 PHP 开发服务器来服务您的应用程序的命令：

services:
  laravel.test:
    environment:
      SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=frankenphp --host=0.0.0.0 --admin-port=2019 --port=80" # [tl! 添加]
      XDG_CONFIG_HOME:  /var/www/html/config # [tl! 添加]
      XDG_DATA_HOME:  /var/www/html/data # [tl! 添加]

要启用 HTTPS、HTTP/2 和 HTTP/3，请进行以下修改：

services:
  laravel.test:
    ports:
        - '${APP_PORT:-80}:80'
        - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        - '443:443' # [tl! 添加]
        - '443:443/udp' # [tl! 添加]
    environment:
      SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --host=localhost --port=443 --admin-port=2019 --https" # [tl! 添加]
      XDG_CONFIG_HOME:  /var/www/html/config # [tl! 添加]
      XDG_DATA_HOME:  /var/www/html/data # [tl! 添加]

通常，您应该通过 https://localhost 访问您的 FrankenPHP Sail 应用程序，因为使用 https://127.0.0.1 需要额外的配置，并且不建议这样做 (opens in a new tab)。

通过 Docker 使用 FrankenPHP

使用 FrankenPHP 的官方 Docker 镜像可以提供更好的性能，并使用静态安装的 FrankenPHP 中未包含的其他扩展。此外，官方 Docker 镜像为在其本身不原生支持的平台（如 Windows）上运行 FrankenPHP 提供了支持。FrankenPHP 的官方 Docker 镜像适用于本地开发和生产使用。

您可以使用以下 Dockerfile 作为将您的由 FrankenPHP 驱动的 Laravel 应用程序进行容器化的起点：

FROM dunglas/frankenphp
 
RUN install-php-extensions \
    pcntl
    # 在此处添加其他 PHP 扩展...
 
COPY. /app
 
ENTRYPOINT ["php", "artisan", "octane:frankenphp"]

然后，在开发过程中，您可以使用以下 Docker Compose 文件来运行您的应用程序：

# compose.yaml
services:
  frankenphp:
    build:
      context:.
    entrypoint: php artisan octane:frankenphp --workers=1 --max-requests=1
    ports:
      - "8000:8000"
    volumes:
      -.:/app

您可以查阅FrankenPHP 官方文档 (opens in a new tab)以获取更多关于使用 Docker 运行 FrankenPHP 的信息。

RoadRunner

RoadRunner (opens in a new tab) 由使用 Go 构建的 RoadRunner 二进制文件提供支持。当您首次启动基于 RoadRunner 的 Octane 服务器时，Octane 会为您提供下载并安装 RoadRunner 二进制文件的选项。

通过 Laravel Sail 使用 RoadRunner

如果您计划使用 Laravel Sail 开发您的应用程序，您应该运行以下命令来安装 Octane 和 RoadRunner：

./vendor/bin/sail up
 
./vendor/bin/sail composer require laravel/octane spiral/roadrunner-cli spiral/roadrunner-http

接下来，您应该启动一个 Sail 外壳并使用 rr 可执行文件来获取最新的基于 Linux 的 RoadRunner 二进制文件构建：

./vendor/bin/sail shell
 
# 在 Sail 外壳中...
./vendor/bin/rr get-binary

然后，在您的应用程序的 docker-compose.yml 文件中的 laravel.test 服务定义中添加一个 SUPERVISOR_PHP_COMMAND 环境变量。这个环境变量将包含 Sail 将用于使用 Octane 而不是 PHP 开发服务器来服务您的应用程序的命令：

services:
  laravel.test:
    environment:
      SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=roadrunner --host=0.0.0.0 --rpc-port=6001 --port=80" # [tl! 添加]

最后，确保 rr 二进制文件可执行并构建您的 Sail 镜像：

chmod +x./rr
 
./vendor/bin/sail build --no-cache

Swoole

如果您计划使用 Swoole 应用服务器来服务您的 Laravel Octane 应用程序，您必须安装 Swoole PHP 扩展。通常，这可以通过 PECL 完成：

pecl install swoole

Open Swoole

如果您想使用 Open Swoole 应用服务器来服务您的 Laravel Octane 应用程序，您必须安装 Open Swoole PHP 扩展。通常，这可以通过 PECL 完成：

pecl install openswoole

使用带有 Open Swoole 的 Laravel Octane 可以提供与 Swoole 相同的功能，例如并发任务、滴答和间隔。

通过 Laravel Sail 使用 Swoole

[!警告]
在通过 Sail 服务 Octane 应用程序之前，请确保您拥有最新版本的 Laravel Sail，并在您的应用程序根目录中执行 ./vendor/bin/sail build --no-cache。

或者，您可以使用 Laravel Sail（Laravel 的官方基于 Docker 的开发环境）来开发您的基于 Swoole 的 Octane 应用程序。Laravel Sail 默认包含 Swoole 扩展。但是，您仍然需要调整 Sail 使用的 docker-compose.yml 文件。

首先，在您的应用程序的 docker-compose.yml 文件中的 laravel.test 服务定义中添加一个 SUPERVISOR_PHP_COMMAND 环境变量。这个环境变量将包含 Sail 将用于使用 Octane 而不是 PHP 开发服务器来服务您的应用程序的命令：

services:
  laravel.test:
    environment:
      SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=swoole --host=0.0.0.0 --port=80" # [tl! 添加]

最后，构建您的 Sail 镜像：

./vendor/bin/sail build --no-cache

Swoole 配置

Swoole 支持一些额外的配置选项，如果有必要，您可以将其添加到您的 octane 配置文件中。由于这些选项很少需要修改，因此它们未包含在默认配置文件中：

'swoole' => [
    'options' => [
        'log_file' => storage_path('logs/swoole_http.log'),
        'package_max_length' => 10 * 1024 * 1024,
    ],
],

运行您的应用程序

可以通过 octane:start Artisan 命令启动 Octane 服务器。默认情况下，此命令将使用应用程序的 octane 配置文件的 server 配置选项指定的服务器：

php artisan octane:start

默认情况下，Octane 将在端口 8000 上启动服务器，因此您可以通过 http://localhost:8000 在网络浏览器中访问您的应用程序。

通过 HTTPS 运行您的应用程序

默认情况下，通过 Octane 运行的应用程序生成的链接前缀为 http:// 。在应用程序的 config/octane.php 配置文件中使用的 OCTANE_HTTPS 环境变量，在通过 HTTPS 运行应用程序时可以设置为 true 。当此配置值设置为 true 时，Octane 将指示 Laravel 将所有生成的链接前缀为 https:// ：

'https' => env('OCTANE_HTTPS', false),

通过 Nginx 运行您的应用程序

[!NOTE]
如果您还没有准备好管理自己的服务器配置，或者对配置运行强大的 Laravel Octane 应用程序所需的各种服务不太熟悉，请查看 Laravel Forge (opens in a new tab) 。

在生产环境中，您应该在传统的 Web 服务器（如 Nginx 或 Apache）后面运行您的 Octane 应用程序。这样做可以让 Web 服务器为您提供静态资产（如图像和样式表）的服务，并管理您的 SSL 证书终止。

在下面的 Nginx 配置示例中，Nginx 将为站点的静态资产提供服务，并将请求代理到在端口 8000 上运行的 Octane 服务器：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}
 
server {
    listen 80;
    listen [::]:80;
    server_name domain.com;
    server_tokens off;
    root /home/forge/domain.com/public;
 
    index index.php;
 
    charset utf-8;
 
    location /index.php {
        try_files /not_exists @octane;
    }
 
    location / {
        try_files $uri $uri/ @octane;
    }
 
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
 
    access_log off;
    error_log  /var/log/nginx/domain.com-error.log error;
 
    error_page 404 /index.php;
 
    location @octane {
        set $suffix "";
 
        if ($uri = /index.php) {
            set $suffix?$query_string;
        }
 
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Scheme $scheme;
        proxy_set_header SERVER_PORT $server_port;
        proxy_set_header REMOTE_ADDR $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
 
        proxy_pass http://127.0.0.1:8000$suffix;
    }
}

监控文件更改

由于在 Octane 服务器启动时，您的应用程序会在内存中加载一次，因此当您刷新浏览器时，对应用程序文件的任何更改都不会反映出来。例如，添加到 routes/web.php 文件中的路由定义，直到服务器重新启动后才会反映出来。为了方便起见，您可以使用 --watch 标志指示 Octane 在应用程序内的任何文件发生更改时自动重新启动服务器：

php artisan octane:start --watch

在使用此功能之前，您应该确保在本地开发环境中安装了 Node (opens in a new tab) 。此外，您应该在项目中安装 Chokidar (opens in a new tab) 文件监控库：

npm install --save-dev chokidar

您可以使用应用程序的 config/octane.php 配置文件中的 watch 配置选项来配置应该监控的目录和文件。

指定工作进程数

默认情况下，Octane 会为您的机器提供的每个 CPU 核心启动一个应用程序请求工作进程。然后，这些工作进程将用于在传入的 HTTP 请求进入您的应用程序时进行服务。您可以在调用 octane:start 命令时使用 --workers 选项手动指定要启动的工作进程数：

php artisan octane:start --workers=4

如果您使用的是 Swoole 应用服务器，您还可以指定要启动的"任务工作进程"数量：

php artisan octane:start --workers=4 --task-workers=6

指定最大请求数

为了帮助防止出现意外的内存泄漏，Octane 会在任何工作进程处理了 500 个请求后优雅地重新启动它。要调整此数字，您可以使用 --max-requests 选项：

php artisan octane:start --max-requests=250

重新加载工作进程

您可以使用 octane:reload 命令优雅地重新启动 Octane 服务器的应用程序工作进程。通常，这应该在部署后进行，以便将新部署的代码加载到内存中，并用于处理后续请求：

php artisan octane:reload

停止服务器

您可以使用 octane:stop Artisan 命令停止 Octane 服务器：

php artisan octane:stop

检查服务器状态

您可以使用 octane:status Artisan 命令检查 Octane 服务器的当前状态：

php artisan octane:status

依赖注入和 Octane

由于 Octane 在处理请求时会启动您的应用程序一次并将其保持在内存中，因此在构建应用程序时您应该考虑一些注意事项。例如，应用程序的服务提供程序的 register 和 boot 方法在请求工作进程首次启动时只会执行一次。在后续请求中，将重复使用相同的应用程序实例。

鉴于此，在将应用程序服务容器或请求注入到任何对象的构造函数时，您应该特别小心。这样做可能会导致该对象在后续请求中拥有过时的容器或请求版本。

Octane 将自动处理在请求之间重置任何第一方框架状态。但是，Octane 并不总是知道如何重置您的应用程序创建的全局状态。因此，您应该了解如何以对 Octane 友好的方式构建您的应用程序。下面，我们将讨论在使用 Octane 时可能导致问题的最常见情况。

容器注入

通常，您应该避免将应用程序服务容器或 HTTP 请求实例注入到其他对象的构造函数中。例如，以下绑定将整个应用程序服务容器注入到一个作为单例绑定的对象中：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
 
/**
 * 注册任何应用程序服务。
 */
public function register(): void
{
    $this->app->singleton(Service::class, function (Application $app) {
        return new Service($app);
    });
}

在这个例子中，如果在应用程序启动过程中解析了 Service 实例，容器将被注入到服务中，并且在后续请求中，Service 实例将持有相同的容器。对于您的特定应用程序，这可能不是问题；然而，它可能导致容器意外地缺少在启动周期的后期或后续请求中添加的绑定。

作为一种解决方法，您可以停止将绑定注册为单例，或者您可以将一个容器解析器闭包注入到服务中，该闭包始终解析当前的容器实例：

use App\Service;
use Illuminate\Container\Container;
use Illuminate\Contracts\Foundation\Application;
 
$this->app->bind(Service::class, function (Application $app) {
    return new Service($app);
});
 
$this->app->singleton(Service::class, function () {
    return new Service(fn () => Container::getInstance());
});

全局 app 助手和 Container::getInstance() 方法将始终返回应用程序容器的最新版本。

请求注入

通常，您应避免将应用程序服务容器或 HTTP 请求实例注入到其他对象的构造函数中。例如，以下绑定将整个请求实例注入到一个绑定为单例的对象中：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
 
/**
 * 注册任何应用程序服务。
 */
public function register(): void
{
    $this->app->singleton(Service::class, function (Application $app) {
        return new Service($app['request']);
    });
}

在此示例中，如果在应用程序启动过程中解析 Service 实例，则 HTTP 请求将被注入到该服务中，并且在后续请求中，该 Service 实例将持有相同的请求。因此，所有标头、输入和查询字符串数据以及所有其他请求数据都将不正确。

作为一种解决方法，您可以停止将绑定注册为单例，或者可以将一个请求解析器闭包注入到服务中，该闭包始终解析当前请求实例。或者，最推荐的方法是在运行时将您的对象所需的特定请求信息传递到对象的一个方法中：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
 
$this->app->bind(Service::class, function (Application $app) {
    return new Service($app['request']);
});
 
$this->app->singleton(Service::class, function (Application $app) {
    return new Service(fn () => $app['request']);
});
 
// 或者...
 
$service->method($request->input('name'));

全局 request 助手将始终返回应用程序当前正在处理的请求，因此在您的应用程序中使用是安全的。

[!WARNING]
在控制器方法和路由闭包中对 Illuminate\Http\Request 实例进行类型提示是可以接受的。

配置存储库注入

通常，您应避免将配置存储库实例注入到其他对象的构造函数中。例如，以下绑定将配置存储库注入到一个绑定为单例的对象中：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
 
/**
 * 注册任何应用程序服务。
 */
public function register(): void
{
    $this->app->singleton(Service::class, function (Application $app) {
        return new Service($app->make('config'));
    });
}

在此示例中，如果在请求之间配置值发生变化，则该服务将无法访问新值，因为它依赖于原始的存储库实例。

作为一种解决方法，您可以停止将绑定注册为单例，或者可以将一个配置存储库解析器闭包注入到类中：

use App\Service;
use Illuminate\Container\Container;
use Illuminate\Contracts\Foundation\Application;
 
$this->app->bind(Service::class, function (Application $app) {
    return new Service($app->make('config'));
});
 
$this->app->singleton(Service::class, function () {
    return new Service(fn () => Container::getInstance()->make('config'));
});

全局 config 将始终返回配置存储库的最新版本，因此在您的应用程序中使用是安全的。

管理内存泄漏

请记住，Octane 在请求之间将您的应用程序保持在内存中；因此，向静态维护的数组添加数据将导致内存泄漏。例如，以下控制器存在内存泄漏，因为对应用程序的每个请求都会继续向静态的 $data 数组添加数据：

use App\Service;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
 
/**
 * 处理传入的请求。
 */
public function index(Request $request): array
{
    Service::$data[] = Str::random(10);
 
    return [
        //...
    ];
}

在构建应用程序时，您应该特别注意避免创建此类内存泄漏。建议您在本地开发期间监控应用程序的内存使用情况，以确保您不会在应用程序中引入新的内存泄漏。

并发任务

[!WARNING]
此功能需要 Swoole。

当使用 Swoole 时，您可以通过轻量级后台任务并发执行操作。您可以使用 Octane 的 concurrently 方法来实现。您可以将此方法与 PHP 数组解构结合使用，以获取每个操作的结果：

use App\Models\User;
use App\Models\Server;
use Laravel\Octane\Facades\Octane;
 
[$users, $servers] = Octane::concurrently([
    fn () => User::all(),
    fn () => Server::all(),
]);

Octane 处理的并发任务使用 Swoole 的“任务工作者”，并在与传入请求完全不同的进程中执行。可用于处理并发任务的工作者数量由 octane:start 命令的 --task-workers 指令确定：

php artisan octane:start --workers=4 --task-workers=6

在调用 concurrently 方法时，由于 Swoole 的任务系统所施加的限制，您不应提供超过 1024 个任务。

滴答和间隔

[!WARNING]
此功能需要 Swoole。

当使用 Swoole 时，您可以注册每隔指定秒数执行的“滴答”操作。您可以通过 tick 方法注册“滴答”回调。提供给 tick 方法的第一个参数应该是一个字符串，表示计时器的名称。第二个参数应该是一个可调用的函数，将在指定的间隔被调用。

在此示例中，我们将注册一个每 10 秒被调用的闭包。通常，tick 方法应在您的应用程序的服务提供者的 boot 方法中调用：

Octane::tick('simple-ticker', fn () => ray('Ticking...'))
        ->seconds(10);

使用 immediate 方法，您可以指示 Octane 在 Octane 服务器最初启动时立即调用滴答回调，然后每隔 N 秒调用一次：

Octane::tick('simple-ticker', fn () => ray('Ticking...'))
        ->seconds(10)
        ->immediate();

Octane 缓存

[!WARNING]
此功能需要 Swoole。

当使用 Swoole 时，您可以利用 Octane 缓存驱动程序，其提供高达每秒 200 万次操作的读写速度。因此，对于需要从其缓存层获得极高读写速度的应用程序，此缓存驱动程序是一个极好的选择。

此缓存驱动程序由 Swoole 表 (opens in a new tab) 提供支持。服务器上的所有工作者都可以访问缓存中的所有数据。但是，当服务器重新启动时，缓存的数据将被刷新：

Cache::store('octane')->put('framework', 'Laravel', 30);

[!NOTE]
Octane 缓存中允许的最大条目数可以在您的应用程序的 octane 配置文件中定义。

缓存间隔

除了 Laravel 的缓存系统提供的典型方法外，Octane 缓存驱动程序还具有基于间隔的缓存功能。这些缓存会在指定的间隔自动刷新，并应在您的应用程序的服务提供者的 boot 方法中注册。例如，以下缓存将每五秒刷新一次：

use Illuminate\Support\Str;
 
Cache::store('octane')->interval('random', function () {
    return Str::random(10);
}, seconds: 5);

表

[!WARNING]
此功能需要 Swoole。

当使用 Swoole 时，您可以定义并与您自己的任意 Swoole 表 (opens in a new tab) 进行交互。Swoole 表提供了极高的性能吞吐量，并且服务器上的所有工作者都可以访问这些表中的数据。但是，当服务器重新启动时，其中的数据将丢失。

表应在您的应用程序的 octane 配置文件的 tables 配置数组中定义。已经为您配置了一个允许最多 1000 行的示例表。可以通过在列类型后指定列大小来配置字符串列的最大大小，如下所示：

'tables' => [
    'example:1000' => [
        'name' => 'string:1000',
        'votes' => 'int',
    ],
],

要访问一个表，您可以使用 Octane::table 方法：

use Laravel\Octane\Facades\Octane;
 
Octane::table('example')->set('uuid', [
    'name' => 'Nuno Maduro',
    'votes' => 1000,
]);
 
return Octane::table('example')->get('uuid');

[!WARNING]
Swoole 表支持的列类型为：string、int 和 float。

Laravel Mix Laravel Passport