Gunicorn 配置文件参数详解

Gunicorn 配置文件参数详解

Gunicorn (Green Unicorn) 是一个用于 UNIX 系统的 Python WSGI HTTP 服务器，以下是其配置文件中的主要参数及其用法说明：

基础配置参数

1. 绑定地址和端口

• bind (字符串): 指定服务器绑定地址和端口

  • 格式: [HOST]:PORT 或 unix:PATH

  • 示例: bind = "0.0.0.0:8000" 或 bind = "unix:/tmp/gunicorn.sock"

  • 默认: "127.0.0.1:8000"

2. 工作进程配置

• workers (整数): 工作进程数量

  • 建议值: CPU核心数 × 2 + 1

  • 示例: workers = 3

  • 默认: 1

• worker_class (字符串): 工作进程类型

  • 选项: sync (同步), gthread (线程), gevent (协程), uvicorn.workers.UvicornWorker (ASGI)

  • 示例: worker_class = "gthread"

  • 默认: "sync"

• threads (整数): 每个工作进程的线程数

  • 仅当使用 gthread 工作器时有效

  • 示例: threads = 4

  • 默认: 1

性能和资源参数

3. 超时控制

• timeout (整数): 工作进程无响应超时时间(秒)

  • 超时后工作进程将被重启

  • 示例: timeout = 30

  • 默认: 30

• graceful_timeout (整数): 优雅关闭超时时间(秒)

  • 工作进程收到停止信号后完成当前请求的时间

  • 示例: graceful_timeout = 30

  • 默认: 30

• keepalive (整数): 保持连接的时间(秒)

  • 示例: keepalive = 2

  • 默认: 2

4. 资源限制

• worker_connections (整数): 每个工作进程的最大并发连接数

  • 示例: worker_connections = 1000

  • 默认: 1000

• max_requests (整数): 工作进程处理的最大请求数

  • 达到此数后工作进程自动重启，防止内存泄漏

  • 示例: max_requests = 1000

  • 默认: 0 (无限制)

• max_requests_jitter (整数): 最大请求数的随机波动范围

  • 避免所有工作进程同时重启

  • 示例: max_requests_jitter = 50

  • 默认: 0

日志配置参数

5. 日志输出

• accesslog (字符串): 访问日志文件路径

  • "-" 表示输出到标准错误

  • 示例: accesslog = "/var/log/gunicorn/access.log" 或 accesslog = "-"

  • 默认: None (不记录访问日志)

• errorlog (字符串): 错误日志文件路径

  • 示例: errorlog = "/var/log/gunicorn/error.log"

  • 默认: "-" (输出到标准错误)

• loglevel (字符串): 日志级别

  • 选项: debug, info, warning, error, critical

  • 示例: loglevel = "info"

  • 默认: "info"

6. 日志格式

• access_log_format (字符串): 访问日志格式

  • 常用变量: %h (客户端地址), %l (用户名), %u (认证用户名), %t (时间), %r (请求行), %s (状态码), %b (响应大小)

  • 示例: access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'

安全相关参数

7. 权限控制

• user (整数/字符串): 运行工作进程的用户ID或用户名

  • 需要以root启动Gunicorn

  • 示例: user = "nobody" 或 user = 65534

  • 默认: 当前用户

• group (整数/字符串): 运行工作进程的组ID或组名

  • 示例: group = "nogroup" 或 group = 65534

  • 默认: 当前组

• umask (整数): 工作进程的文件模式创建掩码

  • 八进制格式: umask = 0o007

  • 默认: 0

高级配置参数

8. 进程管理

• daemon (布尔): 是否以守护进程方式运行

  • 示例: daemon = True

  • 默认: False

• pidfile (字符串): PID文件路径

  • 示例: pidfile = "/var/run/gunicorn.pid"

  • 默认: None

• worker_tmp_dir (字符串): 工作进程临时目录

  • 使用内存文件系统可提高性能

  • 示例: worker_tmp_dir = "/dev/shm"

9. 请求处理

• limit_request_line (整数): 请求行的最大字节数

  • 示例: limit_request_line = 4094

  • 默认: 4094

• limit_request_fields (整数): 请求头字段的最大数量

  • 示例: limit_request_fields = 100

  • 默认: 100

• limit_request_field_size (整数): 单个请求头字段的最大字节数

  • 示例: limit_request_field_size = 8190

  • 默认: 8190

import multiprocessing
import signal
import sys
import os
import gevent.monkey
gevent.monkey.patch_all()

def handle_exit(server):
    print("收到退出信号，开始优雅退出...")
    # 发送 SIGTERM 给所有工作进程
    server.kill_workers(signal.SIGTERM)
    # 等待所有工作进程退出
    print("所有工作进程已退出")
    sys.exit(0)

# 注册主进程退出钩子
def when_ready(server):
    signal.signal(signal.SIGINT, lambda s, f: handle_exit(server))
    signal.signal(signal.SIGTERM, lambda s, f: handle_exit(server))

# ========== 基础配置 ==========
# 绑定地址和端口
bind = "0.0.0.0:8000"

# 工作进程配置
workers = multiprocessing.cpu_count() * 2 + 1  # 自动计算工作进程数
worker_class = "gthread"  # 使用线程工作器
threads = 4  # 每个工作进程的线程数

# ========== 超时控制 ==========
timeout = 30  # 工作进程无响应超时
graceful_timeout = 30  # 优雅关闭超时
keepalive = 2  # 保持连接时间

# ========== 资源限制 ==========
worker_connections = 1000  # 每个工作进程的最大并发连接数
max_requests = 1000  # 工作进程处理的最大请求数
max_requests_jitter = 50  # 最大请求数的随机波动范围

# ========== 日志配置 ==========
accesslog = "-"  # 访问日志输出到stdout
errorlog = "-"  # 错误日志输出到stderr
loglevel = "info"  # 日志级别
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'

# ========== 安全配置 ==========
user = "nobody"  # 运行工作进程的用户
group = "nogroup"  # 运行工作进程的组
umask = 0o007  # 文件模式创建掩码

# ========== 高级配置 ==========
daemon = False  # 不以守护进程运行
pidfile = "/var/run/gunicorn.pid"  # PID文件路径
worker_tmp_dir = "/dev/shm"  # 工作进程临时目录

# 请求处理限制
limit_request_line = 4094  # 请求行最大字节数
limit_request_fields = 100  # 请求头字段最大数量
limit_request_field_size = 8190  # 单个请求头字段最大字节数

# ========== 钩子函数 ==========
def on_starting(server):
    print(" Gunicorn starting...")

def when_ready(server):
    print(f"✅ Gunicorn ready. Serving on {server.cfg.bind}")

def pre_fork(server, worker):
    print(f" About to fork worker {worker.pid}")

def post_fork(server, worker):
    print(f" Worker {worker.pid} forked")

def worker_int(worker):
    print(f" Worker {worker.pid} received INT or QUIT signal")

def worker_exit(server, worker):
    print(f" Worker {worker.pid} exited")

def on_exit(server):
    print(" Gunicorn exiting...")