curl `--unix-socket` 选项深度解析：通过 Unix 域套接字绕过网络发起 HTTP 连接

curl--unix-socket选项深度解析：通过 Unix 域套接字绕过网络发起 HTTP 连接

【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl

本篇围绕 curl 命令行选项--unix-socket（文档位于 docs/cmdline-opts/unix-socket.md）展开，讲解它如何让 curl 完全绕过 TCP/IP 网络、直接经本地 Unix 域套接字（AF_UNIX）访问 HTTP 服务端或本地代理，并深入其 CLI 解析、连接建立、DNS 过滤与地址构造的完整源码链路。读完后你能掌握该选项的适用场景、与--abstract-unix-socket的区别、对应的 libcurl API（CURLOPT_UNIX_SOCKET_PATH/CURLOPT_ABSTRACT_UNIX_SOCKET），以及从源码角度判断连接是否真正走了 Unix 套接字的验证方法。

1. 选项元数据与官方定义

--unix-socket的官方定义非常精炼（docs/cmdline-opts/unix-socket.md）：

Connect to the server through this Unix domain socket, instead of using the network. To connect to a proxy over Unix domain socket, see--proxy.

其文档 frontmatter 中登记的完整元数据如下：

官方给出的标准用法示例：

curl --unix-socket socket-path $URL

也就是说，URL 中的主机名仍然决定 HTTP 语义层的行为（Host 头、SNI、证书校验等），而实际的首跳连接会被重定向到指定的本地套接字文件。原文档最后一句“connect to a proxy over Unix domain socket, see --proxy”点出了该选项最典型的场景：让一个监听 Unix 域套接字的本地 HTTP 代理（如 nginx、HAProxy 等）作为首跳，再经它转往远端服务器。

典型应用场景

• 本地反向代理/网关：在容器或本机部署只监听 Unix 套接字的 HTTP 代理，应用用--unix-socket /var/run/proxy.sock http://target.example/访问，代理负责加签、审计或转发，而目标主机仍可写成真实域名。
• 绕过网络栈访问本地服务：当服务端（或其前置代理）以 UDS 方式暴露时，curl 可以直接“插入”到该本地通道，不占用任何 IP 端口。
• 进程间安全通信：UDS 文件受文件系统权限控制，比127.0.0.1端口更不易被同机其他用户访问。

2. 与--abstract-unix-socket的区别

姊妹选项--abstract-unix-socket（7.53.0 加入，文档见 docs/cmdline-opts/abstract-unix-socket.md）连接的是 Linux 特有的抽象命名空间套接字——它不落地为文件系统路径，而是以一个以 NUL 字节开头的名字注册。官方文档特别强调了一个易错点：netstat会把抽象套接字路径显示为带@前缀的形式，但--abstract-unix-socket的参数不能带这个前导@。

两个选项在 curl 内部共享同一条存储字段（见第 4 节的config->unix_socket_path），只是用一个布尔标志abstract_unix_socket区分两种模式，因此同一次传输中二者互斥，后指定的覆盖先指定的。

3. 对应的 libcurl API

在 include/curl/curl.h 中，该能力对应两个字符串型选项：

/* Path to Unix domain socket */ CURLOPT(CURLOPT_UNIX_SOCKET_PATH, CURLOPTTYPE_STRINGPOINT, 231), // L1973 ... /* Path to an abstract Unix domain socket */ CURLOPT(CURLOPT_ABSTRACT_UNIX_SOCKET, CURLOPTTYPE_STRINGPOINT, 264), // L2090

两者类型均为CURLOPTTYPE_STRINGPOINT（L1973 / L2090）。命令行工具最终就是把--unix-socket <path>映射为这两个 API 之一：命令行入口在 src/config2setopts.c 中根据config->abstract_unix_socket标志二选一：

if(config->unix_socket_path) { if(config->abstract_unix_socket) MY_SETOPT_STR(curl, CURLOPT_ABSTRACT_UNIX_SOCKET, config->unix_socket_path); else MY_SETOPT_STR(curl, CURLOPT_UNIX_SOCKET_PATH, config->unix_socket_path); }

因此在基于 libcurl 的自研程序中，要获得与--unix-socket完全等价的行为，只需设置CURLOPT_UNIX_SOCKET_PATH即可。

4. 源码解析：从命令行参数到 AF_UNIX 连接

4.1 CLI 参数解析

选项在 src/tool_getparam.c 中注册为ARG_FILE类型（第 363 行{"unix-socket", ARG_FILE, ' ', C_UNIX_SOCKET}），实际取值发生在第 2364–2368 行：

case C_UNIX_SOCKET: /* --unix-socket */ config->abstract_unix_socket = FALSE; err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break;

两个细节值得注意：

1. 处理--unix-socket时会显式把abstract_unix_socket复位为FALSE（--abstract-unix-socket的分支则置为TRUE），印证了“单值、后者覆盖前者”的Multi: single语义；
2. 参数以DENY_BLANK约束读取，即路径中不允许出现空白字符，配置文件中书写时不要依赖引号外的空格。

存储字段定义在 src/tool_cfgable.h：char *unix_socket_path; /* path to Unix domain socket */（L153）与位标志BIT(abstract_unix_socket)（L302）。

4.2 连接建立阶段：UDS 优先于代理与 via_peer

库侧的核心逻辑在 lib/url.c 的连接初始化中（L2033–L2044）：

#ifdef USE_UNIX_SOCKETS /************************************************************* * Set UDS first. It overrides "via_peer" and proxy settings. *************************************************************/ if(network_scheme && CURL_EASY_STR(data, STRING_UNIX_SOCKET_PATH)) { result = Curl_peer_uds_create( needle->origin->scheme, CURL_EASY_STR(data, STRING_UNIX_SOCKET_PATH), (bool)data->set.abstract_unix_socket, &needle->via_peer); ... } #endif

源码注释明确写着 “It overrides 'via_peer' and proxy settings”，即一旦设置了 Unix 套接字路径，它覆盖--connect-to产生的 via_peer 以及代理设置（就首跳而言）。紧接着（L2066–L2074）：

/* Going via a unix socket ignores any proxy settings */ if(network_scheme && (!needle->via_peer || !needle->via_peer->unix_socket)) { result = Curl_proxy_init_conn(data, needle); ... }

只要首跳对端是 UDS peer，Curl_proxy_init_conn就整体被跳过。同时（L2102–L2105）当首跳对端被识别为 Unix 套接字时，传输类型被标记为TRNSPRT_UNIX：

if(Curl_conn_get_first_peer(needle, FIRSTSOCKET)->unix_socket) needle->transport_wanted = TRNSPRT_UNIX;

这里的语义恰好对应官方文档中“see --proxy”的提示：UDS 只替换首跳（FIRSTSOCKET）的连接方式，via_peer与origin分离的设计使得 TLS 握手、SNI 与证书校验仍然针对 URL 中的原始主机名进行——这正是“把本地代理当首跳、目标域名照旧”得以成立的底层机制。

4.3 对端对象的创建与比较

Curl_peer_uds_create 负责把路径包装成一个“对端”（peer）：

pp.scheme = scheme; pp.host_user.str = pp.host.str = path; /* 路径直接充当 hostname */ pp.host_user.len = pp.host.len = pathlen; pp.unix_socket = TRUE; pp.abstract_uds = abstract_unix_socket;

路径被直接当作 hostname 使用，peer 上打上unix_socket位（lib/peer.h L40 注释：“hostname is a UDS path without the prefix”）。一个容易忽略的实现细节在 lib/peer.c 的对端比较函数中：

/* UNIX domain socket paths must be compared case-sensitive, * as many filesystem are like that. */ return (p1->unix_socket == p2->unix_socket) && ... (p1->unix_socket ? !strcmp(p1->hostname, p2->hostname) : curl_strequal(p1->hostname, p2->hostname));

普通主机名比较大小写不敏感，而 UDS 路径必须大小写敏感逐字节比较——否则连接缓存与对端判等都会出错。这也意味着/var/run/A.sock与/var/run/a.sock在 curl 看来是两个不同端点。

4.4 “解析”阶段的短路：不产生真实 DNS 查询

Unix 套接字没有域名可言，DNS 过滤层对此做了显式短路。lib/vdns/cf-dns.c 中：

• 详细日志（L141–L147）对 UDS 对端直接输出resolved unix://%s，跳过 IPv4/IPv6 地址报告；
• cf_dns_start（L194–L199）把查询类型统一记为CURL_DNSQ_A（“treat it like an A resolve”），trace 日志中该端点被标识为unix-domain-socket而非host。

也就是说，--unix-socket传输不会触发任何 A/AAAA 查询（c-ares 后端在 lib/vdns/hostip.c 中同样对peer->unix_socket做了特判）。

4.5 地址构造：Curl_unix2addr 与路径长度上限

真正把路径变成内核可connect()的地址，发生在 lib/curl_addrinfo.c 的Curl_unix2addr：

/* sun_path must be able to store the null-terminated path */ path_len = strlen(path) + 1; if(path_len > sizeof(sa_un->sun_path)) return CURLE_TOO_LARGE; ... sa_un->sun_family = AF_UNIX; ai->ai_family = AF_UNIX; ai->ai_socktype = SOCK_STREAM; /* assume reliable transport for HTTP */ ai->ai_addrlen = (curl_socklen_t) ((offsetof(struct sockaddr_un, sun_path) + path_len) & 0x7FFFFFFF); /* Abstract Unix domain socket have NULL prefix instead of suffix */ if(abstract) memcpy(sa_un->sun_path + 1, path, path_len - 1); else memcpy(sa_un->sun_path, path, path_len); /* copy NUL byte */

三个关键点：

1. 长度上限：路径（含末尾 NUL）必须放得进struct sockaddr_un::sun_path，超出即返回CURLE_TOO_LARGE。在大多数 Linux 平台上这约合 107 字节上限，超长路径会直接失败，而不是静默截断；
2. 连接类型：固定SOCK_STREAM，源码注释写明“assume reliable transport for HTTP”，与 HTTP 协议的字节流语义匹配；
3. 抽象套接字的 NUL 前缀：抽象模式下sun_path[0]被写为 NUL，真正的名字从sun_path + 1开始填充——这正是内核区分抽象命名空间的路径型/名字型套接字的机制，也解释了为何用户参数里不能手写@前缀（@只是 netstat 的显示约定）。

套接字创建阶段，lib/cf-socket.c 对AF_UNIX地址族有专门的分支；而 Happy Eyeballs 多地址并行连接逻辑（lib/cf-ip-happy.c L707、L749）对 UDS 只做单端点处理（cf_ai_iter_init(..., AF_UNIX)），因为抽象/路径型 UDS 本就不存在“多 IP 竞速”的问题。

5. 能力检测：如何确认你的 curl 支持该功能

Unix 套接字支持是编译期特性（USE_UNIX_SOCKETS）。命令行侧可以通过版本特性字段确认：src/tool_libinfo.c 将CURL_VERSION_UNIX_SOCKETS映射为UnixSockets特性名，即curl -V输出的 Feature 列表中若含UnixSockets，则--unix-socket/--abstract-unix-socket可用；libcurl 程序则可用curl_version_info检查features & CURL_VERSION_UNIX_SOCKETS位。

6. 使用限制与自检清单

综合文档与源码，可归纳出该选项的适用边界：

• 仅 HTTP 协议：frontmatter 的Protocols: HTTP与url.c中network_scheme前置判断一致，非 HTTP 方案不适用；
• 参数是文件系统路径（路径型）或抽象名（abstract 型），且路径中不能含空白（CLI 解析的DENY_BLANK约束）；
• 路径长度受sun_path限制，超限返回CURLE_TOO_LARGE；
• 覆盖代理与 connect-to 首跳：设置了 UDS 后，代理设置对首跳失效，这是特性而非缺陷；
• 抽象命名空间仅限 Linux，且参数不带@；
• 路径比较大小写敏感，写错大小写会连到“另一个”端点；
• 需 curl 编译时启用 Unix 套接字支持（curl -V显示UnixSockets）。

一个最小可运行的验证流程（只涉及本地查看与运行，不改动仓库内容）：

# 1. 确认特性 curl -V | grep -i unix # 2. 假设本地代理监听 /tmp/proxy.sock，经它访问目标 curl -v --unix-socket /tmp/proxy.sock http://target.example/api/ping # 3. 在 -v 输出中确认连接走的是套接字而非 TCP # 成功时应看到连接建立成功且无 TCP 地址出现

-v模式下若一切正常，将看到经 Unix 套接字建立的连接与随后针对 URL 主机名的正常 HTTP 请求过程；结合 docs/cmdline-opts/abstract-unix-socket.md 中关于@前缀的提示，即可覆盖两类 UDS 端点的全部使用要点。

7. 小结

--unix-socket用一个路径参数把 curl 的首跳连接从“网络上的主机:端口”整体替换为“本机 AF_UNIX 端点”：CLI 层（src/tool_getparam.c → src/config2setopts.c）把它落成CURLOPT_UNIX_SOCKET_PATH，库内部则由 lib/url.c 的 UDS 优先逻辑接管连接建立、lib/peer.c 以路径代主机名并大小写敏感地比较对端、lib/vdns/cf-dns.c 短路真实 DNS、lib/curl_addrinfo.c 构造sockaddr_un并执行sun_path长度校验。理解这条链路后，无论是调试本地 Unix 套接字代理，还是在 libcurl 应用中复刻同等行为，都能做到有据可依、可复制可验证。

【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl