GitHub Runner中Node.js IPv6连接超时问题的分析与解决方案

问题背景

在GitHub Actions的Runner环境中，使用Node.js的fetch API进行多个HTTP请求时，经常会出现连接超时错误(UND_ERR_CONNECT_TIMEOUT)。这个问题主要与IPv6网络配置有关，表现为前1-2个请求可能成功，但后续请求会失败。

问题根源分析

经过深入调查，发现该问题由以下几个因素共同导致：

1. GitHub Runner的Ubuntu环境默认启用了IPv6支持
2. Node.js的网络栈会优先尝试IPv6连接
3. 某些网络环境或DNS服务器对IPv6支持不完善
4. 连接超时设置不够合理

当Node.js尝试通过IPv6建立连接时，如果DNS解析或网络路由存在问题，就会导致连接超时。由于现代网络库通常会进行重试和回退机制，所以前几次请求可能成功，但后续请求会因资源耗尽或状态不一致而失败。

解决方案

方案一：系统级IPv4优先配置

最彻底的解决方案是在Runner环境中强制系统优先使用IPv4协议。这可以通过以下步骤实现：

1. 修改系统配置，设置IPv4优先
2. 配置DNS解析使用可靠的IPv4服务
3. 确保网络库遵循系统设置

具体实现可以创建一个shell脚本，包含以下关键配置：

# 设置系统偏好为IPv4
sysctl -w net.ipv6.conf.all.disable_ipv6=1
sysctl -w net.ipv6.conf.default.disable_ipv6=1

# 配置DNS解析使用公共的IPv4服务
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 8.8.4.4" >> /etc/resolv.conf

方案二：Node.js应用层配置

如果无法修改系统配置，可以在Node.js应用层进行以下调整：

1. 强制fetch API使用IPv4：

const { fetch } = require('node-fetch');
const { Agent } = require('http');

const agent = new Agent({
  family: 4 // 强制使用IPv4
});

const response = await fetch(url, { agent });

2. 增加超时时间和重试机制：

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);

try {
  const response = await fetch(url, {
    signal: controller.signal,
    method: 'HEAD'
  });
  clearTimeout(timeout);
} catch (error) {
  // 处理超时和重试逻辑
}

最佳实践建议

1. 在GitHub Actions工作流中，建议使用专门的Action来配置网络环境
2. 对于关键网络请求，实现完善的错误处理和重试机制
3. 在CI/CD环境中，优先考虑稳定性和确定性，可以牺牲少量性能
4. 定期测试和验证网络配置的有效性

总结

GitHub Runner环境中的IPv6连接问题是一个典型的网络栈兼容性问题。通过理解底层网络协议的工作机制，并采取适当的配置措施，可以有效解决这类问题。无论是选择系统级的配置方案，还是应用层的适配方案，都需要根据具体场景和需求进行权衡。

对于大多数CI/CD场景，推荐采用系统级的IPv4优先配置，这样可以一劳永逸地解决所有潜在的网络连接问题，确保构建过程的稳定性和可靠性。