Python Tricks —— 使用 Supervisor 控

Supervisor 是一个 C/S 架构的进程控制系统，完全由 Python 语言编写。它允许用户监视和控制类 Unix 系统上的一个或多个进程。

在 Linux 系统中，一般可以使用 service <service-name> start|stop|restart 或者 systemctl start|stop|restart <service-name> 等命令启动或停止某个服务的进程实例。
实际上，service 和 systemctl 命令都是通过调用 /etc/init.d/ 目录下的启动脚本对服务进行控制。

相对而言，这类启动脚本在编写和维护上都需要耗费比较大的精力。而 Supervisor 只通过一个简单的 INI 格式的配置文件即能完成对一个或多个进程的集中管理，且能够控制进程在崩溃后自动重启。
同时，Supervisor 还支持对进程进行分组，并为组中的进程分配不同的优先级，使得它们可以按预先定义的顺序进行启动。

一、软件安装

Supervisor 支持 Linux、MacOS、Solaris 和 FreeBSD 等操作系统，直接使用对应的包管理命令安装即可。如 Ubuntu 系统：
$ sudo apt-get install supervisor

Supervisor 完全由 Python 语言编写，因此可以使用 pip 命令安装，也支持安装到由 virtualenv 等工具构建的虚拟环境中。
$ pip install supervisor

组件介绍

supervisord

supervisord 是 Supervisor 的服务端组件，负责控制子进程的生命周期、响应客户端组件的命令请求、重启崩溃的进程以及日志记录等工作。
supervisord 使用 Windows-INI 格式的配置文件。

supervisorctl

supervisorctl 是一个借助命令行进行交互式操作的客户端组件，它可以通过类似 Shell 的接口访问 supervisord 提供的功能。

Web Server

如 Supervisor 配置文件中的 [inet_http_server] 项被启用，则可以通过访问 http://localhost:9001 进入一个功能类似 supervisorctl 的 Web 交互界面。

XML-RPC 接口

Supervisor 的 HTTP 服务还提供了 XML-RPC 接口，参考 XML-RPC API Documentation

二、配置文件

Supervisor 的配置文件一般命名为 supervisord.conf。它可以同时被 supervisord 和 supervisorctl 使用（通过 -c 选项指定）。
如执行上述两个命令时并未手动指定配置文件，则依次在以下位置查找名为 supervisord.conf 的配置文件：

• $CWD/supervisord.conf
• $CWD/etc/supervisord.conf
• /etc/supervisord.conf
• /etc/supervisor/supervisord.conf
• ../etc/supervisord.conf
• ../supervisord.conf

Section Settings

配置文件中的 [inet_http_server] 用于配置可供远程访问的 HTTP 服务，示例如下：

[inet_http_server]
port = 127.0.0.1:9001
username = user
password = 123

[supervisord] 用于配置 supervisord 进程的一些全局选项，示例如下：

[supervisord]
logfile = /tmp/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /tmp/supervisord.pid
nodaemon = false
minfds = 1024
minprocs = 200
umask = 022
user = chrism
identifier = supervisor
directory = /tmp
nocleanup = true
childlogdir = /tmp
strip_ansi = false
environment = KEY1="value1",KEY2="value2"

[supervisorctl] 用于控制交互式 Shell supervisorctl 的行为，示例如下：

[supervisorctl]
serverurl = unix:///tmp/supervisor.sock
username = chris
password = 123
prompt = mysupervisor

[program:x]

配置文件中需要至少包含一个 [program:x] 项用于指定某个由 Supervisor 控制的进程。示例如下：

[program:cat]
command=/bin/cat
process_name=%(program_name)s
numprocs=1
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=10
startretries=3
exitcodes=0
stopsignal=TERM
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_capture_maxbytes=1MB
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

[include] 可以用来引入其他位置的配置文件。示例如下：

[include]
files = /an/absolute/filename.conf /an/absolute/*.conf foo.conf config??.conf

三、实例演示

对于一个初始的 Django 项目，可以通过在项目目录下执行 python manage.py runserver 命令启动 Web 服务。这里使用 Supervisor 控制服务进程。

首先在项目目录下创建 supervisord.conf 配置文件。该文件不需要手动创建，可以直接通过 echo_supervisord_conf 命令获取示例配置并定向到 supervisord.conf 文件中，命令如下：
$ echo_supervisord_conf > supervisord.conf

该示例配置中并不包含任何 [program:x] 项，需要自行添加。这里在文件末尾添加如下两行内容：

[include]
files = ./django_server.ini

即为了清晰起见，这里不把 Supervisor 控制的进程包含在主配置文件中，而是放置在当前目录下的 django_server.ini 文件中，再通过主配置文件中的 [include] 将其导入。django_server.ini 文件内容如下：

[program:django_server]
command=python manage.py runserver 0000:8000          ;程序启动命令
process_name=%(program_name)s                         ;进程名称
directory=/home/starky/project/django/test_project    ;启动目录
autostart=true                                        ;自动启动
autorestart=unexpected                                ;异常退出后自动重启
startsecs=10                                          ;程序启动 10 秒后未异常退出，则正常启动
startretries=3                                        ;自动重启尝试次数
user=starky                                           ;启动该进程的用户
redirect_stderr=true                                  ;stderr 重定向至 stdout 。默认 false
stdout_logfile_maxbytes=20MB                          ;stdout 日志大小，默认 50MB
stdout_log_backups=10                                 ;stdout 日志文件备份数量
stdout_logfile=./logs/django_server.log               ;stdout 日志路径。目录不存在时需手动创建

配置完成后，运行以下命令启动 supervisord 程序：
$ supervisord -c supervisord.conf

运行 supervisorctl 命令进入交互式 Shell ，可以看到 django_server.ini 中配置的 django_server 程序已经启动成功：

$ supervisorctl
django_server                    RUNNING   pid 6210, uptime 0:00:15
supervisor>

Web Server

出于安全上的考虑，Supervisor 提供的 Web Server 默认是关闭的，可以通过修改主配置文件 supervisord.conf 进行启用。删除以下内容前的注释即可：

[inet_http_server]         ; inet (TCP) server disabled by default
port=0.0.0.0:9001          ; ip_address:port specifier, *:port for all iface
username=user              ; default is no username (open server)
password=123               ; default is no password (open server)

配置完成后，首先使用 pkill -9 supervisord 命令退出 supervisord 程序，再使用 supervisord -c supervisord.conf 命令重新启动。
此时通过浏览器访问 http://127.0.0.1:9001/，输入用户名密码后即可进入 Web 控制台界面：

Supervisor Web

supervisorctl

supervisorctl 是一个交互式的 Shell ，可以通过它访问 supervisord 提供的部分功能（如启动和停止某个进程、查看日志等）。它支持的基本命令如下：

$ supervisorctl
django_server                    RUNNING   pid 8661, uptime 0:14:11
supervisor> help
default commands (type help <topic>):
=====================================
add    exit      open  reload  restart   start   tail
avail  fg        pid   remove  shutdown  status  update
clear  maintail  quit  reread  signal    stop    version

输入 help <topic> 可以查看对应命令的帮助信息。

常用命令的使用方法如下：

• help : Print a list of available actions
• help <action> : Print help for <action>
• add <name> [...] : Activates any updates in config for process/group
• remove <name> [...] : Removes process/group from active config
• update : Reload config and add/remove as necessary, and will restart affected programs
• update all : Reload config and add/remove as necessary, and will restart affected programs
• update <gname> [...] : Update specific groups, and will restart affected programs
• clear <name> : Clear a process’ log files.
• clear <name> <name> : Clear multiple process’ log files
• clear all : Clear all process’ log files
• fg <process> : Connect to a process in foreground mode Press Ctrl+C to exit foreground
• pid : Get the PID of supervisord.
• pid <name> : Get the PID of a single child process by name.
• pid all : Get the PID of every child process, one per line.
• reload : Restarts the remote supervisord
• reread : Reload the daemon’s configuration files, without add/remove (no restarts)
• start | stop | restart <name> : Start / Stop / Restart a process
• start | stop | restart <gname>:* : Start / Stop / Restart all processes in a group.
• start | stop | restart <name> <name> : Start / Stop / Restart multiple processes or groups
• start | stop | restart all : Start / Stop / Restart all processes. Note: restart does not reread config files.
• status : Get all process status info.
• status <name> : Get status on a single process by name.
• status <name> <name> : Get status on multiple named processes.
• tail <name> [stdout|stderr] (default stdout) : Output the last part of process logs
• tail -f <name> : Continuous tail of named process stdout Ctrl-C to exit
• tail -100 <name> : last 100 bytes of process stdout

参考资料

Supervisord Docs