DevOps Tool · Process Manager

Supervisor
给后台进程装上“自动驾驶”

用 Python 编写的客户端 / 服务端进程管理工具:把散落在 nohup、& 和 shell 脚本里的后台程序收编成一份配置,由守护进程统一 拉起、监控、重启、收日志。

supervisord 守护进程 supervisorctl 命令行 配置驱动 · INI XML-RPC / Web UI Python 3 · 4.x
01

它是什么:从“手动守护”到“声明式托管”

Why Supervisor

Linux 上启动一个长期运行的服务,最直觉的写法是 nohup python app.py &。但这种方式只解决“退出终端后不被挂断”,一旦进程崩溃、机器重启、日志写爆磁盘,它都无能为力。Supervisor 把“如何运行”写进配置,把“是否活着”交给守护进程。

✕

nohup 不会自愈

进程崩溃后没人知道,第二天才发现服务已停摆数小时。

↻

手动重启不可靠

靠 shell 脚本 while true 循环拉起,容易重复启动、无法优雅停止。

⌘

多程序难统一管理

Web、队列消费者、定时任务各管各的,状态和启停方式互不一致。

▤

日志散落各处

stdout / stderr 混在终端或临时文件里,排查问题先要“找日志”。

核心定义

Supervisor 是一个 客户端 / 服务端架构的进程控制系统,让你在类 UNIX 系统(Linux、macOS、BSD)上监控并控制一批进程。它的设计目标与 daemontools、runit、launchd 类似,但全部用 Python 实现,且通过声明式配置文件而非 shell 脚本描述进程。

它不负责“编排多个容器”或“调度分布式任务”,只专注做一件事:让本机上被托管的程序始终保持期望的运行状态,并留下可追溯的日志。

它替你做了三件事

1

按配置拉起

开机 / 启动 supervisord 时,按 priority 顺序把标记 autostart=true 的程序全部启动。

2

崩溃自动恢复

监测子进程退出码与运行时长,符合 autorestart 策略时自动重启,并记录尝试次数。

3

统一操作与日志

用 supervisorctl 或 Web UI 查看状态、启停进程,stdout / stderr 自动落盘并可轮转。

它不是 systemd 的替代品。Supervisor 是“应用级”进程管理器:需要 Python 运行时、只管理自己的子进程、不能管理 PID 1 级别的系统服务。现代发行版上它更多承担“单机多进程应用”的编排角色,或作为容器内的 PID 1 使用(见 08 横向对比)。
02

架构组成:一个服务端,三种客户端

Architecture

Supervisor 拆成两半:supervisord 是常驻的守护进程,负责真正干活;supervisorctl 与 Web UI 只是客户端,通过本地 socket 或 HTTP 把命令发给它。两者之间用 XML-RPC 协议通信,因此你也可以用 Python 脚本直接调用。

supervisorctlshell-like CLI
Web UIhttp://host:9001
自定义脚本XML-RPC client
unix socket / inet HTTP + XML-RPC
supervisord守护进程 · 配置解析 · 进程状态机 · 事件监听 · 日志管道
fork / exec · 收集 stdout & stderr
program:webgunicorn
program:workercelery
program:beatschedule
program:jobexited / backoff

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(),适合接入监控与自动化。
关键理解:supervisord 只能管理“自己启动的进程”。它不会去接管一个已经在运行的 PID,也无法监控非子进程。所以接入 Supervisor 的正确姿势是:把原来的启动命令交给它执行,而不是让它“看着”一个已有进程。
03

安装与首次启动

Install & Boot

安装方式

bashinstall
# 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/。

四个动作跑起来

1准备配置生成或编辑 supervisord.conf,用 [include] 拆分业务配置。
2启动服务端supervisord -c <conf> 或交给 systemd 托管。
3接入客户端supervisorctl 读取同一配置,连接 socket / HTTP。
4验证状态status 显示 RUNNING,日志文件开始写入。
bashfirst run
# 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.confDebian、Ubuntu 包管理器的默认位置
$HOME/.supervisord.conf用户级配置,常用于免 root 场景
路径不一致是最常见的“连不上”原因。supervisord 与 supervisorctl 必须使用同一份配置(或至少 [supervisorctl] 与 [unix_http_server] 指向同一个 socket),否则会报 unix:///var/run/supervisor.sock no such file。建议统一用 -c 指定,或在 ~/.supervisorctl.conf 里固化。
04

配置文件详解:INI 驱动的进程声明

Configuration

Supervisor 的配置是 INI 格式,由若干 section 组成。可以全部写在一个文件里,也可以拆成多个文件再由 [include] 汇总——生产上几乎都会拆分,一个业务一个 .conf。

/etc/supervisord.confannotated
; ---------- 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 才能切换。
autostarttruesupervisord 启动时是否自动启动该程序。
autorestartunexpectedfalse 不重启 / true 总是重启 / unexpected 退出码不在 exitcodes 内才重启。
exitcodes0,2视为“正常退出”的退出码集合,与 unexpected 配合使用。
startsecs1进程需持续存活多少秒才算 RUNNING;在此之前退出视为启动失败。
startretries3启动失败后的最大重试次数,耗尽后进入 FATAL。
stopsignalTERM停止时发送的信号,可改为 INT、QUIT 等。
stopwaitsecs10等待进程退出的秒数,超时后 SIGKILL。
stopasgroup / killasgroupfalse把信号发给整个进程组,避免 gunicorn / shell 包装留下的孤儿进程。
numprocs + process_name1启动多个同名实例,process_name=%(program_name)s_%(process_num)02d。
priority999启动顺序(小到大),停止顺序相反。
environment—追加环境变量,如 KEY="value",KEY2="v2"。
stdout_logfileAUTO标准输出日志路径,AUTO 自动生成在 childlogdir。
stdout_logfile_maxbytes / _backups50MB / 10日志轮转阈值与保留份数,设 0 表示不轮转。
redirect_stderrfalse把 stderr 合并到 stdout 日志流。
umask022子进程创建文件的权限掩码。
最小可用配置其实只有 6 行。一个 [program:x] 加 command 就能跑;[supervisord]、[rpcinterface]、[supervisorctl] 三件套负责让客户端连得上。其余选项都是工程可靠性上的加固。
05

进程生命周期:状态机怎么走

Lifecycle

理解状态机,就能看懂 status 的每一列,也能解释“为什么它没有自动重启”。Supervisor 为每个被托管的程序维护一个状态,所有操作与重启策略都围绕状态迁移展开。

STOPPED STARTING RUNNING STOPPING BACKOFF FATAL EXITED start stop 提前退出 重试 重试耗尽 进程退出 autorestart 命中 → 重新 STARTING 已停止 / 等待超时后 SIGKILL

实线为常规流转,虚线为 autorestart 触发的自动重启;FATAL 是“不再自动拉起”的终点,需要人工介入。STARTING → RUNNING 需持续存活 startsecs 秒。

STARTING RUNNING BACKOFF STOPPING EXITED STOPPED FATAL UNKNOWN
状态含义下一步
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。
UNKNOWNsupervisord 重启后尚未重新获取进程信息。短暂瞬态,随后自动收敛。

autorestart 的三种取值

  • false:永不自动重启,适合一次性任务。
  • true:只要退出就重启,适合必须常驻的服务。
  • unexpected(默认):退出码不在 exitcodes(默认 0,2)里才重启,避免“正常结束的任务被无限拉起”。

startsecs 的真实含义

它不是“启动耗时”,而是判定成功的观察窗口。设为 5 秒时,进程必须在 fork 后存活 5 秒才算 RUNNING;如果第 3 秒就崩溃,会被记为一次启动失败并进入 BACKOFF,而不是直接重启。启动慢的应用应适当调大,而不是调小。

06

命令速查:supervisorctl 日常操作

Cheatsheet

supervisorctl 有两种用法:直接跟子命令执行一次,或不带参数进入交互式 shell(支持 Tab 补全、help、history)。操作对象可以是程序名、group:name 形式,或 all。

查看状态

  • status — 所有进程一览
  • status web — 指定进程
  • pid web — 查看主进程 PID
  • avail — 列出配置中但未加载的进程
  • tail -f web stderr — 实时跟随日志

启停与信号

  • start web / stop web
  • restart web — 等价先 stop 再 start
  • restart all
  • signal 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

读一次真实输出

terminalstatus
$ 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。reread 只读不生效;update 才会把差异落地到运行中的进程;reload 会让 supervisord 自身重启,所有被托管进程都会跟着重启——线上慎用。
07

日志、Web UI 与事件

Observability

Supervisor 把子进程的 stdout / stderr 当作数据流接管:它 fork 进程时重定向这两个文件描述符,再按行写入日志文件(默认按 50MB 轮转、保留 10 份)。因此程序本身不需要写任何日志框架代码,也能拿到完整输出——前提是打开 Python 的缓冲或无缓冲模式(PYTHONUNBUFFERED=1)。

打开 Web 控制台

/etc/supervisord.confweb ui
[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 端点,脚本和监控系统可以复用这套认证。

pythonxml-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 收集。
交给外部 logrotatelogrotate 配置中使用 copytruncate,避免 Supervisor 持有旧文件句柄。
需要响应进程事件配置 [eventlistener],订阅 PROCESS_STATE 等事件,实现告警或联动。
Web UI 不是监控系统。它没有历史指标、没有告警、没有鉴权体系之外的权限控制。生产上应把它当作“运维操作面板”,真正的存活监控交给 Prometheus / Zabbix / 云监控,通过 getAllProcessInfo() 或进程端口探活采集数据。
08

横向对比:什么时候该用它

Comparison

Supervisor 不是“进程管理”的唯一答案。它在 需要 Python 环境、需要单机多进程统一托管、又不想碰 systemd 单元文件的场合最舒服;在容器化与系统级服务场景里,它往往不是首选。

维度SupervisorsystemdPM2Docker restart
定位应用级进程管理系统级 init / 服务管理Node.js 生态进程管理容器生命周期策略
依赖Python 运行时系统自带Node 运行时Docker / 容器运行时
配置方式INI 声明式Unit 文件JS / JSON启动参数或 compose
自动重启支持支持支持仅容器退出
日志管理内置落盘 + 轮转journald内置文件 / 聚合docker logs / 驱动
多实例numprocs模板单元cluster 模式副本数
开机自启需 systemd / init 拉起原生需 pm2 startup随宿主 / 编排
多机 / 集群不支持不支持有限交给 K8s 等编排
典型场景单机 Python 多进程系统服务、常驻守护Node 应用容器化部署

一句话选型

单机跑多个 Python / 任意语言进程
Supervisor:一份配置统管 web、worker、定时任务,超级省事。
管理系统服务、需要开机自启
systemd:原生、无需额外运行时,集成 journald 与资源限制。
Node.js 应用、需要零停机 reload
PM2:cluster 模式、内置监控与日志聚合更贴合 Node。
容器里需要多进程
Supervisor 作为 PID 1 可行,但要额外处理信号转发与僵尸回收(见 09 节)。
多机、弹性伸缩、滚动发布
Kubernetes:Supervisor 管不到跨节点调度,这不是它的职责。
常见组合:systemd 负责“把 supervisord 拉起来并保活”,Supervisor 负责“把业务进程组拉起来并保活”。两层各司其职,配置文件仍然只有业务那一层需要频繁改动。
09

生产实践:8 个最容易踩的坑

Pitfalls

1. 环境变量不会自动继承

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 / updatesupervisorctl reread && supervisorctl update
10

一页速记

Summary
1服务端 supervisord
INI声明式配置
8进程状态
3客户端:CLI / Web / RPC
conf.d/app.confminimal
; 最小可用:一个常驻 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、不是容器编排,也不是监控系统。

参考资料

  1. Supervisor 官方文档 · supervisord.org
  2. 项目源码与发行说明 · github.com/Supervisor/supervisor
  3. 配置项完整列表 · supervisord.org/configuration.html