Supervisor 安装与使用指南

本文介绍如何在 Debian / Ubuntu 系统上安装 Supervisor，并完成基础配置、进程托管、服务管理与常见问题排查。目标是把它写成一份可以直接照着执行的实用文档，而不是只停留在概念说明。

适用场景

需要长期守护一个 Go / Python / Node / Shell 进程
需要在崩溃后自动拉起服务
需要统一管理多个后台任务
需要比手工 nohup 更可控的进程管理方式

Supervisor 是什么

Supervisor 是一个进程控制系统，用来启动、停止、重启和守护后台进程。它不是 systemd 的替代品，而是更适合管理“具体业务进程”的一层工具。

适合它的场景通常是：

一个服务由你自己的二进制或脚本启动
服务应该持续运行
服务退出后需要自动重启
需要查看标准输出和错误输出

安装前准备

先更新系统软件包索引：

sudo apt update

确认系统已经具备 sudo 权限，并且你知道要托管的程序以什么方式启动。

安装 Supervisor

在 Debian 上，直接使用系统仓库安装即可：

sudo apt install -y supervisor

安装完成后，检查版本：

supervisord --version

说明：

Debian 的 supervisor 包是常规可用方案
如果你只是需要稳定、易维护的进程守护，系统仓库版本通常足够
如果你依赖最新特性，再考虑从上游 Python 包安装

启动服务并设置开机自启

安装完成后，启动 Supervisor 服务并设置开机自动运行：

sudo systemctl enable supervisor
sudo systemctl start supervisor

查看状态：

sudo systemctl status supervisor

正常情况下应显示为 active (running)。

配置文件位置

Debian 常见配置目录是：

/etc/supervisor/supervisord.conf

进程配置通常放在：

/etc/supervisor/conf.d/

Supervisor 官方文档说明，supervisord.conf 是主配置文件，supervisorctl 和 supervisord 都可以读取它。Debian 包通常已经把这套目录结构准备好了。

基础工作原理

Supervisor 的核心是两部分：

supervisord：后台守护进程，负责管理子进程
supervisorctl：命令行控制工具，用来查看状态、启动、停止和重载

常用交互方式：

sudo supervisorctl status

如果你要管理的程序是由 Supervisor 启动的，它必须以前台模式运行，不能自己先 fork 到后台再退出。

添加一个托管程序

下面以一个常见示例说明如何托管程序。

假设你有一个程序：

/opt/myapp/myapp

建议为它创建单独的配置文件：

sudo nano /etc/supervisor/conf.d/myapp.conf

内容示例：

[program:myapp]
command=/opt/myapp/myapp
directory=/opt/myapp
autostart=true
autorestart=true
startsecs=5
startretries=3
stopsignal=TERM
stopasgroup=true
killasgroup=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/myapp/stdout.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5
stderr_logfile=/var/log/myapp/stderr.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5
environment=APP_ENV="prod"

参数说明

command：真正执行的命令
directory：程序工作目录
autostart=true：Supervisor 启动时自动拉起
autorestart=true：进程退出后自动重启
startsecs：启动后至少保持运行多少秒才算启动成功
startretries：启动失败重试次数
stopsignal：停止时发送的信号，常见是 TERM
stopasgroup=true：停止整个进程组
killasgroup=true：强制结束时连子进程一起处理
user：以哪个系统用户运行
redirect_stderr=true：把 stderr 合并到 stdout
stdout_logfile / stderr_logfile：日志文件

重要约束

Supervisor 文档明确说明，程序必须适合在前台运行。很多守护型程序默认会自己后台化，这种程序要改成前台模式再交给 Supervisor 管理。

常见做法：

Go 程序直接前台运行
Python Web 服务加前台参数
Node 程序直接 node app.js
Shell 脚本不要自己 nohup 后台化

重新加载配置

添加或修改配置文件后，需要重新读取并更新：

sudo supervisorctl reread
sudo supervisorctl update

说明：

reread：读取新增或修改过的配置
update：把配置变化应用到运行中的 Supervisor

控制进程

查看状态：

sudo supervisorctl status

启动程序：

sudo supervisorctl start myapp

停止程序：

sudo supervisorctl stop myapp

重启程序：

sudo supervisorctl restart myapp

查看所有日志：

sudo tail -f /var/log/myapp/stdout.log
sudo tail -f /var/log/myapp/stderr.log

常用场景模板

1. Go 二进制

[program:api]
command=/opt/api/api-server
directory=/opt/api
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/api/api.log
stdout_logfile_maxbytes=20MB
stdout_logfile_backups=10

2. Python 脚本

[program:worker]
command=/usr/bin/python3 /opt/worker/main.py
directory=/opt/worker
autostart=true
autorestart=true
user=www-data

3. Node.js 服务

[program:web]
command=/usr/bin/node /opt/web/server.js
directory=/opt/web
autostart=true
autorestart=true
user=www-data

4. Shell 脚本

[program:task]
command=/bin/bash /opt/task/run.sh
directory=/opt/task
autostart=true
autorestart=true
user=www-data

日志管理

Supervisor 默认会把进程输出写到日志文件。要注意这几件事：

不要把多个进程写到同一个带轮转的日志文件里
日志目录要提前创建并保证权限正确
如果日志文件设置不当，程序可能因为权限问题启动失败

建议先创建日志目录：

sudo mkdir -p /var/log/myapp
sudo chown -R www-data:www-data /var/log/myapp

如果你希望程序输出到系统日志，也可以结合 redirect_stderr 和外部日志采集方案处理。

配置检查

在重新加载前，建议先检查配置文件内容是否正确：

command 指向的文件是否存在
directory 是否真实存在
user 是否有执行权限
日志目录是否可写
程序是否支持前台运行

如果要看主配置，可以直接查看：

sudo sed -n '1,260p' /etc/supervisor/supervisord.conf

常见问题

1. 进程启动后又立刻退出

通常是以下原因之一：

程序本身有错误
command 写错
程序要求的环境变量没配置
程序需要前台运行但你给了后台模式

先看状态：

sudo supervisorctl status

再看日志：

sudo tail -n 200 /var/log/myapp/stdout.log
sudo tail -n 200 /var/log/myapp/stderr.log

2. `FATAL Exited too quickly`

这表示 Supervisor 判断程序没有稳定运行成功。通常检查：

startsecs 是否过长或过短
程序启动参数是否正确
程序运行权限是否足够

3. `supervisorctl` 连接失败

先确认服务本身在运行：

sudo systemctl status supervisor

然后确认配置文件里 socket 是否正常。Debian 常见安装会使用本地 Unix socket，通常不需要直接暴露 TCP 端口。

4. 修改了配置但没有生效

执行：

sudo supervisorctl reread
sudo supervisorctl update

如果还是不行，重启 Supervisor 服务：

sudo systemctl restart supervisor

5. 程序卡住无法停止

如果进程不响应正常退出信号，可以检查：

stopsignal
stopasgroup
killasgroup
程序是否自己 fork 出子进程并持有它们

远程管理是否要开启

默认建议只使用本机控制，不要一开始就暴露远程控制接口。Supervisor 也支持 HTTP/XML-RPC 控制，但这会引入额外安全面。

如果你的场景不是明确需要远程管理，优先保留本地 socket 管理即可。

最小可用流程

如果你只想快速跑通一次，按这个顺序执行：

sudo apt update
sudo apt install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor
sudo nano /etc/supervisor/conf.d/myapp.conf
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

结论

在 Debian 上使用 Supervisor 的关键点只有几个：

安装 supervisor 包
让被托管程序以前台方式运行
用 /etc/supervisor/conf.d/ 管理单个程序配置
修改配置后执行 reread 和 update
日志、权限和退出信号要提前设计好