DRF部署cPanel Phusion Passenger报500错误及静态资源加载异常

静态资源全部加载失败的根因 #

• 开发服务器的静态能力不通用：Django本地runserver启动时自带静态资源代理逻辑，会自动处理/static/路径的请求。这一逻辑仅存在于命令行开发服务器入口，不属于WSGI应用的默认能力。Phusion Passenger直接对接WSGI入口时，不会自动完成静态请求的代理，哪怕开启DEBUG模式也不会生效。
• 静态收集路径配置错误：当前STATIC_ROOT指向了项目配置子包的内部目录，不是独立的静态资源存放目录。即便已经执行过collectstatic操作，收集的资源位置与Web服务默认查找静态资源的路径不匹配，自然返回404。
• 反向代理层未做静态路径映射：所有静态请求都被转发给Django应用，没有在Web服务层直接将/static/请求映射到实际的资源存放目录，触发应用路由匹配失败返回404。

访问/users路由返回服务端错误的根因 #

• 数据库文件权限异常：项目使用sqlite3作为数据库，数据库文件存放在项目根目录。如果上传代码时文件权限配置不当，Phusion Passenger运行应用时没有数据库文件的读写权限，执行用户表查询操作时就会直接抛出服务端错误。
• 错误渲染被中间层拦截：Phusion Passenger的开发模式没有正确透传Django的错误输出，本该在DEBUG模式下展示的详细错误页被拦截，用户看到的是通用的服务端报错，无法直接看到具体的异常栈。

已验证的修复方案 #

1. 修正静态目录配置
   调整STATIC_ROOT为项目根目录下的独立静态收集目录，避免存放在Python代码包内部（防止被Python打包逻辑扫描）：

   STATIC_ROOT = BASE_DIR / 'static_collected'
   STATIC_URL = '/static/'
   

   修改完成后重新执行python manage.py collectstatic，确保所有静态资源被正确收集到目标目录。

2. 修正数据库权限
   给项目目录、根目录下的db.sqlite3文件赋予cPanel应用运行用户的读写权限，确保应用可以正常连接数据库执行查询操作。

3. 配置Nginx反向代理
   不通过Phusion Passenger直接对外提供服务，通过Nginx反向代理将请求转发给后端运行的Django服务，同时完成两类路径的规则配置：

   • 所有/static/开头的请求直接映射到STATIC_ROOT对应的物理目录，不经过Django应用处理，直接返回静态资源
   • 其余业务请求转发给本地端口运行的Django WSGI服务

   这种配置下，静态资源加载失败的问题会彻底解决，同时Nginx不会拦截Django的错误输出，访问业务路由时如果出现异常可以看到详细的错误栈，原先的通用500报错也会消失。

生产环境注意：当前配置长期开启DEBUG=True、ALLOWED_HOSTS为全匹配存在安全风险，反向代理配置完成后建议切换为生产DEBUG模式，保持Nginx静态路径映射规则即可正常运行。

内容的提问来源于stack exchange，提问作者nzf