Hyperf 基于 Supervisor 的常驻进程守护部署指南

原创2026-10-09 11:22:561,893 阅读
文章标签:后端微服务

Hyperf 基于 Supervisor 的常驻进程守护部署指南

导读

Hyperf 是常驻内存的 CLI 协程框架,服务以 php bin/hyperf.php start 的方式在命令行中长期运行,一旦进程意外退出(被 Kill、内存耗尽、OOM 等),服务就会中断。Supervisor 是 Linux/Unix 系统下的进程管理工具,可以监听、启动、停止和重启一个或多个进程,并能在进程异常退出时自动拉起,是 Hyperf 生产环境中最常用的守护方案之一。本文以 docs/zh-tw/tutorial/supervisor.md 为骨架,结合仓库内快速开始文档与源码,完整讲解 Supervisor 的安装、配置、启动与日常管理,并给出关键的 ulimit 与 minfds 调优建议。

Supervisor 能解决 Hyperf 的什么问题

Hyperf 内置了协程服务器,服务以 CLI(命令行)形式执行。从 快速开始 - 启动 Hyperf 服务 可以看到,启动命令为:

php bin/hyperf.php start

由于 Hyperf 是持久化的 CLI 应用,一旦进程启动,已解析的 PHP 代码会持久化在进程内,这意味着服务运行期间修改的 PHP 代码不会生效,需要重启进程才能重新加载(详见 快速开始 - 重新加载代码 与 快速开始 - 安装)。

这种「常驻 + 单进程多协程」的运行模式对进程稳定性要求极高:

  • 进程被系统 OOM Killer 杀掉后,服务立即不可用;
  • 内存泄漏或未捕获异常可能导致进程异常退出;
  • 手动用 nohup 等方式后台运行,进程挂掉后没有任何自动恢复机制。

Supervisor 恰好解决这些问题:它作为守护进程监听被管理程序的运行状态,当程序意外被 Kill 时,会自动将其重启,无需自己编写 shell 脚本来管理进程,即可实现程序自动恢复。Supervisor 在文档导航中同样出现在 部署相关文档索引 里,与 Nginx 反向代理、Docker 化部署、DaoCloud 部署 等共同构成 Hyperf 的部署体系。

安装 Supervisor

Supervisor 官方支持的平台为 Linux/Unix,安装方式因发行版而异。以下以 CentOS 系统为例(对应文档 Supervisor 部署 的安装章节):

# 安装 epel 源,如果此前安装过,此步骤跳过
yum install -y epel-release
yum install -y supervisor

说明:epel-release 是 CentOS 的扩展软件源(Extra Packages for Enterprise Linux),Supervisor 位于该源中,因此需要先启用。如果你的系统此前已经安装过 epel 源,可直接跳过第一条命令。安装完成后,系统会提供 supervisord(守护进程本体)与 supervisorctl(管理客户端)两个命令。

创建 Supervisor 配置文件

复制默认配置

yum 安装完成后,系统默认会生成一份全局配置 /etc/supervisord.conf。文档建议将其复制到配置目录中再编辑:

cp /etc/supervisord.conf /etc/supervisord.d/supervisord.conf

添加 Hyperf 应用配置段

编辑新复制出来的配置文件 /etc/supervisord.d/supervisord.conf,在文件结尾处追加以下内容后保存:

# 新建一个应用并设置一个名称,这里设置为 hyperf
[program:hyperf]
# 设置命令在指定的目录内执行
directory=/var/www/hyperf/
# 这里为您要管理的项目的启动命令
command=php ./bin/hyperf.php start
# 以哪个用户来执行该进程
user=root
# supervisor 启动时自动启动该应用
autostart=true
# 进程退出后自动重启进程
autorestart=true
# 进程持续运行多久才认为是启动成功
startsecs=1
# 重试次数
startretries=3
# stderr 日志输出位置
stderr_logfile=/var/www/hyperf/runtime/stderr.log
# stdout 日志输出位置
stdout_logfile=/var/www/hyperf/runtime/stdout.log

关键配置项说明

配置项 示例值 作用
[program:hyperf] hyperf 定义一个被管理应用,hyperf 是该应用在 Supervisor 中的唯一名称,后续 supervisorctl start hyperf 即以此名称操作
directory /var/www/hyperf/ 设置命令执行的目录,对应项目的真实根目录,command 中的相对路径 ./bin/hyperf.php 以此为基准
command php ./bin/hyperf.php start 项目启动命令,即 Hyperf 服务的启动入口;也可以写成绝对路径形式,如英文版文档中的 php /var/www/hyperf/bin/hyperf.php start
user root 以哪个系统用户运行该进程,决定进程对项目目录、日志文件的读写权限
autostart true Supervisor 自身启动时是否自动拉起该应用
autorestart true 进程退出后是否自动重启,这是实现「自动恢复」的核心开关
startsecs 1 进程持续运行多少秒才被认为「启动成功」,避免启动即崩溃的程序被反复计为重试(英文版文档示例为 5,可按业务启动耗时调整)
startretries 3 启动失败后的最大重试次数
stderr_logfile /var/www/hyperf/runtime/stderr.log 标准错误输出日志文件路径
stdout_logfile /var/www/hyperf/runtime/stdout.log 标准输出日志文件路径,Hyperf 的运行日志(含启动 banner、协程服务器监听信息等)会写入此处

其中 command 对应的 bin/hyperf.php 是 Hyperf 框架标准的命令行入口文件:在 watcher 组件的入口脚本 中可以看到,它依次在项目目录、上级目录、当前工作目录中探测 bin/hyperf.php 并 require_once,印证了 bin/hyperf.php 是 Hyperf 应用的统一入口约定;快速开始文档同样使用 php bin/hyperf.php start 作为标准启动命令(见 快速开始 - 安装)。

调优 minfds 与系统 ulimit

!> 文档特别提醒:建议同时增大配置文件中的 minfds 配置项(Supervisor 默认为 1024),同时修改系统的 ulimit 设置,防止出现 Failed to open stream: Too many open files 的问题。

背景说明:Hyperf 基于 Swoole 协程实现,单进程内可承载成千上万的并发连接(HTTP、WebSocket、TCP、Redis 连接池、数据库连接池等都会占用文件描述符)。Supervisor 默认对每个子进程设置 minfds = 1024 的文件描述符下限,如果系统层面的 ulimit -n 也保持默认的 1024,高并发场景下就很容易触发文件描述符耗尽。

建议的调整方式:

  • 在 /etc/supervisord.d/supervisord.conf 的 [supervisord] 段中调大 minfds,例如 minfds=65535;
  • 同时通过 ulimit -n(或修改 /etc/security/limits.conf)提升当前用户与 shell 会话的文件描述符上限,使其与 minfds 匹配;
  • 由于 Swoole 服务器本身也会占用文件描述符,必要时还需结合 Swoole 文档中对系统参数的说明进行整体规划,确保「Supervisor 下限 ≤ 系统上限」,且两者都留有余量。

启动 Supervisor

基于配置文件启动 Supervisor 守护进程:

supervisord -c /etc/supervisord.d/supervisord.conf
  • supervisord 是 Supervisor 的守护进程本体,-c 参数指定使用哪个配置文件;
  • 因为配置中 autostart=true,Supervisor 启动时会自动拉起 hyperf 应用;
  • 启动后可立即用下面的 supervisorctl status 验证 hyperf 是否处于 RUNNING 状态。

使用 supervisorctl 管理 Hyperf 应用

supervisorctl 是 Supervisor 提供的管理客户端,日常对 Hyperf 服务的启停、重启、状态查看与配置热加载都通过它完成:

# 启动 hyperf 应用
supervisorctl start hyperf
# 重启 hyperf 应用
supervisorctl restart hyperf
# 停止 hyperf 应用
supervisorctl stop hyperf
# 查看所有被管理项目的运行状态
supervisorctl status
# 重新加载配置文件(新增或修改 [program:x] 段后执行,使配置生效)
supervisorctl update
# 重启所有程序(supervisord 自身重新读取配置并拉起所有应用)
supervisorctl reload

与 Hyperf 代码变更流程配合

结合 Hyperf「持久化 CLI 应用」的特性,日常发布流程通常是:

  1. 拉取 / 同步最新代码到 /var/www/hyperf/;
  2. 执行 supervisorctl restart hyperf 重启服务,使新代码生效(这一点与快速开始文档中「CTRL + C 终止后再重新启动」的手动方式等价,只是由 Supervisor 托管后通过 restart 命令完成);
  3. 执行 supervisorctl status 确认服务回到 RUNNING 状态,再继续后续验证。

若修改了配置文件中的 [program:hyperf] 段(例如调整 command、startsecs、日志路径),无需重启整个 supervisord,执行 supervisorctl update 即可热加载新配置;需要变更 [supervisord] 段(如 minfds)时,则使用 supervisorctl reload 或重启 supervisord 进程。

部署方案搭配与备选

Supervisor 负责「进程拉起与自动恢复」,而 Hyperf 对外提供服务还需要网络层面的配套:

  • 配合 Nginx 反向代理:HTTP 服务由 Supervisor 守护、监听 9501 端口,Nginx 负责对外 80/443 端口代理与负载均衡,参见 Nginx 部署文档;
  • 容器化 / 云平台场景:若采用容器或云托管,可参考 Docker 化部署(Docker Swarm) 与 DaoCloud 部署,由容器编排平台承担类似守护职责;
  • 开发期热重载:Supervisor 的 restart 是代码变更生效的标准方式;若希望在开发期免重启,可了解 watcher 组件入口 所支撑的热更新方案,生产环境仍建议以 Supervisor(或容器编排)守护为准。

总结

对常驻内存的 Hyperf 应用而言,Supervisor 提供了开箱即用的进程守护能力:通过 <a href="https://link.gitcode.com/i/d2c302a63f6a9a9f1c6230eae7caf14a" target="_blank">program:hyperf] 配置段声明启动命令与重启策略,autostart 与 autorestart 保证进程在系统重启或异常退出后自动恢复;supervisorctl 系列命令覆盖启动、停止、重启、状态查看与配置热加载的完整操作闭环。部署时需特别注意 minfds 与系统 ulimit 的一致性调优,避免高并发场景下文件描述符耗尽导致服务异常。结合 [Nginx、Docker Swarm 等部署文档,即可搭建一套完整的 Hyperf 生产部署方案。

登录后查看全文
hyperf