极客工场

Appearance

共 2,311 字预计阅读约 8 分钟

docker 容器名冲突与端口占用速查：name is already in use 处置 ​

更新时间：2026-10-24。FAQ 速查页，面向「明明就起一个容器，docker 偏说名字被占了」「端口明明没在听，docker 偏说已分配」的同学。docker 容器名冲突与端口占用的本质一句话：容器名与宿主端口都是全局唯一资源——名字在 daemon 的容器表里登记着（哪怕容器早已停止），端口在宿主机网络栈里占着（哪怕占它的是另一个进程），后来者一律被拒。病灶收敛在六根轴上：同名旧容器没删（含已停止的）、起容器的脚本被重复执行、compose down 没跑干净留了残、端口被宿主机其它进程占用、对 TIME_WAIT 的误解、IPv4 与 IPv6 双栈绑定打架。容器起来后自己崩掉的其它死因看 docker 容器段错误速查 与 docker 容器卡死速查。

本文要回答的问题 ​

  • docker ps 里明明没有这个名字，为什么还说 name is already in use？
  • 端口用 ss -tlnp 看没人监听，docker 为什么还是报 port is already allocated？
  • 只想「原地重来」，一条命令怎么干净地替换同名容器？
  • compose 项目换目录后旧容器删不掉，残留资源怎么清？
  • 怎么从流程上让这类冲突根本不发生？

一、报错原文与典型现象 ​

两类冲突各有一条标志性报错（路径以 /proj/demo 占位）：

bash
# 名字冲突：name 已被一个已停止的旧容器占着
$ docker run -d --name demo-app -p 8080:8080 myapp:1.0
docker: Error response from daemon: Conflict. The container name
"/demo-app" is already in use by container "9f3a1c2b7d04".
You have to remove (or rename) that container to be able to reuse that name.
bash
# 端口冲突：宿主 8080 已被占用（占用者可能是另一个容器，也可能是裸进程）
$ docker run -d --name demo-app2 -p 8080:8080 myapp:1.0
docker: Error response from daemon: driver failed programming external
connectivity on endpoint demo-app2: Bind for <宿主IP>:8080 failed:
port is already allocated.
bash
# 反直觉场景：ps 看不到，但名字确实被占 —— 因为默认只列运行中的容器
$ docker ps --filter name=demo-app
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES
$ docker ps -a --filter name=demo-app
CONTAINER ID   IMAGE    STATUS                     NAMES
9f3a1c2b7d04   myapp:1.0   Exited (0) 2 hours ago   demo-app

读现象抓三条判据：名字冲突的报错会直接把占坑容器的 ID 报给你（上例 9f3a1c2b7d04），不用猜；docker ps 默认只列运行中容器，ps -a 才看得到已停止的——「看不见但存在」是这类问题最大的迷惑点；端口报错里的 Bind for <宿主IP>:8080 说的是宿主机端口，占用者未必是容器，ss -tlnp 能直接揪出真凶（注意示例输出里的回环与内网地址在本文一律以 <容器IP> 占位）。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
name already in use 且 ps 看不到已停止同名容器残留docker ps -a 按名过滤docker rm 旧容器后起新
每次部署脚本都偶发冲突脚本无幂等、重复执行看脚本是否先 rm -frun 前加 docker rm -f 兜底
compose up 报名字冲突旧项目容器没 down 干净docker ps -a 找旧项目前缀compose -p 旧项目名 down
port already allocated 但 ss 无监听docker-proxy 或残留映射ss 与 ps 双查 8080停旧容器或杀 docker-proxy
端口被裸进程占用宿主机 Nginx/Java 等在听ss -tlnp 看进程名挪端口或停宿主进程
容器停了立刻重起还报占用旧容器释放有延迟稍等重试或强制 rm -frm -f 后立即重建
双栈环境绑定冲突IPv4/IPv6 重复绑同口ss -tlnp 看 :::8080只绑一族或显式拆两条映射
想原地替换不想删流程缺 replace 语义—run 前 rm -f 或 docker rename

三、排查决策图 ​

这张图是标准排查路线：红是冲突现象与命中的根因，蓝是排查动作，绿是验证通过，橙是修复，紫是防复发沉淀。

engineering/docker/ts-docker-duplicate-redefine.md D2 示意图

读这张图抓住第一刀：先把报错按「名字线」与「端口线」分开，两者看似同类（都是唯一资源撞车），查证工具完全不同——名字线用 docker ps -a，端口线用 ss -tlnp，端口线的占用者甚至可能跟 docker 无关。分线之后各自一步定位，比笼统地「删了重来」稳得多。

四、逐条排查展开 ​

已停止容器占名是最常见的根因。 容器停止（Exited）后不会自动消失，名字、配置、日志全留在 daemon 里，直到显式删除。所以「我昨天跑过一个 demo-app」就足够挡住今天的同名新容器。标准处置：

bash
docker rm demo-app            # 已停止的直接删
docker rm -f demo-app         # 还在运行的先 SIGKILL 再删
docker run -d --name demo-app -p 8080:8080 myapp:1.0   # 重建

如果工作流就是「同名原地替换」，把 docker rm -f demo-app || true 写进部署脚本 run 之前，一次到位。注意 rm -f 对运行中的容器是强杀，有状态容器先确认数据落盘。

端口占用要先分清占用者是谁。 ss -tlnp | grep 8080（Linux）输出里的进程名列直接给答案：是 docker-proxy 说明另一个容器的端口映射还挂着，docker ps 查谁映射了 8080；是裸进程（nginx、java、node）说明宿主机上有个非容器服务在听，要么停它、要么给容器换宿主端口。一个隐蔽场景：容器删了但 docker-proxy 进程残留仍占着端口——多见于 dockerd 异常重启后，kill 掉残留的 docker-proxy 即可，治本还是升级 docker 版本。

compose 残留是团队环境的高发区。 docker compose down 只清当前项目名（-p 或目录名推导）的资源；换了目录、改了项目名、或拷了别人的 compose 文件直接 up，旧项目的容器就成了「无主残留」，名字还占着。清理动作：先 docker ps -a 找到旧项目前缀的容器，docker compose -p <旧项目名> down 干净退场；彻底失控时 docker container prune 清掉所有停止容器（注意这会无差别清理，生产慎用）。

TIME_WAIT 不是端口占用的凶手，别冤枉它。 经常看到「端口处于 TIME_WAIT 所以 docker 绑不上」的说法——这是误解：docker-proxy 绑监听端口用的是 LISTEN 语义，与此前连接残留的 TIME_WAIT 不冲突（SO_REUSEADDR 会放行）。真报 port is already allocated 时，去查的是谁还在 LISTEN，而不是 TIME_WAIT 计数。把排查方向搞错，会白白等上几十秒「等它消散」。

双栈绑定在部分环境会打架。 docker 默认对 -p 8080:8080 同时尝试 IPv4 通配地址与 IPv6 的 :::8080 绑定；个别内核或网络配置下其中一族已被占用（比如宿主机进程只绑了 IPv6），就出现「ss 看 IPv4 空闲但 docker 仍报占用」的错觉。处置：-p 里显式写出宿主地址、只绑实际可用的那一族，或给宿主侧占用者挪窝。

自动化脚本的幂等性是源头治理。 CI 部署脚本、crontab 拉起脚本若无「先清后起」的幂等结构，重试一次就撞名。标准骨架只有两步：docker rm -f <name> 2>/dev/null || true 兜底清场，再 docker run -d --name <name> ...。compose 场景对应 docker compose up -d --force-recreate，让编排器自己做替换，不要手工 run 与 compose 混用同一个服务。

五、规范做法与预防 ​

  • 部署脚本幂等化：run 前固定 docker rm -f 兜底，脚本可反复执行无副作用。
  • 命名带项目与环境前缀：如 proj-demo-app-dev，避免跨项目撞名，也便于批量清理。
  • 端口分配建台账：团队共用宿主机的端口段登记在案，新服务先查表再选口。
  • 退场走 compose down：compose 项目禁止手工 rm 容器，一律 down 保证资源成组释放。
  • 定期清停止容器：docker container prune 进巡检节奏（限定环境），不让 Exited 尸体堆积。
  • 冲突报错进告警白名单：部署流水线遇到 already in use 直接失败并提示人工查残留，不静默重试放大问题。

这一篇在知识体系里的位置 ​

本篇是 docker 排错速查簇的资源唯一性篇，定位「容器还没出生就被拒」：镜像侧的名称/标签与版本语义问题看 docker 镜像版本不匹配速查；容器起来后的运行期死因看 docker 容器卡死速查 与 docker 容器 OOMKilled 速查；网络连接层的拒绝看 docker 连接被拒速查；同批的镜像内依赖问题看 docker 镜像缺运行依赖速查、架构问题看 docker 镜像架构不匹配速查。命名纪律、端口台账、脚本幂等，是容器化协作的低成本高收益项。

一句话总结 ​

docker 报 name is already in use 与 port is already allocated，本质都是全局唯一资源撞车：名字线用 docker ps -a 找已停止的旧容器，rm -f 后重建；端口线用 ss -tlnp 揪占用者——是容器就停旧映射，是裸进程就挪口或停它，残留的 docker-proxy 直接杀。别冤枉 TIME_WAIT（它与 LISTEN 绑定不冲突），双栈环境注意两族分别占用的情况。治本靠三件事：部署脚本 run 前 rm -f 幂等兜底、容器名带项目环境前缀、端口分配进团队台账——做到这三条，这类报错基本绝迹。