属于 PHP 开发者的 Supervisor 实用指南

在 PHP 开发中，我们经常需要运行一些后台进程：队列处理、长时间运行的脚本、WebSocket 服务器等。这些进程可能会因为各种原因意外退出，手动重启既麻烦又不可靠。Supervisor 是一个进程控制系统，专门用来解决这类问题——它能够自动管理后台进程，在进程异常退出时自动重启，并提供统一的日志管理。

本文将详细介绍 Supervisor 的安装、配置和使用，帮助您构建更稳定的 PHP 应用。

Supervisor 简介

Supervisor 是一个进程控制系统，主要功能包括：

• 自动重启异常退出的进程
• 统一管理进程日志输出
• 提供命令行和 Web 界面进行进程监控和控制

对于 PHP 开发者而言，Supervisor 特别适用于：

• Laravel 队列处理器
• 长时间运行的后台脚本（如 WebSocket 服务）
• 需要持续运行的任务处理程序

安装 Supervisor

Ubuntu/Debian 系统

sudo apt update sudo apt install supervisor 

CentOS/RedHat 系统

sudo yum install epel-release sudo yum install supervisor 

安装完成后启动并设置开机自启：

sudo systemctl start supervisord sudo systemctl enable supervisord 

基本用法

Supervisor 通过配置文件来管理各个程序，配置文件通常存放在 /etc/supervisor/conf.d/ 目录下。

基础配置示例

以下是一个简单的配置示例。假设需要持续运行一个 PHP 脚本，在 /etc/supervisor/conf.d/my_worker.conf 中创建配置文件：

[program:my_worker] command=php /path/to/worker.php autostart=true autorestart=true stderr_logfile=/var/log/my_worker.err.log stdout_logfile=/var/log/my_worker.out.log 

配置完成后，需要让 Supervisor 重新读取配置并启动程序：

sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start my_worker 

详细配置选项

基础配置

command

：指定要执行的命令

command=php /path/to/worker.php 

autostart

：Supervisor 启动时是否自动启动该程序

autostart=true # 默认值为 true 

autorestart

：程序退出时的重启策略

autorestart=true # 总是重启 autorestart=false # 从不重启 autorestart=unexpected # 仅在异常退出时重启（推荐） 

user

：指定运行程序的系统用户

user=www-data 

directory

：设置程序的工作目录

directory=/path/to/your/app 

启动和重启控制

startsecs

：程序启动后需要保持运行多少秒才算启动成功

startsecs=5 # 默认 1 秒 

startretries

：启动失败时的重试次数

startretries=3 # 默认 3 次 

exitcodes

：哪些退出码被认为是正常退出（不会触发重启）

exitcodes=0,2 # 默认值 

stopwaitsecs

：发送停止信号后等待多少秒再强制杀死进程

stopwaitsecs=10 # 默认 10 秒 

stopasgroup

：停止时是否连同子进程一起停止

stopasgroup=true # 推荐设置为 true 

killasgroup

：强制杀死时是否连同子进程一起杀死

killasgroup=true # 推荐设置为 true 

日志管理

stdout_logfile / stderr_logfile

：标准输出和错误输出的日志文件

stdout_logfile=/var/log/my_program.out.log stderr_logfile=/var/log/my_program.err.log 

redirect_stderr

：是否把错误输出重定向到标准输出

redirect_stderr=true # 所有输出都记录到一个文件 

stdout_logfile_maxbytes

：日志文件最大大小，超过后会自动轮转

stdout_logfile_maxbytes=50MB # 默认 50MB 

stdout_logfile_backups

：保留多少个轮转后的日志文件

stdout_logfile_backups=10 # 默认 10 个 

环境变量和优先级

environment

：配置环境变量

environment=APP_ENV="production",DB_HOST="localhost",REDIS_HOST="127.0.0.1" 

priority

：设置启动优先级，数值越小优先级越高

priority=100 # 默认值为 999 

实际应用场景

管理 Laravel 队列处理器

Laravel 队列处理是 Supervisor 最常见的应用场景：

[program:laravel_queue_worker] command=php /var/www/html/artisan queue:work --sleep=3 --tries=3 --max-time=3600 directory=/var/www/html autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/log/laravel_queue_worker.log stopwaitsecs=3600 

配置说明：

• numprocs=2：同时运行 2 个队列处理进程
• --max-time=3600：每小时重启一次，避免内存泄漏
• stopwaitsecs=3600：停止时等待足够时间让当前任务完成

运行定时任务

需要注意：Supervisor 不是 cron 的替代品，它是进程管理器。如果你需要定时执行任务，应该：

1. 用 cron 调用一次性脚本，或者
2. 写一个循环脚本用 Supervisor 管理

循环脚本示例：

[program:task_scheduler] command=php /var/www/html/task_scheduler.php directory=/var/www/html autostart=true autorestart=true user=www-data stdout_logfile=/var/log/task_scheduler.log stderr_logfile=/var/log/task_scheduler_error.log 

管理 WebSocket 服务器

长时间运行的 WebSocket 服务：

[program:websocket_server] command=php /var/www/html/websocket_server.php directory=/var/www/html autostart=true autorestart=true user=www-data stdout_logfile=/var/log/websocket_server.log stderr_logfile=/var/log/websocket_server_error.log stopasgroup=true killasgroup=true 

多进程配置

如果需要运行多个相同的进程：

[program:multi_worker] command=php /var/www/html/worker.php directory=/var/www/html autostart=true autorestart=true user=www-data numprocs=4 process_name=%(program_name)s_%(process_num)02d stdout_logfile=/var/log/worker_%(process_num)02d.log 

这会创建 4 个进程：multi_worker_00、multi_worker_01、multi_worker_02、multi_worker_03。

常用命令

# 查看所有程序状态 sudo supervisorctl status # 启动程序 sudo supervisorctl start program_name # 停止程序 sudo supervisorctl stop program_name # 重启程序 sudo supervisorctl restart program_name # 重新读取配置文件 sudo supervisorctl reread # 应用配置变更 sudo supervisorctl update # 查看程序输出（类似 tail -f） sudo supervisorctl tail program_name # 清空日志 sudo supervisorctl clear program_name 

开机自启设置

确保系统重启后 Supervisor 能自动启动：

# 设置开机自启 sudo systemctl enable supervisord # 启动服务（如果还没启动的话） sudo systemctl start supervisord # 检查状态 sudo systemctl status supervisord 

实用技巧

日志轮转配置

为了避免日志文件过大，建议这样配置：

stdout_logfile_maxbytes=50MB stdout_logfile_backups=5 stderr_logfile_maxbytes=50MB stderr_logfile_backups=5 

环境变量管理

对于需要不同环境变量的程序：

environment=APP_ENV="production", DB_HOST="localhost", DB_PORT="3306", REDIS_HOST="127.0.0.1" 

优雅停止

对于需要优雅停止的程序（比如正在处理任务的队列处理器）：

stopsignal=QUIT stopwaitsecs=60 stopasgroup=true killasgroup=true 

监控和调试

Web 界面

Supervisor 提供了一个简单的 Web 界面，在主配置文件 /etc/supervisor/supervisord.conf 中启用：

[inet_http_server] port=127.0.0.1:9001 username=admin password=your_password 

然后重启 Supervisor，就可以通过 http://localhost:9001 访问管理界面。

日志查看

# 实时查看程序输出 sudo supervisorctl tail -f program_name # 查看错误日志 sudo supervisorctl tail -f program_name stderr 

常见问题排查

程序启动失败

• 检查命令路径是否正确（使用绝对路径）
• 确认运行用户有执行权限
• 验证工作目录是否存在且可访问
• 查看错误日志：sudo supervisorctl tail program_name stderr

程序反复重启

• 检查程序本身是否有问题（手动运行测试）
• 适当增加 startsecs 值，给程序更多启动时间
• 检查 exitcodes 配置，确保正常退出码不会触发重启

无法停止程序

• 检查程序是否正确处理信号（SIGTERM）
• 增加 stopwaitsecs 值
• 设置 stopasgroup=true 和 killasgroup=true

日志相关问题

• 日志目录权限问题：确保运行用户可写入日志目录
• 日志文件过大：设置合理的 stdout_logfile_maxbytes
• 日志轮转：配置 stdout_logfile_backups 数量

总结

Supervisor 是 PHP 开发者管理后台进程的重要工具。无论是 Laravel 队列处理、长时间运行的服务，还是其他需要持续运行的程序，都可以通过 Supervisor 实现稳定运行和自动恢复。

成功使用 Supervisor 的关键在于根据具体应用场景合理配置各项参数，特别要注意日志管理、重启策略和优雅停止等方面的设置。正确配置后，您的 PHP 应用将能够实现 24×7 稳定运行。

原文链接-属于 PHP 开发者的 Supervisor 实用指南