sing-box IPv4/IPv6双栈支持：无缝切换的网络配置

在当今网络环境中，IPv4地址资源枯竭与IPv6普及加速的双重驱动下，网络工具对双栈（Dual-Stack）的支持已成为刚需。作为通用代理平台，sing-box通过模块化设计实现了对IPv4/IPv6的完整支持，本文将从配置实践、技术实现和场景优化三个维度，详解如何构建无缝切换的双栈网络环境。

核心功能与应用场景

sing-box的双栈支持覆盖从地址解析到流量路由的全链路处理，主要解决三类用户痛点：

• 运营商网络过渡：部分地区ISP已实现IPv6优先分配，但仍保留IPv4访问需求
• 跨境服务访问：某些服务仅提供特定协议接入（如IPv6-only CDN节点）
• 网络冗余设计：通过双栈配置实现故障自动切换，提升服务可用性

技术实现上，双栈支持主要依赖以下模块：

• IP地址处理：common/srs/ip_cidr.go 实现CIDR网段解析
• 地址集管理：common/srs/ip_set.go 提供高效IP范围查询
• 路由规则系统：route/router.go 支持协议类型条件匹配

快速配置指南

基础双栈启用

在主配置文件中通过network字段指定协议类型，默认配置将同时启用IPv4/IPv6：

{
  "inbounds": [
    {
      "type": "mixed",
      "listen": "::",  // 绑定双栈地址
      "network": "tcp,udp",  // 同时启用TCP/UDP
      "sniff": true
    }
  ]
}

配置文件规范详见官方文档：docs/configuration/inbound/

协议优先级控制

通过路由规则实现基于协议类型的流量分流，例如优先使用IPv6访问特定域名：

{
  "route": {
    "rules": [
      {
        "domain": ["example.com"],
        "network": "udp6,tcp6",  // 仅匹配IPv6流量
        "outbound": "ipv6-out"
      }
    ]
  }
}

技术实现解析

IP地址处理机制

sing-box使用netip.Addr作为统一地址容器，通过类型断言实现协议无关处理：

// 从字节切片创建IP地址（支持IPv4/IPv6自动识别）
func AddrFromIP(ip []byte) netip.Addr {
    if len(ip) == 4 {
        return netip.AddrFrom4([4]byte(ip))
    } else {
        return netip.AddrFrom16([16]byte(ip))
    }
}

高效地址集查询

common/srs/ip_set.go 实现了基于区间树的IP集合管理，支持百万级地址范围的快速匹配：

// 从序列化数据加载IP地址集
func readIPSet(reader varbin.Reader) (*netipx.IPSet, error) {
    version, err := reader.ReadByte()
    if err != nil {
        return nil, err
    }
    // ... 版本校验与数据解析逻辑
    for i, rangeData := range ranges {
        mySet.rr[i].from = M.AddrFromIP(rangeData.From)  // 双栈地址统一存储
        mySet.rr[i].to = M.AddrFromIP(rangeData.To)
    }
}

路由决策流程

路由系统通过network条件字段区分协议类型，核心逻辑位于route/rule_conds.go：

// 网络类型匹配器
func NewNetworkCondition(networks []string) (Condition, error) {
    var ipv4, ipv6 bool
    for _, network := range networks {
        switch network {
        case "tcp4", "udp4":
            ipv4 = true
        case "tcp6", "udp6":
            ipv6 = true
        // ... 其他网络类型处理
        }
    }
    // 返回基于IP版本的匹配函数
}

高级优化策略

DNS双栈分流配置

通过DNS模块实现协议隔离解析，配置示例：

{
  "dns": {
    "servers": [
      {
        "tag": "ipv4-dns",
        "address": "8.8.8.8",
        "detour": "direct"
      },
      {
        "tag": "ipv6-dns",
        "address": "2001:4860:4860::8888",
        "detour": "direct"
      }
    ],
    "rules": [
      {
        "domain_suffix": ["ipv6-only.com"],
        "server": "ipv6-dns"
      }
    ]
  }
}

完整DNS配置文档：docs/configuration/dns/

故障转移机制

利用group outbound实现双栈自动切换，当主协议不可用时自动切换至备用协议：

{
  "outbounds": [
    {
      "type": "group",
      "tag": "dual-stack-out",
      "outbounds": ["ipv4-out", "ipv6-out"],
      "strategy": "fallback",  // 故障转移策略
      "fallback_delay": "3s"
    }
  ]
}

组策略详细说明见：docs/configuration/outbound/group.md

常见问题与解决方案

地址冲突排查

当出现address already in use错误时，需检查是否存在IPv4/IPv6端口占用冲突：

# 检查IPv4监听
sudo lsof -i4 -P -n | grep sing-box
# 检查IPv6监听
sudo lsof -i6 -P -n | grep sing-box

协议优先级调整

修改系统内核参数优化IPv6优先级（Linux系统）：

# 临时调整
sysctl -w net.ipv6.conf.all.use_tempaddr=2
# 永久生效
echo "net.ipv6.conf.all.use_tempaddr=2" >> /etc/sysctl.d/60-sing-box.conf

流量监控与分析

通过sing-box的内置日志系统跟踪双栈流量：

{
  "log": {
    "level": "debug",
    "output": "sing-box.log",
    "timestamp": true,
    "include": ["dns", "router"]  // 启用DNS和路由日志
  }
}

日志配置参考：docs/configuration/log/

总结与展望

sing-box的双栈实现通过协议无关的抽象设计，为复杂网络环境提供了灵活解决方案。随着IPv6全面部署加速，后续版本将进一步优化：

• 基于网络质量的动态协议选择
• IPv6扩展头支持增强
• 双栈流量统计与可视化

完整配置示例可参考官方仓库：release/config/，建议结合自身网络环境进行压力测试后再投入生产使用。