3. Development 环境网络故障排查：容器网络模型与 DNS 解析

在 Development 环境中，服务间调用超时是最常见的“假性故障”之一。绝大多数情况下，代码逻辑并未出错，而是容器网络模型配置不当、端口映射遗漏或 DNS 解析失败导致请求无法到达目标实例。本章聚焦这三类根因，结合 Docker 网络模型与 Go 中间件调用链路，提供可复现的排查路径。

3.1 容器网络模型：Bridge 与 Host 模式对比

Docker 默认使用 Bridge 网络模式，每个容器拥有独立网络命名空间，通过虚拟网桥（docker0）通信。Host 模式则共享宿主机网络栈，容器直接使用宿主机 IP 和端口。两种模式在 Development 环境中的适用场景与风险差异显著。

3.2 端口映射错误：从“无法访问”到“连接超时”

端口映射错误是 Development 环境中最频繁的故障模式。典型表现为：容器内服务正常启动，但宿主机或其他容器无法通过映射端口访问。排查时需区分以下三种场景：

1. 映射遗漏：docker run 或 docker-compose.yml 中未配置 ports 字段，容器端口仅对同网络容器可见。
2. 映射冲突：宿主机端口已被其他进程占用，Docker 静默失败（不报错，但映射无效）。
3. 绑定地址错误：Go 服务监听 127.0.0.1:8080 而非 0.0.0.0:8080，导致宿主机端口映射无法转发。

3.3 DNS 解析失败：服务间调用超时的隐形杀手

在 Docker Compose 管理的 Development 环境中，服务间通过 service name 进行 DNS 解析。当 DNS 解析失败时，Go 客户端（如 net/http、grpc）会等待默认超时（通常 30s）后返回错误，表现为“间歇性超时”。

3.4 Go 客户端超时配置与重试策略

在 Development 环境中，Go 服务应配置合理的超时与重试机制，避免因网络抖动导致调用链雪崩。以下是一个针对容器环境的 HTTP 客户端配置示例：

// 适用于 Development 环境的 HTTP 客户端
client := &http.Client{
    Timeout: 5 * time.Second, // 总超时，避免长时间等待 DNS 解析
    Transport: &http.Transport{
        DialContext: (&net.Dialer{
            Timeout:   2 * time.Second, // TCP 连接超时
            KeepAlive: 30 * time.Second,
        }).DialContext,
        MaxIdleConns:        10,
        IdleConnTimeout:     90 * time.Second,
        TLSHandshakeTimeout: 3 * time.Second,
        // 强制使用 IPv4，避免 DNS 返回 IPv6 地址导致连接失败
        DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
            return (&net.Dialer{
                Timeout:   2 * time.Second,
                DualStack: false, // 禁用双栈，优先 IPv4
            }).DialContext(ctx, "tcp4", addr)
        },
    },
}

// 带指数退避的重试调用
func callWithRetry(ctx context.Context, url string, maxRetries int) (*http.Response, error) {
    for i := 0; i < maxRetries; i++ {
        resp, err := client.Get(url)
        if err == nil {
            return resp, nil
        }
        // 仅对 DNS 解析错误和连接超时进行重试
        if netErr, ok := err.(net.Error); ok && (netErr.Timeout() || netErr.Temporary()) {
            wait := time.Duration(math.Pow(2, float64(i))) * 100 * time.Millisecond
            select {
            case <-ctx.Done():
                return nil, ctx.Err()
            case <-time.After(wait):
            }
            continue
        }
        return nil, err
    }
    return nil, fmt.Errorf("max retries exceeded")
}

3.5 综合排查清单

当 Development 环境出现服务间调用超时时，按以下清单逐项排查，可覆盖 90% 以上的容器网络故障：