传统 FPM 项目渐进式迁移到 Swoole/Hyperf 完整方案 下面是一份实战派迁移指南,不搞理想化重写,而是一边赚钱一边换引擎。---一、先讲清楚:为啥要迁?要迁到哪?1.1FPM 的痛点-每个请求都要重新加载框架(Laravel 启动30~80ms,Hyperf 启动后0ms)-不能保持长连接(MySQL/Redis 每次重连)-无法做内存级缓存、定时任务、WebSocket、长轮询1.2两条迁移路线对比 ┌───────────────────────────────────┬────────────────┬──────────┬─────────────────┐ │ 路线 │ 工作量 │ 性能提升 │ 风险 │ ├───────────────────────────────────┼────────────────┼──────────┼─────────────────┤ │ FPM → LaravelOctane(Swoole 模式)│ 小,改5%代码 │3~5倍 │ 低,代码几乎不动 │ ├───────────────────────────────────┼────────────────┼──────────┼─────────────────┤ │ FPM → Hyperf 重写 │ 大,改60%代码 │10~20倍 │ 中,但架构干净 │ └───────────────────────────────────┴────────────────┴──────────┴─────────────────┘ 大白话决策树:-业务还在快速迭代、团队人少 → 走 Octane-项目要做大、有微服务需求、QPS 目标过万 → 逐步迁 Hyperf-不要一次性全迁,无论选哪条都要渐进---二、路线 A:Laravel →Octane(渐进、低风险)阶段0:体检(1天)跑一遍单例污染扫描:composer require--dev laravel/octane php artisan octane:install--serverswoole php artisan octane:check # Laravel11自带 手工扫这些坑(关键!):#1.找静态属性 grep-rnstatic \$app/|grep-vfunction#2.找单例存请求状态的 grep-rnapp()-instance\|app()-singletonapp/#3.找 Auth::user()缓存在静态变量里的 grep-rnstatic.*user\|self::\$userapp/阶段1:改造代码(3~7天)1.1静态变量污染(最常见的坑)❌ 错误写法(FPM 没事,Octane 会跨请求泄漏):class CurrentUser{privatestatic?User $usernull;// ← 上个请求的用户被下个请求看到!publicstaticfunctionset(User $u):void{self::$user$u;}publicstaticfunctionget():?User{returnself::$user;}}✅ 正确写法:用容器作用域// app/Providers/AppServiceProvider.phppublic functionregister():void{$this-app-scoped(CurrentUser::class,function(){returnnewCurrentUser();});}scoped()单例,但每个请求结束后自动销毁。Octane 专门为这种场景设计的容器方法,大白话就是请求级单例。1.2单例里别存 Request ❌ 错误:class ReportService{public function__construct(private Request $request){}// 绑死了第一个请求!}$this-app-singleton(ReportService::class);✅ 正确:用 scoped 或每次从容器取 $this-app-scoped(ReportService::class);// 请求级单例// 或者改用 method 注入:public function build(Request $request)1.3配置 Octane 监听器(关键)config/octane.php:listeners[RequestReceived::class[...Octane::prepareApplicationForNextOperation(),...Octane::prepareApplicationForNextRequest(),// 自己的清理逻辑\App\Listeners\FlushApplicationState::class,],RequestTerminated::class[FlushUploadedFiles::class,\App\Listeners\FlushApplicationState::class,],],warm[// 这些单例每次请求开始时自动重建\App\Services\ReportService::class,\Illuminate\Auth\AuthManager::class,],flush[// 这些环境变量 / 配置每次请求清掉],app/Listeners/FlushApplicationState.php:?php namespace App\Listeners;use Illuminate\Support\Facades\DB;class FlushApplicationState{public functionhandle():void{// 清掉自己的全局状态(如果有)\App\Support\CurrentUser::reset();// 防 DB 连接状态泄漏(事务没提交、临时表等)foreach(array_keys(config(database.connections))as $conn){DB::connection($conn)-disconnect();}}}阶段2:本地预发跑通(1周)php artisan octane:start--serverswoole--port8000--workers4--max-requests500压测对比:#FPM 跑ab-n10000-c50http://fpm.local/api/orders#Octane 跑ab-n10000-c50http://octane.local:8000/api/orders通常 QPS 翻3~5倍。 阶段3:灰度上线(2周)关键:同时跑 FPM 和 Octane,Nginx 按权重分流。/etc/nginx/sites-available/myapp.conf:upstream backend{#FPM 占90%流量(走 unix socket)server unix:/var/run/php/php8.2-fpm.sock weight9;#Octane 占10%流量(先观察)server127.0.0.1:8000weight1;}server{listen443ssl http2;server_name api.myapp.com;location/{# 如果是 FPM 请求,走 fastcgiif($upstream_addr~unix:){#...走 fastcgi}proxy_pass http://backend;}}更稳妥的做法:Nginx 按 URL 灰度 location/api/v2/{proxy_pass http://127.0.0.1:8000; # 新接口走 Octane}location/{fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;# 老接口走 FPM}大白话:新写的接口直接 Octane,老接口慢慢迁。 阶段4:全量切换(确认无内存泄漏后)监控指标:-Worker 内存增长曲线(必须平稳)-请求耗时 P99-业务异常率 切完后:-关掉 FPM-Nginx 改成纯 Octane upstream-删掉 FPM 配置---三、路线 B:Laravel → Hyperf 渐进式迁移 核心思想:双写流量切分,不停机 ┌──→ Nginx ──┬──→ 老 Laravel/FPM(80%流量)公网域名 ────────┤ │ └──→ API Gateway ──┬──→ 新 Hyperf 服务(20%流量)└──→ 共享 MySQL/Redis 阶段0:架构对齐(2周)0.1数据库不变,共用-Laravel 和 Hyperf 连同一个 MySQL-两边的 ORM 都用同一张表,模型字段保持一致0.2缓存/Session 改成集中存储-Session 从 file 改成Redis(两边能读同一个 session)-Cache 改成 Redis,key 加版本号防冲突 config/session.php:driverenv(SESSION_DRIVER,redis),connectionsession,Hyperf 这边对应配置:// config/autoload/session.phpreturn[handlerHyperf\Session\Handler\RedisHandler::class,options[connectiondefault,gc_maxlifetime1200,cookie_namePHPSESSID,// ← 跟 Laravel 一致!],];0.3用户认证打通(关键)-JWT 是最简单的方案-Laravel 签发的 JWT,Hyperf 能解开,反之亦然-Secret 和算法两边必须一致.env(两边一样):JWT_SECRET同一个长字符串 JWT_ALGOHS256 阶段1:搭 Hyperf 骨架(1周)composer create-project hyperf/hyperf-skeleton hyperf-app cd hyperf-app composer require hyperf/jwt firebase/php-jwt composer require hyperf/model-cache hyperf/redis 目录约定(和 Laravel 保持类似,降低心智负担):hyperf-app/├── app/│ ├── Controller/← 对标 Laravel app/Http/Controllers │ ├── Service/← 业务逻辑 │ ├── Model/← 对标 Laravel app/Models,字段和 Laravel 完全一致 │ ├── Middleware/│ └── Exception/├── config/└── bin/hyperf.php Model 直接抄 Laravel 的字段:// Laravel: app/Models/Order.phpclass Order extends Model{protected $tableorders;protected $fillable[user_id,amount,status];}// Hyperf: app/Model/Order.phpclass Order extends \Hyperf\DbConnection\Model\Model{protected?string $tableorders;protected array $fillable[user_id,amount,status];}接口契约严格一致:同一个 URL 在 FPM 和 Hyperf 上返回的 JSON 完全一样。 阶段2:按接口迁移(每周迁1~3个)2.1选迁移顺序的原则 按高 QPS 低耦合优先:┌──────────────┬────────┬────────────────────┐ │ 类型 │ 优先级 │ 例子 │ ├──────────────┼────────┼────────────────────┤ │ 只读高频接口 │ ★★★★★ │ 商品列表、文章详情 │ ├──────────────┼────────┼────────────────────┤ │ 简单 CRUD │ ★★★★ │ 评论、点赞 │ ├──────────────┼────────┼────────────────────┤ │ 长连接需求 │ ★★★★★ │ WebSocket、SSE │ ├──────────────┼────────┼────────────────────┤ │ 复杂业务 │ ★ │ 下单、支付(最后迁)│ ├──────────────┼────────┼────────────────────┤ │ 后台管理 │ 不迁 │ 留 FPM 就行 │ └──────────────┴────────┴────────────────────┘2.2Nginx 路由切分(核心配置)upstream laravel_fpm{server unix:/var/run/php/php8.2-fpm.sock;}upstream hyperf_app{server127.0.0.1:9501;keepalive32;# 长连接复用}server{listen443ssl http2;server_name api.myapp.com;# 已迁移的接口走 Hyperf location/api/products{proxy_pass http://hyperf_app;proxy_http_version1.1;proxy_set_header Connection;}location~^/api/products/[0-9]${proxy_pass http://hyperf_app;}location/ws{proxy_pass http://hyperf_app;proxy_http_version1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connectionupgrade;proxy_read_timeout86400;}# 其余全部 Laravel location/{try_files $uri/index.php?$query_string;}location~\.php${fastcgi_pass laravel_fpm;include fastcgi_params;}}2.3灰度发布单个接口 第1步:Hyperf 实现接口// app/Controller/ProductController.php#[Controller(prefix:/api)]class ProductController{#[Inject]protected ProductService $service;#[GetMapping(/products)]public functionindex(RequestInterface $request):array{return[code0,data$this-service-list(page:(int)$request-input(page,1),size:(int)$request-input(size,20),),];}}第2步:返回结果对比工具(自动校验两边一致)写一个临时中间件,同时打 FPM 和 Hyperf,比对结果:// 跑在压测机上,不上生产class DualCallChecker{public functioncheck(string $path):array{$aHttp::get(http://fpm.internal{$path})-json();$bHttp::get(http://hyperf.internal{$path})-json();if(json_encode($a)!json_encode($b)){Log::error(mismatch,[path$path,fpm$a,hyperf$b]);return[okfalse];}return[oktrue];}}第3步:Nginx 灰度1%split_clients${remote_addr}${request_uri}$backend{1%hyperf_app;*laravel_fpm;}location/api/products{proxy_pass http://$backend;}观察1天 →5%→20%→50%→100%。2.4共享代码怎么办?老项目里有 app/Helpers.php、app/Services/PaymentService.php,Hyperf 怎么复用?三种方式:1.简单工具函数:复制粘贴一份到 Hyperf,几十行不疼2.复杂业务逻辑:抽成 HTTP 微服务,FPM 和 Hyperf 都调3.超复杂的(支付、计费):暂时不迁,Hyperf 调 FPM 的接口// Hyperf 调老 Laravel 的支付接口$result$this-httpClient-post(http://fpm.internal/api/pay,[json[order_id$id,amount$amount],]);大白话:别一上来就把所有代码搬过去,先打通流量,业务慢慢拆。 阶段3:数据一致性兜底3.1缓存 key 命名空间隔离// Laravel: cache:laravel:user:1001// Hyperf: cache:hyperf:user:1001// 共享数据: cache:shared:product:423.2数据库迁移谁来管?约定:DDL(建表改表)只在 Laravel 这边跑,Hyperf 只读结构、不发起 migration。否则两边的 migration 历史会打架。#Laravelphp artisan migrate#Hyperf 不跑 migration,只跑业务3.3模型监听器(observer)Laravel 的 Order::saved 监听器,在 FPM 写订单时触发,但 Hyperf 写订单时不会触发(它根本不知道你写了 Laravel 的监听器)。 解决:重要的写后逻辑改成事件队列// Laravel 和 Hyperf 都往同一个 Redis 队列发事件Redis::lpush(events:order:created,json_encode($order));// 起一个独立的 worker 消费(放哪边都行)阶段4:WebSocket/定时任务迁过去(Hyperf 强项)4.1WebSocket-原本 LaravelPusher/Soketi 的方案,直接换成 Hyperf 自带的 WebSocket Server-推送消息时,Laravel 往 Redis 发,Hyperf 订阅推送给客户端// Laravel 端Redis::publish(user.1001.notice,json_encode([msghello]));// Hyperf 端订阅 Redis → 推 WebSocket4.2定时任务-Laravel 的 schedule:run 是 FPM,每分钟启动一次,启动开销大-Hyperf 的 Crontab 常驻内存,秒级精度,零启动开销-任务一个一个迁过去 阶段5:Laravel 萎缩到只剩老接口→ 最终下线 迁移到70%后,Laravel 这边只剩:-老的后台管理-几个复杂的支付/账单接口-离线脚本 这时再决定:-留着也行(后台管理对 QPS 没要求)-想全干掉就再花1~2个月把支付迁完---四、迁移期监控清单(必做)┌─────────────────┬────────────────────────────┬──────────────────────────┐ │ 监控项 │ 工具 │ 告警阈值 │ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ 两边响应一致率 │ 自研对比脚本 │99.9%告警 │ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ Worker 内存增长 │ Prometheusnode_exporter │1小时涨100M │ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ 请求 P99 │APM(Sentry/SkyWalking)│ 比 FPM 慢就回滚 │ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ Redis 连接数 │ RedisInsight │ 突增50%│ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ MySQL 连接数 │ MySQL Exporter │ 接近 max_connections80%│ ├─────────────────┼────────────────────────────┼──────────────────────────┤ │ 业务异常率 │ 日志聚合 │ 同比0.1%立即查 │ └─────────────────┴────────────────────────────┴──────────────────────────┘---五、回滚预案(必须有)任何阶段都要能1分钟回滚:# 灰度阶段:改 Nginx 配置 sed-is/1% hyperf_app/0% hyperf_app//etc/nginx/conf.d/myapp.conf nginx-s reload # 流量瞬间全回 FPM # 全量阶段:DNS/SLB 切回老入口 # 提前留一个完整 FPM 环境别拆,至少留1个月---六、常见踩坑清单 ┌───────────────────────────────────┬───────────────────┬─────────────────────────────────────────────────────────┐ │ 坑 │ 路线 │ 解决 │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ 静态变量跨请求泄漏 │ Octane/Hyperf │ 用容器 scoped,禁用static存状态 │ │ │ 都有 │ │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ MySQL 连接 MySQL server has gone │ 两边都有 │ 开心跳/连接池 max_idle_time │ │ away │ │ │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ Session 在两边不通 │ 路线 B │ 改 Redis sessioncookie 名一致 │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ Auth::user()拿不到 │ 路线 B │ 改成 JWT,两边共用 secret │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ Carbon::now()在 Octane 被冻结 │ 路线 A │ 用 Date::createFromMutable(now()-toDateTime())或每次 │ │ │ │ new │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ 容器单例污染 │ 路线 A │ singleton 改 scoped │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ Hyperf 模型缓存和 Laravel 不一致 │ 路线 B │ 缓存 key 加 namespace,或关闭一边的缓存 │ ├───────────────────────────────────┼───────────────────┼─────────────────────────────────────────────────────────┤ │ 文件上传后路径不对 │ 路线 A │ Octane 下 $_FILES 已废弃,用 $request-file()│ └───────────────────────────────────┴───────────────────┴─────────────────────────────────────────────────────────┘---七、时间线参考(中型项目)┌────────────┬────────────────┬────────────────┐ │ 阶段 │ 路线A(Octane)│ 路线B(Hyperf)│ ├────────────┼────────────────┼────────────────┤ │ 体检改造 │1周 │2周 │ ├────────────┼────────────────┼────────────────┤ │ 灰度上线 │1~2周 │1个月 │ ├────────────┼────────────────┼────────────────┤ │ 全量切换 │2周 │3~6个月 │ ├────────────┼────────────────┼────────────────┤ │ 回收老环境 │1周 │1个月 │ ├────────────┼────────────────┼────────────────┤ │ 合计 │1~2个月 │ 半年 │ └────────────┴────────────────┴────────────────┘---八、一句话总结 ▎ 不要重写,要替换。 一边赚钱一边换引擎:▎-流量层用 Nginx 切分 ▎-数据层共享 MySQL/Redis ▎-认证用 JWT 打通 ▎-一个接口一个接口迁,有问题随时回滚 ▎ ▎ 想省事选 Octane,想做大选 Hyperf,别犹豫别贪多。---要不要我再展开:-Octane 改造完整 checklist自动扫描脚本-Hyperf 端 JWT 共享 Laravel session 的完整代码-双跑校验工具(自动对比 FPM 和 Hyperf 接口返回)-Nginx 灰度配置进阶(按用户 ID、按 header 灰度)