如何优化 proxy_pass 目标地址为本地 Unix Domain Socket 彻底消灭本地安全路径转发的网络栈耗时

使用 proxy_pass 指向本地 Unix Domain Socket（UDS）可消除网络栈开销，但需正确配置 URL 格式、权限路径、upstream keepalive 及后端适配，否则无法启用或性能归零。

直接用 proxy_pass 指向本地 Unix Domain Socket（UDS）是消除网络栈耗时最有效的方式——它绕过 TCP/IP 协议栈，数据在内核内存中直传，没有封包、解包、校验、路由等开销。但“写对”只是起点，“跑稳且高效”需要整套协同配置。

必须用对 proxy_pass 的 URL 格式

格式错误会导致启动失败或 502，不是性能问题而是根本不可用：

• ✅ 正确写法：proxy_pass http://unix:/run/myapp.sock;（注意 http://unix: 前缀 + 绝对路径）
• ❌ 错误写法：proxy_pass unix:/run/myapp.sock;（缺 http://，报 invalid URL prefix）
• ❌ 错误写法：proxy_pass /run/myapp.sock;（被当域名处理，连不上）
• 路径不能含变量、空格、~、相对路径；不能加端口或 http:// 后再拼 unix:

权限与路径要同时达标

Nginx worker 进程必须能“进目录、看文件、读写 socket”，三者缺一不可：

• socket 文件权限设为 srw-rw----（即 660），属主可读写，属组可读写
• Nginx 运行用户（如 www-data）必须属于 socket 所属组，或直接是属主
• 父目录（如 /run/）需有 x 权限（允许进入），/run/ 是推荐位置——tmpfs 内存文件系统，无磁盘 I/O、不被系统清理
• 启动前确保 socket 文件已存在，或由后端服务创建（Nginx 启动时会校验路径）

必须启用 upstream + keepalive 复用连接

不启用 keepalive，每次请求都新建销毁 UDS 连接，低开销优势几乎归零：

• 定义 upstream 块：upstream backend { server unix:/run/myapp.sock; keepalive 32; }
• location 中写：proxy_pass http://backend;（不是 unix:）
• 配套设置：proxy_http_version 1.1; 和 proxy_set_header Connection '';（清空客户端传来的 Connection: close）
• keepalive 32 表示每个 worker 进程最多缓存 32 个空闲连接；建议从 16 或 32 开始压测，过高易耗尽文件描述符

后端服务要配合监听与生命周期管理

UDS 性能释放依赖后端主动适配：

• 后端（如 Gunicorn、Uvicorn、Express）必须监听 UDS 路径，而非 127.0.0.1:8000
• 启动时显式设权限，例如 Gunicorn 加参数：--chmod-socket=660 --umask=007
• 确保后端先于 Nginx 启动；systemd 中可用 After=nginx.service 控制顺序
• 异常退出后 socket 文件可能残留，启动脚本中加清理逻辑：rm -f /run/myapp.sock
• Host 头默认丢失，务必补全：proxy_set_header Host $host;