From b11464a8a70d582c5934a94515bc3608c2b4c45a Mon Sep 17 00:00:00 2001
From: Huarch <huarch97@outlook.com>
Date: Fri, 21 Aug 2026 15:29:57 +0800
Subject: [PATCH] docs: document NPMplus upload permission fix

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index e9f6a65..c52603c 100644
--- a/README.md
+++ b/README.md
@@ -138,6 +138,36 @@ location / {
 
 应用会基于当前请求生成密码重置和注册链接。请确保用户访问的公网域名能够正确转发到该服务。
 
+### NPMplus 上传文件返回 500
+
+如果小请求可以正常转发，但上传稍大的文件时 Nginx 返回 HTML 格式的 500，先检查 NPMplus 的错误日志：
+
+```bash
+sudo docker exec npmplus sh -lc \
+  "grep -E 'client_body_temp.*Permission denied' /data/nginx/logs/error.log | tail"
+```
+
+Nginx 会在请求体超过内存缓冲区后将内容写入 `client_body_temp`。当 NPMplus 以非 root 的 `PUID`、`PGID` 运行，而 `/usr/local/nginx/*_temp` 目录被 root 拥有且权限为 `0700` 时，写入会因权限不足失败并返回 500。可按实际的 `PUID`、`PGID` 修复全部临时目录；下面以 `1000:1000` 为例：
+
+```bash
+sudo docker exec -u 0 npmplus sh -lc '
+  for name in client_body_temp proxy_temp fastcgi_temp scgi_temp uwsgi_temp; do
+    chown -R 1000:1000 "/usr/local/nginx/$name"
+    chmod 700 "/usr/local/nginx/$name"
+  done
+'
+sudo docker exec -u 1000:1000 npmplus nginx -t
+```
+
+不要在 NPMplus 的 Compose 服务中直接设置 `user: 1000:1000`，其启动脚本需要先以 root 初始化，再根据 `PUID`、`PGID` 降权运行。检查 Nginx 配置时也应指定相同的运行账号：
+
+```bash
+sudo docker exec -u 1000:1000 npmplus nginx -t
+sudo docker exec -u 1000:1000 npmplus nginx -T
+```
+
+以 root 身份执行 `nginx -t` 或 `nginx -T` 可能重新改变临时目录属主，使上传故障复发。此问题与 HTTPS、CrowdSec 拦截和 `client_max_body_size` 无关；如果响应为 413 或 403，应分别检查请求体大小限制和访问控制日志。
+
 ## 测试
 
 ```bash