fix: surface install progress behind reverse proxies

README.md

@@ -254,6 +254,25 @@ Linux 默认路径：
 
 使用 `--no-service` 只用于开发验收：启动器会在当前用户下运行，但默认设置 `OA_UPDATE_ENABLED=false`。生产环境应使用 systemd/launchd，让在线更新可以在 Java 进程退出后自动拉起新版本。
 
+### HTTPS 反向代理
+
+正式服务监听 `8090`。Nginx、宝塔、Caddy 或 CDN 终止 HTTPS 后，必须把公网协议和主机转发给 Spring Boot；否则浏览器的同源 API 请求会被误判为跨域，并收到纯文本 `403 Invalid CORS request`，前端表现为“响应非 JSON (HTTP 403)”。Nginx 的代理位置至少包含：
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8090;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Port $server_port;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+如果 Nginx 前面还有 Cloudflare 等上游代理，`X-Forwarded-Proto` 必须保留浏览器实际使用的 `https`，不能被内层 HTTP 链路覆盖。前端与 `/api/oa/*` 推荐使用同一个公网域名；不要在 Nginx 中附加 `Access-Control-Allow-Origin *`。
+
 ## 在线更新与回滚
 
 管理员登录后进入：
@@ -417,6 +436,10 @@ Gitea 仓库尚未发布首个可安装版本，或 Release 缺少四个必需
 
 运行 `ngrok config check` 确认配置有效，并检查固定域名是否属于当前 ngrok 账号。可以通过 `ERP_RUN_NGROK_BIN`、`ERP_RUN_NGROK_CONFIG` 和 `ERP_RUN_NGROK_API_PORT` 覆盖路径与端口。
 
+### 反向代理后提示“响应非 JSON (HTTP 403)”
+
+应用自身的 401/403 权限错误始终是 JSON。该提示表示 Nginx、WAF 或 Spring CORS 层提前返回了纯文本/HTML。先确认代理目标为 `http://127.0.0.1:8090`，再按“HTTPS 反向代理”一节补齐 `Host` 和 `X-Forwarded-*` 请求头；响应正文为 `Invalid CORS request` 时即可确认是协议/主机转发不完整。
+
 ### 签名验证失败
 
 不要跳过验证。确认 Release 的四个资产来自同一次构建、`SHA256SUMS` 未被改写、签名私钥与 `distribution/release-public-key.pem` 匹配。