supervisor配置文件(详细说明)

supervisor 安装启动

supervisor配置文件叫supervisord.conf，supervisord和supervisorctl共用一个配置文件，如果应用启动时，没有使用-c选项，应用会按照指定顺序寻找supervisord.conf文件：
$CWD/supervisord.conf
$CWD/etc/supervisord.conf
/etc/supervisord.conf
/etc/supervisor/supervisord.conf (since Supervisor 3.3.0)
../etc/supervisord.conf (Relative to the executable)
../supervisord.conf (Relative to the executable)

一、配置文件格式

Windows-INI-style (Python ConfigParser)类型文件，包含以[header]标记开头的模块和这个模块里一系列的key/value键值对

二、环境变量配置

supervisord启动时使用的环境变量，用的是python%(ENV_X)s字符串表达式语法格式

→ [unix_http_server]

[unix_http_server]模块下配置了需要监听UNIX domain socket的http服务的配置参数；如果在conf文件里没有配置这个模块，那需要监听UNIX domain socket的supervisorctl就不会被启动

• values说明：

  1. file: supervisor为HTTP/XML-RPC请求监听UNIX domain socket的路径（socket文件路径）；supervisorctl通过这个文件完成与supervisor的交流；这个选项可以用%(here)s，如果用%(here)s这个值，那么会直接扩展到supervisord的配置文件所在目录
   这个关键字默认不配置，也不是必须要配置的，但是要注意，如果supervisor.sock文件被删除或者没有配置，supervisorctl就不能连接到supervisord，也就不能用suepervisorctl控制进程了，例如下面这个错误：

报错：Unlinking stale socket /var/run/supervisor/supervisor.sock
解决：unlink /var/run/supervisor/supervisor.sock，然后重启supervisor

  2. chmod: socket文件权限的指定，默认是0700
  3. chown: 改变socket文件的用户和组，默认使用启动supervisord的用户和用户组
  4. username: supervisorctl连接supervisord时的授权用户，默认无指定用户
  5. password: supervisorctl连接supervisord时的授权密码，默认无密码；密码既可以是纯文本密码，也可以是带有{SHA}前缀的SHA-1的哈希，例如：{SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d

• 举个栗子：

[unix_http_server]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123

→ [inet_http_server]

[unix_http_server]这个模块配置是监听TCP socket的配置，如果.conf里面没有配置这个模块，inet的http服务就不会启动，那web server和remote supervisorctl就不能使用；
这个模块默认未开启状态，如果需要启用这个模块需要绝对信任的环境——应该绑定localhost或者只能通过一个可信赖的独立网络访问，inet的http服务不支持任何形式的加密，不能使用默认认证方式；
inet的http服务可以被supervisorctl远程控制，也可以通过web界面的方式控制子进程，查看log，但是不可以把inet的http服务暴露在公共网络里面

• values说明：

  1. port: 一个tcp的host:port配置，例如127.0.0.1:9001，supervisorctl会通过这个端口和supervisord交流；无默认配置
  2. username和password: 与[unix_http_server]模块下的username && password作用相同

• 举个例子：

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

→ [supervisord]

这个模块配置了supervisord进程有关的全局配置，这个默认可以不配置，但是不配置时，supervisord运行可能会出现问题

• values：

  1. logfile：默认值：$CWD/supervisord.log，指定supervisord进程的log文件的路径，也可以直接用%(here)s；如果指定了log文件&&需要做log滚动（根据log大小限制生成新的log文件）的话，必须配置logfile_maxbytes > 0
  2. logfile_maxbytes: 默认50MB，配置日志滚动的log字节数限制，KB/MB/GB这些单位都是可以用的，如果配置为0，则认为log文件不限制大小，不做log滚动
  4. logfile_backups: 备份保留log个数，默认保留最近10个，如果设置为0就不做任何备份
  5. loglevel: log级别：默认记录info级别的日志，可选：critical||error||warn||info||debug||trace||blather；如果指定日志记录为debug级别，supervisord 的log文件里会记录子进程的输入输出，也会记录进程状态改变的信息，在某个进程启动异常做调试的时候比较方便
  6. pidfile: supervisord的pid文件路径，默认$CWD/supervisord.pid，也可以使用%(here)s
  7. umask: supervisord进程的文件权限掩码，默认 022
  8. nodaemon: 设置这个选项为true的时候，会在前台启动supervisor，默认flase
  8. minfds : supervisor启动前要求的最小空闲文件描述符数值，supervisord启动时对硬件和软件资源的要求，低于这个最低值，supervisor无法启动；如果supervisord基于root用户启动，硬件限制会有所提高，所以指定要求的资源限制最低值，可以确保程序运行过程中不会造成资源耗尽的情况，默认值是1024
  9. minprocs: supervisord启动时，系统中最小可用进程数的配置，低于当前数值，supervisord不会启动；默认值=200
  10. nocleanup : 默认false，如果想避免supervisord启动时“auto”路径下的清理子进程的log文件可以设置为true
  11. childlogdir: 子进程的“auto” log文件目录，默认取的是python的tempfile.get_tempdir()路径，也可以用%(here)s
  12. user: 在做进程管理之前，supervisord需要转变用户使用指定的unix用户（默认是当前用户），支持这个配置的前提是supervisord使用root用户启动
  PS：3.3.4版本以后，如果supervisord不能转换到指定用户，会记录错误信息到log里然后立即退出；之前的版本会记criticallog，但是程序可以继续运行
  13. directory: supervisord作为守护进程的时候，会转换路径到这个dictionary，默认不配置，可以使用%(here)s
  14. strip_ansi: 清除子进程log文件中的ANSI内容，默认不清除
  15. environment: supervisord进程启动环境中的环境变量配置，是KEY="val",KEY2="val2"这样一系列的key-value键值对，如果键值对的value值包含一些非标准字符，例如KEY="val:123",KEY2="val,456"这种一定要用""括起来，最好的话还是使用转义减少问题
  16. identifier: RPC交互使用的supervisor进程的声明，默认值=supervisor

• 举例：

[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]

使用supervisorctl和supervisord交互的配置

• values：

  1. serverurl: 访问supervisord服务的url：unix:///absolute/path/to/file.sock；默认配置http://localhost:9001
  2. username和password: 访问supervisord服务时的身份认证用户和密码，username需要和supervisord的用户是同一个，默认是不配置的；需要注意的是，如果使用password，就必须设置密码为纯文本字符串，这里不支持SHA hash格式的密码
  3. prompt: supervisorctl 命令行标识符，默认supervisor
  4. history_file: 历史文件的路径，如果启用这个配置指定文件路径，那么supervisorctl的历史命令会被保存在这个文件里面，并且可以命令查看之前supervisorctl session的历史记录，默认不配置

• 栗子：

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

→ [program:x]

这个模块在配置文件中至少要有1个，是必须要有的模块，可以有多个，这个模块告诉supervisord 需要控制的服务项目有哪些；模块的头部是program:接项目名组成的，后面的名字就是supervisord控制的服务名，后面supervisorctl就是直接通过这个服务名称来做进程管理；
如果一个program没有指定名字，或者不是用:指定的，supervisod启动时会直接失败；
新版本（3.0）中，一个[program:x]将会被supervisor看做是一个同类进程组，这一系列进程组通过numprocs和process_name定义在配置文件中，当然默认情况下还是一个program就只是一个单独的进程，以便更好的兼容历史版本；

• 例如：

testMul这个program就是一个进程组，包含了相同命令启动的三个进程：testMul_00、testMul_01、testMul_02

[program:testMul]
command=/bin/cat              ; the program (relative uses PATH, can take args)
numprocs=3                    ; number of processes copies to start (def 1)
process_name=%(program_name)s_%(process_num)02d

一个program包含多个进程.jpeg

• values：

     1. command: 启动program的命令，可以是 /usr/bin/python，也可以是python，但是如果准备直接用python这种相对命令，需要保证supervisord的环境变量能够找到命令路径并且有权限执行命令；
  command的值可以是一个python字符串类型的表达式。例如：/path/to/programname --port=80%(process_num)02d在运行时就可能被扩展成/path/to/programname --port=8000，所有这些表达式都是可以包含group_name, host_node_name, process_num, program_name, here这些key的，而且supervisord的环境变量前缀必须以ENV_开头；
     所有program自己本身不应该是一个守护进程，因为他们会被作为supervisord的子进程；
     还有就是命令行里不要使用单引号，如果有需要要使用双引号，否则可能解析错误；
     command是必须填的
    2. process_name: 组成进程名的表达式，默认%(program_name)s，可以自行修改
     3. numprocs: 如果numprocs>1，supervisor启动当前program时会实例化好几个子进程，默认情况取1
     4. numprocs_start: 一个program启动时开始的增量偏移量（进程编号初始值），默认=0
     5. priority : program启动和停止的优先级顺序，尤其是在start all||stop all这种操作的时候，优先级越低的program，将会先启动后关闭，相反优先级越高的program会后启动先关闭，默认值是999
     6. autostart: 是否在supervisord启动的时候自动启动进程，默认是true
     7.startsecs: 项目启动后认为项目启动成功，变更进程启动状态从STARTING到RUNNING的秒数，默认是1s；
     如果进程终止，且给出符合预期的状态码，则在修改STARTING状态之前，根据exitcodes后处理为进程启动失败；
     8. startretries: 失败重启次数，超过这个次数直接将状态置为FATAL，进程启动失败，默认3次
     9. autorestart： 当进程在running状态下exit时，是否自动重启，允许配置false, unexpected, or true三个状态，如果是false，不会自动重启，如果是unexpected，则在异常退出时进行自动重启，true则是不考虑状态码，始终自动重启；默认unexpected
     10. exitcodes: 退出码，一般是配合着autorestart使用的，默认是0
     11. stopsignal: 终止信号标识，在stop进程时的终止信号，可以使用TERM, HUP, INT, QUIT, KILL, USR1, or USR2，默认是TERM
     12. stopwaitsecs: 发出stop指令以后，等待进程结束信号的时间，默认10s，如果当前时间内没有收到进程终止信号，直接进行kill
     13. stopasgroup: 设置成true，则表示stop信号要发给整个进程组，也意味着killasgroup标识为true，一般情况下默认设置为false
     14. killasgroup: 设置为true的时候，标识需要发送kill信号到整个进程组，也包括这个组里的子进程们，使用python multiprocessing的时候很方便，当然默认为false
     15. user: supervisord启动进程时使用的用户，同样的这个用户使用的前提是supervisord服务是root用户启动的，否则这个项目不会被启动的，默认没有设置
     16. redirect_stderr: 默认值是false，设置为true的时候，进程的标准错误输出内容会被写入supervisord的标准输出stdout文件里；
     需要注意的是在[eventlistener:x]里不要设置redirect_stderr=true，因为eventlistener是用stdout和stdin和supervisord交流的，如果被设置重定向了，stderr的内容会和eventlistener协议进行交互的
     17. stdout_logfile: 进程标准输出内容写入文件，如果没有设置stdout_logfile或者使用默认值AUTO，supervisor会自动选择一个本地文件，如果设置为NONE，就不创建log文件了；
     同样，stdout_logfile的值可以用python的表达式
     19. stdout_logfile_maxbytes: stdout_logfile文件做log滚动时，单个stdout_logfile文件的最大字节数，默认50M，设置为0则认为不做log滚动方式
     20. stdout_logfile_backups: stdout_logfile备份文件个数，默认为10
     21. stdout_capture_maxbytes: 当进程处于stdout capture mode模式的时候，写入capture FIFO的最大字节数限制，默认为0，此时认为stdout capture mode模式关闭；
     22. ** stdout_events_enabled**: 默认值为0，如果设置为true，在进程写入标准文件是会发起PROCESS_LOG_STDOUT 时间
     23. stdout_syslog: 默认false，设置为true的时候，标准输出会被指向进程名的系统log
     24. stderr_logfile: 默认AUTO，redirect_stderr!=true的时候，stderr的输出文件
     25. stderr_logfile_maxbytes: 默认50MB，stderr_logfile的最大值
     26. stderr_logfile_backups: stderr_logfile的最大备份数
     27. stderr_capture_maxbytes: 进程在stderr capture mode模式下，写入 capture FIFO的最大字节数限制，默认为0，即stderr capture mode模式关闭；
     28. stderr_events_enabled: 默认false，进程写入stderr文件是发出的PROCESS_LOG_STDERR事件
     29. stderr_syslog: 默认false，设置为true的时候，标准错误输出会被指向进程名的系统log
     30. environment、directory、umask: 和前面模块的意义是类似的
     31. serverurl: 这个URL是子进程作为SUPERVISOR_SERVER_URL通过环境与内部http服务做交流的一个媒介的，如果配置这个关键字，和[supervisorctl]里的作用是相同的

• 栗子：

[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这个配置，指定额外的配置文件要包含在当前配置中；
这个模块只有supervisord用，supervisorctl不会用到

• values：

   1. files: 一个隔离开来的文件系列，每个系列里的文件可以是独立的，也可以实现相互关联的，直接包含就可以了；这个所谓的一个系列，需要根据unix的使用规则指定一定的模式，然后用*||?||[]这种匹配模式去匹配，包含host_node_name||here的字符喜欢表达式也是可以的；
   没有默认值，启用模块必须配置

• 栗子：

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

→ [group:x]

这个模块通常是做组进程管理的，将多个[program:x]放到一个进程中管理，为了把一组program作为一个整体进行管理，就要在配置[group:x]的时候，必须填好programs的配置项，指定你要绑定在一起的programs们；
模块命名与program一样的，header错误会导致启动失败
一个group模块下可以配置多个programs；

• values：

   1. programs: 成组的programs
   2. priority: 优先级

• 栗子：

[group:testgroup]
programs=theprogramname,test  ; each refers to 'x' in [program:x] definitions
priority=999                  ; the relative start priority (default 999)

groups组示例.jpeg

→ [fcgi-program:x]

• supervisor可以管理所有监听相同 socket的FastCGI进程组，为了实现完整的进程管理， Apache下可以用mod_fastcgi 来管理，但是Apache的这个模式的处理会比较复杂，这种方式对CPU和内存也有一定的要求；
• 而且为了用例如nginx这种不内嵌进程管理器的服务，还需要借助cgi-fcgi or spawn-fcgi脚本；
• 这些都可以被结合使用在supervisor或者其他进程守护工具的进程管理中，但是这就要求每个FastCGI的子进程都要绑定自己的socket，这样做的缺点是：不能过于复杂的web服务配置，重启和减少的容错性并不好；由于配置需要的sockets 更少，如果FastCGI进程组可以共享sockets ，那么web服务器配置就会更小。共享sockets允许优雅的重新启动，因为在重新启动任何子进程时，仍然是父进程绑定了这些sockets，容错性也会更好；
• supervisor可以实现使用一组不必要绑定web服务的FastCGI进程共享sockets来完成完整的进程组管理，完成了web服务和进程管理的独立化

→ [eventlistener:x]

supervisor允许在配置文件里指定进程组（“事件监听池”）的，这些进程可能需要接受或者回应supervisor事件系统的事件提醒，eventlistener做的就是订阅这些事件做监听

• values：

   1. 支持 [program:x] 下除了stdout_capture_maxbytes的所有可选配置项
   2. buffer_size: 事件监听池里时间序列的缓存大小，当一个事件监听池发生溢出时，就会丢弃缓存中最旧的事件
   3. events: 逗号分隔的事件类型列表，只出需要监听的进程的的哪些事件
   4. result_handler: 一个python回调函数pkg_resources模块的入口，默认supervisor.dispatchers:default_handler

• 栗子：

[eventlistener:theeventlistenername]
command=/bin/eventlistener
process_name=%(program_name)s_%(process_num)02d
numprocs=5
events=PROCESS_STATE
buffer_size=10
directory=/tmp
umask=022
priority=-1
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0
stopsignal=QUIT
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

→ [rpcinterface:x]

只用于扩展supervisor额外的用户定制行为