Laravel Octane

介绍
安装
服务器先决条件
服务您的应用程序
依赖注入与 Octane
管理内存泄漏
并发任务
滴答和间隔
Octane 缓存
表

介绍

Laravel Octane 通过使用高性能应用服务器（包括 FrankenPHP、Open Swoole、Swoole 和 RoadRunner）来提升您应用程序的性能。Octane 一次性启动您的应用程序，将其保留在内存中，然后以超音速速度处理请求。

安装

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

shell

composer require laravel/octane

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

shell

php artisan octane:install

服务器先决条件

WARNING

Laravel Octane 需要 PHP 8.1+。

FrankenPHP

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

通过 Laravel Sail 安装 FrankenPHP

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

shell

./vendor/bin/sail up

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

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

shell

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

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

yaml

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='${APP_PORT:-80}'" 
      XDG_CONFIG_HOME:  /var/www/html/config 
      XDG_DATA_HOME:  /var/www/html/data

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

yaml

services:
  laravel.test:
    ports:
        - '${APP_PORT:-80}:80'
        - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        - '443:443' 
        - '443:443/udp' 
    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" 
      XDG_CONFIG_HOME:  /var/www/html/config 
      XDG_DATA_HOME:  /var/www/html/data

通常，您应该通过 https://localhost 访问您的 FrankenPHP Sail 应用程序，因为使用 https://127.0.0.1 需要额外的配置，并且是不推荐的。

通过 Docker 安装 FrankenPHP

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

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

dockerfile

FROM dunglas/frankenphp

RUN install-php-extensions \
    pcntl
    # 在此添加其他 PHP 扩展...

COPY . /app

ENTRYPOINT ["php", "artisan", "octane:frankenphp"]

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

yaml

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

如果显式传递 --log-level 选项给 php artisan octane:start 命令，Octane 将使用 FrankenPHP 的本地记录器，并且除非另行配置，否则将生成结构化的 JSON 日志。

您可以查阅 FrankenPHP 官方文档以获取有关使用 Docker 运行 FrankenPHP 的更多信息。

RoadRunner

RoadRunner 由使用 Go 构建的 RoadRunner 二进制文件提供支持。第一次启动基于 RoadRunner 的 Octane 服务器时，Octane 将提供下载并安装 RoadRunner 二进制文件的选项。

通过 Laravel Sail 安装 RoadRunner

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

shell

./vendor/bin/sail up

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

接下来，您应该启动 Sail shell 并使用 rr 可执行文件检索最新的基于 Linux 的 RoadRunner 二进制文件构建：

shell

./vendor/bin/sail shell

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

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

yaml

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='${APP_PORT:-80}'"

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

shell

chmod +x ./rr

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

Swoole

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

shell

pecl install swoole

Open Swoole

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

shell

pecl install openswoole

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

通过 Laravel Sail 安装 Swoole

WARNING

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

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

要开始，请向您应用程序的 docker-compose.yml 文件中的 laravel.test 服务定义添加 SUPERVISOR_PHP_COMMAND 环境变量。此环境变量将包含 Sail 用于通过 Octane 而不是 PHP 开发服务器服务您的应用程序的命令：

yaml

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='${APP_PORT:-80}'"

最后，构建您的 Sail 镜像：

shell

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

Swoole 配置

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

php

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

服务您的应用程序

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

shell

php artisan octane:start

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

通过 HTTPS 服务您的应用程序

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

php

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

通过 Nginx 服务您的应用程序

NOTE

如果您还没有准备好管理自己的服务器配置，或者不熟悉配置运行强大 Laravel Octane 应用程序所需的各种服务，请查看 Laravel Forge。

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

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

nginx

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 在应用程序内的任何文件更改时自动重新启动服务器：

shell

php artisan octane:start --watch

在使用此功能之前，您应该确保在本地开发环境中安装了 Node。此外，您应该在项目中安装 Chokidar 文件监视库：

shell

npm install --save-dev chokidar

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

指定工作进程数量

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

shell

php artisan octane:start --workers=4

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

shell

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

指定最大请求数量

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

shell

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

重新加载工作进程

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

shell

php artisan octane:reload

停止服务器

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

shell

php artisan octane:stop

检查服务器状态

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

shell

php artisan octane:status

依赖注入与 Octane

由于 Octane 一次性启动您的应用程序并在服务请求时将其保留在内存中，因此在构建应用程序时有一些注意事项。例如，您应用程序的服务提供者的 register 和 boot 方法仅在请求工作进程最初启动时执行一次。在后续请求中，将重用相同的应用程序实例。

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

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

容器注入

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

php

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 实例持有。这可能对您的特定应用程序没有问题；但是，它可能导致容器意外缺少在启动周期的后期或通过后续请求添加的绑定。

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

php

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 请求实例注入到其他对象的构造函数中。例如，以下绑定将整个请求实例注入到作为单例绑定的对象中：

php

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 实例持有。因此，所有头部、输入和查询字符串数据将不正确，以及所有其他请求数据。

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

php

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 实例是可以接受的。

配置存储库注入

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

php

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'));
    });
}

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

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

php

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 数组添加数据：

php

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 数组解构结合使用，以检索每个操作的结果：

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 指令确定：

shell

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

在调用 concurrently 方法时，您不应提供超过 1024 个任务，因为这受到 Swoole 任务系统施加的限制。

滴答和间隔

WARNING

此功能需要 Swoole。

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

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

php

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

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

php

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

Octane 缓存

WARNING

此功能需要 Swoole。

使用 Swoole 时，您可以利用 Octane 缓存驱动程序，提供高达每秒 200 万次的读写速度。因此，此缓存驱动程序是需要极端读/写速度的应用程序的绝佳选择。

此缓存驱动程序由 Swoole tables 提供支持。缓存中存储的所有数据对服务器上的所有工作进程均可用。但是，服务器重启时，缓存数据将被清除：

php

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

NOTE

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

缓存间隔

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

php

use Illuminate\Support\Str;

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

表

WARNING

此功能需要 Swoole。

使用 Swoole 时，您可以定义并与自己的任意 Swoole tables 进行交互。Swoole 表提供极高的性能吞吐量，表中的数据可以被服务器上的所有工作进程访问。但是，服务器重启时，它们的数据将丢失。

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

php

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

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

php

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 Octane ​

介绍 ​

安装 ​

服务器先决条件 ​

FrankenPHP ​

通过 Laravel Sail 安装 FrankenPHP ​

通过 Docker 安装 FrankenPHP ​

RoadRunner ​

通过 Laravel Sail 安装 RoadRunner ​

Swoole ​

Open Swoole ​

通过 Laravel Sail 安装 Swoole ​

Swoole 配置 ​

服务您的应用程序 ​

通过 HTTPS 服务您的应用程序 ​

通过 Nginx 服务您的应用程序 ​

监视文件更改 ​

指定工作进程数量 ​

指定最大请求数量 ​

重新加载工作进程 ​

停止服务器 ​

检查服务器状态 ​

依赖注入与 Octane ​

容器注入 ​

请求注入 ​

配置存储库注入 ​

管理内存泄漏 ​

并发任务 ​

滴答和间隔 ​

Octane 缓存 ​

缓存间隔 ​

表 ​

Laravel Octane

介绍

安装

服务器先决条件

FrankenPHP

通过 Laravel Sail 安装 FrankenPHP

通过 Docker 安装 FrankenPHP

RoadRunner

通过 Laravel Sail 安装 RoadRunner

Swoole

Open Swoole

通过 Laravel Sail 安装 Swoole

Swoole 配置

服务您的应用程序

通过 HTTPS 服务您的应用程序

通过 Nginx 服务您的应用程序

监视文件更改

指定工作进程数量

指定最大请求数量

重新加载工作进程

停止服务器

检查服务器状态

依赖注入与 Octane

容器注入

请求注入

配置存储库注入

管理内存泄漏

并发任务

滴答和间隔

Octane 缓存

缓存间隔

表