Nginx代理本地Unix Socket必须通过upstream定义+http://前缀转发，禁用直接unix:写法；需配齐HTTP/1.1升级头、keepalive连接池及socket文件权限（srw-rw----）、/run/路径和worker用户组一致。
Linux 下 Nginx 用 proxy_pass 代理本地 Unix Socket，核心是走 HTTP 模块 + upstream 定义，不能直接写 proxy_pass unix:/path.sock —— 这种写法不支持 WebSocket 升级、无法复用连接，且多数场景会失败。
必须用 upstream 声明 UDS 地址
在 http 块内定义 upstream，路径以 unix: 开头，后接绝对路径：
- ✅ 正确：
upstream backend { server unix:/run/myapp.sock; } - ❌ 错误：
server /run/myapp.sock（被当域名） - ❌ 错误：
server http://unix:/run/myapp.sock（Nginx 启动报 invalid URL prefix） - ❌ 错误：
server unix:./myapp.sock（不支持相对路径）
location 中 proxy_pass 必须指向 http://upstream_name
转发时协议前缀固定为 http://，不是 unix:：
- ✅ 正确：
proxy_pass http://backend; - ❌ 错误：
proxy_pass unix:/run/myapp.sock;（语法非法） - ❌ 错误：
proxy_pass http://unix:/run/myapp.sock;（协议冲突）
同时要配齐 HTTP/1.1 升级头，尤其 WebSocket 场景：
proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";
启用 keepalive 复用连接
UDS 默认每次请求新建 socket，高并发下易耗尽文件描述符。必须在 upstream 中启用连接池：
upstream backend { server unix:/run/myapp.sock; keepalive 32; }- 值建议 16–64；低于 16 复用率低，高于 128 需检查系统
fs.file-max和进程nofile限制
权限与路径位置不能忽略
Nginx worker 进程要能真正打开 socket 文件，需满足三者一致：
- socket 文件权限为
srw-rw----（即 660），类型为s（socket） - Nginx worker 用户（如
www-data或nginx）必须属于 socket 所属组，或为属主 - 父目录（如
/run/）对 Nginx 用户有执行（x）权限，否则进不去目录 - 推荐路径：
/run/myapp.sock（tmpfs 内存文件系统，无磁盘 I/O、自动清理友好）
后端启动时需主动设权，例如 Uvicorn 加参数：--chmod-socket=660 --umask=007，Gunicorn 类似。
