属于 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 实用指南 - CatchAdmin 后台管理系统框架 - 最新技术的 Laravel Admin Management System