hyperf项目迁移关键在配置一致性、环境兼容性和服务状态还原；需完整备份代码配置、composer.lock、数据库与redis数据、运行时元信息及定时任务配置，并严格校验php/swoole版本、权限和启动顺序。
Hyperf项目迁移不是简单复制文件，关键在配置一致性、环境兼容性和服务状态还原。单机部署下，备份恢复的核心是“可复现”——确保新环境能完全还原原运行态，包括进程管理、协程上下文、定时任务锁和数据库连接池状态。
一、备份阶段必须包含的5类内容
缺一不可，漏掉任意一项都可能导致启动失败或数据异常：
-
代码与配置文件：整个项目目录（含
app、config、runtime下的cache和container），特别注意.env和.watcher.php等隐藏配置文件 -
依赖锁定文件：必须保留
composer.lock，仅靠composer.json重装可能引入不兼容版本（尤其Swoole、Hyperf组件小版本差异易引发协程调度异常） -
数据库结构与数据：使用
mysqldump导出全库（含存储过程、触发器），推荐加--routines --triggers --events参数；若用Redis作缓存/锁，需redis-cli bgsave后拷贝dump.rdb -
运行时元信息：记录原服务器
php -v、php --ri swoole输出，以及ps aux | grep hyperf看到的worker数、端口、PID文件路径（如runtime/hyperf.pid） -
自定义进程与定时任务配置：检查
config/autoload/processes.php和config/autoload/crontab.php，确认onOneServer、mutexPool等分布式锁参数是否适用于单机场景（迁移后应设为false避免Redis依赖）
二、新服务器初始化要点
Windows系统需额外处理WSL兼容性，Linux服务器则要校验Swoole基础：
- 验证
php版本与原环境一致（Hyperf 3.x要求PHP ≥ 8.1，且pcntl、posix扩展必须启用） - Swoole需≥5.0，执行
php --ri swoole确认enable_coroutine为On，short_name为Off（MineAdmin等衍生框架强制要求） - 若原环境用WSL，新机也需启用WSL2并安装相同发行版（如Ubuntu 22.04），否则
swoole_get_local_mac()等底层调用可能返回空值，影响Crontab节点识别 - 新建项目用户（如
hyperf），将项目目录归属权赋给该用户，避免runtime目录权限拒绝写入
三、恢复与启动关键操作
顺序不能颠倒，否则服务会卡在等待Redis锁或数据库连接超时：
- 先还原数据库：
mysql -u root -p minadmin ，再修改<code>.env中的DB_HOST指向本地（127.0.0.1而非localhost，规避MySQL socket连接问题） - 执行
composer install --no-dev --optimize-autoloader，跳过开发依赖并生成高效自动加载映射 - 清空旧缓存：
rm -rf runtime/container/ runtime/cache/，防止容器注入关系错乱 - 启动前校验配置：
php bin/hyperf.php gen:publish确保所有配置已发布，再运行php bin/hyperf.php migrate:status确认迁移版本匹配 - 正式启动：
php bin/hyperf.php start，观察日志中Worker#0 started及HTTP Server listening at 0.0.0.0:9501是否出现；若报Address already in use，检查netstat -tuln | grep 9501并杀掉残留进程
四、验证与收尾动作
仅访问首页成功不算完成，需验证核心链路是否真正就绪：
- 用
curl -I http://127.0.0.1:9501/health检查健康接口（Hyperf默认提供），返回200 OK且Content-Type: application/json - 触发一个带数据库操作的API（如登录接口），观察
runtime/logs/hyperf.log是否有SQL query日志，确认PDO连接池已生效 - 手动执行一条定时任务：
php bin/hyperf.php cron:run --force，验证crontab.php中singleton => true是否阻止重复执行 - 最后设置开机自启：Linux用
systemd服务文件（指定User=hyperf和WorkingDirectory），Windows WSL则用sudo crontab -e添加@reboot /usr/bin/php /var/www/MineAdmin/bin/hyperf.php start
