一、問題背景

業(yè)務(wù)反饋文件上傳接口 /api/v1/upload 在處理部分文件是時返回 500 錯誤。

通過實時查看 Nginx 日志error.log，發(fā)現(xiàn)核心報錯信息：

 open() "/usr/local/nginx/client_body_temp/00000000142" failed (13: Permission denied)

同時 access.log 中對應(yīng)請求狀態(tài)碼為 500，確認(rèn)是 Nginx 層面權(quán)限問題導(dǎo)致上傳失敗。

二、初步排查：定位問題根源

1. 查看 Nginx 運行用戶

通過進程命令確認(rèn) Nginx 實際運行用戶：

ps aux | grep nginx

結(jié)果顯示 Nginx master/worker 進程均由 work 用戶運行，而非默認(rèn)的 nginx

2. 查看臨時目錄權(quán)限

進入 Nginx 根目錄，查看臨時目錄權(quán)限：

cd /usr/local/nginx && ll

發(fā)現(xiàn)關(guān)鍵問題：

• client_body_temp 目錄所有者為 nobody，權(quán)限為 drwx------

• work 用戶無寫入權(quán)限，導(dǎo)致 Nginx 無法存儲上傳文件臨時數(shù)據(jù)

三、核心問題：Nginx 權(quán)限與目錄歸屬不匹配

1. 根本原因

Nginx 運行用戶為 work，但所有臨時目錄的所有者/權(quán)限未同步修改，導(dǎo)致：

• 上傳文件時，Nginx 無法在 client_body_temp 創(chuàng)建臨時文件

2. 為何部分文件能正常運行

很多同學(xué)會疑惑：為什么有的小文件能上傳成功，大文件卻報錯？這核心和 Nginx 的 client_body_buffer_size 配置相關(guān)，也是部分文件能正常運行的關(guān)鍵原因。

首先明確該配置的作用：client_body_buffer_size 用于設(shè)置 Nginx 接收客戶端請求體（即上傳文件、表單數(shù)據(jù)等）時，在內(nèi)存中開辟的緩沖區(qū)大小。

• 當(dāng)上傳文件小于等于該緩沖區(qū)大小時：Nginx 會直接將文件數(shù)據(jù)存放在內(nèi)存緩沖區(qū)中，無需寫入 client_body_temp 臨時目錄，因此即使該目錄權(quán)限異常，小文件上傳也能正常執(zhí)行。

• 當(dāng)上傳文件大于該緩沖區(qū)大小時：Nginx 會將超出內(nèi)存緩沖區(qū)的部分，臨時寫入 client_body_temp 目錄，此時若該目錄權(quán)限不足（所有者不匹配、無寫入權(quán)限），就會觸發(fā) Permission denied 錯誤，返回 500 狀態(tài)碼。

默認(rèn)情況下，client_body_buffer_size 配置值通常為 16k 或 32k（不同 Nginx 版本略有差異），這也是為什么小文件能正常上傳、大文件報錯的核心原因——小文件未觸發(fā)臨時目錄寫入，避開了權(quán)限問題。

補充建議：

若業(yè)務(wù)中存在大量大文件上傳，可適當(dāng)調(diào)大 client_body_buffer_size（如設(shè)置為 100m），減少臨時目錄寫入頻率，但仍需確保 client_body_temp 目錄權(quán)限正常，避免極端場景下的報錯。

示例配置如下：

client_body_buffer_size 100m;  # 按需調(diào)整，過大可能占用過多內(nèi)存

4. 補充：client_body_max_size 配置（控制上傳文件最大限制）

除了 client_body_buffer_size，還有一個關(guān)鍵配置 client_body_max_size，負(fù)責(zé)限制客戶端上傳文件的最大大小，這也是部分文件能上傳、部分文件失敗的另一個核心原因，容易與權(quán)限問題混淆。

先明確兩者區(qū)別，避免混淆：

• client_body_buffer_size：控制「內(nèi)存緩沖區(qū)大小」，決定文件是否需要寫入臨時目錄（和權(quán)限相關(guān)）；

• client_body_max_size：控制「上傳文件的最大允許大小」，超過這個值直接拒絕上傳，和權(quán)限無關(guān)。

注意要點

• 若僅調(diào)大 client_body_max_size，未修正 client_body_temp 權(quán)限，大文件（超過緩沖區(qū)大小）仍會報 500 權(quán)限錯誤；

• 若僅修正權(quán)限，未調(diào)大 client_body_max_size，超過限制的文件會報 413 錯誤，無法上傳；

• 兩者需配合配置，才能確保不同大小的文件都能正常上傳，同時避免權(quán)限和大小限制導(dǎo)致的報錯。

四、完整修復(fù)方案

1. 批量修正目錄權(quán)限

執(zhí)行以下命令，將 Nginx 所有臨時目錄及核心文件歸屬給運行用戶 work：

chown -R work:root /usr/local/nginx/
chmod -R 755 client_body_temp

2. 重啟 Nginx 生效

./sbin/nginx -s reload

3. 為什么部分文件可以上傳偶發(fā)失敗

./sbin/nginx -s reload

總結(jié)

以上為個人經(jīng)驗，希望能給大家一個參考，也希望大家多多支持腳本之家。

最新評論