Supervisor 是什么

约 4486 字大约 15 分钟

Tool

2026-08-09

严格来说，Supervisor 不是代码部署工具，而是进程托管工具。

什么是Supervisor

介绍

它扮演的角色是：代码部署完成后，由它持续管理Webman的运行，确保Webman进程一直活着。
Supervisor是运行在Linux/Unix系统上的进程管理工具。它负责启动、停止、监控和自动重启长期运行的程序—————比如Webman、队列消费者、定时任务等

提示

Supervisor不是Webman的一部分，也不是Composer依赖，而是安装在服务器操作系统上的独立软件。

简答来说：Supervisor 是 Webman 的"保姆"，Webman 进程意外退出时，Supervisor 会自动把它重新拉起来。

组成部分

三大组成部分

组件	角色	说明
`supervisord`	服务端	真正负责启动和监控进程的后台守护进程
`supervisorctl`	客户端	命令行工具，向 `supervisord` 发送管理命令
`supervisord.conf`	配置文件	定义 `supervisord` 自身以及需要管理的程序

安装

方式一：通过系统软件包安装

Ubuntu / Debian：

sudo apt update
sudo apt install supervisor
sudo systemctl enable --now supervisor

CentOS / Rocky Linux / AlmaLinux：

dnf info supervisor        # 先检查是否存在
sudo dnf install supervisor

系统软件包通常会自动配置 systemd 开机启动，比较省心，但版本可能落后于 PyPI 官方版本。如果默认仓库中没有该软件包，需要根据当前发行版配置对应软件源，或选择 pip 方式安装。

方式二：通过 Python pip 安装

Supervisor 本身是用 Python 编写的，可以通过 pip 安装到独立虚拟环境，便于获取较新版本。

# 创建独立虚拟环境
python3 -m venv /opt/supervisor
/opt/supervisor/bin/pip install supervisor

# 生成示例配置
/opt/supervisor/bin/echo_supervisord_conf > /etc/supervisord.conf

# 启动 supervisord（当前会话有效）
/opt/supervisor/bin/supervisord -c /etc/supervisord.conf

# 查看状态
/opt/supervisor/bin/supervisorctl -c /etc/supervisord.conf status

pip 安装后，supervisord 不会自动开机启动。需要手动配置 systemd 服务或 init 脚本，否则服务器重启后 Supervisor 不会自动恢复。

配置Supervisor开机启动

创建 systemd 服务文件：

sudo vim /etc/systemd/system/supervisor.service

写入以下内容（注意路径替换为你的实际安装路径）：

[Unit]
# 服务的简短描述，说明该服务的作用
Description=Supervisor process control system
# 依赖关系：指定本服务在网络服务（network.target）启动之后再启动，确保网络环境就绪
After=network.target

[Service]
# 服务进程模型：forking 表示主进程启动后会派生（fork）子进程，然后父进程退出，
# systemd 会追踪子进程作为主服务进程。这符合传统 Unix 守护进程的启动方式
Type=forking

# 启动命令：执行 supervisord 守护进程，并通过 -c 参数指定其主配置文件路径
ExecStart=/opt/supervisor/bin/supervisord -c /etc/supervisord.conf

# 停止命令：当执行 systemctl stop 时，通过 supervisorctl 客户端发送 shutdown 指令，优雅地关闭 supervisord 及其管理的所有子进程
ExecStop=/opt/supervisor/bin/supervisorctl -c /etc/supervisord.conf shutdown

# 重载命令：当执行 systemctl reload 时，通知 supervisord 重新读取配置文件并应用变更
ExecReload=/opt/supervisor/bin/supervisorctl -c /etc/supervisord.conf reload

# 停止时的信号发送模式：process 表示仅向主进程发送停止信号，而不影响其管理的子进程组
KillMode=process

# 重启策略：on-failure 表示当服务异常退出（非正常退出码）或被信号终止时，systemd 会自动尝试重启该服务
Restart=on-failure

# 重启延迟：服务异常退出后，等待 42 秒再进行重启操作，避免频繁重启导致系统资源耗尽
RestartSec=42s

[Install]
# 安装目标：指定当系统进入多用户模式（multi-user.target，相当于传统的 runlevel 3 或 5）时，自动启动此服务，实现开机自启
WantedBy=multi-user.target

重新加载 systemd 并设置开机自启：

# 1. 重新加载 systemd 管理器配置
# 作用：当你新增、修改或删除了 .service 单元文件（如 supervisor.service）后，
# 必须执行此命令，让 systemd 重新扫描并识别磁盘上最新的配置变更。
# 注意：如果不执行这一步，后续启动或启用服务时，systemd 可能仍在使用内存中的旧配置，导致不生效或报错。
sudo systemctl daemon-reload


# 2. 设置开机自启并立即启动服务（合并操作）
# 作用：这是 `systemctl enable` 和 `systemctl start` 的合并写法。
# - `enable`：配置服务在系统启动时自动拉起，实现开机自启。
# - `--now`：在设置自启的同时，立刻启动该服务，使其在当前会话中开始运行并接管子进程。
sudo systemctl enable --now supervisor

验证状态：

sudo systemctl status supervisor

宝塔安装

宝塔私有 Python 环境
→ 宝塔版 supervisord
→ 宝塔负责启动和管理

重要

软件包安装通常自带 systemd 服务；pip 安装不带 systemd 服务，所以需要手动配置开机启动；宝塔服务器则使用宝塔自己的 Supervisor 管理方式。

为什么使用Supervisor：八个核心优点

1.SSH 断开后程序仍然运行

手动执行

php start.php start

关闭 SSH 会话后，程序可能跟着停止。因为手动启动的进程是当前 Shell 的子进程，Shell 断开时子进程可能收到 SIGHUP 信号而退出。

Supervisor 作为系统服务在后台独立运行，不依赖任何 SSH 会话，启动后持续运行。

2.Webman 崩溃后自动重启

配置：

autorestart=true

如果 Webman 主进程异常退出，Supervisor 会重新执行：

php start.php start

把服务中断时间降到最低。

3.服务器重启后自动启动

配置:

autostart=true

服务器重启后（比如机房断电、系统更新重启），supervisor会自动启动Webman，不需要重新登录服务器手动启动。

4.统一管理进程

可以使用统一命令操作：

supervisorctl status video-oss-webman
supervisorctl start video-oss-webman
supervisorctl stop video-oss-webman
supervisorctl restart video-oss-webman

日常管理命令

Supervisor 的管理命令取决于安装方式：

安装方式	`supervisorctl` 路径	配置文件
系统软件包	`/usr/bin/supervisorctl`	由发行版决定
pip虚拟环境	`/opt/supervisor/bin/supervisorctl`	`/etc/supervisord.conf`
宝塔安装	`/www/server/panel/pyenv/bin/supervisorctl`	`/etc/supervisor/supervisord.conf`

使用前应先确认 Supervisor 的安装方式。不要混用命令路径和配置文件，否则可能连接到错误的 Supervisor 实例，或者出现 command not found、connection refused、no such process 等错误。

系统软件包安装:

Ubuntu、Debian、CentOS等系统软件包安装后，通常可以直接使用：

命令	作用
`supervisorctl status`	查看所有进程状态
`supervisorctl status video-oss-webman`	查看指定进程状态
`supervisorctl start video-oss-webman`	启动 Webman
`supervisorctl stop video-oss-webman`	停止 Webman
`supervisorctl restart video-oss-webman`	重启 Webman
`supervisorctl reread`	重新读取配置文件
`supervisorctl update`	应用配置变更
`supervisorctl tail -f video-oss-webman`	实时查看 Webman 日志

pip虚拟环境安装:

如果 Supervisor 安装在：
/opt/supervisor

需要使用完整命令路径：
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  status

其他操作只需要替换最后的动作：

# 查看指定进程
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  status video-oss-webman

# 启动
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  start video-oss-webman

# 停止
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  stop video-oss-webman

# 重启
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  restart video-oss-webman

# 读取并应用配置
sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  reread

sudo /opt/supervisor/bin/supervisorctl \
  -c /etc/supervisord.conf \
  update

宝塔安装

宝塔版 Supervisor 使用自己的 Python 环境：

/www/server/panel/pyenv/bin/supervisorctl \
-c /etc/supervisor/supervisord.conf \
status

当前 Webman 项目的常用命令：

# 查看状态
/www/server/panel/pyenv/bin/supervisorctl \
  -c /etc/supervisor/supervisord.conf \
  status video-oss-webman

# 启动
/www/server/panel/pyenv/bin/supervisorctl \
  -c /etc/supervisor/supervisord.conf \
  start video-oss-webman

# 停止
/www/server/panel/pyenv/bin/supervisorctl \
  -c /etc/supervisor/supervisord.conf \
  stop video-oss-webman

# 重启
/www/server/panel/pyenv/bin/supervisorctl \
  -c /etc/supervisor/supervisord.conf \
  restart video-oss-webman

# 查看实时日志
/www/server/panel/pyenv/bin/supervisorctl \
  -c /etc/supervisor/supervisord.conf \
  tail -f video-oss-webman

也可以直接在宝塔面板的进程管理页面中完成启动、停止和重启。

重要

比手动查PID、执行kill更清晰、更规范

video-oss-webman 是 Supervisor 配置中的程序名称，来自 [program:video-oss-webman]。如果读者配置的程序名称不同，应将命令中的名称替换为自己的程序名称。

5.可以看到真实的进程状态

Supervisor能准确显示进程状态：

状态	含义
`RUNNING`	正在运行
`STOPPED`	已经停止
`BACKOFF`	启动后马上又退出了
`FATAL`	多次启动失败
`EXITED`	进程已经退出

Supervisor自己创建Webman子进程并持续监控，所以比单纯读取PID文件更清楚进程是否还存在、处于什么阶段。
注意：RUNNING 只代表进程还在运行，不代表 HTTP 服务、数据库连接、业务逻辑一定健康。

6.集中管理日志

stdout_logfile=/www/wwwlogs/video-oss-webman.log
redirect_stderr=true

Webman的标准输出和错误输出会统一写入日志文件，方便排查启动失败、进程退出等问题。

重要

生产环境建议配置日志轮转，防止日志文件持续增长占满磁盘：

stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10

7.限定运行用户和目录

配置：

directory=/www/wwwroot/upload-video-play-video
user=www

这样可以保证

在正确的项目目录启动 Webman

使用 www 用户运行，而不是 root

避免长期使用 root 权限运行 Webman 带来的安全风险

文件权限更加统一、可控

8.可以管理多个后台程序

除了Webman HTTP服务，Supervisor还能同时管理：

Webman HTTP 服务

队列消费者（如 Redis 队列消费进程）

视频处理任务

定时任务调度进程

WebSocket 服务

消息推送进程

提示

每个进程可以独立启动、停止、重启和查看日志，通过一个配置目录统一管理。

完整的配置事例

下面是一份Webman项目的Supervisor 完整配置文件

[program:video-oss-webman]

; 项目根目录
directory=/www/wwwroot/upload-video-play-video

; 启动命令（前台运行，不要加 -d）
command=/www/server/php/82/bin/php start.php start
; 运行用户
user=www
; supervisord 启动时自动拉起 
autostart=true

; 进程退出后自动重启
autorestart=true

; 将错误输出重定向到标准输出
redirect_stderr=true

; 日志文件路径
stdout_logfile=/www/wwwlogs/video-oss-webman.log

; 日志轮转：单文件最大 50MB，保留 10 个备份
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10

关键配置点说明

关键点说明

配置项	说明
`command`	使用前台模式，不要加 `-d`。Supervisor 需要直接监控 Webman / Workerman 主进程；如果程序自己 daemon`（守护进程）` 化到后台，Supervisor 可能无法准确跟踪真正运行的进程，进而影响状态判断、停止和自动重启。
`directory`	指定程序启动时的工作目录。Webman 的 `start.php`、`.env`、配置文件等通常都依赖正确的项目目录，因此建议明确配置，避免 Supervisor 从其他目录启动导致文件找不到。
`user`	指定运行 Webman 的系统用户。生产环境建议使用低权限用户，例如宝塔环境中的 `www`，不要长期使用 `root` 运行应用进程，以降低安全风险。
`autostart`	设置为 `true` 后，表示 supervisord 启动时自动启动该程序。需要注意，它只有在 `supervisord` 本身已经配置为系统开机自启的前提下，才能实现服务器重启后自动启动 Webman。
`autorestart`	设置为 `true` 后，当 Webman 主进程退出时，Supervisor 会自动重新执行 `command`。它解决的是“进程退出”问题，不等同于 HTTP 健康检查；如果进程仍然存在但接口已经卡死，Supervisor 默认不会自动重启。
`redirect_stderr`	设置为 `true` 后，会把标准错误输出 `stderr` 合并到标准输出 `stdout`，统一写入 `stdout_logfile`，方便集中查看启动错误和运行异常。
`stdout_logfile`	指定程序标准输出日志文件的位置。建议使用独立日志文件，方便通过 `tail -f` 等命令查看 Webman 启动和运行日志。
`stdout_logfile_maxbytes`	限制单个日志文件的最大大小。生产环境建议配置，防止日志文件无限增长最终占满磁盘，例如 `50MB`。
`stdout_logfile_backups`	指定日志轮转后保留多少个历史文件。例如设置为 `10`，表示最多保留 10 个旧日志文件，与 `stdout_logfile_maxbytes` 配合使用。
`startsecs`	指定程序启动后需要连续运行多少秒，Supervisor 才认为启动成功。程序如果在这个时间内退出，可能被判定为启动失败并进入 `BACKOFF`。
`startretries`	指定程序启动失败后最多重试多少次。超过次数后，进程可能进入 `FATAL` 状态，需要人工排查启动失败原因。
`stopsignal`	指定 Supervisor 停止程序时发送的信号，默认通常为 `TERM`。对于能够正确处理 `SIGTERM` 的程序，一般不需要修改。
`stopwaitsecs`	Supervisor 发送停止信号后等待程序正常退出的最长时间。超过该时间仍未退出时，Supervisor 可能会强制结束进程。

Supervisor的加载原理

整个过程可以简单理解为：

启动 supervisord 
    ↓ 
读取 Supervisor 主配置文件 
    ↓ 
加载各个 [program:xxx] 配置 
    ↓ 
解析 command、directory、user 等参数 
    ↓
根据 autostart 判断是否启动程序 
    ↓
执行 php start.php start 
    ↓ 
创建 Webman / Workerman 主进程 
    ↓ 
持续监控主进程 
    ↓ 
进程异常退出时根据 autorestart 决定是否重新启动

1.supervisord启动

在使用 systemd 的 Linux 系统中，我们通常不会手动直接运行它，而是通过：

systemctl start supervisor

进程关系大致如下：

systemd
    ↓
supervisord

supervisord 启动之后会长期运行在后台，负责管理所有交给 Supervisor 托管的程序。

例如：

supervisord 
    ├── Webman 
    ├── Queue Worker 
    ├── WebSocket 
    └── Video Worker

2.读取主配置文件

supervisord 启动之后，首先需要读取自己的配置文件。

常见位置包括：

/etc/supervisor/supervisord.conf

或者：

/etc/supervisord.conf

具体路径会根据 Linux 发行版和 Supervisor 安装方式有所不同。

主配置文件中通常会存在类似配置：

[include]
files = /etc/supervisor/conf.d/*.conf

意思是：
除了读取当前主配置文件，还要继续加载 /etc/supervisor/conf.d/ 目录中的所有 .conf 配置。

因此实际结构通常类似：

/etc/supervisor/supervisord.conf 
        │ └── include ↓ /etc/supervisor/conf.d/ 
        │ ├── webman.conf 
        ├── queue.conf 
        └── websocket.conf

重要

这样就可以把不同程序拆成不同配置文件管理

3.加载 [program:xxx]

Supervisor 读取以后，可以理解为得到了这样一份“运行说明书”：

程序名称 
    ↓ video-oss-webman 工作目录 
    ↓ /www/wwwroot/upload-video-play-video 启动命令 
    ↓ /www/server/php/82/bin/php start.php start 运行用户 
    ↓ www supervisord 启动后是否自动运行 
    ↓ 是 程序退出后是否重新启动 
    ↓ 是

4.[program:video-oss-webman]
本质上就是在告诉 Supervisor：请帮我管理一个叫 video-oss-webman 的程序，并按照下面这些配置运行它。

4.根据 autostart 判断是否启动

如果配置：

autostart=true

那么 supervisord 在加载这个 program 后，就会尝试启动它。

完整关系是：

服务器启动
    ↓
systemd 启动 supervisord
    ↓
supervisord 读取配置
    ↓
发现 video-oss-webman
    ↓
发现 autostart=true
    ↓
启动 Webman

因此这里一定要注意：

autostart=true

并不是 Linux 系统直接帮你启动 Webman。

当 supervisord 自己启动后，自动启动这个 program。

5.切换到 directory 指定的目录

配置：

directory=/www/wwwroot/upload-video-play-video

表示 Supervisor 在执行启动命令之前，需要先进入这个目录。

可以近似理解成：

cd /www/wwwroot/upload-video-play-video

然后再运行：

/www/server/php/82/bin/php start.php start

6.使用 user 指定的用户运行

user=www

Supervisor 会使用 www 用户运行 Webman。

也就是说：

supervisord
    ↓
切换为 www 用户
    ↓
执行 php start.php start

因此 Webman 运行过程中涉及的：

日志文件

缓存文件

runtime 目录

上传文件

临时文件

都会受到 www 用户权限的影响。

所以必须保证运行用户对需要读写的目录具有正确权限。

7.执行 command

前面的参数准备完成之后，Supervisor 最终会执行：

command=/www/server/php/82/bin/php start.php start

也就是启动：

/www/server/php/82/bin/php start.php start

此时进程关系大致变成：

supervisord
PID 1000
    │
    └── php start.php start
        PID 2000
            │
            ├── Worker PID 2001
            ├── Worker PID 2002
            ├── Worker PID 2003
            └── Worker PID 2004

其中：

PID 2000

就是 Supervisor 直接启动并监控的 Webman / Workerman 主进程。

而 Workerman 主进程再负责管理下面的 Worker。

所以进程管理关系是：

Supervisor
    ↓
Workerman 主进程
    ↓
Worker 子进程

这也是为什么前面强调：

php start.php start

不要写成：

php start.php start -d

因为使用 -d 后，Workerman 会自己 daemon 化到后台，可能脱离 Supervisor 直接创建的前台进程。

Supervisor 最理想的管理关系应该始终是：

supervisord
↓
Webman / Workerman 主进程
↓
Worker

8.Supervisor 持续监控进程

Supervisor 并不是把 Webman 启动起来以后就不管了。启动只是第一步。

接下来最重要的工作是：持续监控这个进程是否还存在。

Supervisor
    ↓
Webman 主进程
    ↓
RUNNING

如果 Webman 主进程突然异常退出：

Webman 主进程
    ↓
EXIT

Supervisor 会检测到：

我管理的进程已经退出了

如果配置：

autorestart=true

Supervisor 就会再次执行
php start.php start

于是：

Webman 主进程退出
    ↓
Supervisor 检测到退出
    ↓
autorestart=true
    ↓
重新执行 command
    ↓
创建新的 Webman 主进程
    ↓
恢复 RUNNING

Supervisor 解决不了什么

Supervisor 是进程托管工具，不是部署系统，以下事情它不负责：

能力	Supervisor 是否提供
上传和更新项目代码	❌
数据库迁移	❌
自动回滚版本	❌
检查接口业务是否正常	❌
保证零停机发布	❌
检查 Webman 是否卡死但进程仍存在	❌

重要

Supervisor 判断程序是否正常，主要依据是它启动的子进程是否还活着，而不是检查网站接口是否返回 200。

Nginx / Webman / Workerman / Supervisor 的关系

请求链（谁处理请求）

客户端请求
    ↓
Nginx（80/443 端口）
    ↓ 转发动态请求
127.0.0.1:8787（Webman 监听地址）
    ↓
Workerman HTTP Worker（执行业务逻辑）

管理链（谁管理谁）

Supervisor
    ↓ 监控
Workerman 主进程（php start.php start）
    ↓ 管理
HTTP Worker 进程池（处理实际请求）

关系图

链	方向	关系
请求链	Nginx → Worker	请求转发
管理链	Supervisor → 主进程 → Worker	进程监控与生命周期管理

遇到异常

Workerman 主进程异常退出
    ↓
Supervisor 检测到子进程消失
    ↓
Supervisor 重新执行 php start.php start
    ↓
Workerman 重新创建 HTTP Worker 进程池
    ↓
网站恢复服务

版权所有

版权归属：念宇

许可证：署名-非商业性-禁止演绎 4.0 国际 (CC-BY-NC-ND-4.0)