Docker port is already allocated：端口被容器占用的排查与修复

现象：容器起不来，说是端口分不出去

# docker run 时
docker: Error response from daemon: driver failed programming external
connectivity on endpoint ...: Bind for 0.0.0.0:8080 failed: port is already allocated.

# 或更底层的形态
Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

一行结论：你要映射到宿主机的那个端口，已经被别人占了。注意主语——不是容器内部端口（那层是 NAT，随便重复），是 -p 冒号左边的宿主机端口。

第一步：分清占坑的是容器还是宿主机进程

# 嫌疑一：别的容器映射了同一端口
docker ps --filter "publish=8080"

# 嫌疑二：宿主机上的普通进程（nginx、本地 dev server……）
sudo ss -tlnp | grep :8080

两条都跑，谁在监听一目了然。处理方式完全不同：

占坑的是容器：

docker ps -a --filter "publish=8080"    # 包括已停止的
docker rm -f <容器名或ID>               # 旧容器删掉，端口释放
docker stop <容器名>                    # 或者只是停掉也释放

占坑的是宿主机进程：要么停掉它（systemctl stop nginx），要么换端口重跑容器。

高频场景一：换了 compose 配置，旧容器还占着端口

compose 以项目名（默认 = 目录名）管理容器。常见的两种撞车：

1. 改了 docker-compose.yml 的端口想「再起一套」，但旧一套 docker compose up 的容器还在——先 docker compose down；
2. 两个不同目录恰好同名（比如都叫 app/），compose 项目名相同，互相抢容器、抢端口。用 -p 显式指定项目名隔离：

docker compose -p projectA up -d

高频场景二：容器删了，端口还被占（docker-proxy 残留）

少数情况下 docker ps 里没有占用者，ss 里监听的是 docker-proxy 进程——重启 Docker 服务可清掉残留：

sudo systemctl restart docker

这是最后手段，所有容器会一起重启，生产环境先评估影响。

一个反直觉细节：绑定地址不同，可以共存

docker run -p 127.0.0.1:8080:80 --name a ...   # 只绑回环
docker run -p 192.168.1.5:8080:80 --name b ... # 绑特定网卡

端口冲突的判定是**「地址+端口」组合**，不是单独的端口号。127.0.0.1:8080 和 0.0.0.0:8080 冲突（后者包含前者），但 127.0.0.1:8080 和 192.168.1.5:8080 可以共存。调试时这个细节能省一次「明明没人在用怎么还冲突」的纠结——冲突的那方往往就是 0.0.0.0 的隐形绑定。

和宿主机 EADDRINUSE 的关系

同一件事的两个视角：你的应用进程监听端口被占报 EADDRINUSE；你的容器映射端口被占报 port is already allocated。排查思路相通，详见：端口被占用怎么办？EADDRINUSE 排查。而「连不上某端口」的 ECONNREFUSED 是相反方向的问题，见：ECONNREFUSED 排查。

排查清单

1. docker ps --filter "publish=<端口>" — 有容器占着吗？
2. ss -tlnp | grep :<端口> — 宿主机进程占着吗？（两查都要做）
3. 旧容器：docker rm -f；compose 场景先 docker compose down
4. 都没人占却仍报错？systemctl restart docker 清 docker-proxy 残留
5. 复用端口注意绑定地址：127.0.0.1 与 0.0.0.0 冲突，与特定网卡 IP 不冲突

本文由 ToolVault 工具匣 提供。相关工具：Dockerfile 生成器、CIDR 子网计算、HTTP 状态码速查。相关阅读：端口被占用 EADDRINUSE 排查、ECONNREFUSED 排查。访问 首页 查看更多开发者工具。