hyperf 是运行在 linux 上的 php 协程框架，非发行版；单台服务器完整部署需四步：环境准备（ubuntu 22.04/centos 7/8、php ≥8.0、禁用 opcache.enable_cli）、swoole 扩展安装验证、composer 创建项目并配置多协议服务、nginx 反代加 supervisor 进程守护。

Hyperf 不是发行版，而是一个运行在 Linux 上的 PHP 协程框架。单台服务器完整部署，核心是环境准备、项目构建、服务暴露和生产加固四步，不依赖 Docker 也能稳定运行。

一、系统与 PHP 环境准备

推荐 Ubuntu 22.04 LTS（内核 ≥5.4）或 CentOS 7/8。需确保：

• PHP 版本 ≥8.0，编译时启用 mbstring、pcntl、bcmath、sockets、openssl、json、pdo、curl
• 禁用 CLI 模式下的 OPcache：opcache.enable_cli = 0（写入 php.ini）
• 关闭 SELinux（CentOS）：setenforce 0 并修改 /etc/selinux/config 中 SELINUX=disabled
• 关闭 firewalld 或放行端口：9501（HTTP）、9502（WebSocket）、9503（RPC）

二、Swoole 扩展安装与验证

Swoole 是 Hyperf 的底层引擎，必须正确安装：

Browser Setup (No-Root Linux)

在无 root/sudo 权限的环境（云容器、VPS、隔离主机）中安装并配置 OpenClaw 浏览器工具的 headless Chrome。适用场景：...

下载

• 执行 pecl install swoole（建议 v5.1+）
• 在 php.ini 中添加：extension=swoole
• 验证是否就绪：php --ri swoole，确认输出中包含 coroutine => enabled
• 检查扩展是否加载：php -m | grep swoole

三、创建项目并启用多协议服务

使用 Composer 创建标准骨架，按需开启 HTTP + WebSocket：

• 执行：composer create-project hyperf/hyperf-skeleton myapp
• 进入目录后安装 WebSocket 组件：cd myapp && composer require hyperf/websocket-server
• 编辑 config/autoload/server.php，在 servers 数组中追加 WebSocket 配置块，端口设为 9502
• 启动服务：php bin/hyperf.php start，应看到两个 Worker 启动日志，分别监听 9501 和 9502

四、Nginx 反向代理与生产加固

不直接暴露 Swoole 端口，用 Nginx 做统一入口和静态资源托管：

• 配置 Nginx 虚拟主机，location / 代理到 http://127.0.0.1:9501
• 对 WebSocket 路径（如 /ws）单独配置：proxy_http_version 1.1、Upgrade websocket、Connection "Upgrade"
• 设置 proxy_read_timeout 60，避免长连接被意外中断
• 生产环境务必配置 Supervisor 管理进程：supervisorctl reread && supervisorctl add hyperf，防止异常退出