Nginx文件上传500错误的完整排查与解决过程
作者：台风-.-
一、问题背景
业务反馈文件上传接口 /api/v1/upload 在处理部分文件是时返回 500 错误。
通过实时查看 Nginx 日志error.log，发现核心报错信息：
open() "/usr/local/nginx/client_body_temp/00000000142" failed (13: Permission denied)
同时 access.log 中对应请求状态码为 500，确认是 Nginx 层面权限问题导致上传失败。
二、初步排查：定位问题根源
1. 查看 Nginx 运行用户
通过进程命令确认 Nginx 实际运行用户：
ps aux | grep nginx
结果显示 Nginx master/worker 进程均由 work 用户运行，而非默认的 nginx
2. 查看临时目录权限
进入 Nginx 根目录，查看临时目录权限：
cd /usr/local/nginx && ll
发现关键问题：
client_body_temp目录所有者为nobody，权限为drwx------work用户无写入权限，导致 Nginx 无法存储上传文件临时数据
三、核心问题：Nginx 权限与目录归属不匹配
1. 根本原因
Nginx 运行用户为 work，但所有临时目录的所有者/权限未同步修改，导致：
- 上传文件时，Nginx 无法在
client_body_temp创建临时文件
2. 为何部分文件能正常运行
很多同学会疑惑：为什么有的小文件能上传成功，大文件却报错？这核心和 Nginx 的 client_body_buffer_size 配置相关，也是部分文件能正常运行的关键原因。
首先明确该配置的作用：client_body_buffer_size 用于设置 Nginx 接收客户端请求体（即上传文件、表单数据等）时，在内存中开辟的缓冲区大小。
当上传文件小于等于该缓冲区大小时：Nginx 会直接将文件数据存放在内存缓冲区中，无需写入
client_body_temp临时目录，因此即使该目录权限异常，小文件上传也能正常执行。当上传文件大于该缓冲区大小时：Nginx 会将超出内存缓冲区的部分，临时写入
client_body_temp目录，此时若该目录权限不足（所有者不匹配、无写入权限），就会触发Permission denied错误，返回 500 状态码。
默认情况下，client_body_buffer_size 配置值通常为 16k 或 32k（不同 Nginx 版本略有差异），这也是为什么小文件能正常上传、大文件报错的核心原因——小文件未触发临时目录写入，避开了权限问题。
补充建议：
若业务中存在大量大文件上传，可适当调大 client_body_buffer_size（如设置为 100m），减少临时目录写入频率，但仍需确保 client_body_temp 目录权限正常，避免极端场景下的报错。
示例配置如下：
client_body_buffer_size 100m; # 按需调整，过大可能占用过多内存
4. 补充：client_body_max_size 配置（控制上传文件最大限制）
除了 client_body_buffer_size，还有一个关键配置 client_body_max_size，负责限制客户端上传文件的最大大小，这也是部分文件能上传、部分文件失败的另一个核心原因，容易与权限问题混淆。
先明确两者区别，避免混淆：
client_body_buffer_size：控制「内存缓冲区大小」，决定文件是否需要写入临时目录（和权限相关）；client_body_max_size：控制「上传文件的最大允许大小」，超过这个值直接拒绝上传，和权限无关。
注意要点
若仅调大
client_body_max_size，未修正client_body_temp权限，大文件（超过缓冲区大小）仍会报 500 权限错误；若仅修正权限，未调大
client_body_max_size，超过限制的文件会报 413 错误，无法上传；两者需配合配置，才能确保不同大小的文件都能正常上传，同时避免权限和大小限制导致的报错。
四、完整修复方案
1. 批量修正目录权限
执行以下命令，将 Nginx 所有临时目录及核心文件归属给运行用户 work：
chown -R work:root /usr/local/nginx/ chmod -R 755 client_body_temp
2. 重启 Nginx 生效
./sbin/nginx -s reload
3. 为什么部分文件可以上传偶发失败
./sbin/nginx -s reload
总结
以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。