HyperfApi 安装部署教程（宝塔面板）

本教程基于宝塔 / aaPanel 面板演示如何从零部署一套 HyperfApi。Hyperf 是常驻内存、基于 Swoole 协程的 PHP 框架，运行机制和传统 PHP-FPM 项目差别较大，因此安装前需要对 PHP 环境做一些针对性配置，请按步骤操作。

什么是Hyperf Api？

基于 Hyperf 3.1 构建的后台管理与会员服务系统，面向 API 接口平台、内容站点和积分运营场景。系统内置后台管理端、用户中心、CMS 内容管理、接口市场、支付订单、积分商城、短信、工单、搜索索引和在线安装能力，可作为业务后台或接口服务平台的基础骨架继续扩展。

演示站点：https://api.qzqi.com/

核心功能

• 后台管理：管理员登录、角色组、菜单规则、操作日志、系统配置、附件、区块和友情链接管理。
• 会员体系：用户注册登录、资料维护、余额与积分、签到、等级、邀请、地址和资产流水。
• API 平台：接口分类、接口详情、API Key、套餐、VIP、兑换码、调用日志、计费扣减和用户购买能力。
• CMS 内容管理：栏目、内容模型、字段配置、内容、标签、评论、搜索日志、付费记录，以及前台栏目、详情、搜索、标签页。
• 支付订单：支持余额充值、积分充值、API 套餐、CMS 付费内容等业务场景的支付处理，并预留支付宝、微信、易支付通道。
• 积分商城：商品分类、商品、卡密、兑换、发货、退款与用户兑换记录。
• 工单系统：用户提交工单、回复工单，后台处理与关闭工单。
• 短信能力：短信通道配置、模板、变量解析和验证码发送。
• 搜索与 SEO：Elasticsearch / Scout 索引管理、站点地图、RSS、robots.txt 与百度推送服务。
• 在线安装：提供数据库、Redis、Elasticsearch 连接检测，支持写入环境配置并执行初始化流程。

技术栈

• PHP 8.2+
• Hyperf 3.1
• Swoole协程运行环境
• MySQL
• Redis
• Elasticsearch/Hyperf Scout
• Twig 模板引擎
• Pest、PHPUnit、PHPStan、PHP-CS-Fixer

环境要求

组件	版本
Nginx	1.30.3
MySQL	8.4.8
PHP	8.2.31
Swoole	6.x
Redis	需安装（扩展 + 服务）

提示：Hyperf 3.1 要求 PHP ≥ 8.1，本教程使用 PHP 8.2。请确保面板中已安装 Redis 服务（用于缓存/队列等）。

---

1. 新建 MySQL 数据库

在宝塔面板 数据库 中新建一个数据库，记下数据库名、用户名和密码，后续安装页面需要填写。

---

2. 配置 PHP 8.2 扩展

2.1 安装必要扩展

进入 软件商店 → PHP 8.2 → 设置 → 安装扩展，依次安装：

• fileinfo
• redis
• Swoole6

Swoole 是 Hyperf 的运行基础，必须安装；redis 扩展用于连接 Redis 服务；fileinfo 是常见依赖。

2.2 关闭 Swoole 短名称

进入 软件商店 → PHP 8.2 → 设置 → 配置文件，新增以下配置项并保存：

swoole.use_shortname = 'Off'

为什么要关闭：Swoole 默认会注册 go()、defer() 等短别名函数，这些会与 Hyperf 框架内部的同名函数冲突，导致启动报错，因此必须关闭。

---

3. 解除 PHP 禁用函数

宝塔面板出于安全考虑默认禁用了一批函数，但 Hyperf 依赖这些函数来管理进程和协程，需要解除禁用。

进入 软件商店 → PHP 8.2 → 设置 → 禁用函数，删除以下函数：

• exec
• putenv
• proc_open
• pcntl_fork
• pcntl_wait

这些函数用于子进程管理、信号处理和协程调度，缺一不可。删除后建议重启 PHP。

---

4. 上传并解压程序

将程序压缩包 HyperfApi.zip 上传到建站目录（本教程为 /data/wwwroot/HyperfApi），并解压。
HyperfApi.zip 

---

5. 安装依赖包

进入解压后的项目目录，执行 composer install 安装依赖：

cd /data/wwwroot/HyperfApi
composer install

常见问题排查

1. Composer 下载慢

可将源切换为国内镜像后再安装：

composer config -g repos.packagist composer https://mirrors.cloud.tencent.com/composer/

2. Composer 版本低

可将Composer更新后再安装：

composer self-update

3. Composer 依赖问题

composer update

---

6. 启动并完成安装向导

在项目目录命令行执行启动命令：

cd /data/wwwroot/HyperfApi
php bin/hyperf.php start

注意：宝塔环境下默认的 php 命令未必是 8.2，若版本不符请使用完整路径，例如：
/www/server/php/82/bin/php bin/hyperf.php start

启动成功后，浏览器访问：

http://服务器IP:9501

进入安装向导页面，按提示填写数据库 / Redis / 网站信息完成配置。

安装完成后，回到启动服务的终端，按 Ctrl + C 终止 Hyperf 进程，准备进入正式部署。

若访问不通，请检查：服务器安全组 / 防火墙是否放行 9501 端口；启动终端是否有报错日志。

---

7. 生产环境部署

7.1 使用 Supervisor 守护进程

Hyperf 是常驻进程，需要使用 Supervisor 守护，确保异常退出后自动拉起、并随系统开机自启。

配置方法参考官方文档：https://hyperf.wiki/3.1/#/zh-cn/tutorial/supervisor

或使用 宝塔 进程守护管理 插件

7.2 Nginx 反向代理

Supervisor 配置完成、服务稳定运行在 127.0.0.1:9501 后，使用 Nginx 反向代理对外提供服务。在站点配置中加入：

location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_pass http://127.0.0.1:9501;
}

保存并重载 Nginx 后，即可通过域名正常访问。

---

至此，Hyperf 应用部署完成。后续更新代码后，记得通过 Supervisor 重启服务（如 supervisorctl restart 进程名）使变更生效。

程序下载