Go IPv4 mapped IPv6 白名单未命中的地址归一化

Go 的白名单判断出现“明明是同一个 IPv4，却匹配不上”时，常见原因不是字符串大小写，而是地址被表示成了 IPv4-mapped IPv6：普通地址是 192.0.2.10，另一种表示是 ::ffff:192.0.2.10。在 net/netip 中，后者仍被视为 IPv6，直接拿它和 IPv4 前缀比较会失败。处理办法是先用 Is4In6 识别，再调用 Unmap 生成统一比较键；真正的 IPv6 地址则保持原样。

先确认白名单为什么没有命中

把输入直接转成字符串再比较，会把同一地址拆成两个键；把输入直接交给 IPv4 前缀，也会遇到位宽不一致。官方文档说明，Addr.Is4In6 判断的是 ::ffff:0:0/96 范围，Addr.Is6 也包含这类 mapped 地址，而 Addr.Is4 对它返回 false。

因此排障时应同时记录原始文本、解析后的 Addr.String()、Is4() 和 Is4In6()。这样才能确认问题是地址表示差异，而不是白名单前缀写错。

用 Is4In6 和 Unmap 生成稳定比较键

归一化函数可以很小，但要把无效输入和原始值分开处理。ParseAddr 失败时不要拿零值继续参加白名单判断；解析成功后调用 Unmap，普通 IPv4 和普通 IPv6 都会原样返回。

package main

import (
    "fmt"
    "net/netip"
)

// normalizeAddr 将 IPv4-mapped IPv6 转为普通 IPv4，便于生成白名单键。
func normalizeAddr(raw string) (netip.Addr, error) {
    addr, err := netip.ParseAddr(raw)
    if err != nil {
        // 解析失败不能进入白名单判断，避免把零值误当成地址。
        return netip.Addr{}, fmt.Errorf("parse address %q: %w", raw, err)
    }
    if !addr.IsValid() {
        // ParseAddr 通常已保证有效，这里保留显式边界便于复用函数。
        return netip.Addr{}, fmt.Errorf("invalid address %q", raw)
    }
    return addr.Unmap(), nil
}

func main() {
    for _, raw := range []string{"192.0.2.10", "::ffff:192.0.2.10", "2001:db8::10"} {
        normalized, err := normalizeAddr(raw)
        if err != nil {
            fmt.Println(err)
            continue
        }
        // String 只用于展示；比较时直接使用 Addr 值。
        fmt.Printf("raw=%s normalized=%s is4=%t is4in6=%t\n",
            raw, normalized, normalized.Is4(), normalized.Is4In6())
    }
}

这里的关键是返回 netip.Addr 而不是返回字符串。Addr 是可比较的值类型，可以作为 map 键；字符串只适合日志或跨系统传输。若业务需要保留客户端原貌，可以把原始文本和归一化后的值放在同一条审计记录里。

在 Prefix.Contains 之前统一地址位宽

netip.Prefix.Contains 对 IPv4 与 IPv6 有明确边界：IPv4 地址不匹配 IPv6 前缀，IPv4-mapped IPv6 也不会匹配 IPv4 前缀。白名单初始化和请求判断都走同一个归一化函数，才能避免“配置端是 IPv4、请求端是 mapped IPv6”的不对称。

type AllowList struct {
    networks []netip.Prefix
}

// Contains 先归一化请求地址，再与同位宽前缀比较。
func (a AllowList) Contains(raw string) (bool, error) {
    addr, err := normalizeAddr(raw)
    if err != nil {
        return false, err
    }
    for _, network := range a.networks {
        // Prefix.Contains 只负责比较，不替调用方修正地址表示。
        if network.Contains(addr) {
            return true, nil
        }
    }
    return false, nil
}

如果白名单同时包含 IPv4 和 IPv6，不能把所有地址都“压成 IPv4”。只有 Is4In6 为真时才使用 Unmap；例如 2001:db8::10 仍应使用 IPv6 前缀进行判断。

日志、zone 和输入安全边界

归一化解决的是地址表示问题，不会替你解决路径协议、代理头信任或权限策略。建议日志至少保留 raw、解析结果、归一化结果和命中的前缀 ID；对外只返回统一的拒绝结果，避免把内部白名单结构泄露给请求方。

带 zone 的 IPv6 地址与普通 IPv6 仍有额外语义，不能为了方便比较而删除 zone。无效地址、零值地址和不在允许协议范围内的输入，应在归一化之后、白名单判断之前明确拒绝。这样既能修复 mapped IPv6 的漏匹配，也不会把“格式相似”误当成“来源可信”。

相关问题

为什么 Is4 对 ::ffff:192.0.2.10 返回 false？

因为它的内部表示仍是 IPv4-mapped IPv6。先用 Is4In6 识别，再调用 Unmap，结果才会成为普通 IPv4。

Unmap 会把所有 IPv6 地址变成 IPv4 吗？

不会。它只移除 IPv4-mapped IPv6 前缀；普通 IPv4 原样返回，真正的 IPv6 也原样返回。

能不能直接比较 Addr.String()？

不建议把字符串作为白名单主键。应比较归一化后的 netip.Addr 或调用 Prefix.Contains，字符串仅用于展示和日志。