Go net TCP排查双栈监听只开一族地址的处理方案

Go 服务明明写的是 net.Listen("tcp", ":8080")，实际却只有 IPv4 或 IPv6 能连通，通常不是 TCP 协议“随机失效”，而是监听器的地址族、操作系统双栈策略、容器映射或防火墙规则没有被分别确认。排查时先看 network 和 Listener.Addr()，需要稳定双栈时再显式创建两个监听器。

官方地址：https://pkg.go.dev/net

一、先确认 Go TCP 监听器绑定了什么

官方 net.Listen 支持 tcp、tcp4 和 tcp6。其中空主机地址表示监听系统可用的地址，但这只说明 Go 请求了监听，不代表内核一定把 IPv4 映射到 IPv6 套接字。先把真实监听地址打印出来，再分别从 IPv4 与 IPv6 客户端测试。

package main

import (
    "fmt"
    "log"
    "net"
)

func main() {
    // 使用 tcp 观察当前系统对未指定地址和双栈的默认处理。
    listener, err := net.Listen("tcp", ":8080")
    if err != nil {
        log.Fatal(err)
    }
    defer listener.Close() // 程序退出前释放监听端口。

    // Addr 只能说明监听器的本地地址，双栈仍需用两种地址族实连验证。
    fmt.Println("listening:", listener.Addr().Network(), listener.Addr().String())
}

如果代码写成 tcp4，IPv6 客户端失败是预期结果；写成 tcp6 后 IPv4 是否可用，则取决于系统是否允许 IPv4-mapped IPv6。不要把一次 connection refused 直接归咎于 Go 代码。

二、用 tcp、tcp4、tcp6 明确地址族边界

需要单族服务时，直接写出意图比依赖默认行为更稳。IPv4-only 使用 tcp4 配合 0.0.0.0:8080，IPv6-only 使用 tcp6 配合 [::]:8080。若部署环境要求双栈兼容，不要只凭 tcp 的默认语义做承诺。

同时检查地址写法：IPv6 端口必须使用方括号，例如 [::1]:8080。如果只在 127.0.0.1 测试，得到的只是回环地址结论，不能代表公网网卡、容器网卡或云安全组已经放行。

三、真正需要双栈时显式建立两条监听

要让行为跨操作系统、容器和基础设施更可控，可以分别监听 IPv4 与 IPv6，再把连接交给同一个处理函数。两个监听器必须共享同一端口；任何一个创建失败都要关闭已经创建的资源，避免留下半套服务。

package main

import (
    "fmt"
    "net"
)

func serve(listener net.Listener, label string) error {
    // 每条连接交给统一处理器，示例只展示地址族编排。
    for {
        conn, err := listener.Accept()
        if err != nil {
            return fmt.Errorf("%s accept: %w", label, err)
        }
        go func() {
            defer conn.Close() // 连接处理结束后及时释放文件描述符。
            // 这里接入实际协议处理，不把 IPv4/IPv6 分支复制两份。
        }()
    }
}

func main() {
    // 明确拆分两个地址族，避免依赖 IPv4-mapped IPv6 的系统开关。
    v4, err := net.Listen("tcp4", "0.0.0.0:8080")
    if err != nil {
        panic(err)
    }
    v6, err := net.Listen("tcp6", "[::]:8080")
    if err != nil {
        v4.Close() // 第二个监听失败时回收第一个监听器。
        panic(err)
    }
    go serve(v4, "ipv4")
    go serve(v6, "ipv6")
}

生产代码还要把两个 serve 的错误送到统一退出或重启策略，避免一族已经停止而另一族仍在接流。若平台明确支持可靠双栈，也可以保留 tcp 单监听，但应把该平台前提写进部署文档。

四、上线前按地址族完成检查

检查顺序建议固定下来：先确认进程监听地址，再从同机使用 127.0.0.1 与 [::1] 测试；然后检查容器是否同时发布 TCP 端口、主机防火墙是否放行 IPv6、云安全组是否存在 IPv6 规则。容器内监听 127.0.0.1 还会让宿主机无法访问，这与双栈不是同一个问题。

• 只有 IPv4 成功：检查是否误用了 tcp4、IPv6 端口映射或 IPv6 防火墙。
• 只有 IPv6 成功：检查是否依赖了映射地址，以及客户端是否真的发起 IPv4 连接。
• 两者本机成功、外部失败：优先查容器发布、路由、安全组和监听网卡范围。

相关问题

把地址写成 :8080 就一定是双栈吗？

不一定。它表示未指定主机地址，最终是否同时接受两族连接由 tcp 监听语义和操作系统策略共同决定。

为什么 tcp6 监听后有时还能收到 IPv4？

可能是 IPv4-mapped IPv6 行为。若应用必须区分两族，使用两个显式监听器并分别测试。

双监听创建时报端口已占用怎么办？

先确认是否已有旧的 tcp 或 tcp6 套接字占用端口，再决定关闭旧监听、调整绑定地址，或采用平台支持的复用策略。