当前位置：首页 > 文章列表 > Golang > Go问答 > Go IPv4 mapped IPv6 白名单未命中的地址归一化

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

来源：17golang原创 2026-10-28 06:59:59 0浏览收藏

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

要点速览

Is4() 对 IPv4-mapped IPv6 返回 false，不能只靠它判断。
Unmap() 只移除 IPv4-mapped 前缀，普通 IPv4 和真正 IPv6 都保持语义不变。
归一化必须发生在白名单的 Prefix.Contains 之前，并保留原始地址用于日志和审计。

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

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

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

Go netip.Addr 普通 IPv4、IPv4 mapped IPv6 与真正 IPv6 的静态关系说明图 — 图1：三种地址表示与白名单比较键的关系说明图，不是运行截图。

用 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
}