Supervisor进程管理

概述

Supervisor 是一个 Python 编写的进程管理工具，用于在 Linux 服务器上管理 FastAPI 应用进程。它提供自动重启、日志管理、进程监控等功能，是生产环境部署的推荐方案之一。

适用场景

• Linux 服务器直接部署（非 Docker）
• 需要进程自动重启和日志轮转
• 管理多个相关进程

配置文件示例

项目提供了 Supervisor 配置模板 deploy/supervisor.conf，完整内容：

; Supervisor 进程管理示例配置
; 将 command / directory 替换为实际路径后复制到 /etc/supervisor/conf.d/

[program:djangoadmin-fastapi]
; 启动命令：使用项目虚拟环境中的 uvicorn
command=/path/to/venv/bin/uvicorn src.main:app --host 127.0.0.1 --port 8031
; 项目根目录
directory=/data/apps/djangoadmin
; 自动启动
autostart=true
; 异常退出后自动重启
autorestart=true
; 停止时终止子进程
stopasgroup=true
killasgroup=true
; 错误输出重定向到标准输出
redirect_stderr=true
; 日志文件
stdout_logfile=/path/to/logs/supervisor.out.log
; 日志轮转：单文件最大 50MB，保留 10 个备份
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10
; 环境变量
environment=PYTHONUNBUFFERED=1

配置路径

将修改后的配置文件复制到 /etc/supervisor/conf.d/ 目录下，需修改两处路径：

# 1. 修改 command 中的虚拟环境路径
# 2. 修改 directory 为项目实际路径
# 3. 修改 stdout_logfile 为日志实际路径
cp deploy/supervisor.conf /etc/supervisor/conf.d/djangoadmin-fastapi.conf

安装 Supervisor

# Ubuntu/Debian
sudo apt-get install supervisor

# CentOS/RHEL
sudo yum install supervisor

# pip 安装
pip install supervisor

常用命令

进程管理

# 读取配置并启动进程
sudo supervisorctl reread
sudo supervisorctl update

# 启动进程
sudo supervisorctl start djangoadmin-fastapi

# 停止进程
sudo supervisorctl stop djangoadmin-fastapi

# 重启进程
sudo supervisorctl restart djangoadmin-fastapi

# 查看进程状态
sudo supervisorctl status

# 停止所有进程
sudo supervisorctl stop all

# 重启所有进程
sudo supervisorctl restart all

服务管理

# 启动 Supervisor 服务
sudo systemctl start supervisord

# 停止 Supervisor 服务
sudo systemctl stop supervisord

# 设置开机自启
sudo systemctl enable supervisord

# 查看服务状态
sudo systemctl status supervisord

日志轮转

Supervisor 内置日志轮转功能，通过以下配置控制：

; 单个日志文件最大 50MB
stdout_logfile_maxbytes=50MB
; 保留 10 个历史日志文件
stdout_logfile_backups=10

日志文件命名

当 stdout_logfile_maxbytes 达到上限时，Supervisor 自动轮转：

• supervisor.out.log（当前日志）
• supervisor.out.log.1（上一个）
• supervisor.out.log.2（更早的）
• ...最多保留 stdout_logfile_backups 个

Web 管理界面

Supervisor 提供可选的 Web 管理界面：

[inet_http_server]
port=127.0.0.1:9001
username=admin
password=your_password

安全提醒

Web 界面仅监听 127.0.0.1，禁止暴露到公网。如需远程访问，应通过 SSH 隧道或 VPN。

多进程管理

如需同时管理多个进程（如应用 + Celery Worker）：

[program:djangoadmin-fastapi]
command=/path/to/venv/bin/uvicorn src.main:app --host 127.0.0.1 --port 8031
directory=/data/apps/djangoadmin
autostart=true
autorestart=true

[program:djangoadmin-worker]
command=/path/to/venv/bin/celery -A tasks worker
directory=/data/apps/djangoadmin
autostart=true
autorestart=true
numprocs=4

常见问题

进程启动失败

# 查看详细错误日志
sudo supervisorctl tail -f djangoadmin-fastapi

# 检查配置语法
sudo supervisorctl status

常见原因

1. Python 虚拟环境路径错误
2. 项目目录路径错误
3. 端口被占用
4. .env 文件缺失或配置错误

进程频繁重启

# 查看退出原因
sudo supervisorctl tail djangoadmin-fastapi stderr

# 调整启动等待时间（给应用足够的启动时间）
startsecs=10

总结

Supervisor 是 Linux 环境下管理 FastAPI 进程的可靠方案，提供自动重启、日志轮转、进程监控等能力。配置文件位于 deploy/supervisor.conf，修改路径后复制到 /etc/supervisor/conf.d/ 即可使用。生产环境建议配合 systemd 管理 Supervisor 自身的启动。