参考来源与致谢
- 引用来源:Limit File Upload Size in NGINX
- 原作者:原页面署名作者或发布机构(剪藏记录未保存可核验的个人署名)
- 感谢词:感谢原作者及发布机构对技术知识的公开分享。本文已结合企业运维场景完成脱敏、核验与原创重写,并非原文转载;如权利人需要更正署名或来源信息,请联系本站。
适用场景 #
NGINX 默认对单个请求体大小设有限制,超出限制的请求会被拒绝并返回 413 状态码。当业务需要支持较大的文件上传(如附件、镜像、备份包、日志归档)时,需要显式调整该阈值。合理设置上传上限可以降低大体积请求耗尽连接与带宽资源的风险,属于常见的拒绝服务防护手段之一。
本文适用于以 NGINX 作为反向代理或静态资源服务器的企业环境,涉及配置项为 client_max_body_size。不同版本对默认值、指令可用上下文及错误码表现可能存在差异,具体请查阅所用版本的官方文档。
准备与风险 #
- 确认 NGINX 配置文件路径,常见为
/etc/nginx/nginx.conf,站点配置可能位于/etc/nginx/conf.d/或/etc/nginx/sites-enabled/。 - 确认当前生效的默认限制,可通过响应头或错误日志中的 413 记录判断。
- 确认上游应用(如应用服务器、对象存储网关)自身是否也有请求体大小限制,避免只改 NGINX 而请求仍被后端拒绝。
- 确认反向代理链路中是否存在其他中间层,例如负载均衡、WAF、CDN,它们可能各自设有独立上限。
修改前必须备份配置文件,并在测试环境验证后再应用到生产。放大的上限会同时放大资源消耗,请结合磁盘、内存、超时设置一并评估。
处理步骤 #
1. 备份配置 #
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S)
若使用独立站点配置文件,同样对其做备份。
2. 选择作用域 #
http块:影响所有 server 块,即全部虚拟主机。server块:仅影响该站点或应用。location块:仅影响该站点下某个上传目录。
作用域越精确,影响面越小。生产环境建议优先使用 server 或 location,避免全局放宽。
3. 写入配置 #
http 作用域示例:
http {
...
client_max_body_size 100M;
}
server 作用域示例:
server {
...
client_max_body_size 100M;
}
location 作用域示例:
location /uploads {
...
client_max_body_size 100M;
}
数值与单位按实际业务需求填写,不要直接照搬示例值。若需完全取消限制可设为 0,但这会显著增加资源耗尽风险,通常不建议在生产使用。
4. 校验并生效 #
nginx -t
语法检查通过后再重载或重启:
systemctl reload nginx
或使用 SysV init 环境:
service nginx reload
重载不会中断现有连接,通常优于重启。若配置结构变化较大,可改用 systemctl restart nginx。
验证方法 #
- 使用小于新上限的文件上传,确认返回成功。
- 使用略大于新上限的文件上传,确认返回 413 且错误日志有对应记录。
- 检查响应头与错误日志,确认限制值已按预期生效。
- 在多个虚拟主机或目录上分别验证,确认作用域符合设计。
回退建议 #
若出现异常,恢复备份文件后重载配置:
cp /etc/nginx/nginx.conf.bak.[时间戳] /etc/nginx/nginx.conf
nginx -t
systemctl reload nginx
回退后再次验证原有上传功能是否恢复正常。
常见问题 #
- 已修改配置但仍返回 413:检查是否存在更内层的
location覆盖,或上游代理、WAF、CDN 另有上限。 - 上传大文件超时而非被拒:需同时检查
client_body_timeout、proxy_read_timeout等超时参数。 - 上传占用大量临时空间:请求体可能先写入临时目录,需关注
client_body_temp_path所在分区的容量。 - 配置未生效:确认修改的是实际被加载的配置文件,可用
nginx -T查看完整生效配置。
以上参数名称与行为以所用 NGINX 版本的官方文档为准。
