若依系统上传图片报错504网关超时快速排查清单

核心定义：504错误是网关（如Nginx、负载均衡器）等待上游服务器（后端服务/数据库）响应超时导致，上传场景中多与网络传输、服务器处理速度或配置限制相关。

一、基础用户自查（优先）

适用于普通用户（如网站/APP上传者），无需技术权限，3分钟内可完成。

步骤	操作方法	判断标准	处理结果
1. 网络切换	① 断开当前WiFi/网线，重新连接；② 切换至手机热点（关闭5G用4G更稳定）；③ 关闭VPN/代理工具	上传进度条是否持续推进，无中断	网络稳定则进入步骤3，仍超时则进入步骤2
2. 错峰上传	避开平台高峰时段（如工作日10:00-12:00、14:00-16:00），选择凌晨或深夜重试	同一网络环境下，不同时段上传成功率对比	错峰成功则为服务器负载问题，失败则进入步骤3
3. 图片优化	① 用「画图工具」或「微信截图」压缩图片（JPG质量设为80%，PNG转JPG）；② 裁剪分辨率至1920px以内；③ 单张大小控制在5MB内	优化后文件大小≤5MB，格式为JPG/PNG	优化后成功则为文件参数超限，失败则进入步骤4
4. 操作简化	① 单次开启一个网页，且仅上传1张图片；② 刷新页面并清空浏览器缓存（Ctrl+Shift+Del）；③ 换浏览器重试（推荐Chrome/Firefox）	上传请求是否秒发起，无卡顿提示	简化后成功则为操作方式问题，失败需联系平台

二、管理员/开发者进阶排查

适用于网站/APP维护者，需服务器权限，针对系统性问题。

步骤	操作方法	判断标准	解决方案
1. 日志分析	① Nginx日志：tail -f /var/log/nginx/error.log；② 后端日志：查看应用服务器（如Tomcat/Node.js）错误日志	日志中是否含「upstream timed out」「read timeout」关键词	定位超时环节（Nginx/后端服务），进入对应步骤
2. 网关配置	编辑Nginx配置文件（nginx.conf），调整超时参数：proxy_connect_timeout 300s;proxy_read_timeout 300s;重启Nginx：sudo systemctl restart nginx	超时时间从默认60s延长至300s后，上传是否恢复	按业务需求调整，最大不超过600s（避免资源浪费）
3. 服务器负载	用top或htop命令查看CPU/内存占用，df -h查看磁盘空间	CPU使用率≥80%、内存占用≥90%、磁盘空间≤10%	① 杀占资源进程；② 升级服务器配置；③ 增加负载均衡节点
4. 数据库优化	① 查看MySQL慢查询日志：show variables like 'slow_query_log';；② 为上传相关表添加索引	是否存在执行时间≥2s的上传记录插入语句	优化SQL语句，添加CREATE INDEX idx_upload_time ON uploads(create_time);

三、通用注意事项

• 缓存与CDN：若使用CDN，清除上传路径的CDN缓存，避免旧配置生效；

• 防火墙规则：检查服务器防火墙（如iptables）是否阻止了上传端口（如8080），需开放网关与后端服务的通信端口；

• 异步处理：大文件上传建议改为异步队列（如RabbitMQ），避免同步等待导致超时。