Docker 端口映射怎么设置?新建、重建与访问不通排查
简答:容器显示运行中但浏览器打不开,先确认是否写了 <code>-p 宿主机端口:容器端口</code>,例如 <code>-p 8080:80</code>。新建容器直接配置映射;已有容器漏配时,先用 <code>docker inspect</code> 记录参数和挂载,再按原配置重建;已经有映射仍访问不到,则依次检查应用监听、映射结果、访问地址和防火墙。
定义:Docker 端口映射是把 Docker 主机上的端口转发到容器内应用监听端口的配置方式,常用格式为 <code>宿主机端口:容器端口</code>。
先判断你属于哪种情况
Docker 端口映射通常在创建容器时配置。Docker 官方说明,-p 或 --publish 会把主机端口转发到容器端口;如果没有发布端口,容器内正在监听的服务通常不能直接从 Docker 主机外部访问。查看 Docker 官方端口发布说明
| 你的情况 | 先做什么 | 对应位置 |
|---|---|---|
| 准备新建容器 | 使用 -p 或 Compose 的 ports | 看下方“docker run”和“Compose” |
| 已有容器没有宿主机端口 | 用 docker inspect 记录原参数,再重建 | 看“已有容器怎么修改” |
| 已经有映射但打不开 | 检查应用监听端口、映射、访问地址和防火墙 | 看“5层排查表” |
| 只想本机访问 | 绑定 127.0.0.1 | 看“安全绑定地址” |
| 不确定宿主机端口 | 使用 -p 容器端口,再查 docker ps | 看“随机宿主机端口” |
最快示例:docker run -d --name web-demo -p 8080:80 nginx。容器启动后,在运行 Docker 的这台机器上访问 http://localhost:8080。
docker run 怎么设置端口映射
最常见格式是:
docker run -d --name web-demo -p 8080:80 nginx
左侧的 8080 是 Docker 主机端口,右侧的 80 是容器内应用监听的端口。两边不需要相同,例如容器内应用监听 8000,也可以使用 -p 8080:8000。查看 Docker 官方 docker run 说明
| 需求 | 写法 | 访问或验证方式 |
|---|---|---|
| 固定宿主机端口 | -p 8080:80 | http://localhost:8080 |
| 仅本机访问 | -p 127.0.0.1:8080:80 | 只在 Docker 主机访问 |
| 指定 TCP | -p 8080:80/tcp | TCP 客户端访问 |
| 指定 UDP | -p 5353:5353/udp | UDP 客户端访问 |
| 随机宿主机端口 | -p 80 | 用 docker ps 查询实际端口 |
| 发布镜像声明的全部端口 | -P | 用 docker ps 查询随机端口 |
省略宿主机端口时,Docker 会为容器端口分配一个临时宿主机端口;使用 -P 时,Docker 会发布镜像通过 EXPOSE 或运行参数声明的端口。查看 Docker 官方发布端口示例
一个容器可以重复使用 -p 发布多个端口:
docker run -d --name app -p 8080:80 -p 127.0.0.1:9000:9000 -p 5353:5353/udp example/app
安全绑定地址:本机、局域网和远程服务器怎么选
如果不写宿主机 IP,例如 -p 8080:80,Docker 默认会把已发布端口绑定到主机的所有接口,即 IPv4 的 0.0.0.0 和可能存在的 IPv6 地址。这样不仅本机能访问,能够连接到这台主机的其他设备也可能访问该服务。查看 Docker 官方默认绑定说明
| 场景 | 推荐写法 | 注意事项 |
|---|---|---|
| 本机开发、管理后台 | -p 127.0.0.1:8080:80 | 只让 Docker 主机本机访问 |
| 局域网共享 | -p 192.0.2.10:8080:80 | 该 IP 必须确实属于 Docker 主机 |
| 远程服务器对外提供服务 | -p 8080:80 或绑定指定公网网卡 | 同时检查主机防火墙、云平台入站规则和应用认证 |
| 数据库或内部接口 | 优先绑定 127.0.0.1,或仅允许指定来源 | 不要因为容器能启动就默认允许公网访问 |
在 Linux 主机上,Docker 会为桥接网络创建防火墙规则;官方文档特别说明,发布端口后的流量可能在到达 ufw 的常规规则前就被 Docker 的 NAT 规则处理,因此不能只看 ufw 状态判断端口是否已被限制。查看 Docker 官方防火墙与端口发布说明
不要直接改 Docker 自动创建的规则。需要对发布端口增加来源限制时,应根据主机环境使用防火墙配置,Linux iptables 场景可以在 DOCKER-USER 链添加用户规则;官方文档提供了限制来源 IP 的示例。查看 Docker 官方 iptables 与 DOCKER-USER 说明
Compose 端口映射怎么写和应用
使用 Compose 时,在项目目录创建或修改 compose.yaml,把端口写在服务的 ports 下:
services:
app:
image: nginx
ports:
- "8080:80"
如果只允许本机访问,可以写成:
services:
app:
image: nginx
ports:
- "127.0.0.1:8080:80"
应用配置的基本步骤是:
- 进入包含
compose.yaml的目录。 - 执行
docker compose up -d。 - 执行
docker compose ps,查看服务状态和端口列。 - 在 Docker 主机上访问
http://localhost:8080。 - 如果修改了
ports,再次执行docker compose up -d,让 Compose 根据变更重新创建需要更新的容器。
Compose 的 ports 使用的仍是宿主机端口到容器端口的映射关系。需要注意,docker compose run 与常规服务启动不同:官方参考说明,docker compose run 默认不会创建服务配置中的端口,临时运行时要显式使用 --publish,或使用适合该命令的服务端口选项。查看 Docker 官方 compose run 说明
EXPOSE 也不能替代 Compose 的 ports。Dockerfile 中的 EXPOSE 80 主要用于声明应用预计使用的容器端口,并不会自动把它发布到宿主机;需要从主机访问时,仍要在运行参数或 Compose 中声明映射。查看 Dockerfile EXPOSE 官方参考
已有容器漏配端口,如何安全重建
端口发布通常属于创建容器时的配置。对已经创建的容器,不要把修改镜像、进入容器或重启容器误认为能够追加宿主机端口;更稳妥的做法是记录原配置后重建。
先查看当前状态:
docker ps
docker port old-app
docker inspect old-app
docker inspect 可以返回容器的低级配置信息,适合记录镜像、环境变量、挂载、网络和启动参数。查看 docker inspect 官方参考
- 记录原容器参数:保存
docker inspect old-app输出,并重点确认Config.Image、环境变量、挂载、网络、重启策略和启动命令。 - 确认数据位置:优先确认数据库、上传文件和配置是否位于命名卷或主机挂载目录。只在容器可写层中的文件,不能因为重建容器就默认保留。
- 需要导出文件时先复制:例如
docker cp old-app:/etc/app/config.yml ./config.yml。Docker 官方说明,docker cp可以在运行中或已停止的容器与本地文件系统之间复制文件。查看 docker cp 官方参考 - 停止旧容器:
docker stop old-app。如果新容器要沿用原名称,需要先处理名称冲突。 - 按原参数增加端口后创建:
docker run -d --name new-app -p 8080:80 -v app-data:/data example/app。实际命令中的镜像、卷、环境变量和网络应以原容器记录为准。 - 验证后再清理:确认服务、日志和数据正常后,再删除旧容器。不要在验证前执行不可逆的清理操作。
如果新容器启动失败,回滚思路是保留旧容器及其数据,先停止或删除失败的新容器,再启动旧容器;如果旧容器的宿主机端口仍被占用,应先停止占用该端口的对象,或临时使用其他宿主机端口进行验证。
端口映射成功但访问不到:5层排查表
不要只看容器状态是否为 Up。按下面顺序检查,能够把“应用没启动”“端口映射错误”“访问地址错误”和“主机侧拦截”区分开。
| 层级 | 检查命令或动作 | 正常结果 | 异常时怎么改 |
|---|---|---|---|
| 1. 容器状态 | docker ps -adocker logs 容器名 | 状态为 Up,日志没有启动失败 | 先处理应用崩溃、配置错误或容器反复退出 |
| 2. 应用监听 | 查看应用配置或进入容器检查监听端口 | 应用实际监听右侧容器端口,例如 80 | 把映射右侧改成真实监听端口,或修正应用启动参数 |
| 3. 映射结果 | docker psdocker port 容器名 | 看到类似 0.0.0.0:8080->80/tcp | 没有映射就按 -p 重建;端口写反则修正左右顺序 |
| 4. 主机访问 | 在 Docker 主机执行 curl http://127.0.0.1:8080 | 本机能收到 HTTP 响应或应用返回内容 | 检查宿主机端口占用、应用监听地址和 Docker 网络模式 |
| 5. 外部访问 | 从其他设备访问 Docker 主机地址和宿主机端口 | 使用 Docker 主机的可达 IP,例如 http://主机IP:8080 | 检查绑定 IP、主机防火墙、云平台入站规则和上游访问控制 |
本机测试时,localhost 指的是发起请求的那台机器。如果 Docker 运行在远程服务器上,远程服务器上的 localhost:8080 与你个人电脑上的 localhost:8080 不是同一个地址。Docker 官方端口发布说明也将主机端口定义为运行 Docker 的主机端口。查看 Docker 官方访问示例
如果使用 --network host,容器会使用主机网络栈,-p 和 -P 不再按照桥接网络的方式发布端口;此时应直接检查应用是否监听主机端口,而不是继续查找容器端口映射。查看 Docker 官方 host 网络说明
设置完成后的验收清单
- 配置:确认宿主机端口在左、容器端口在右,例如
8080:80。 - 监听:确认应用实际监听的是容器内端口,而不是只写在 Dockerfile 的
EXPOSE中。 - 状态:执行
docker ps -a,确认容器没有反复退出。 - 映射:执行
docker port 容器名,确认协议和端口方向正确。 - 本机访问:先在 Docker 主机执行
curl或打开浏览器,再测试其他设备。 - 范围:本机服务优先绑定
127.0.0.1;需要局域网或公网访问时,再单独配置防火墙和入站规则。 - 迁移:重建前保存
docker inspect输出,导出容器可写层中需要保留的文件,并确认卷和挂载目录。
一句话判断:看不到宿主机端口,先查创建参数;看得到端口但打不开,再查应用监听、访问地址和主机侧防火墙。
常见问题
Docker 端口映射左右两边分别是什么?
左边是 Docker 主机端口,右边是容器内应用监听端口。例如应用在容器内监听 80,而希望从本机 8080 访问,就写 <code>-p 8080:80</code>。
为什么写了 EXPOSE 还是访问不到?
<code>EXPOSE</code> 主要是镜像对容器端口的声明,不会自动创建宿主机端口映射。运行容器时仍需使用 <code>-p</code>、<code>-P</code> 或 Compose 的 <code>ports</code>。
Docker 端口映射可以给运行中的容器直接追加吗?
通常应记录原配置后重建容器,而不是把重启或进入容器当作追加宿主机端口的方法。使用 Compose 时,修改 <code>ports</code> 后重新执行 <code>docker compose up -d</code>。
为什么 docker ps 只显示 80/tcp?
这通常表示容器内部声明或使用了 80 端口,但没有显示宿主机到容器的发布关系。执行 <code>docker port 容器名</code> 进一步确认;没有输出映射时,需要按正确的 <code>-p</code> 参数重建。
端口映射后访问 localhost 还是容器 IP?
在 Docker 主机本机测试时,通常访问宿主机映射端口,例如 <code>http://localhost:8080/</code>。从其他设备访问时,应使用 Docker 主机的可达 IP 和宿主机端口,不要使用其他设备自己的 <code>localhost</code>。
如何让端口只在本机开放?
在映射字符串前加入 <code>127.0.0.1</code>,例如 <code>-p 127.0.0.1:8080:80</code>。这适合管理后台、调试接口和不需要局域网访问的开发服务。
Docker 端口映射提示端口已被占用怎么办?
先更换左侧宿主机端口,例如把 <code>8080:80</code> 改成 <code>8081:80</code>。通常只需要调整宿主机端口,容器内应用监听的右侧端口可以保持不变。
使用 host 网络后为什么 -p 不生效?
host 网络让容器使用主机网络栈,Docker 官方说明此模式下 <code>-p</code> 和 <code>-P</code> 不按桥接网络方式发布端口。此时应检查应用是否直接监听主机端口,或改用桥接网络配合显式映射。