Supervisor 入门指南一篇就够 —— 安装、项目配置与常见报错速查

Supervisor 入门指南一篇就够 —— 安装、项目配置与常见报错速查

一、Supervisor 是什么

在服务器进程管理中，Supervisor 是一款用 Python 编写的进程守护与管理工具。它的核心功能是将普通的命令行进程转变为后台 daemon 进程，并且在进程因意外情况退出时，能够自动将其重启，保证进程的持续运行。

在实际应用中，它常出现在多层架构里。比如在 Nginx → Gunicorn/Django → Supervisor 这样的四层架构中，Supervisor 就承担着让 Gunicorn 进程保持运行、“死不掉” 的重要角色。

二、安装（Linux 通用）

在不同的 Linux 系统中，我们可以通过多种方式安装 Supervisor，具体命令如下：

系统 / 方式	命令
Debian/Ubuntu	sudo apt-get install supervisor
CentOS/RHEL	sudo yum install -y supervisor
pip	pip install supervisor
无网络时	下载源码后执行 python setup.py install

安装完成后，系统会生成两个核心组件，分别是：

• supervisord：这是 Supervisor 的守护进程服务端，负责后台监控和管理进程。

• supervisorctl：作为命令行客户端，它提供了便捷的命令接口，用于对进程进行各种操作。

三、项目配置 3 步走

要使用 Supervisor 管理项目进程，只需完成以下三个步骤的配置：

（一）主配置文件

主配置文件通常位于 /etc/supervisord.conf。为了方便对不同项目的配置进行拆分管理，需要确保该文件末尾包含如下 include 段：

[include]


files = /etc/supervisor/conf.d/\*.conf

这样的设置能让 Supervisor 自动加载 /etc/supervisor/conf.d/ 目录下所有以 .conf 结尾的文件，实现项目配置的分离管理。

（二）创建项目专属配置

在 /etc/supervisor/conf.d/ 目录下，新建项目专属的配置文件，例如 myproject.conf，文件内容如下：

[program:myproject]


directory=/home/dlnu/myproject


command=python3 manage.py runserver 0.0.0.0:8000

autostart=true

autorestart=true

startsecs=3

user=dlnu


stdout\_logfile=/var/log/supervisor/myproject.out.log

stderr\_logfile=/var/log/supervisor/myproject.err.log

其中，[program:myproject] 用于标识项目名称，directory 指定项目运行目录，command 是启动项目的命令，autostart 和 autorestart 分别设置是否随 Supervisor 启动和进程意外退出时是否自动重启，startsecs 为启动超时时间，user 是运行项目的用户，stdout_logfile 和 stderr_logfile 则指定标准输出和错误输出的日志文件路径。

（三）载入并启动

完成上述配置后，执行以下命令载入配置并启动项目：

sudo supervisorctl reread


sudo supervisorctl update


sudo supervisorctl start myproject

reread 命令用于重新读取配置文件，update 命令会根据新的配置更新 Supervisor 管理的进程，start myproject 则启动指定项目。

四、日常命令速记

在日常管理进程时，以下这些命令非常实用：

任务	命令
查看全部状态	supervisorctl status
启动 / 停止 / 重启	supervisorctl start/stop/restart myproject
重新加载配置	supervisorctl reload
实时日志	supervisorctl tail -f myproject stderr

通过这些命令，我们可以方便地查看进程状态、控制进程的启动停止和重启，以及重新加载配置和查看实时日志。

五、常见报错与解决

使用过程中，可能会遇到一些错误，以下是常见的报错及解决办法：

报错信息	原因 & 解决
unix:///tmp/supervisor.sock no such file	由于 /tmp 目录会被系统定期清理，可能导致该 sock 文件丢失。解决办法是修改 supervisord.conf，将 sock、pid、log 等文件的路径指向 /var/run 和 /var/log 目录，这些目录相对稳定，不易被清理 。
Exited too quickly (process log may have details)	可能的原因有：一是 command 路径错误，导致无法启动进程；二是未激活虚拟环境，进程依赖的环境不正确；三是日志目录不存在或没有权限，进程无法写入日志。解决时需逐一排查这些问题，对权限问题可使用 chmod 更改权限、chown 更改所有者 。
Error: .ini file does not include supervisorctl section	该错误可能是因为配置文件缺少 [supervisorctl] 区块，或者相关文件权限不足。解决方法是在配置文件中添加该区块，并执行 chmod +x /usr/bin/supervisor* 赋予文件可执行权限，同时检查文件是否完整 。
端口已被占用	此时可通过 `ps -ef

六、小结

总的来说，Supervisor 就如同 “Linux 下的 pm2”，具有轻量且稳定的特点。

它的一个重要优势是所有配置支持热加载，执行 supervisorctl update 即可让新配置生效，不会中断正在运行的业务。

另外需要注意的是，日志文件一定要放在 /var/log 等持久目录，避免因 /tmp 目录被系统清空而导致日志丢失，进而引发异常。

按照本文介绍的步骤操作，只需 10 分钟左右，就能将 Python、Node、Go 等各类进程托管给 Supervisor，实现 “服务器重启也不怕” 的稳定运行效果。