Docker容器主机端口映射失败调试：指定端口为何被随机分配？

核心原因 #

你遇到的问题是因为仅配置了HostConfig.PortBindings，但未同步设置Config.ExposedPorts。Docker API要求端口映射必须同时满足两个条件：

• 在容器配置（Config）中声明要暴露的端口（ExposedPorts）
• 在主机配置（HostConfig）中绑定主机端口到容器端口（PortBindings）

如果只设置PortBindings，Docker会自动暴露容器端口，但会随机分配一个主机端口，这就导致你看到NetworkSettings里出现随机端口49158，而HostConfig里的配置看似正确。

另外，还要检查端口格式是否正确：Docker的端口标识必须包含协议（如40405/tcp），仅写端口号会导致配置不生效。

解决方法 #

1. 同时配置ExposedPorts和PortBindings #

在Go代码中需要同时设置这两个字段，且端口的协议部分要保持一致。以下是正确的代码示例：

import (
    "context"
    "github.com/docker/docker/api/types"
    "github.com/docker/docker/api/types/container"
    "github.com/docker/docker/api/types/network"
    "github.com/docker/go-connections/nat"
)

func main() {
    // 假设已初始化Docker client
    // client, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())

    ctx := context.Background()
    targetPort := "40405/tcp"

    // 容器基础配置：声明要暴露的端口
    containerConfig := &container.Config{
        Image: "your-target-image",
        ExposedPorts: nat.PortSet{
            nat.Port(targetPort): {},
        },
    }

    // 主机配置：绑定主机端口到容器端口
    hostConfig := &container.HostConfig{
        PortBindings: nat.PortMap{
            nat.Port(targetPort): []nat.PortBinding{
                {
                    HostIP:   "0.0.0.0", // 绑定到所有网卡，可指定特定IP
                    HostPort: "40405",   // 目标主机端口
                },
            },
        },
        NetworkMode: "my-network", // 指定自定义bridge网络
    }

    // 网络配置（非必需，但若需自定义网络参数可补充）
    networkConfig := &network.NetworkingConfig{}

    // 创建容器
    resp, err := client.ContainerCreate(ctx, containerConfig, hostConfig, networkConfig, nil, "")
    if err != nil {
        panic(err)
    }

    // 启动容器
    if err := client.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
        panic(err)
    }
}

2. 排查自定义网络配置 #

如果上述配置后仍有问题，检查my-network是否为内部网络（创建时使用了--internal参数）。内部网络会禁用容器与外部的端口映射，需要重新创建不带该参数的网络：

# 删除旧网络
docker network rm my-network
# 创建正常的自定义bridge网络
docker network create my-network

3. 验证配置是否生效 #

容器启动后，通过以下命令验证端口映射：

docker container inspect <container-id> | grep -A5 -B5 "40405"

如果配置正确，会看到NetworkSettings.Ports中显示40405/tcp: [{0.0.0.0:40405}]，而非随机端口。

内容的提问来源于stack exchange，提问作者BhanuKiran