Docker Swarm部署Portainer报Pool overlaps地址池冲突问题求助

报错Pool overlaps with other one on this address space本质是Docker Swarm为Portainer服务创建overlay网络时，待分配的子网段和集群内已存在的网络段（包括主机本地网络、其他服务的overlay网络、节点内网路由段）冲突，导致网络创建失败，服务启动被拒绝。

• 第一步：列出集群所有overlay网络及占用子网
  在管理节点执行命令获取所有overlay网络ID：
  docker network ls --filter driver=overlay
  对每个返回的网络ID执行如下命令，记录所有在用的overlay子网段：
  docker network inspect <网络ID> | grep Subnet
• 第二步：采集所有节点的本地网络段
  分别登录3个节点执行如下命令，记录物理网卡、Docker默认网桥、自定义网桥、静态路由的所有网段：
  ip addr && ip route
• 第三步：确认Portainer部署配置和Swarm全局地址池
  查看Portainer的docker-compose.yml配置，是否手动指定了固定子网；同时执行如下命令查看Swarm默认分配的地址池范围：
  docker info | grep -A 10 "Default Address Pools"
• 第四步：核对冲突网段
  对比前三步获取的所有网段，定位Portainer待分配的网段与已有网段的重叠部分。

根据排查到的冲突场景选择对应方案：

1. Portainer配置硬编码了冲突子网
   直接修改Portainer的docker-compose.yml中networks段的subnet配置，替换为未被占用的私有网段后重新部署即可。
2. Swarm全局默认地址池与已有网络冲突
   需重建Swarm集群并手动指定不冲突的全局地址池：

• 先删除所有运行中的Stack：docker stack rm <所有Stack名称>
• 所有工作节点执行命令离开集群：docker swarm leave
• 管理节点执行命令强制解散Swarm：docker swarm leave --force
• 管理节点重新初始化Swarm，指定未被占用的全局地址池（示例中用10.200.0.0/16作为全局大段，可根据实际情况替换）：

  docker swarm init --default-addr-pool 10.200.0.0/16 --default-addr-pool-mask-length 24 --advertise-addr <管理节点内网IP>
  

• 工作节点重新执行加入集群命令，再依次重新部署Traefik、Portainer等服务即可。

3. 临时应急方案（无需重建Swarm）
   在Portainer的docker-compose.yml中手动为Portainer网络指定未被占用的子网，示例配置如下：

networks:
  agent_network:
    driver: overlay
    ipam:
      config:
        - subnet: 10.200.20.0/24 # 替换为你确认未被占用的网段
services:
  portainer:
    networks:
      - agent_network
      # 需接入Traefik网络的话在此处追加，同时确认Traefik网络无冲突
  agent:
    networks:
      - agent_network

修改配置后重新部署Portainer Stack即可。

验证网段是否可用的小技巧：在所有节点执行ping <拟用网段的网关IP>（比如拟用10.200.20.0/24就ping 10.200.20.1），无返回则说明该网段无设备占用。

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