在开发后端服务、定时任务或长期运行的脚本时，你是否遇到过这些问题：

  • 程序意外崩溃后无法自动重启，导致服务中断；

  • 多个进程需要同时管理，手动启动/停止效率低下；

  • 想查看进程日志却找不到输出位置，排查问题困难。

如果你有这些困扰，**Supervisor** 正是你需要的工具。它是一个用 Python 开发的进程控制系统，能帮助你监控、启动、停止和重启进程，确保服务稳定运行。

本文将从安装到实战，带你掌握 Supervisor 的核心用法，包括配置文件编写、进程管理命令、日志查看等，让你的服务管理变得简单高效。

一、什么是 Supervisor？

Supervisor 是一个跨平台的进程管理工具，核心功能是：

  • 进程监控：实时监控进程状态，一旦崩溃立即自动重启；

  • 集中管理：通过配置文件定义多个进程，统一启动、停止、重启；

  • 日志管理：自动记录进程输出日志，支持按大小/时间切割；

  • 命令行与 Web 界面：既可以通过命令行操作，也能通过网页可视化管理。

它特别适合管理 Python 编写的后端服务（如 Flask/Django 应用）、爬虫脚本、定时任务等长期运行的进程。

二、安装 Supervisor

Supervisor 是 Python 第三方库，支持 Python 2.7 和 3.x，安装非常简单：

1. 用 pip 安装



# Python 3 推荐使用 pip3
pip3 install supervisor

# 验证安装（查看版本）
supervisord --version
# 输出示例：4.2.5






2. 初始化配置文件


Supervisor 依赖配置文件（supervisord.conf）定义进程和运行规则。首次使用需生成默认配置：


# 生成默认配置（会显示配置文件路径）
echo_supervisord_conf > /etc/supervisord.conf




    
 
  • 
  
    Linux/macOS：建议放在 /etc/supervisord.conf 或 /usr/local/etc/supervisord.conf；
    • 
 
  • 
  
    Windows：建议放在 C:\supervisord\supervisord.conf（需手动创建目录）。
    • 







三、核心配置文件详解




Supervisor 的所有功能都通过配置文件控制，我们只需修改默认配置中的关键部分即可。




1. 核心配置结构


配置文件分为多个块（section），核心块包括：


    
 
  • 
  
    [unix_http_server]：本地 UNIX 套接字配置（用于命令行通信）；
    • 
 
  • 
  
    [inet_http_server]：网络 HTTP 服务配置（用于 Web 界面）；
    • 
 
  • 
  
    [supervisord]：主进程自身的配置；
    • 
 
  • 
  
    [supervisorctl]：命令行客户端配置；
    • 
 
  • 
  
    [program:x]：定义需要管理的进程（x 是进程名称）；
    • 
 
  • 
  
    [include]：引入外部配置文件（推荐用这种方式管理多个进程）。
    • 







2. 基础配置示例


以下是一个简化的常用配置（以 Linux 为例）：


; /etc/supervisord.conf

[unix_http_server]
file=/tmp/supervisor.sock   ; UNIX 套接字路径（supervisorctl 会用到）
chmod=0700                  ; 套接字权限

; 启用 Web 管理界面（可选，方便可视化操作）
[inet_http_server]
port=0.0.0.0:9001           ; 监听所有IP的9001端口
username=admin              ; 登录用户名
password=123456             ; 登录密码

[supervisord]
logfile=/var/log/supervisord/supervisord.log  ; 主进程日志
logfile_maxbytes=50MB                         ; 日志文件最大50MB
logfile_backups=10                            ; 日志备份数
loglevel=info                                 ; 日志级别（info/warn/error）
pidfile=/var/run/supervisord.pid              ; 主进程PID文件
nodaemon=false                                ; 是否后台运行（false为前台，调试用）
minfds=1024                                   ; 最小文件描述符
minprocs=200                                  ; 最小进程数

[supervisorctl]
serverurl=unix:///tmp/supervisor.sock  ; 与主进程通信的套接字路径（需与[unix_http_server]一致）

; 引入外部进程配置（推荐将每个进程的配置单独放在一个文件中）
[include]
files = /etc/supervisor/conf.d/*.conf  ; 加载所有 .conf 结尾的文件




注意：


    
 
  • 
  
    需手动创建日志目录（如 /var/log/supervisord），否则启动会报错；
    • 
 
  • 
  
    [inet_http_server] 是可选配置，若不需要 Web 界面可注释掉。
    • 







3. 进程配置文件（关键！）


为了管理方便，建议将每个进程的配置单独放在 [include] 指定的目录中（如 /etc/supervisor/conf.d/）。




例如，创建一个管理 Flask 应用的配置文件 flask_app.conf：


; /etc/supervisor/conf.d/flask_app.conf

[program:flask_app]
; 进程启动命令（需绝对路径，或确保环境变量中有该命令）
command=/home/ubuntu/venv/bin/gunicorn -w 4 -b 0.0.0.0:5000 app:app
; 进程工作目录
directory=/home/ubuntu/my_flask_app
; 启动用户（建议用非root用户）
user=ubuntu
; 自动启动：当 supervisord 启动时自动启动该进程
autostart=true
; 自动重启：进程意外退出时自动重启
autorestart=true
; 重启延迟（秒）
startretries=3
; 启动超时（秒）
startsecs=5
; 日志输出（stdout 和 stderr 分别记录）
stdout_logfile=/var/log/supervisor/flask_app_stdout.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5
stderr_logfile=/var/log/supervisor/flask_app_stderr.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5
; 环境变量（可选，如数据库连接信息）
environment=
    FLASK_ENV="production",
    DATABASE_URL="mysql://user:pass@localhost/db"




配置参数说明：


    
 
  • 
  
    [program:flask_app]：flask_app 是进程的唯一名称（后续命令会用到）；
    • 
 
  • 
  
    command：必须是能在终端直接运行的命令（推荐用绝对路径，避免环境变量问题）；
    • 
 
  • 
  
    autostart 和 autorestart：这两个参数是 Supervisor 的核心，确保进程崩溃后自动恢复；
    • 
 
  • 
  
    stdout_logfile/stderr_logfile：分别记录标准输出和错误输出，方便排查问题。
    • 







四、Supervisor 基本操作




Supervisor 的使用主要依赖两个命令：


    
 
  • 
  
    supervisord：启动 Supervisor 主进程；
    • 
 
  • 
  
    supervisorctl：命令行客户端，用于管理进程。
    • 







1. 启动 Supervisor 主进程




# 启动主进程（默认读取 /etc/supervisord.conf）
supervisord -c /etc/supervisord.conf

# 检查是否启动成功（查看进程）
ps -ef | grep supervisord






如果启动失败，通常是配置文件错误或目录权限问题，可查看主进程日志（/var/log/supervisord/supervisord.log）排查。






2. 用 supervisorctl 管理进程




# 进入交互式管理界面（类似命令行终端）
supervisorctl -c /etc/supervisord.conf

# 在交互式界面中，可执行以下命令（以 flask_app 为例）：
status          # 查看所有进程状态
status flask_app  # 查看单个进程状态
start flask_app   # 启动进程
stop flask_app    # 停止进程
restart flask_app # 重启进程
reload           # 重新加载配置文件（新增进程需执行）
update           # 更新配置并重启受影响的进程
exit             # 退出交互式界面

# 也可以直接在终端执行命令（无需进入交互式界面）
supervisorctl -c /etc/supervisord.conf restart flask_app








3. Web 界面管理（可选）


如果在配置中启用了 [inet_http_server]，可通过浏览器访问 http://服务器IP:9001，输入配置的用户名和密码登录。




Web 界面支持可视化查看进程状态、启动/停止/重启进程、查看日志等，非常适合不熟悉命令行的开发者。






五、实战：用 Supervisor 管理多个进程




假设我们需要同时管理两个进程：


    
 
  1. 
  
    一个 Flask 后端服务（flask_app）；
    2. 
 
  2. 
  
    一个定时数据同步脚本（data_sync）。
    3. 





1. 编写进程配置文件




Flask 服务配置（/etc/supervisor/conf.d/flask_app.conf）：




[program:flask_app]
command=/home/ubuntu/venv/bin/gunicorn -w 4 -b 0.0.0.0:5000 app:app
directory=/home/ubuntu/my_flask_app
user=ubuntu
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/flask_app_stdout.log
stderr_logfile=/var/log/supervisor/flask_app_stderr.log






数据同步脚本配置（/etc/supervisor/conf.d/data_sync.conf）：


[program:data_sync]
; 脚本用 Python 运行，每小时执行一次（通过 sleep 循环实现）
command=/bin/bash -c 'while true; do python3 /home/ubuntu/scripts/sync.py; sleep 3600; done'
directory=/home/ubuntu/scripts
user=ubuntu
autostart=true
autorestart=true
; 允许脚本退出码为0（正常结束）时不重启
exitcodes=0
stdout_logfile=/var/log/supervisor/data_sync_stdout.log
stderr_logfile=/var/log/supervisor/data_sync_stderr.log






2. 启动并管理进程


# 启动 Supervisor 主进程
supervisord -c /etc/supervisord.conf

# 加载新配置（首次添加进程时需要）
supervisorctl -c /etc/supervisord.conf reload

# 查看所有进程状态
supervisorctl -c /etc/supervisord.conf status
# 输出示例：
# flask_app    RUNNING   pid 12345, uptime 0:01:23
# data_sync    RUNNING   pid 12346, uptime 0:01:23

# 单独重启数据同步脚本
supervisorctl -c /etc/supervisord.conf restart data_sync






3. 查看日志


当进程出现问题时，日志是排查的关键：


# 查看 Flask 服务的标准输出日志
tail -f /var/log/supervisor/flask_app_stdout.log

# 查看数据同步脚本的错误日志
tail -f /var/log/supervisor/data_sync_stderr.log






六、常见问题与解决方案




1. 进程启动失败，状态显示 FATAL


可能原因：


    
 
  • 
  
    command 路径错误（建议用绝对路径）；
    • 
 
  • 
  
    工作目录（directory）不存在或权限不足；
    • 
 
  • 
  
    进程依赖的环境变量未配置（需在 environment 中指定）。
    • 





解决方法：


查看进程的错误日志（stderr_logfile），通常能找到具体原因。






2. 新增进程后，status 中看不到


原因：新增进程的配置未被 Supervisor 加载。


解决方法：执行 supervisorctl reload 重新加载配置。






3. 进程被自动重启，但希望正常退出后不重启


解决方法：在进程配置中添加 autorestart=false，或指定允许的退出码：


autorestart=unexpected  # 只有非预期退出才重启（默认）
exitcodes=0,1           # 退出码为0或1时视为正常退出，不重启






4. 日志文件过大，占用磁盘空间


解决方法：配置日志切割参数：


stdout_logfile_maxbytes=10MB  # 单个日志文件最大10MB
stdout_logfile_backups=5      # 最多保留5个备份
stdout_logfile=/var/log/supervisor/app.log  # 日志路径






七、Supervisor 适用场景与优势




适用场景：


    
 
  • 
  
    后端服务（Flask/Django/Node.js 等）的进程管理；
    • 
 
  • 
  
    定时任务脚本（如数据同步、报表生成）；
    • 
 
  • 
  
    长期运行的爬虫程序；
    • 
 
  • 
  
    需要高可用性的服务（崩溃后自动恢复）。
    • 





核心优势：


    
 
  • 
  
    简单易用：配置文件直观，命令行操作简洁；
    • 
 
  • 
  
    稳定性高：确保进程持续运行，减少人工干预；
    • 
 
  • 
  
    集中管理：多进程统一管理，避免逐个启动的麻烦；
    • 
 
  • 
  
    日志集成：自动记录输出，方便问题排查；
    • 
 
  • 
  
    跨平台：支持 Linux、macOS（Windows 需特殊配置）。
    • 







八、总结




Supervisor 是 Python 开发者管理长期运行进程的理想工具，它通过简单的配置就能实现进程的自动启动、崩溃重启和日志管理，大幅降低服务维护成本。




本文介绍了 Supervisor 的安装、配置文件编写、基本操作和实战案例，核心要点包括：


    
 
  • 
  
    用 [program:x] 块定义进程，重点配置 command、autostart、autorestart 和日志路径；
    • 
 
  • 
  
    通过 supervisord 启动主进程，supervisorctl 管理具体进程；
    • 
 
  • 
  
    利用 Web 界面可可视化操作，适合快速排查问题。
    • 





如果你正在为进程管理烦恼，不妨试试 Supervisor——它会让你的服务稳定性提升一个台阶。
 
  

        # python
      
        # 开发语言
      
  
 
 Logo 
AI Agent技术社区
 
Agent 垂直技术社区，欢迎活跃、内容共建。
 
 
  
更多推荐
  
cover
 
《Claude Code工程化实践》第 29 讲 Harness 架构、模式与工程实践
 
 
avatar AI Agent技术社区
 
cover
 
Python agent-cloud 包：功能详解、安装配置与实战案例
 
 
avatar AI Agent技术社区
 
cover
 
Python agent-control-layer 包：功能、安装与实战案例详解
 
 
avatar AI Agent技术社区