使用Gunicorn/Nginx部署Flask应用 新增路由本地正常却服务器报404的排查求助

1. 先确认服务器实际运行的代码确实是你改后的版本 #

这是最容易踩的低级错误，别跳过：

• 核对Gunicorn配置里写的项目入口路径，确认它加载的是你刚上传更新代码的目录，而不是之前残留的旧项目目录
• 直接在服务器上打开对应的路由文件，肉眼搜索有没有@app.route('/domain_group/admin')这行，别全信上传工具的"传输成功"提示
• 删除项目目录下所有__pycache__文件夹，再重启Gunicorn，避免Python读取旧的字节码缓存
• 如果你是用Git拉取部署的，执行git log确认当前分支已经拉到了包含新增路由的最新提交，没有拉错分支
• 重启Gunicorn后执行ps aux | grep gunicorn，确认所有worker进程都是刚启动的，没有旧进程残留还在加载旧代码

2. 确认路由是否真的注册到了Flask应用 #

如果代码确实更新了还是404，直接验证路由是否被Flask加载：

• 进入项目目录，用项目对应的Python环境执行以下代码，把Flask应用初始化出来后打印所有注册的路由：

from 你的Flask应用入口名 import app
print(app.url_map)

• 检查输出的路由列表里有没有/domain_group/admin这条，如果没有，说明路由根本没注册成功
  • 大概率是路由文件导入时报错：检查Gunicorn的错误日志（systemd部署的话一般在/var/log/syslog，或你配置里指定的error.log路径），看启动时有没有导入该路由文件时的缺包、变量未定义等报错，导入失败会导致该文件下的所有路由都不会被注册

3. 区分404是Nginx返回还是Flask返回 #

很多人会把两层的404搞混，直接验证：

• 在服务器本地直接curl访问Gunicorn的监听端口（比如curl -i http://127.0.0.1:8000/domain_group/admin）：
  • 如果返回302跳转（到登录页，符合@login_required的预期），说明Flask本身路由没问题，404是Nginx层返回的
    • 检查Nginx的location配置：如果之前是单独给各个路径配转发规则（比如只匹配了/admin/、/profile/等路径转发到Gunicorn），新增的/domain_group/admin不在匹配范围内，Nginx就会直接返回404，不会转发请求给后端
    • 如果开了Nginx的代理缓存，清一下缓存目录再试，避免旧的404响应被缓存下来
  • 如果curl直接返回404，说明还是Flask侧的路由没注册成功，回到上一步排查导入报错的问题

4. 排除其他小概率冲突 #

• 检查是否有其他路由规则覆盖了这个路径，比如存在通配符路由/<任意值>/admin，匹配优先级高于你的精确路由
• 确认访问时的路径大小写完全匹配，Flask默认是区分路径大小写的
• 确认Gunicorn启动时用的是项目虚拟环境里的Python，而不是系统Python，避免加载到旧的依赖或代码

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