Supervisor 是基於 Python 的進程控制系統,專為類 Unix 系統設計,能將普通命令行程序轉化為守護進程,提供自動啟動、崩潰自動重啟、日誌輪轉、Web 管理界面、XML-RPC API 等企業級特性。本文從安裝、配置詳解、實戰驗證自動重啟、進階配置到生產環境最佳實踐,構建完整知識體系。
# 1. 安裝 (推薦虛擬環境)
pip install supervisor
# 2. 生成默認配置文件
echo_supervisord_conf > /etc/supervisord.conf
# 或指定路徑
supervisord -c /etc/supervisord.conf
# 3. 目錄結構約定
/etc/supervisord.conf # 主配置
/etc/supervisor/conf.d/ # 子配置目錄 (include)
/var/log/supervisor/ # 日誌目錄
/var/run/supervisor.sock # UNIX socket (ctl 通訊)
supervisord.conf[unix_http_server]
file=/var/run/supervisor.sock ; ctl 通訊 socket
chmod=0700
;username=user ; password=pass ; 可選認證
[supervisord]
logfile=/var/log/supervisor/supervisord.log
logfile_maxbytes=50MB
logfile_backups=10
loglevel=info
pidfile=/var/run/supervisord.pid
nodaemon=false ; 後台運行
minfds=1024
minprocs=200
user=root ; 權限降級建議專用用戶
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
[supervisorctl]
serverurl=unix:///var/run/supervisor.sock
[include]
files = /etc/supervisor/conf.d/*.conf ; 包含子配置
/etc/supervisor/conf.d/myapp.conf[program:myapp]
; === 核心命令 ===
command=/home/user/venv/bin/python /home/user/app/main.py ; 絕對路徑,使用虛擬環境 python
directory=/home/user/app ; 工作目錄
user=appuser ; 運行用戶 (非 root)
autostart=true ; supervisord 啟動時自動啟動
autorestart=true ; 關鍵:非預期退出自動重啟 (exitcodes 除外)
startsecs=3 ; 運行 3 秒視為啟動成功
startretries=3 ; 啟動失敗重試次數
exitcodes=0,2 ; 預期退出碼 (不觸發重啟),默認 0,2
stopsignal=QUIT ; 停止信號 (優雅關閉)
stopwaitsecs=10 ; 等待優雅退出超時
; === 環境與資源 ===
environment=PYTHONPATH="/home/user/app",ENV="production" ; 環境變量
numprocs=1 ; 進程數 (如需多進程用 gunicorn/uwsgi)
process_name=%(program_name)s_%(process_num)02d ; 多進程命名模板
; === 日誌管理 (關鍵) ===
stdout_logfile=/var/log/supervisor/myapp_stdout.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5
stdout_capture_maxbytes=1MB ; 捕獲最後 1MB 供 tail -f
stderr_logfile=/var/log/supervisor/myapp_stderr.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5
redirect_stderr=true ; 合併 stderr 到 stdout
; === 進階 ===
priority=999 ; 啟動優先級 (數值大先啟動)
serverurl=AUTO ; 給子進程訪問 supervisor XML-RPC
創建測試腳本 daemon.py:
#!/usr/bin/env python3
import time, os, sys
LOG_FILE = "/tmp/daemon.log"
def log(msg):
with open(LOG_FILE, "a") as f:
f.write(f"{time.time():.2f} {msg}\n")
f.flush()
log(f"START pid={os.getpid()}")
try:
while True:
time.sleep(1)
log("heartbeat")
except KeyboardInterrupt:
log("SIGINT received")
sys.exit(0) # 預期退出碼 0,不觸發 autorestart
except Exception as e:
log(f"CRASH: {e}")
sys.exit(1) # 非預期退出碼,觸發 autorestart
配置 [program:daemon] 指向該腳本,啟動 supervisord,然後測試:
# 1. 啟動
supervisord -c /etc/supervisord.conf
supervisorctl status
# daemon:daemon_00 RUNNING pid 12345, uptime 0:00:01
# 2. 模擬崩潰
kill -9 12345 # 強制殺死,非預期退出
# 3. 觀察日誌
tail -f /tmp/daemon.log
# 1700000000.00 START pid=12345
# 1700000001.00 heartbeat
# 1700000002.00 heartbeat
# 1700000003.00 START pid=12356 <-- 自動重啟新進程!
# 1700000004.00 heartbeat
# 4. supervisorctl 狀態
supervisorctl status
# daemon:daemon_00 RUNNING pid 12356, uptime 0:00:01
| 命令 | 作用 |
|---|---|
status | 查看所有程序狀態 |
start | 啟動程序 |
stop | 優雅停止 (發送 stopsignal) |
restart | 重啟 (stop + start) |
reload | 重新讀取配置並重啟變更程序 |
tail -f | 實時查看日誌 (無需登錄服務器) |
pid | 查看 PID |
signal | 發送信號 (如 USR1 觸發熱重載) |
maxbytes/backups) 但不支援按時間切割。stdout_logfile=/dev/stdout stderr_logfile=/dev/stderr,由容器/系統日誌驅動 (Docker logs, journald, Fluentd/Filebeat) 收集,統一存儲 ELK/Loki。# supervisord.conf
user=appuser
# 程序配置
user=appuser
創建專用用戶,授予必要目錄權限,chown -R appuser:appuser /var/log/supervisor /var/run/supervisor.sock。
SIGTERM/SIGQUIT (對應 stopsignal),完成「完成當前請求、刷新緩存、關閉連接池」再退出。stopwaitsecs 給足時間,超時後 Supervisor 發送 SIGKILL 強殺。Supervisor 管理單進程。Web 應用多進程應由 Gunicorn/uWSGI 內部管理 (prefork/worker),Supervisor 僅管理 Gunicorn master 進程。不要 用 numprocs>1 運行 Web 應用(端口衝突、共享狀態難題)。
supervisorctl status 解析 RUNNING 狀態;或 HTTP API https://localhost:9001/RPC2 (需配置 [inet_http_server])。supervisor_exporter 導出進程狀態、CPU/內存、重啟次數指標。[inet_http_server]
port=0.0.0.0:9001
username=admin
password=strong_random_password # 必須修改!
瀏覽器訪問 https://server:9001 可視化管理。生產環境務必開啟 HTTPS 反向代理 + IP 白名單。
| 現象 | 排查方向 |
|---|---|
| 啟動即 FATAL | supervisorctl tail 查看啟動報錯;檢查命令路徑、權限、虛擬環境、依賴安裝、工作目錄 |
| 頻繁重啟 (BACKOFF) | 程序啟動後立即退出 (startsecs 內)。檢查代碼邏輯、端口衝突、配置文件讀取失敗 |
| 日誌不輸出 | Python 緩衝問題:啟動命令加 -u 或代碼 sys.stdout.reconfigure(line_buffering=True) (Py3.7+) / flush() |
| 無法停止 | 程序忽略 stopsignal。檢查信號處理器、僵屍進程 |
| 配置修改不生效 | 需 supervisorctl reload 或 supervisorctl update |
Supervisor 以單一職責、配置驅動、零依賴 (純 Python) 成為進程管理「瑞士軍刀」。核心價值在於 autorestart=true 讓脆弱進程擁有「自我修復」能力,配合規範的日誌、優雅關閉、監控接口,構成生產環境進程守護的基石。記住:Supervisor 管進程,不管業務邏輯;業務高可用靠集群、負載均衡、熔斷降級,進程級高可用靠 Supervisor。