如何使用 Supervisor 守护生产环境 Django Gunicorn 进程？

在生产环境部署 Django 时，使用 Supervisor 守护 Gunicorn 进程是一种成熟且广泛采用的方案，特别适合需要精细控制进程重启策略、日志收集以及在没有 systemd 权限的环境下的场景。

先说结论：Supervisor 能确保 Gunicorn 意外退出后自动拉起，并提供统一的状态管理界面，是 Python Web 服务进程管理的经典选择。

适合生产环境需要进程自动恢复的场景
配置前需确认虚拟环境路径与 Django 设置模块
验收时确认进程存活、日志正常写入且权限正确

准备工作和路径确认

在编写配置前，必须获取准确的虚拟环境路径和 Gunicorn 绝对路径，避免调用系统默认 Python 导致依赖缺失。

# 激活虚拟环境后执行，获取 gunicorn 绝对路径
which gunicorn
# 输出示例：/path/to/venv/bin/gunicorn

# 确认 Django 项目设置模块名称
ls myproject/settings.py

编写 Supervisor 配置文件

在 /etc/supervisor/conf.d/ 目录下新建文件，例如 gunicorn.conf。注意命令中不要包含反引号，并显式声明环境变量。

[program:gunicorn]
command=/path/to/venv/bin/gunicorn myproject.wsgi:application `--bind` 127.0.0.1:8000 `--workers` 3
directory=/path/to/your/project
user=www-data
autostart=true
autorestart=true
environment=DJANGO_SETTINGS_MODULE="myproject.settings"
stderr_logfile=/var/log/gunicorn.err.log
stdout_logfile=/var/log/gunicorn.out.log

注意：请将 /path/to/venv/bin/gunicorn 和 /path/to/your/project 替换为实际绝对路径。

如何使用 Supervisor 守护生产环境 Django Gunicorn 进程？

文件权限配置指南

若配置中指定了 user=www-data，需确保该用户对项目目录和日志文件有读写权限，否则会导致启动失败或日志无法写入。

# 修改项目目录所有者
sudo chown -R www-data:www-data /path/to/your/project

# 创建日志文件并授权
sudo touch /var/log/gunicorn.err.log
sudo touch /var/log/gunicorn.out.log
sudo chown www-data:www-data /var/log/gunicorn.*.log

加载配置与验证

使用 supervisorctl 工具通知守护进程读取新配置。

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start gunicorn

验证步骤：

检查进程状态：sudo supervisorctl status，状态应为 RUNNING。
验证服务响应：curl -I http://127.0.0.1:8000，确认返回 HTTP 200。
测试自动重启：手动 kill 掉 Gunicorn 进程，观察 Supervisor 是否将其重新拉起。
检查日志：tail -f /var/log/gunicorn.err.log，确认无报错。

常见坑

路径问题：配置中的 command 必须使用虚拟环境中 gunicorn 的绝对路径。
端口占用：如果之前手动启动过 Gunicorn 未关闭，Supervisor 启动时会因端口占用失败，需先清理旧进程。
环境变量缺失：未在配置中声明 DJANGO_SETTINGS_MODULE 可能导致 Django 无法找到设置文件。

参考来源

Supervisor Official Documentation, Configuration File Section, http://supervisord.org/configuration.html
Gunicorn Documentation, Deployment, https://docs.gunicorn.org/en/stable/deploy.html
Django Documentation, How to deploy with Gunicorn, https://docs.djangoproject.com/en/stable/howto/deployment/wsgi/gunicorn/