Nginx长路径反向代理出问题90%因proxy_pass末尾斜杠与location匹配逻辑未对齐：location /api/匹配后，proxy_pass以/结尾则截断/api/，无/则报错；需校准路径截断、避免正则干扰、显式设Host头、调大proxy_read_timeout防504。
长路径（比如 /api/v2/users/123/settings/permissions）在 Nginx 反向代理中出问题，90% 是因为 proxy_pass 末尾斜杠和 location 匹配逻辑没对齐——不是配置写错了，是路径截断规则被忽略了。
location 匹配后，proxy_pass 末尾斜杠决定路径怎么转发
这是最常踩的坑。Nginx 不会“智能拼接”路径，它只按固定规则做字符串替换：
- 如果
location /api/和proxy_pass http://127.0.0.1:3000/都以/结尾 → 请求/api/v2/foo会被转发为http://127.0.0.1:3000/v2/foo（/api/被完全截掉） - 如果
location /api/但proxy_pass http://127.0.0.1:3000/backend/→ 请求/api/v2/foo会变成http://127.0.0.1:3000/backend/v2/foo - 如果
location /api/但proxy_pass http://127.0.0.1:3000（无结尾斜杠）→ Nginx 会报错：nginx: [emerg] invalid URL prefix in ...
验证方法：开一个本地 nc -l 8080 监听，用 curl -v http://localhost/api/test 看原始请求行是否符合预期。
匹配长嵌套路径时，别用正则 location 做默认兜底
像 location ~ ^/api/.* 这种写法看似灵活，但实际会干扰 Nginx 的最长前缀匹配优先级，尤其当有多个 location 共存时，容易导致本该走 /api/v1/ 的请求被错误捕获到 /api/ 的正则块里。
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
- 优先用前缀匹配：
location /api/v1/、location /api/v2/、location /healthz - 必须用正则时，加
^~前缀强制前缀优先：location ^~ /api/（此时即使后面有更长的正则，也先走这个） - 避免
location /放在最后做“万能 fallback”，它会吃掉所有未匹配路径，包括你忘了配的静态资源路径
proxy_set_header Host $host 不够，长路径服务常要显式设 Host
后端服务（比如 Express、FastAPI）依赖 Host 头生成绝对 URL（如重定向地址、Webhook 回调地址）。如果只写 proxy_set_header Host $host，而客户端用 IP 访问（如 http://192.168.1.100/api/...），$host 就是 IP，后端生成的链接就带 IP 而非域名，前端可能跨域或失效。
- 安全做法是硬编码真实域名：
proxy_set_header Host example.com; - 或者用
$host但配合server_name严格限定可接受的域名，防止 Host 头污染 - 别漏掉
proxy_set_header X-Forwarded-Proto $scheme;——否则后端判断 HTTPS 会失败，302 重定向可能跳回 HTTP
长路径下超时和缓冲区容易触发 502/504，得调 proxy_read_timeout
路径越长，往往意味着后端处理链路越深（比如多层鉴权、嵌套数据库查询）。默认 proxy_read_timeout 60 在复杂场景下不够用，Nginx 会在后端还没返回时主动断连，返回 504 Gateway Timeout。
- 先确认后端真实耗时：
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/api/v2/long-op - 把
proxy_read_timeout设为后端 P95 耗时的 1.5 倍，比如实测 12s，则配proxy_read_timeout 18; - 同时检查
proxy_buffer_size和proxy_buffers，大响应体（如导出 CSV）可能因缓冲区小被截断，出现502 Bad Gateway
真正麻烦的从来不是写几行配置，而是路径截断逻辑和超时阈值这种“看不见的契约”——它们不出错时一切正常，一出错就是 502/504，还很难复现。
