未改配置的Django应用突现502,gunicorn报Worker启动失败
上层抛出的HaltServer 'Worker failed to boot.'是通用兜底报错,本次故障的根本触发原因是debug日志中明确抛出的ModuleNotFoundError: No module named 'inventory4'——gunicorn启动worker时,Python解释器的模块搜索路径中无法识别到inventory4目录,导致WSGI应用加载失败。
基础路径校验
先进入supervisor配置指定的工作目录/home/ubuntu/exostocksaas,执行ls -la确认:inventory4目录真实存在- 目录下存在
__init__.py文件(Python识别为可导入模块的必要标识) - 目录及文件的读权限对运行gunicorn的用户(通常为ubuntu)开放
这类无征兆故障的常见触发场景包括:磁盘写满导致目录元数据损坏、误删文件/目录、系统权限策略更新导致进程无权限读取项目目录。
手动复现排除环境干扰
直接在当前shell中手动执行验证命令,绕开supervisor的环境变量封装:cd /home/ubuntu/exostocksaas /home/ubuntu/exo/bin/python -c "import inventory4.wsgi"如果上述命令抛出同样的
ModuleNotFoundError,说明是Python搜索路径的问题:执行echo $PYTHONPATH,确认项目根目录/home/ubuntu/exostocksaas未被加入搜索路径。这类问题通常出现在服务器自动重启后,之前手动配置的临时环境变量未随supervisor服务持久化生效的场景。修正启动配置彻底规避路径问题
不要依赖supervisor的directory参数隐式将工作目录加入Python搜索路径,选择以下任意一种方式显式配置路径:- 在supervisor的gunicorn配置块中增加环境变量声明:
directory=/home/ubuntu/exostocksaas environment=PYTHONPATH=/home/ubuntu/exostocksaas command=/home/ubuntu/exo/bin/gunicorn --log-level debug --bind unix:/home/ubuntu/exostocksaas/app.sock inventory4.wsgi:application autostart=true autorestart=true stderr_logfile=/var/log/gunicorn/gunicorn.err.log stdout_logfile=/var/log/gunicorn/gunicorn.out.log [group:guni] programs:gunicorn - 在gunicorn的配置文件中增加
pythonpath = '/home/ubuntu/exostocksaas'配置项,显式指定Python模块搜索路径。
- 在supervisor的gunicorn配置块中增加环境变量声明:
资源问题验证
之前怀疑的虚拟机资源不足可顺手校验,但和本次报错无直接关联:- 执行
df -h查看磁盘各分区使用率,若存在100%占用的分区,清理冗余文件即可 - 执行
dmesg | grep -i oom确认是否有进程被OOM killer强制终止 - 执行
free -h查看内存占用情况
- 执行
配置重载验证
配置修改完成后,依次执行命令重载服务:supervisorctl reread supervisorctl update supervisorctl restart guni:gunicorn查看gunicorn错误日志确认无模块导入报错后,验证nginx对gunicorn生成的unix sock文件的读写权限,即可恢复站点访问。
服务连续稳定运行数月后突然报模块找不到,基本和代码配置无关,大概率是以下场景触发:
- 服务器自动重启后,supervisor启动gunicorn时的环境变量和手动调试时的环境变量不一致
- 磁盘写满导致
inventory4目录下的核心文件(如__init__.py)无法正常读取 - 系统自动更新修改了目录访问权限,导致gunicorn进程无法读取项目文件
内容的提问来源于stack exchange,提问作者Murcielago

