Laravel Octane + FrankenPHP + 宝塔部署步骤

适用场景：Laravel 项目在宝塔面板中使用 Nginx 作为入口，后端由 Laravel Octane + FrankenPHP 常驻运行。

1. 前置条件

• 服务器内存建议大于 4GB。
• Laravel 项目已能正常通过 PHP-FPM / Nginx 运行。
• 服务器已安装 Composer。
• 宝塔站点已创建，站点根目录指向 Laravel 项目的 public 目录。
• 后续守护进程运行目录必须填写 Laravel 项目根目录，不是 public 目录。

2. 安装 Laravel Octane

在 Laravel 项目根目录执行：

composer require laravel/octane

安装 Octane 的 FrankenPHP 服务端：

php artisan octane:install --server=frankenphp

说明：

• 这个命令安装的是 Laravel Octane 对 FrankenPHP 的集成。
• vendor/bin 中没有单独的 frankenphp 二进制文件是正常现象。
• FrankenPHP 会通过 Octane 命令间接调用，不是以独立二进制包形式存在。

3. 调整 Octane 配置

打开：

config/octane.php

将：

'max_execution_time' => 30,

改为：

'max_execution_time' => 600,

含义：

• 0 表示不由 Octane 限制单次请求执行时间。
• 实际请求超时主要交给 Nginx、上传配置和业务代码控制。

4. 配置宝塔守护进程

打开宝塔面板的「守护进程」，新增一个 Octane 守护进程。

核心配置如下：

启动命令：

php artisan octane:start --server=frankenphp --host=0.0.0.0 --port=8000 --workers=2--max-requests=500

参数说明：

• --host=0.0.0.0：允许外部访问。必须配置，否则可能只监听本机地址。
• --port=8000：Octane 监听端口，可改为 9000 等未被占用端口。
• --workers=2：工作进程数，建议按服务器 CPU 核心数配置，例如 2、4、8。
• --max-requests=500：每个 worker 处理多少请求后自动重启，用于降低长期运行导致的内存泄漏风险。

5. 配置网站目录下的 php.ini

在网站目录下创建或编辑：

php.ini

写入：

upload_max_filesize = 100M
post_max_size = 120M
memory_limit = 512M
max_file_uploads = 20
max_execution_time = 300
max_input_time = 300

说明：

• upload_max_filesize：单个上传文件最大限制。
• post_max_size：整个 POST 请求体最大限制，必须大于 upload_max_filesize。
• memory_limit：单个 PHP 请求可使用的内存上限。
• max_execution_time、max_input_time：控制上传和请求处理的最长时间。

6. Nginx 配置思路

当宝塔站点已经配置了 Laravel 伪静态规则，并且无法直接添加反向代理时，推荐直接修改站点 Nginx 配置。

核心目标：

• Nginx 直接处理静态资源，例如图片、CSS、JS、字体文件。
• 所有动态请求转发给 Octane + FrankenPHP 的 8000 端口。
• 删除 PHP-FPM 解析配置，避免和 Octane 冲突。
• 删除宝塔伪静态规则引用，避免覆盖反向代理配置。

7. 站点 Nginx 示例配置

在宝塔站点 Nginx 配置中，按以下方式调整关键部分。

先注释或删除 PHP-FPM 解析配置：

# include enable-php-83.conf;

再注释或删除宝塔伪静态规则引用：

# include /www/server/panel/vhost/rewrite/nabi.host.conf;

静态资源由 Nginx 直接处理：

location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2|ttf|eot|svg|bmp|swf)$ {
    expires 30d;
    add_header Cache-Control "public, max-age=2592000";
    try_files $uri =404;
    error_log /dev/null;
    access_log /dev/null;
}

动态请求转发到 Octane + FrankenPHP：

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
}

8. 验证 Octane 是否运行

检查 FrankenPHP / Octane 进程：

ps aux | grep frankenphp

也可以检查端口是否监听：

ss -lntp | grep 8000

验证访问链路：

curl -I http://127.0.0.1:8000

如果本机 8000 端口正常，再访问站点域名确认 Nginx 反向代理是否生效。

9. 常见问题

9.1 vendor/bin 中没有 frankenphp

这是正常现象。当前安装方式是 Laravel Octane 集成 FrankenPHP，不一定会在 vendor/bin 中生成独立的 frankenphp 二进制文件。

9.2 站点仍然走 PHP-FPM

检查站点 Nginx 配置中是否仍包含：

include enable-php-83.conf;

如果存在，需要注释或删除，否则请求可能仍被 PHP-FPM 接管。

9.3 Laravel 伪静态和反向代理冲突

检查是否仍包含类似配置：

include /www/server/panel/vhost/rewrite/nabi.host.conf;

如果伪静态规则覆盖了 location / 的代理逻辑，需要注释或删除，并改为当前文档中的反向代理配置。

9.4 上传文件大小不生效

需要同时检查：

• 网站目录下的 php.ini 是否已创建。
• upload_max_filesize 是否小于 post_max_size。
• Nginx 是否存在额外的 client_max_body_size 限制。
• Octane 守护进程是否已重启。

如 Nginx 侧仍限制上传体积，可在站点配置中补充：

client_max_body_size 120M;

10. 总结

当 Laravel 伪静态与 Octane 反向代理冲突时，直接修改 Nginx 站点配置是最直接的方案。

最终结构应为：

• Nginx 负责处理静态资源，减少 Octane 压力。
• Nginx 将动态请求转发到 127.0.0.1:8000。
• Octane + FrankenPHP 常驻处理 Laravel 应用请求。
• 保留必要代理头，确保 Laravel 能正确识别域名、客户端 IP 和协议。

这种配置同时保留了 Octane 的高性能，以及 Nginx 处理静态资源的优势，适合作为生产环境部署方式。