nginx通过proxy_pass unix:/path/to.sock配合upstream keepalive可显著提升本地高并发性能，实测吞吐增15%+、p99延迟降30%，但需严格配置协议前缀、权限、连接复用及缓冲参数。
直接用 proxy_pass 指向 Unix Domain Socket（UDS）并启用 upstream keepalive，是本地高并发场景下最有效的性能组合——实测吞吐提升 15% 以上，P99 延迟下降约 30%，但配置稍有不慎就会触发 Permission denied 或连接复用失效。
proxy_pass unix:/path/to.sock 必须带 unix: 前缀且路径准确
UDS 路径不是普通文件路径，Nginx 要求显式声明协议类型。漏掉 unix: 或多写空格都会导致解析失败，错误日志里通常只报 invalid URL prefix，不提具体哪行错。
-
proxy_pass unix:/run/myapp.sock;✅ 正确，注意末尾分号和无空格 -
proxy_pass /run/myapp.sock;❌ 缺少unix:，Nginx 当作普通域名处理 -
proxy_pass unix: /run/myapp.sock;❌ 冒号后有空格，解析中断 - 路径必须绝对，不能用
~或环境变量；$document_root等变量在proxy_pass中不可用
upstream 块里加 keepalive 才能真正复用 UDS 连接
很多人只在 location 里设 proxy_http_version 1.1 和 proxy_set_header Connection ''，却忘了 upstream 层必须显式启用连接池——否则每次请求仍会新建/销毁 socket 文件描述符，UDS 的优势全白费。
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- upstream 必须定义名称，不能直接在
proxy_pass里写unix:/...：upstream uds_backend { server unix:/run/myapp.sock; keepalive 32; } -
keepalive 32表示每个 worker 最多缓存 32 个空闲 UDS 连接；值太小（如 4）会导致复用率低，太大（如 256）可能耗尽 socket 描述符限制 - 对应 location 中必须用该 upstream 名：
proxy_pass http://uds_backend;，不能写成proxy_pass unix:/... - 务必配
proxy_http_version 1.1和proxy_set_header Connection ''，否则后端可能主动断连
权限问题比 TCP 复杂得多，属主/组+文件权限缺一不可
UDS 是文件系统对象，Nginx worker 进程必须同时满足：对 socket 文件有读写权限、与后端服务同属一个 group（常见坑）、且 socket 文件不能被 umask 截断权限。
- 检查 socket 属主：
ls -l /run/myapp.sock应类似srw-rw---- 1 myapp www-data，其中www-data是 Nginx worker 默认用户组 - Nginx 配置中确认运行用户：
user www-data;（或对应组），不能是nobody或root - 后端启动时需显式设置 socket 权限，例如 Gunicorn 加
--umask 002，uWSGI 加chmod-socket = 660 - systemd 管理时，在
[Socket]段加SocketGroup=www-data和SocketMode=0660，避免启动顺序导致权限错乱
proxy_buffering off + tcp_nodelay on 适合低延迟 API 场景
UDS 本身延迟极低，但默认开启的 proxy buffering 和 Nagle 算法反而会引入毫秒级抖动，尤其对小包 JSON 接口明显。
-
proxy_buffering off;强制流式转发，避免 Nginx 缓存整个响应再发，但要求后端支持 chunked 或明确Content-Length -
tcp_nodelay on;禁用 Nagle，让小包立即发出；和proxy_buffering off搭配效果更稳 - 不要设
proxy_buffer_size过大（如 64k），UDS 不需要 TCP 那种大缓冲，4k～8k 足够 - 禁用
sendfile：它对 UDS 无效，且可能干扰流式响应
真正难的不是写对那几行配置，而是让 Nginx worker、UDS 文件、后端进程三者在权限、生命周期、连接复用策略上严丝合缝——任意一环松动，性能就掉回 TCP loopback 水平。
