属于 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 的替代品，它是进程管理器。如果你需要定时执行任务，应该：

用 cron 调用一次性脚本，或者
写一个循环脚本用 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 实用指南