如果你在用 Docker Compose 启动项目时被这条报错卡住那你大概率已经试过重新创建容器、重启 Docker 甚至重装环境结果发现全都无效。这个错误的完整描述是network xxx declared as external, but could not be found我第一次遇到时也是懵的——既然我已经在 compose 文件里把网络声明成 external 了Docker 为什么反而说找不到这个报错在部署微服务、搭建监控系统比如 Prometheus Grafana、或者需要多个 compose 项目共享同一个网络时非常常见。尤其是新服务器、新环境、或者刚跑完docker system prune之后报错概率直线上升。适合所有用 Docker Compose 做部署的运维、后端开发和全栈工程师阅读读完你不仅能解决当前问题还能彻底搞懂 external 网络的机制以后再遇到相关的跨项目通信问题也不会慌。1. external 网络到底是什么Compose 为什么要设计这个选项1.1 先看看 Docker Compose 默认的网络行为Docker Compose 启动项目时默认会为每个项目创建一个独立的网络命名规则是“项目名 下划线 default”。比如你在目录backend下有一个 compose 文件项目名默认取目录名backend那么它创建的网络就叫backend_default。项目内的所有服务都会自动加入这个网络彼此之间通过服务名就能互相访问。这种默认行为的好处是隔离性和便捷性都很好每个项目独立成网互不干扰项目内的服务不需要额外配置就能用服务名通信。但缺点也很明显——如果两个不同的项目想互相访问或者你想让运维提前规划好网络这个默认的“一键创建”就帮不上忙了。# 最简单的 compose 配置 services: web: image: nginx:1.27跑起来之后执行docker network ls你会看到多了一个类似web_default的网络这就是 Compose 自动创建的。1.2 external 网络是什么告诉 Compose“这条路不是我修的”external: true的含义很直接这个网络不是当前 Compose 项目创建的而是已经存在于 Docker 环境中的网络。Compose 只负责把容器接进去不负责创建它也不会在项目停止时删除它。我一般用一个类比来解释默认网络是开发商给每个项目修的私家路项目结束路就收回external 网络是市政规划的主干道谁都可以走但前提是这条路已经修好了你不能在驾驶时指望开发商顺手帮你修一条市政路。官方文档里对 external 的标准写法是这样networks: shared-net: external: true name: my-shared-network这段配置的意思是我要使用一个叫my-shared-network的网络它已经不是由 Compose 管理的了你在 Docker 环境里应该能找到它。如果找不到就会抛出一开始那条declared as external, but could not be found。1.3 external 和默认网络的几个关键区别对比维度默认网络external 网络创建时机Compose 自动创建需要 pre-createCompose 不负责创建删除行为docker-compose down会删除docker-compose down不会删除跨项目访问项目内隔离跨项目不可见多个项目可共享同一个网络适用场景单项目内部服务通信跨项目共享、独立运维管理理解这张表非常重要。很多人在排查这个报错时下意识认为是 compose 文件写错了其实根源是“external 网络有自己独立的生命周期”。它不随着 compose 项目生自然也不会随着 compose 项目死。这种设计让运维可以统一规划网络但也让那些习惯了“Compose 全自动”的开发者容易踩坑。2. 为什么明明声明了 external却还是报 could not be found2.1 最直白的原因网络压根还没创建这个原因说出来简单但在实际故障场景里却是出现频率最高的。很多人把external: true当成一个“开关”认为加了之后 Docker Compose 就会自动去创建网络。事实恰恰相反——external意味着“这个网络已经存在我只是要用它”Compose 不会创建它。我见过太多同学在新服务器上部署项目先拉代码然后直接docker-compose up -d结果报错。他们完全没有意识到服务器上根本没有提前执行过创建网络的命令。这种场景在 CI/CD 流水线里尤其常见每次部署到一台全新的机器上如果创建网络的步骤没有被集成到自动化流程里就必然会报这个错。解决方式本身很简单先创建网络再启动项目docker network create my-shared-network docker-compose up -d但这只是治标。更关键的思路是在你的部署文档里要把“创建 external 网络”这一步作为前置条件写清楚而不是默认每个环境都已经有这个网络。2.2 网络名对不上差一个字符你就找不到它这是最容易让人抓狂的一种情况。因为报错信息里的网络名是xxx你去看 compose 文件里写的也是xxx看起来完全一致但 Docker 就是提示找不到。问题通常出在“看起来一致”这个环节。Docker 网络名对大小写和特殊符号极其敏感。my-shared-network和my_shared_network是两个完全不同的网络MySharedNetwork又是另一个。哪怕你在创建网络时多打了一个空格或者用 tab 缩进导致 yaml 解析出了隐藏字符网络名就已经变了。我在实际排查中遇到过一个非常典型的案例compose 文件里写的是app-shared-net创建网络时执行的是docker network create app_shared_net报错信息就一直提示app-shared-net找不到。排查了半天最后用docker network ls一对比才意识到连字符和下划线根本不通用。建议的做法是项目里所有网络命名统一用小写字母加连字符或下划线并在 README 里明确写清楚。同时不要手动在终端里敲网络创建命令直接复制文档里的命令减少人工输入带来的误差。2.3 external 声明的位置写错了Docker Compose 对external的识别位置有严格要求。它必须写在顶层networks字段的某个网络定义里不能写在services里。错误示例services: web: image: nginx networks: shared-net: external: true这样写 Compose 会直接报配置错误或者把external当作一个未知字段忽略掉导致最终行为不符合预期。正确示例services: web: image: nginx networks: - shared-net networks: shared-net: external: true还有一点要注意external: true这种写法在 Compose V2 里还可以再配合name指定实际存在的网络名称。如果使用了external: true但不指定nameCompose 默认会拿顶层网络的名称即shared-net去 Docker 环境里找。如果实际网络名不同就会报找不到。2.4 你是不是连错了 Docker 环境这个原因相对隐蔽。docker-compose 命令执行的时候并不一定是连接你本地那个 Docker daemon。如果你设置了DOCKER_HOST环境变量、或者用了 Docker Context 切换到远程机器那么你在本地docker network ls看到的网络和 docker-compose 实际操作的那台机器看到的网络就不是同一个。我有一个同事遇到过这样的情况他自己电脑上明明能看到my-shared-network存在但 docker-compose 就是提示找不到。后来排查发现他在 shell 配置文件里设置了DOCKER_HOSTtcp://xxx.xxx.xxx.xxx:2375docker-compose 连接的是远程服务器的 Docker而远程服务器上根本没有这个网络。排查思路很直接docker context ls docker info | grep -i host确认 docker-compose 实际连接的 daemon 和你查看网络的 daemon 是同一个。这个坑在多人协作和远程开发环境中非常容易踩到。2.5 Compose 版本差异导致的兼容性问题Docker Compose 的版本迭代也引入了一些差异。早期 docker-compose v1 时代external网络的写法通常是networks: shared-net: external: name: my-shared-network到了 Compose V2 时代external: true加上name字段的写法更简洁也被官方推荐networks: shared-net: external: true name: my-shared-network两种写法在 Compose V2 里都能正常工作但在旧版 v1 里后面这种新写法可能不被识别导致name字段失效。如果你的项目还在用老版本的 docker-compose建议检查一下版本并优先使用兼容性更好的external.name写法。执行docker-compose version可以查看当前版本新版建议直接使用docker compose插件。3. 从报错到正常启动一套完整的诊断和修复流程3.1 第一步看清 Docker 网络现状拿到这个报错第一件事不是改 yaml而是查看当前 Docker 环境里到底有哪些网络docker network ls重点看 NAME、DRIVER、SCOPE 这三列。NAME 就是网络名DRIVER 一般是 bridge 或 overlaySCOPE 一般是 local 或 swarm。你要找的网络如果存在会出现在这个列表里。列名含义常见值NAME网络名称my-shared-networkDRIVER网络驱动bridge单机、overlay跨主机SCOPE作用域local本机、swarm集群如果列表里没有你配置的网络那问题很简单网络不存在创建即可。如果列表里有同名网络那就要继续核对——docker-compose 用的那个 daemon 是不是当前这个3.2 第二步用 config 校验你的 compose 配置docker-compose 自带一个校验命令会把最终生效的配置打印出来非常适合排查网络定义是否正确docker-compose config如果你用的是新版 Docker Compose 插件docker compose config这个命令会输出解析后的完整配置。重点看networks部分确认网络名、external 标志、name 字段的解析结果和你的预期一致。提示如果docker-compose config都直接报错说明 compose 文件语法有问题先修语法错误再排查网络问题。这个命令不会启动任何容器放心执行。3.3 第三步创建缺失的 external 网络如果网络确实不存在执行创建命令docker network create my-shared-network默认驱动是 bridge适用于单机环境。如果是 Swarm 集群或者跨主机通信场景需要指定 overlay 驱动docker network create -d overlay --attachable my-shared-network这里我额外提一个细节--attachable参数在共享网络场景下非常重要。不加这个参数Swarm 模式下非 swarm 服务无法正常挂载到 overlay 网络。即便你现在用不到我个人建议创建共享网络时统一加上--attachable避免以后踩坑。创建完成后再次执行docker network ls确认然后重新启动项目docker-compose up -d3.4 第四步网络名不一致时修改哪一边如果网络已经存在但 compose 文件里配置的名字和它不一致你有两个选择改网络名或者改 compose 配置。改网络名比较麻烦需要重建网络所以我更推荐改 compose 配置。假设实际存在的网络叫actual-shared-netcompose 文件里这样写networks: shared-net: external: true name: actual-shared-net这样 Compose 就会用actual-shared-net这个名字去 Docker 环境里找只要它存在就不会报错。顶层shared-net只是项目内部的逻辑名称实际对接哪个网络由name决定。改完之后记得再跑一次docker-compose config校验。3.5 第五步验证容器是否真的挂上了网络项目启动成功后不要急着欢呼。检查一下容器是否真的加入了 external 网络docker network inspect actual-shared-net输出结果里有一个Containers字段会列出所有连接在这个网络上的容器及其 IP 地址。一个共享网络要正常工作需要能看到所有相关项目的容器都在这个列表里。容器内的连通性测试也很重要。如果你的容器里有 ping 工具可以直接测试docker exec -it container-name ping another-container-name如果没有 ping也可以用 Docker 自带的 DNS 解析来验证docker exec -it container-name getent hosts service-name能解析出 IP 说明容器间通信链路已经打通不能解析则说明网络配置或别名配置有问题下一部分会详细讲。注意docker-compose down不会删除 external 网络所以你修改网络配置后不需要担心 down 掉项目会把共享网络一起带走。但如果要彻底重建容器建议docker-compose down后再up -d确保容器重新获取网络配置。4. 实战案例两个 compose 项目通过 external 网络互通4.1 场景说明假设你现在有两个项目一个是backend项目提供 API 服务另一个是proxy项目用 Nginx 做反向代理。这两个项目都有自己的 compose 文件、独立的生命周期和发布流程。Nginx 需要访问 backend 的 API但它们不在同一个 compose 文件里。如果不用 external 网络常规做法是把两个项目合并到同一个 compose 文件但这会打破团队之间的独立部署节奏。用 external 网络则能在保持项目独立的前提下实现通信这正是这个机制最典型的应用场景。4.2 第一步先创建共享网络docker network create shared-net这里我特意不指定驱动让它默认用 bridge。单机环境下 bridge 完全够用也最容易理解和维护。4.3 第二步编写 backend 项目的 compose 文件# backend/docker-compose.yml services: api: image: my-backend-api:latest ports: - 8080:8080 networks: - shared-net - default # 关键给容器指定网络别名方便其他项目通过固定名称访问 networks: shared-net: aliases: - api networks: shared-net: external: true default: driver: bridge这里有个很容易被忽略的细节networks下给api服务配置了shared-net和default两个网络。shared-net负责跨项目通信default让同一个 compose 项目内部的服务可以互相访问。关键配置是aliases: - api。没有这个别名时其他项目里的容器访问不到http://api:8080因为跨项目时 Docker 默认的网络别名解析不一定可靠。4.4 第三步编写 proxy 项目的 compose 文件# proxy/docker-compose.yml services: nginx: image: nginx:1.27 ports: - 80:80 volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro networks: - shared-net networks: shared-net: external: trueproxy 项目的 Nginx 配置里把请求转发到http://api:8080# proxy/nginx.conf server { listen 80; location / { proxy_pass http://api:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这里的api不是 IP 地址而是 DNS 名称。Docker 内嵌的 DNS 服务器会把api解析到 backend 项目中那个设置了别名api的容器 IP。4.5 第四步启动顺序和连通性验证先启动 backend 项目确保 API 服务已经注册到共享网络里cd backend docker-compose up -d再启动 proxy 项目cd proxy docker-compose up -d查看网络上的容器列表docker network inspect shared-net你应该能看到两个项目的容器都在列表中。然后进入 Nginx 容器测试docker exec -it nginx-container curl http://api:8080如果返回 API 的响应说明网络链路完全正常。如果 curl 报无法解析主机先检查 backend 项目里aliases是否配置成功。提示如果你不想绑定api这个别名也可以直接给容器设置固定的container_name通过容器名访问。但我个人更推荐aliases方式因为它不会影响 Compose 对服务名和容器名的管理也更语义化。5. 踩坑记录、排查清单和预防习惯5.1 我说几个自己踩过的典型坑第一个坑就是网络名里的连字符和下划线问题。有一次凌晨上线我拷贝 compose 文件到生产服务器启动就报 external network 找不到。我反复看 compose 文件都没发现问题最后和生产环境的网络列表一对比才发现测试环境创建的app_shared_net生产环境却写成了app-shared-net。两个环境不能直接共享网络这个问题只能靠统一命名规范来根治。第二个坑是docker system prune把网络顺手清理了。external 网络虽然不会因为docker-compose down被删除但如果你执行了带网络清理的 prune 命令并且这个网络当时没有被任何容器使用就会直接被清理掉。第二天部署时一切代码都没变但项目起不来。从那次以后我在生产环境基本只用精确指定的清理命令不再用docker system prune -a这种激进操作。第三个坑是 Docker daemon 连接错乱。远程开发环境下我习惯用 Docker Context 切换环境有一次在上下文还指向远程机器时直接跑了docker-compose up。本地的网络列表和远程环境完全不同导致报错信息特别误导人。排查到最后检查docker context ls才发现问题。5.2 快速排查清单一表定位问题现象可能原因处理方式external 网络找不到网络确实不存在docker network ls确认不存在则创建网络列表里有但 compose 报错网络名不一致连字符/下划线/大小写对比 compose 的name字段和docker network ls的实际名称本机能看网络compose 找不到docker-compose 连接了远程 daemon执行docker context ls、docker info检查 DOCKER_HOST网络都正常但容器间不能互访缺少 network alias给目标服务添加aliases或使用固定container_name之前正常重启后报错external 网络被 prune 清理检查网络是否存在不存在则重新创建以后避免无差别 prune5.3 怎么避免下次再犯几个小习惯能让这个问题彻底远离你。第一把“创建外部网络”的步骤写进项目 README 或者 Makefile作为部署前置步骤强制执行。不能期望每个团队的成员都默认知道要先创建网络。第二在 compose 文件顶部用注释写清楚这个项目依赖哪些 external 网络以及这些网络应该在什么环境里存在。这样不管是同事接手还是换环境部署都能第一时间看到关键信息。第三养成启动前跑docker-compose config的习惯。这个命令哪怕在 CI/CD 里也可以作为 preflight 检查配置有问题时第一时间暴露而不是等容器真正启动时才报错。第四对于共享网络建议把创建命令固定在一个基础设施脚本里用幂等的方式去执行。比如 Shell 脚本先检查网络是否存在存在则跳过不存在则创建避免重复执行时报错。我个人在实际操作中的体会是external 网络这个机制本身并不复杂它本质上就是一个跨项目通信的桥梁。绝大多数排错时间其实都花在了“名字对不上”和“环境不对”这两类问题上。遇到declared as external, but could not be found这个报错先冷静下来按docker network ls、docker-compose config、docker context ls这三步排查基本都能在五分钟内定位问题。真正的坑往往不在技术本身而在环境差异和操作习惯上。
Docker Compose external网络报错排查与解决指南
如果你在用 Docker Compose 启动项目时被这条报错卡住那你大概率已经试过重新创建容器、重启 Docker 甚至重装环境结果发现全都无效。这个错误的完整描述是network xxx declared as external, but could not be found我第一次遇到时也是懵的——既然我已经在 compose 文件里把网络声明成 external 了Docker 为什么反而说找不到这个报错在部署微服务、搭建监控系统比如 Prometheus Grafana、或者需要多个 compose 项目共享同一个网络时非常常见。尤其是新服务器、新环境、或者刚跑完docker system prune之后报错概率直线上升。适合所有用 Docker Compose 做部署的运维、后端开发和全栈工程师阅读读完你不仅能解决当前问题还能彻底搞懂 external 网络的机制以后再遇到相关的跨项目通信问题也不会慌。1. external 网络到底是什么Compose 为什么要设计这个选项1.1 先看看 Docker Compose 默认的网络行为Docker Compose 启动项目时默认会为每个项目创建一个独立的网络命名规则是“项目名 下划线 default”。比如你在目录backend下有一个 compose 文件项目名默认取目录名backend那么它创建的网络就叫backend_default。项目内的所有服务都会自动加入这个网络彼此之间通过服务名就能互相访问。这种默认行为的好处是隔离性和便捷性都很好每个项目独立成网互不干扰项目内的服务不需要额外配置就能用服务名通信。但缺点也很明显——如果两个不同的项目想互相访问或者你想让运维提前规划好网络这个默认的“一键创建”就帮不上忙了。# 最简单的 compose 配置 services: web: image: nginx:1.27跑起来之后执行docker network ls你会看到多了一个类似web_default的网络这就是 Compose 自动创建的。1.2 external 网络是什么告诉 Compose“这条路不是我修的”external: true的含义很直接这个网络不是当前 Compose 项目创建的而是已经存在于 Docker 环境中的网络。Compose 只负责把容器接进去不负责创建它也不会在项目停止时删除它。我一般用一个类比来解释默认网络是开发商给每个项目修的私家路项目结束路就收回external 网络是市政规划的主干道谁都可以走但前提是这条路已经修好了你不能在驾驶时指望开发商顺手帮你修一条市政路。官方文档里对 external 的标准写法是这样networks: shared-net: external: true name: my-shared-network这段配置的意思是我要使用一个叫my-shared-network的网络它已经不是由 Compose 管理的了你在 Docker 环境里应该能找到它。如果找不到就会抛出一开始那条declared as external, but could not be found。1.3 external 和默认网络的几个关键区别对比维度默认网络external 网络创建时机Compose 自动创建需要 pre-createCompose 不负责创建删除行为docker-compose down会删除docker-compose down不会删除跨项目访问项目内隔离跨项目不可见多个项目可共享同一个网络适用场景单项目内部服务通信跨项目共享、独立运维管理理解这张表非常重要。很多人在排查这个报错时下意识认为是 compose 文件写错了其实根源是“external 网络有自己独立的生命周期”。它不随着 compose 项目生自然也不会随着 compose 项目死。这种设计让运维可以统一规划网络但也让那些习惯了“Compose 全自动”的开发者容易踩坑。2. 为什么明明声明了 external却还是报 could not be found2.1 最直白的原因网络压根还没创建这个原因说出来简单但在实际故障场景里却是出现频率最高的。很多人把external: true当成一个“开关”认为加了之后 Docker Compose 就会自动去创建网络。事实恰恰相反——external意味着“这个网络已经存在我只是要用它”Compose 不会创建它。我见过太多同学在新服务器上部署项目先拉代码然后直接docker-compose up -d结果报错。他们完全没有意识到服务器上根本没有提前执行过创建网络的命令。这种场景在 CI/CD 流水线里尤其常见每次部署到一台全新的机器上如果创建网络的步骤没有被集成到自动化流程里就必然会报这个错。解决方式本身很简单先创建网络再启动项目docker network create my-shared-network docker-compose up -d但这只是治标。更关键的思路是在你的部署文档里要把“创建 external 网络”这一步作为前置条件写清楚而不是默认每个环境都已经有这个网络。2.2 网络名对不上差一个字符你就找不到它这是最容易让人抓狂的一种情况。因为报错信息里的网络名是xxx你去看 compose 文件里写的也是xxx看起来完全一致但 Docker 就是提示找不到。问题通常出在“看起来一致”这个环节。Docker 网络名对大小写和特殊符号极其敏感。my-shared-network和my_shared_network是两个完全不同的网络MySharedNetwork又是另一个。哪怕你在创建网络时多打了一个空格或者用 tab 缩进导致 yaml 解析出了隐藏字符网络名就已经变了。我在实际排查中遇到过一个非常典型的案例compose 文件里写的是app-shared-net创建网络时执行的是docker network create app_shared_net报错信息就一直提示app-shared-net找不到。排查了半天最后用docker network ls一对比才意识到连字符和下划线根本不通用。建议的做法是项目里所有网络命名统一用小写字母加连字符或下划线并在 README 里明确写清楚。同时不要手动在终端里敲网络创建命令直接复制文档里的命令减少人工输入带来的误差。2.3 external 声明的位置写错了Docker Compose 对external的识别位置有严格要求。它必须写在顶层networks字段的某个网络定义里不能写在services里。错误示例services: web: image: nginx networks: shared-net: external: true这样写 Compose 会直接报配置错误或者把external当作一个未知字段忽略掉导致最终行为不符合预期。正确示例services: web: image: nginx networks: - shared-net networks: shared-net: external: true还有一点要注意external: true这种写法在 Compose V2 里还可以再配合name指定实际存在的网络名称。如果使用了external: true但不指定nameCompose 默认会拿顶层网络的名称即shared-net去 Docker 环境里找。如果实际网络名不同就会报找不到。2.4 你是不是连错了 Docker 环境这个原因相对隐蔽。docker-compose 命令执行的时候并不一定是连接你本地那个 Docker daemon。如果你设置了DOCKER_HOST环境变量、或者用了 Docker Context 切换到远程机器那么你在本地docker network ls看到的网络和 docker-compose 实际操作的那台机器看到的网络就不是同一个。我有一个同事遇到过这样的情况他自己电脑上明明能看到my-shared-network存在但 docker-compose 就是提示找不到。后来排查发现他在 shell 配置文件里设置了DOCKER_HOSTtcp://xxx.xxx.xxx.xxx:2375docker-compose 连接的是远程服务器的 Docker而远程服务器上根本没有这个网络。排查思路很直接docker context ls docker info | grep -i host确认 docker-compose 实际连接的 daemon 和你查看网络的 daemon 是同一个。这个坑在多人协作和远程开发环境中非常容易踩到。2.5 Compose 版本差异导致的兼容性问题Docker Compose 的版本迭代也引入了一些差异。早期 docker-compose v1 时代external网络的写法通常是networks: shared-net: external: name: my-shared-network到了 Compose V2 时代external: true加上name字段的写法更简洁也被官方推荐networks: shared-net: external: true name: my-shared-network两种写法在 Compose V2 里都能正常工作但在旧版 v1 里后面这种新写法可能不被识别导致name字段失效。如果你的项目还在用老版本的 docker-compose建议检查一下版本并优先使用兼容性更好的external.name写法。执行docker-compose version可以查看当前版本新版建议直接使用docker compose插件。3. 从报错到正常启动一套完整的诊断和修复流程3.1 第一步看清 Docker 网络现状拿到这个报错第一件事不是改 yaml而是查看当前 Docker 环境里到底有哪些网络docker network ls重点看 NAME、DRIVER、SCOPE 这三列。NAME 就是网络名DRIVER 一般是 bridge 或 overlaySCOPE 一般是 local 或 swarm。你要找的网络如果存在会出现在这个列表里。列名含义常见值NAME网络名称my-shared-networkDRIVER网络驱动bridge单机、overlay跨主机SCOPE作用域local本机、swarm集群如果列表里没有你配置的网络那问题很简单网络不存在创建即可。如果列表里有同名网络那就要继续核对——docker-compose 用的那个 daemon 是不是当前这个3.2 第二步用 config 校验你的 compose 配置docker-compose 自带一个校验命令会把最终生效的配置打印出来非常适合排查网络定义是否正确docker-compose config如果你用的是新版 Docker Compose 插件docker compose config这个命令会输出解析后的完整配置。重点看networks部分确认网络名、external 标志、name 字段的解析结果和你的预期一致。提示如果docker-compose config都直接报错说明 compose 文件语法有问题先修语法错误再排查网络问题。这个命令不会启动任何容器放心执行。3.3 第三步创建缺失的 external 网络如果网络确实不存在执行创建命令docker network create my-shared-network默认驱动是 bridge适用于单机环境。如果是 Swarm 集群或者跨主机通信场景需要指定 overlay 驱动docker network create -d overlay --attachable my-shared-network这里我额外提一个细节--attachable参数在共享网络场景下非常重要。不加这个参数Swarm 模式下非 swarm 服务无法正常挂载到 overlay 网络。即便你现在用不到我个人建议创建共享网络时统一加上--attachable避免以后踩坑。创建完成后再次执行docker network ls确认然后重新启动项目docker-compose up -d3.4 第四步网络名不一致时修改哪一边如果网络已经存在但 compose 文件里配置的名字和它不一致你有两个选择改网络名或者改 compose 配置。改网络名比较麻烦需要重建网络所以我更推荐改 compose 配置。假设实际存在的网络叫actual-shared-netcompose 文件里这样写networks: shared-net: external: true name: actual-shared-net这样 Compose 就会用actual-shared-net这个名字去 Docker 环境里找只要它存在就不会报错。顶层shared-net只是项目内部的逻辑名称实际对接哪个网络由name决定。改完之后记得再跑一次docker-compose config校验。3.5 第五步验证容器是否真的挂上了网络项目启动成功后不要急着欢呼。检查一下容器是否真的加入了 external 网络docker network inspect actual-shared-net输出结果里有一个Containers字段会列出所有连接在这个网络上的容器及其 IP 地址。一个共享网络要正常工作需要能看到所有相关项目的容器都在这个列表里。容器内的连通性测试也很重要。如果你的容器里有 ping 工具可以直接测试docker exec -it container-name ping another-container-name如果没有 ping也可以用 Docker 自带的 DNS 解析来验证docker exec -it container-name getent hosts service-name能解析出 IP 说明容器间通信链路已经打通不能解析则说明网络配置或别名配置有问题下一部分会详细讲。注意docker-compose down不会删除 external 网络所以你修改网络配置后不需要担心 down 掉项目会把共享网络一起带走。但如果要彻底重建容器建议docker-compose down后再up -d确保容器重新获取网络配置。4. 实战案例两个 compose 项目通过 external 网络互通4.1 场景说明假设你现在有两个项目一个是backend项目提供 API 服务另一个是proxy项目用 Nginx 做反向代理。这两个项目都有自己的 compose 文件、独立的生命周期和发布流程。Nginx 需要访问 backend 的 API但它们不在同一个 compose 文件里。如果不用 external 网络常规做法是把两个项目合并到同一个 compose 文件但这会打破团队之间的独立部署节奏。用 external 网络则能在保持项目独立的前提下实现通信这正是这个机制最典型的应用场景。4.2 第一步先创建共享网络docker network create shared-net这里我特意不指定驱动让它默认用 bridge。单机环境下 bridge 完全够用也最容易理解和维护。4.3 第二步编写 backend 项目的 compose 文件# backend/docker-compose.yml services: api: image: my-backend-api:latest ports: - 8080:8080 networks: - shared-net - default # 关键给容器指定网络别名方便其他项目通过固定名称访问 networks: shared-net: aliases: - api networks: shared-net: external: true default: driver: bridge这里有个很容易被忽略的细节networks下给api服务配置了shared-net和default两个网络。shared-net负责跨项目通信default让同一个 compose 项目内部的服务可以互相访问。关键配置是aliases: - api。没有这个别名时其他项目里的容器访问不到http://api:8080因为跨项目时 Docker 默认的网络别名解析不一定可靠。4.4 第三步编写 proxy 项目的 compose 文件# proxy/docker-compose.yml services: nginx: image: nginx:1.27 ports: - 80:80 volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro networks: - shared-net networks: shared-net: external: trueproxy 项目的 Nginx 配置里把请求转发到http://api:8080# proxy/nginx.conf server { listen 80; location / { proxy_pass http://api:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这里的api不是 IP 地址而是 DNS 名称。Docker 内嵌的 DNS 服务器会把api解析到 backend 项目中那个设置了别名api的容器 IP。4.5 第四步启动顺序和连通性验证先启动 backend 项目确保 API 服务已经注册到共享网络里cd backend docker-compose up -d再启动 proxy 项目cd proxy docker-compose up -d查看网络上的容器列表docker network inspect shared-net你应该能看到两个项目的容器都在列表中。然后进入 Nginx 容器测试docker exec -it nginx-container curl http://api:8080如果返回 API 的响应说明网络链路完全正常。如果 curl 报无法解析主机先检查 backend 项目里aliases是否配置成功。提示如果你不想绑定api这个别名也可以直接给容器设置固定的container_name通过容器名访问。但我个人更推荐aliases方式因为它不会影响 Compose 对服务名和容器名的管理也更语义化。5. 踩坑记录、排查清单和预防习惯5.1 我说几个自己踩过的典型坑第一个坑就是网络名里的连字符和下划线问题。有一次凌晨上线我拷贝 compose 文件到生产服务器启动就报 external network 找不到。我反复看 compose 文件都没发现问题最后和生产环境的网络列表一对比才发现测试环境创建的app_shared_net生产环境却写成了app-shared-net。两个环境不能直接共享网络这个问题只能靠统一命名规范来根治。第二个坑是docker system prune把网络顺手清理了。external 网络虽然不会因为docker-compose down被删除但如果你执行了带网络清理的 prune 命令并且这个网络当时没有被任何容器使用就会直接被清理掉。第二天部署时一切代码都没变但项目起不来。从那次以后我在生产环境基本只用精确指定的清理命令不再用docker system prune -a这种激进操作。第三个坑是 Docker daemon 连接错乱。远程开发环境下我习惯用 Docker Context 切换环境有一次在上下文还指向远程机器时直接跑了docker-compose up。本地的网络列表和远程环境完全不同导致报错信息特别误导人。排查到最后检查docker context ls才发现问题。5.2 快速排查清单一表定位问题现象可能原因处理方式external 网络找不到网络确实不存在docker network ls确认不存在则创建网络列表里有但 compose 报错网络名不一致连字符/下划线/大小写对比 compose 的name字段和docker network ls的实际名称本机能看网络compose 找不到docker-compose 连接了远程 daemon执行docker context ls、docker info检查 DOCKER_HOST网络都正常但容器间不能互访缺少 network alias给目标服务添加aliases或使用固定container_name之前正常重启后报错external 网络被 prune 清理检查网络是否存在不存在则重新创建以后避免无差别 prune5.3 怎么避免下次再犯几个小习惯能让这个问题彻底远离你。第一把“创建外部网络”的步骤写进项目 README 或者 Makefile作为部署前置步骤强制执行。不能期望每个团队的成员都默认知道要先创建网络。第二在 compose 文件顶部用注释写清楚这个项目依赖哪些 external 网络以及这些网络应该在什么环境里存在。这样不管是同事接手还是换环境部署都能第一时间看到关键信息。第三养成启动前跑docker-compose config的习惯。这个命令哪怕在 CI/CD 里也可以作为 preflight 检查配置有问题时第一时间暴露而不是等容器真正启动时才报错。第四对于共享网络建议把创建命令固定在一个基础设施脚本里用幂等的方式去执行。比如 Shell 脚本先检查网络是否存在存在则跳过不存在则创建避免重复执行时报错。我个人在实际操作中的体会是external 网络这个机制本身并不复杂它本质上就是一个跨项目通信的桥梁。绝大多数排错时间其实都花在了“名字对不上”和“环境不对”这两类问题上。遇到declared as external, but could not be found这个报错先冷静下来按docker network ls、docker-compose config、docker context ls这三步排查基本都能在五分钟内定位问题。真正的坑往往不在技术本身而在环境差异和操作习惯上。
