后盾人

Appearance

Laravel Octane ​

简介 ​

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

安装 ​

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

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=80" # [tl! add]
      XDG_CONFIG_HOME:  /var/www/html/config # [tl! add]
      XDG_DATA_HOME:  /var/www/html/data # [tl! add]

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

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

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

通过 Docker 使用 FrankenPHP ​

使用 FrankenPHP 的官方 Docker 镜像可以提供更好的性能,并使用不包含在静态安装的 FrankenPHP 中的其他扩展。此外,官方 Docker 镜像还支持在 FrankenPHP 不支持的平台上运行 FrankenPHP,例如 Windows。FrankenPHP 的官方 Docker 镜像既适用于本地开发,也适用于生产环境。

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

dockerfile
FROM dunglas/frankenphp

RUN install-php-extensions \
    pcntl
    # Add other PHP extensions here...

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

你可以参考 官方 FrankenPHP 文档获取更多关于如何使用 Docker 运行 FrankenPHP 的信息。

RoadRunner ​

RoadRunner 由 RoadRunner 二进制文件提供支持,该二进制文件是使用 Go 构建的。第一次启动基于 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

# Within the 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=80" # [tl! add]

最后,确保 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 的官方 Docker 开发环境。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=80" # [tl! add]

最后,构建你的 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 请求。你可以使用 --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;

/**
 * Register any application services.
 */
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;

/**
 * Register any application services.
 */
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']);
});

// Or...

$service->method($request->input('name'));

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

WARNING

在你的控制器方法和路由闭包上类型提示 Illuminate\Http\Request 实例是可以接受的。

配置仓库注入 ​

一般来说,你应该避免将配置仓库实例注入其他对象的构造函数。例如,以下绑定将配置仓库注入了一个作为单例绑定的对象:

php
use App\Service;
use Illuminate\Contracts\Foundation\Application;

/**
 * Register any application services.
 */
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;

/**
 * Handle an incoming request.
 */
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 方法时,由于 Swoole 任务系统的限制,你不应提供超过 1024 个任务。

定时任务和间隔 ​

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 表提供支持。存储在缓存中的所有数据都可以由服务器上的所有工作进程访问。但是,服务器重新启动时,缓存中的数据将被清除:

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

NOTE

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

缓存间隔 ​

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

php
use Illuminate\Support\Str;

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

表格 ​

WARNING

此功能需要 Swoole。

使用 Swoole 时,你可以定义和与任意 Swoole 表进行交互。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。

后盾人版权所有 © 2018-2024 创作不易请尊重他人劳动成果，未经授权禁止转载！