Supervisor
给后台进程装上“自动驾驶”
用 Python 编写的客户端 / 服务端进程管理工具:把散落在 nohup、& 和 shell 脚本里的后台程序收编成一份配置,由守护进程统一 拉起、监控、重启、收日志。
它是什么:从“手动守护”到“声明式托管”
Why SupervisorLinux 上启动一个长期运行的服务,最直觉的写法是 nohup python app.py &。但这种方式只解决“退出终端后不被挂断”,一旦进程崩溃、机器重启、日志写爆磁盘,它都无能为力。Supervisor 把“如何运行”写进配置,把“是否活着”交给守护进程。
nohup 不会自愈
进程崩溃后没人知道,第二天才发现服务已停摆数小时。
手动重启不可靠
靠 shell 脚本 while true 循环拉起,容易重复启动、无法优雅停止。
多程序难统一管理
Web、队列消费者、定时任务各管各的,状态和启停方式互不一致。
日志散落各处
stdout / stderr 混在终端或临时文件里,排查问题先要“找日志”。
核心定义
Supervisor 是一个 客户端 / 服务端架构的进程控制系统,让你在类 UNIX 系统(Linux、macOS、BSD)上监控并控制一批进程。它的设计目标与 daemontools、runit、launchd 类似,但全部用 Python 实现,且通过声明式配置文件而非 shell 脚本描述进程。
它不负责“编排多个容器”或“调度分布式任务”,只专注做一件事:让本机上被托管的程序始终保持期望的运行状态,并留下可追溯的日志。
它替你做了三件事
按配置拉起
开机 / 启动 supervisord 时,按 priority 顺序把标记 autostart=true 的程序全部启动。
崩溃自动恢复
监测子进程退出码与运行时长,符合 autorestart 策略时自动重启,并记录尝试次数。
统一操作与日志
用 supervisorctl 或 Web UI 查看状态、启停进程,stdout / stderr 自动落盘并可轮转。
架构组成:一个服务端,三种客户端
ArchitectureSupervisor 拆成两半:supervisord 是常驻的守护进程,负责真正干活;supervisorctl 与 Web UI 只是客户端,通过本地 socket 或 HTTP 把命令发给它。两者之间用 XML-RPC 协议通信,因此你也可以用 Python 脚本直接调用。
supervisord 是唯一的管理者;所有子进程都由它 fork 而来,因此它必须掌握每个进程的真实 PID。
| 组件 | 角色 | 关键能力 |
|---|---|---|
supervisord |
服务端守护进程 | 解析配置文件;启动子进程;崩溃后按策略重启;收集 stdout/stderr;生成进程生命周期事件;对外提供 XML-RPC 接口。 |
supervisorctl |
命令行客户端 | 交互式 shell 或一次性命令:status、start、stop、restart、tail、reread、update。 |
| Web UI | 浏览器客户端 | 由内置 HTTP 服务器提供(默认 9001 端口),可视化查看进程状态、日志与启停操作,可加 Basic Auth。 |
| XML-RPC API | 程序化接口 | 任何支持 XML-RPC 的语言都能调用,例如 getAllProcessInfo()、startProcess(),适合接入监控与自动化。 |
安装与首次启动
Install & Boot安装方式
# Debian / Ubuntu(包管理器自带 systemd 单元) sudo apt-get update && sudo apt-get install -y supervisor # CentOS / RHEL(需先启用 EPEL) sudo yum install -y epel-release && sudo yum install -y supervisor # 任意发行版 / 隔离环境:pip 方式,会同时生成 supervisord、supervisorctl python3 -m pip install supervisor
包管理器安装后,标准位置通常是:配置 /etc/supervisor/supervisord.conf(Debian 系)或 /etc/supervisord.conf,日志 /var/log/supervisor/,子配置目录 /etc/supervisor/conf.d/。
四个动作跑起来
supervisord.conf,用 [include] 拆分业务配置。supervisord -c <conf> 或交给 systemd 托管。supervisorctl 读取同一配置,连接 socket / HTTP。status 显示 RUNNING,日志文件开始写入。# 1. 生成一份带注释的完整示例配置(pip 安装时提供该命令) echo_supervisord_conf > /etc/supervisord.conf # 2. 前台启动,便于观察启动日志(-n = nodaemon) supervisord -n -c /etc/supervisord.conf # 3. 系统服务方式(包管理器安装时) sudo systemctl enable --now supervisor sudo systemctl status supervisor # 4. 客户端查看托管进程 supervisorctl -c /etc/supervisord.conf status
| 配置文件查找顺序 | 说明 |
|---|---|
$CWD/supervisord.conf | 先看当前工作目录,方便项目内自带配置 |
$CWD/etc/supervisord.conf | 项目内 etc 子目录 |
/etc/supervisord.conf | 源码 / pip 安装的常见位置 |
/etc/supervisor/supervisord.conf | Debian、Ubuntu 包管理器的默认位置 |
$HOME/.supervisord.conf | 用户级配置,常用于免 root 场景 |
supervisord 与 supervisorctl 必须使用同一份配置(或至少 [supervisorctl] 与 [unix_http_server] 指向同一个 socket),否则会报 unix:///var/run/supervisor.sock no such file。建议统一用 -c 指定,或在 ~/.supervisorctl.conf 里固化。配置文件详解:INI 驱动的进程声明
ConfigurationSupervisor 的配置是 INI 格式,由若干 section 组成。可以全部写在一个文件里,也可以拆成多个文件再由 [include] 汇总——生产上几乎都会拆分,一个业务一个 .conf。
; ---------- 1. 通信通道:本地 UNIX socket ---------- [unix_http_server] file=/var/run/supervisor.sock ; supervisorctl 连接的 socket chmod=0700 ; 权限收紧,只有属主可读写 ; ---------- 2. 守护进程自身 ---------- [supervisord] logfile=/var/log/supervisor/supervisord.log pidfile=/var/run/supervisord.pid childlogdir=/var/log/supervisor ; 子进程日志默认目录 user=root ; 需要以 root 运行才能为子进程降权 nodaemon=false ; 前台运行用于容器 / 调试 ; ---------- 3. RPC 接口(Web UI / 客户端依赖) ---------- [rpcinterface:supervisor] supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface ; ---------- 4. 客户端默认连接方式 ---------- [supervisorctl] serverurl=unix:///var/run/supervisor.sock ; ---------- 5. 拆分业务配置 ---------- [include] files = conf.d/*.conf ; ---------- 6. 一个被托管的程序 ---------- [program:web] ; web = 程序名,客户端用它操作 command=/opt/app/venv/bin/gunicorn -c gunicorn.conf.py app:application directory=/opt/app ; 工作目录,避免相对路径出错 user=www-data ; 以低权限用户运行 autostart=true ; supervisord 启动时自动拉起 autorestart=unexpected ; 非预期退出才重启(见 05 节) startsecs=5 ; 存活满 5 秒才算启动成功 startretries=3 ; 连续失败 3 次进入 FATAL stopsignal=TERM ; 停止时先发 SIGTERM stopwaitsecs=10 ; 10 秒未退出则 SIGKILL stopasgroup=true killasgroup=true ; 连同子进程 / 线程一起处理 environment=ENV="prod",PYTHONUNBUFFERED="1" stdout_logfile=/var/log/supervisor/web.out.log stdout_logfile_maxbytes=50MB stdout_logfile_backups=5 redirect_stderr=true ; stderr 合并进 stdout 日志
[program:x] 最常用的选项
| 选项 | 默认值 | 作用 |
|---|---|---|
command | 必填 | 启动命令。不经过 shell 解析,通配符 / 管道 / 变量展开都不会生效;需要时写成 bash -c "..."。 |
directory | — | 子进程的工作目录(chdir)。 |
user | — | 以哪个用户身份运行;supervisord 自身需为 root 才能切换。 |
autostart | true | supervisord 启动时是否自动启动该程序。 |
autorestart | unexpected | false 不重启 / true 总是重启 / unexpected 退出码不在 exitcodes 内才重启。 |
exitcodes | 0,2 | 视为“正常退出”的退出码集合,与 unexpected 配合使用。 |
startsecs | 1 | 进程需持续存活多少秒才算 RUNNING;在此之前退出视为启动失败。 |
startretries | 3 | 启动失败后的最大重试次数,耗尽后进入 FATAL。 |
stopsignal | TERM | 停止时发送的信号,可改为 INT、QUIT 等。 |
stopwaitsecs | 10 | 等待进程退出的秒数,超时后 SIGKILL。 |
stopasgroup / killasgroup | false | 把信号发给整个进程组,避免 gunicorn / shell 包装留下的孤儿进程。 |
numprocs + process_name | 1 | 启动多个同名实例,process_name=%(program_name)s_%(process_num)02d。 |
priority | 999 | 启动顺序(小到大),停止顺序相反。 |
environment | — | 追加环境变量,如 KEY="value",KEY2="v2"。 |
stdout_logfile | AUTO | 标准输出日志路径,AUTO 自动生成在 childlogdir。 |
stdout_logfile_maxbytes / _backups | 50MB / 10 | 日志轮转阈值与保留份数,设 0 表示不轮转。 |
redirect_stderr | false | 把 stderr 合并到 stdout 日志流。 |
umask | 022 | 子进程创建文件的权限掩码。 |
[program:x] 加 command 就能跑;[supervisord]、[rpcinterface]、[supervisorctl] 三件套负责让客户端连得上。其余选项都是工程可靠性上的加固。进程生命周期:状态机怎么走
Lifecycle理解状态机,就能看懂 status 的每一列,也能解释“为什么它没有自动重启”。Supervisor 为每个被托管的程序维护一个状态,所有操作与重启策略都围绕状态迁移展开。
实线为常规流转,虚线为 autorestart 触发的自动重启;FATAL 是“不再自动拉起”的终点,需要人工介入。STARTING → RUNNING 需持续存活 startsecs 秒。
| 状态 | 含义 | 下一步 |
|---|---|---|
| RUNNING | 进程已启动并存活超过 startsecs,正常服务中。 | 进程退出 → EXITED;收到 stop → STOPPING。 |
| STARTING | 刚 fork 出子进程,处于“观察期”,还没被认定为启动成功。 | 存活满 startsecs → RUNNING;提前退出 → BACKOFF。 |
| BACKOFF | 启动过程中退出,正在等待下一次重试(间隔递增)。 | 重试 → STARTING;次数用尽 → FATAL。 |
| STOPPING | 已发送 stopsignal,等待进程自行退出。 | 退出 → STOPPED;超时 → SIGKILL 后 STOPPED。 |
| EXITED | 从 RUNNING 状态退出的进程,退出码决定是否自动重启。 | autorestart 命中 → STARTING;否则停留。 |
| STOPPED | 从未启动,或被 stop 正常停止。 | 收到 start → STARTING。 |
| FATAL | 启动重试次数耗尽,Supervisor 放弃自动拉起。 | 只能人工 start 或修配置后 update。 |
| UNKNOWN | supervisord 重启后尚未重新获取进程信息。 | 短暂瞬态,随后自动收敛。 |
autorestart 的三种取值
false:永不自动重启,适合一次性任务。true:只要退出就重启,适合必须常驻的服务。unexpected(默认):退出码不在exitcodes(默认 0,2)里才重启,避免“正常结束的任务被无限拉起”。
startsecs 的真实含义
它不是“启动耗时”,而是判定成功的观察窗口。设为 5 秒时,进程必须在 fork 后存活 5 秒才算 RUNNING;如果第 3 秒就崩溃,会被记为一次启动失败并进入 BACKOFF,而不是直接重启。启动慢的应用应适当调大,而不是调小。
命令速查:supervisorctl 日常操作
Cheatsheetsupervisorctl 有两种用法:直接跟子命令执行一次,或不带参数进入交互式 shell(支持 Tab 补全、help、history)。操作对象可以是程序名、group:name 形式,或 all。
查看状态
status— 所有进程一览status web— 指定进程pid web— 查看主进程 PIDavail— 列出配置中但未加载的进程tail -f web stderr— 实时跟随日志
启停与信号
start web/stop webrestart web— 等价先 stop 再 startrestart allsignal HUP web— 给进程发信号clear web— 清空进程日志
配置变更
reread— 重读配置,仅报告差异update— 应用差异(启动新增、停止移除、重启受影响)reload— 重启 supervisord 自身shutdown— 关闭 supervisord 及其子进程
服务端
supervisord -c <conf>supervisord -n— 前台运行supervisord -h— 全部参数supervisorctl -c <conf>supervisorctl -s http://127.0.0.1:9001
读一次真实输出
$ supervisorctl status web RUNNING pid 2417, uptime 3 days, 4:12:07 worker RUNNING pid 2419, uptime 3 days, 4:12:05 beat RUNNING pid 2421, uptime 3 days, 4:12:02 job-import FATAL Exited too quickly (process log may have details) report STOPPED Not started
三列分别是 名称、状态、描述。描述里通常会带 PID 与 uptime;启动失败时则显示 Exited too quickly、Backoff 等线索——这往往比翻日志更快定位问题。
reread 只读不生效;update 才会把差异落地到运行中的进程;reload 会让 supervisord 自身重启,所有被托管进程都会跟着重启——线上慎用。日志、Web UI 与事件
ObservabilitySupervisor 把子进程的 stdout / stderr 当作数据流接管:它 fork 进程时重定向这两个文件描述符,再按行写入日志文件(默认按 50MB 轮转、保留 10 份)。因此程序本身不需要写任何日志框架代码,也能拿到完整输出——前提是打开 Python 的缓冲或无缓冲模式(PYTHONUNBUFFERED=1)。
打开 Web 控制台
[inet_http_server] port=127.0.0.1:9001 ; 建议只监听回环,外部通过 SSH 隧道访问 username=admin ; 可省略,但公网暴露时必须设置 password=change-me
重启 supervisord 后访问 http://127.0.0.1:9001,即可看到进程列表、状态、uptime、日志尾部,并直接执行 Start / Stop / Restart / Clear Log。它同时是 XML-RPC 端点,脚本和监控系统可以复用这套认证。
import xmlrpc.client server = xmlrpc.client.ServerProxy("http://127.0.0.1:9001/RPC2") for p in server.supervisor.getAllProcessInfo(): print(p["name"], p["statename"], p["pid"]) server.supervisor.restartProcess("web", True) # wait=True 等待完成
日志策略
| 场景 | 推荐做法 |
|---|---|
| 普通单机服务 | 每个 program 显式指定 stdout_logfile,配 maxbytes 与 backups 做轮转。 |
| 需要区分错误输出 | 不设 redirect_stderr,分别配置 stdout_logfile 与 stderr_logfile。 |
| 容器内运行 | stdout_logfile=/dev/stdout、stdout_logfile_maxbytes=0,把日志交给 Docker 收集。 |
| 交给外部 logrotate | logrotate 配置中使用 copytruncate,避免 Supervisor 持有旧文件句柄。 |
| 需要响应进程事件 | 配置 [eventlistener],订阅 PROCESS_STATE 等事件,实现告警或联动。 |
getAllProcessInfo() 或进程端口探活采集数据。横向对比:什么时候该用它
ComparisonSupervisor 不是“进程管理”的唯一答案。它在 需要 Python 环境、需要单机多进程统一托管、又不想碰 systemd 单元文件的场合最舒服;在容器化与系统级服务场景里,它往往不是首选。
| 维度 | Supervisor | systemd | PM2 | Docker restart |
|---|---|---|---|---|
| 定位 | 应用级进程管理 | 系统级 init / 服务管理 | Node.js 生态进程管理 | 容器生命周期策略 |
| 依赖 | Python 运行时 | 系统自带 | Node 运行时 | Docker / 容器运行时 |
| 配置方式 | INI 声明式 | Unit 文件 | JS / JSON | 启动参数或 compose |
| 自动重启 | 支持 | 支持 | 支持 | 仅容器退出 |
| 日志管理 | 内置落盘 + 轮转 | journald | 内置文件 / 聚合 | docker logs / 驱动 |
| 多实例 | numprocs | 模板单元 | cluster 模式 | 副本数 |
| 开机自启 | 需 systemd / init 拉起 | 原生 | 需 pm2 startup | 随宿主 / 编排 |
| 多机 / 集群 | 不支持 | 不支持 | 有限 | 交给 K8s 等编排 |
| 典型场景 | 单机 Python 多进程 | 系统服务、常驻守护 | Node 应用 | 容器化部署 |
一句话选型
生产实践:8 个最容易踩的坑
Pitfalls1. 环境变量不会自动继承
supervisord 只在自身启动的那一刻继承 shell 环境。之后你在终端里 source venv/bin/activate、改 export PATH,被托管的进程都看不到。
解决办法:command 写绝对路径,需要什么就在 environment 里显式声明。127 退出码、Exited too quickly 大多源于此。
2. command 不经过 shell 解析
command=cd /app && python app.py、> log.txt、$HOME 展开全部无效——Supervisor 直接 exec,不经过 bash。
用 directory= 指定工作目录;确实需要 shell 语义时写 bash -c "...",并评估 stopasgroup。
3. 别用 root 跑业务进程
supervisord 以 root 运行是为了降权,不是为了让业务跑在 root 下。给每个 program 配 user=www-data 这类低权限账号。
注意切换用户发生在 exec 之后,因此 stdout_logfile 所在目录需提前创建并授予该用户写权限,否则会静默启动失败。
4. 停止只发信号,不做优雅回收
Supervisor 只负责按 stopsignal 发一次信号,stopwaitsecs 超时后 SIGKILL,不会帮你调用应用的优雅退出钩子。
对 gunicorn / celery 这类会派生 worker 的程序,务必打开 stopasgroup=true、killasgroup=true,否则容易留下孤儿进程。
5. 改配置忘了 update
只编辑文件不会生效。标准动作是 supervisorctl reread 看差异,再 supervisorctl update 落地。
update 只会重启“配置发生变化”的程序;reload 会让 supervisord 自身重启,所有进程一起中断。
6. 容器里当 PID 1 需要额外条件
容器中必须 nodaemon=true / -n 前台运行,否则容器会立刻退出;同时 Supervisor 作为 PID 1 不擅长回收僵尸进程。
更稳的做法是用 tini / dumb-init 作为入口,或在编排层拆成多个容器——一个进程一个容器更符合云原生习惯。
7. 日志把磁盘写满
默认只在配置了 maxbytes 时才轮转,而且 Supervisor 自己轮转时不支持外部“移走文件”式 logrotate(句柄仍在旧文件)。
两条路:用内置 maxbytes + backups;或外部 logrotate 配 copytruncate 截断而非 mv。
8. 把 socket 暴露给所有人
[unix_http_server] 等于“本机 root 级操作入口”:能启停任意被托管进程。默认 chmod=0700 不要放宽。
Web UI 用 127.0.0.1 监听 + SSH 隧道;确需公网时加反向代理、HTTPS 与强口令。
故障速查表
| 现象 | 常见原因 | 处理 |
|---|---|---|
no such file(socket) | supervisord 未运行,或客户端连错 socket 路径 | 确认进程在跑;-c 指向同一份配置;检查 [supervisorctl] serverurl |
Exited too quickly / FATAL | 命令路径错误、依赖缺失、启动即崩 | 看该 program 的 stderr 日志;startsecs 是否过短 |
| 退出码 127 | 找不到可执行文件(PATH / venv) | command 改为绝对路径,或在 environment 补 PATH |
| 退出码 126 | 文件存在但无执行权限 | chmod +x,或改用解释器显式执行 |
| status 显示 BACKOFF 循环 | 启动阶段反复失败,重试中 | 先看日志定位崩溃原因;修好后 start 复位 |
| stop 后残留子进程 | 只杀了主进程,进程组未处理 | 开启 stopasgroup / killasgroup |
| 日志不更新 | Python 输出被缓冲 | 设 PYTHONUNBUFFERED=1 或 python -u |
| 配置改了没反应 | 未执行 reread / update | supervisorctl reread && supervisorctl update |
一页速记
Summary; 最小可用:一个常驻 Web 进程 + 一个队列消费者 [program:web] command=/opt/app/venv/bin/gunicorn app:application -b 127.0.0.1:8000 directory=/opt/app user=www-data autorestart=true startsecs=5 redirect_stderr=true stdout_logfile=/var/log/supervisor/web.log stdout_logfile_maxbytes=50MB stdout_logfile_backups=5 [program:worker] command=/opt/app/venv/bin/celery -A app worker -l info directory=/opt/app user=www-data autorestart=true stopasgroup=true killasgroup=true environment=PYTHONUNBUFFERED="1" redirect_stderr=true stdout_logfile=/var/log/supervisor/worker.log
上线检查清单
command全部使用绝对路径- 每个 program 明确
user,不用 root - 常驻服务
autorestart=true,一次性任务用false startsecs覆盖真实启动耗时- 有子进程的程序开启
stopasgroup/killasgroup - 日志路径存在、可写,并设置轮转
- Web UI 只监听回环并加口令
- 变更走
reread+update,而非reload
记住这三句话
① Supervisor 只能管自己 fork 出来的子进程,不能“接管”已有进程。
② 状态机的关键是 startsecs(判定成功)与 autorestart(判定是否拉起)。
③ 它是应用级工具,不是 init、不是容器编排,也不是监控系统。
参考资料
- Supervisor 官方文档 · supervisord.org
- 项目源码与发行说明 · github.com/Supervisor/supervisor
- 配置项完整列表 · supervisord.org/configuration.html