客户端连接localhost:12355失败（errno: 99）

Question

客户端连接 localhost:12355 失败，报错 errno: 99（Address not available），通常出现在尝试绑定或连接本地端口时。常见原因是目标端口被防火墙屏蔽、服务未监听 IPv4/IPv6 对应地址，或端口已被其他进程占用。尤其在 macOS 或 Linux 上，若服务仅绑定到 127.0.0.1 而客户端尝试通过 [::1] 连接，会导致地址不可达。需检查服务是否正常启动并监听 12355 端口（使用 netstat -an | grep 12355），确认 bind 地址配置正确，并排除网络策略限制。

Answer 1

客户端连接 localhost:12355 失败，报错 errno: 99（Address not available）深度解析

1. 问题现象与初步定位

当客户端尝试连接本地服务 localhost:12355 时，出现连接失败并返回系统错误码 errno: 99，对应错误信息为 "Address not available"。该错误通常出现在调用 connect() 或 bind() 系统调用期间。

在 Linux 和 macOS 系统中，此错误表明内核无法将请求的地址族（IPv4 或 IPv6）映射到可用的本地接口地址。

常见触发场景包括：

• 目标端口未被任何服务监听
• 服务仅绑定 IPv4 地址（如 127.0.0.1），而客户端使用 IPv6 回环地址 [::1] 尝试连接
• 防火墙或网络策略阻止了本地回环通信
• 端口已被其他进程占用导致服务启动失败
• 应用配置中 bind 地址设置不当，例如绑定了非本地地址

2. 分析流程：从表象到本质

为系统化排查此类问题，可遵循以下分析流程图：

        开始
          ↓
    客户端 connect(localhost:12355) → 失败 (errno=99)
          ↓
    检查服务是否运行？ → 否 → 启动服务或检查日志
          ↓ 是
    使用 netstat/lsof 查看 12355 是否监听？
          ↓ 否
    检查服务配置 bind 地址 & 端口声明
          ↓ 是
    监听地址是 127.0.0.1 还是 [::1] 或 0.0.0.0？
          ↓
    客户端连接方式匹配地址族？（IPv4 vs IPv6）
          ↓
    检查本地防火墙规则（pf, iptables）
          ↓
    验证 /etc/hosts 中 localhost 解析
          ↓
    结束
    

3. 常见技术原因详述

原因分类	具体表现	诊断命令	影响平台
服务未启动	端口无监听进程	lsof -i :12355	All
IPv4/IPv6 不匹配	服务绑 127.0.0.1，客户端连 [::1]	netstat -an | grep 12355	macOS/Linux
端口被占用	bind() 失败，服务无法启动	ss -tulnp | grep 12355	All
防火墙拦截	即使本地也受限	sudo pfctl -sr (macOS)	macOS/Linux
bind 地址配置错误	绑定到外部 IP 或不存在接口	查看服务日志	All
/etc/hosts 配置异常	localhost 解析失败	getent hosts localhost	Linux/macOS
双栈协议栈不一致	IPv6 启用但未正确支持	sysctl net.ipv6.conf.all.disable_ipv6	Linux
DNS 缓存污染	getaddrinfo 返回错误地址	dscacheutil -q host -a name localhost	macOS
容器环境网络隔离	localhost 指向宿主而非容器内部	docker exec -it <container> ss -lnp	Docker/K8s
SELinux/AppArmor 限制	权限拒绝绑定或连接	ausearch -m avc -ts recent	Linux (RHEL/CentOS)

4. 实际诊断命令与输出示例

以下是常用的诊断命令及其典型输出：

# 查看端口监听状态
$ netstat -an | grep 12355
tcp4       0      0  127.0.0.1.12355         *.*                     LISTEN

# 使用 lsof 查找占用进程
$ lsof -i :12355
COMMAND   PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
myserver 1234   dev    3u  IPv4 0x...       0t0  TCP 127.0.0.1:12355 (LISTEN)

# 测试连接性（区分 IPv4/IPv6）
$ telnet 127.0.0.1 12355    # 成功
$ telnet ::1 12355         # 可能失败，若服务未绑定 IPv6

5. 解决方案矩阵

针对不同成因，提供如下解决方案：

1. 确保服务已启动：通过 systemd、supervisor 或直接运行确认服务进程存在。
2. 统一地址族绑定：配置服务监听 0.0.0.0:12355 或同时绑定 127.0.0.1 和 [::1]。
3. 修改客户端连接逻辑：强制使用 IPv4 地址 127.0.0.1 而非域名 localhost。
4. 检查防火墙规则：macOS 上使用 pf，Linux 上使用 iptables/nftables 允许本地回环流量。
5. 验证 hosts 文件：/etc/hosts 应包含 127.0.0.1 localhost 和 ::1 localhost。
6. 启用双栈支持：若需 IPv6 支持，确保操作系统和应用层均启用并正确配置。
7. 避免端口冲突：使用动态端口或提前检测端口可用性。
8. 容器化部署注意：使用 --network=host 或正确映射端口至容器内服务。

6. Mermaid 流程图：完整排查路径

graph TD
    A[客户端 connect localhost:12355 失败] --> B{服务正在运行?}
    B -- 否 --> C[启动服务并检查日志]
    B -- 是 --> D[执行: netstat -an | grep 12355]
    D --> E{端口监听?}
    E -- 否 --> F[检查 bind 配置与端口占用]
    E -- 是 --> G[查看监听地址是 IPv4 还是 IPv6?]
    G --> H{客户端连接地址匹配?}
    H -- 否 --> I[修改客户端使用 127.0.0.1]
    H -- 是 --> J[检查防火墙/安全模块]
    J --> K[测试 getent hosts localhost]
    K --> L[最终验证连接]
    

7. 高级调试技巧

对于资深开发者，建议使用以下工具深入分析：

• strace/truss：跟踪系统调用，观察 connect() 调用参数及返回值。
• Wireshark/tcpdump：抓取 lo 接口流量，确认是否有 SYN 发出或 RST 返回。
• getaddrinfo() 调试：编写小型测试程序验证域名解析行为。
• LD_PRELOAD 拦截：用于模拟或记录网络调用过程。

示例 strace 输出片段：

connect(3, {sa_family=AF_INET6, sin6_port=htons(12355), inet_pton(AF_INET6, "::1", &sin6_addr)}, 28) = -1 EADDRNOTAVAIL (Cannot assign requested address)
    

此输出明确显示客户端尝试通过 IPv6 连接，但系统无法分配地址，说明服务未在 IPv6 上监听。