正确方式是 upstream 块中声明 server unix:/path/to/app.sock,proxy_pass 指向 http://upstream_name;需严格满足绝对路径、660权限且属组一致、启用 keepalive 16–64 并配 HTTP/1.1 长连接。

直接在 upstream 块中声明 server unix:/path/to/app.sock,再让 proxy_pass 指向该 upstream 名,是 Nginx 利用 Unix Socket 通信的标准方式。关键不在“能不能”,而在路径写法、权限控制、连接复用三者必须同时到位。
upstream 中正确声明 Unix Socket 服务
Unix Socket 必须以 unix: 开头,后接绝对路径,不能加 http:// 或省略协议前缀:
- ✅ 正确:
server unix:/run/myapp.sock; - ❌ 错误:
server /run/myapp.sock;(会被当域名解析) - ❌ 错误:
server http://unix:/run/myapp.sock;(Nginx 报 invalid URL prefix) - ❌ 错误:
server unix:./myapp.sock;(不支持相对路径)
必须搭配 keepalive 实现连接复用
若只写 server unix:/run/myapp.sock; 而不启用 keepalive,每次请求都会新建销毁 socket,UDS 的性能优势几乎消失:
- 在
upstream块内添加keepalive 32;(建议值 16–64) - location 中使用
proxy_pass http://backend;(注意是http://+ upstream 名,不是unix:) - 配套设置:
proxy_http_version 1.1;和proxy_set_header Connection '';
文件权限与运行环境需严格匹配
Nginx worker 进程要能真正打开并读写 socket 文件,需满足完整访问链:
- socket 文件权限应为
srw-rw----(即660),类型为 socket(s标志) - Nginx worker 用户(如
www-data)必须属于 socket 所属组,或直接是属主 - 父目录(如
/run/)对 Nginx 用户要有执行(x)权限,否则无法进入目录 - 推荐将 socket 放在
/run/(tmpfs 内存文件系统),避免磁盘 I/O 和自动清理干扰
后端服务需主动配合监听与生命周期管理
upstream 的 unix: 地址只是“指向”,真正通信依赖后端是否就绪:
- 后端(如 Gunicorn、Uvicorn、PHP-FPM)必须显式监听该 UDS 路径,而非
127.0.0.1:8000 - 启动时需设置 socket 权限,例如 Gunicorn 加参数:
--chmod-socket=660 --umask=007 - 建议在启动脚本中加入清理逻辑:
rm -f /run/myapp.sock,防止异常退出后残留 - 用 systemd 管理时,可设
After=nginx.service,确保后端先于 Nginx 启动


















