1. 为什么单机思维在集群里一定会翻车

很多人第一次把服务从单机 Docker 搬到 Swarm 集群时，都会经历一个相似的困惑：容器明明都起来了，docker service ls显示副本数也正常，但服务之间就是互相调不通。ping不通、端口连不上、DNS 解析失败，各种问题一股脑冒出来。这时候如果还拿着单机 Docker 那套docker inspect看 IP、手动--link的思路去排查，基本是白费力气。

问题的根源在于：单机 Docker 的网络是"一台机器上的局域网"，而 Swarm 的 overlay 网络是"跨多台机器的虚拟局域网"。这两者的底层实现、地址分配、流量路径完全不是一回事。overlay 网络模型是 Swarm 模式里最核心也最容易被低估的一块，搞懂它，你才能明白为什么服务发现是自动的、为什么跨节点通信不需要手动配路由、为什么有时候抓包看到的源地址和你想象的不一样。

这篇内容适合两类人：一类是已经把 Swarm 跑起来、但遇到跨节点通信问题不知道怎么下手的运维或后端同学；另一类是准备在生产环境用 Swarm 承载多服务、需要提前搞清楚网络模型边界和坑点的架构决策者。我会从设计思路讲起，把 overlay 的地址分配、控制面与数据面、VXLAN 封装、服务发现、负载均衡这几块拆开揉碎，再给出一套可以直接照着做的实操流程和排查方法。全程基于我在实际集群里踩过的坑，不讲教科书式的概念堆砌。

需要先说明一点：Swarm 的 overlay 网络在不同版本上有细节差异，下面涉及具体行为的地方，我以当前主流稳定版本的常见表现为准，个别参数名或默认值如果你在用的版本对不上，以docker network inspect的实际输出为准。这是基于常见实践的补充说明，不是绝对标准。

2. overlay 网络模型到底在解决什么问题

2.1 从单机 bridge 到跨主机虚拟网络

单机 Docker 的默认 bridge 网络，本质是宿主机上的一块虚拟网桥，容器通过 veth pair 挂到这块网桥上，宿主机做 NAT 让容器访问外网。这套模型的问题在于它的作用域被锁死在一台机器上——网桥只存在于本机内核里，另一台机器上的容器根本不知道这块网桥的存在。

Swarm 要解决的是"多台机器上的容器像在一个局域网里一样通信"。最直觉的做法是让所有节点之间建立某种隧道，把容器的二层或三层流量封装后通过宿主机网络传过去，对端解封装后再投递给目标容器。这就是 overlay（覆盖网络）的基本思想：在物理网络之上再叠一层虚拟网络，物理网络只负责把封装后的包送到对端节点，虚拟网络负责容器之间的寻址和隔离。

为什么选 overlay 而不是别的方案？因为 overlay 对底层物理网络的要求最低。你不需要物理交换机支持什么特殊协议，不需要改路由表，只要节点之间 IP 可达、特定端口能通，overlay 就能工作。这对很多机房网络不由自己完全掌控的场景来说，是决定性的优势。代价是封装带来额外的头部开销和一点点转发延迟，但对绝大多数业务来说完全可以接受。

2.2 Swarm 模式下网络的分层结构

理解 Swarm 网络，脑子里要有一张分层图。最底层是宿主机的物理网卡和物理网络，负责节点之间的实际连通。往上一层是 Docker 在每个节点上创建的 ingress 网络和用户自定义的 overlay 网络，这些是虚拟网络。再往上才是挂在这些虚拟网络上的服务和容器。

这里有个关键点容易被忽略：Swarm 里有两类 overlay 网络，一类是自动创建的ingress网络，专门承载对外发布端口（--publish）的流量；另一类是你用docker network create --driver overlay手动创建的业务网络，服务通过--network挂上去做服务间通信。这两类网络的职责完全不同，排查问题时必须先分清流量走的是哪一类。很多"端口映射不生效"的案例，其实是把业务网络的内部通信和 ingress 的对外发布混为一谈了。

2.3 控制面与数据面的分工

overlay 网络能自动工作，靠的是控制面和数据面的配合。控制面负责"谁在哪里"——哪个容器分配了什么虚拟 IP、这个 IP 当前落在哪个节点上、服务名对应哪些后端。这部分信息由 Swarm 的管理节点维护，通过 gossip 协议在集群内传播。数据面负责"包怎么走"——根据控制面下发的映射关系，把虚拟网络里的包封装后送到正确的节点。

这个分工解释了一个常见现象：新扩容的副本刚起来时，可能有短暂时间其他服务访问不到它。因为控制面的映射更新和数据面的转发规则生效之间有一个极短的窗口。这不是 bug，是分布式系统的正常收敛过程。理解这一点，你就不会在扩容后立刻做连通性测试然后误判为故障。

3. 地址分配与 VXLAN 封装：包到底怎么走的

3.1 虚拟 IP 的分配逻辑

每个 overlay 网络在创建时会分配一个子网，比如10.0.1.0/24。挂到这个网络上的每个容器（更准确说是每个服务的每个任务）会从子网里分到一个虚拟 IP。这个 IP 在整个 overlay 网络内唯一，但只在虚拟网络里有意义——物理网络里没人认识它。

分配是由管理节点统一协调的，避免不同节点分到重复地址。你可以用docker network inspect看到子网配置，用docker service ps配合docker inspect看到具体任务分到的虚拟 IP。这里有个实操细节：虚拟 IP 是跟着任务走的，任务重建（比如节点故障后重新调度）会拿到新 IP，所以任何依赖固定 IP 的配置都是不可靠的，正确做法永远是用服务名做服务发现。

3.2 VXLAN 封装的实际过程

虚拟网络里的包要跨节点传输，必须经过封装。Swarm 用的是 VXLAN 技术，把原始的虚拟网络包整个塞进一个 UDP 包里，外层用节点的物理 IP 做源和目的，通过 4789 端口（默认）传输。对端节点收到后拆开外层，取出里面的原始包，再根据虚拟 IP 投递给目标容器。

用生活化的类比：虚拟网络里的通信像两个人用内部暗号写信，物理网络是邮局。邮局看不懂暗号，所以寄信的人把暗号信装进一个标准信封，写上双方的真实地址寄出去，收信人拆开标准信封取出暗号信再解读。VXLAN 封装就是这个"套信封"的过程，外层 UDP 头就是标准信封。

这个机制带来两个直接影响。第一，节点之间必须能通 UDP 4789，如果中间有防火墙拦了这个端口，跨节点通信就会失败，而且现象往往是"同节点能通、跨节点不通"，非常有迷惑性。第二，抓包时在物理网卡上看到的是封装后的 UDP 包，要看原始流量得在虚拟网卡上抓或者用支持 VXLAN 解析的工具，这一点排查时特别重要。

3.3 同节点与跨节点通信的差异

同一个节点上的两个容器通信，流量其实不需要经过 VXLAN 封装，直接在内核里通过虚拟网桥转发就行，效率高很多。只有跨节点时才走封装路径。这个差异导致一个典型现象：小规模测试时所有副本恰好调度到同一节点，通信一切正常；一旦扩容到多节点，问题才暴露出来。

所以做连通性验证时，一定要确保测试的容器分布在不同节点上。我见过不止一次"本地测试通过、上线就挂"的案例，根因就是测试环境单节点、生产环境多节点，overlay 的跨节点路径从来没被真正验证过。这是个必须刻意设计的测试场景，不能靠运气。

4. 服务发现与负载均衡：为什么不用手动配地址

4.1 内嵌 DNS 的工作方式

Swarm 给每个 overlay 网络内置了一个 DNS 解析器，监听在127.0.0.11:53。容器里的 DNS 请求会被拦截并转发到这个内嵌解析器，它知道当前网络里所有服务的名字和对应的虚拟 IP。所以你用服务名就能直接访问，比如curl http://api-service:8080，不需要知道任何 IP。

这个 DNS 解析是"服务级"的，不是"容器级"的。解析服务名返回的是该服务的虚拟 IP（VIP），而不是某个具体任务的 IP。这个 VIP 由 Swarm 的负载均衡机制接管，把请求分发到后端健康的任务上。理解"服务名解析到 VIP、VIP 再分发到任务"这个两级结构，是搞懂 Swarm 服务发现的关键。

4.2 VIP 模式与 DNSRR 模式的取舍

Swarm 默认用 VIP（虚拟 IP）模式做服务发现。客户端解析服务名拿到一个 VIP，这个 VIP 不属于任何具体容器，而是由内核的 IPVS 规则接管，把流量负载均衡到后端任务。好处是客户端无感知，后端扩缩容对客户端透明，连接复用也友好。

另一种模式是 DNSRR（DNS 轮询），解析服务名直接返回所有后端任务的 IP 列表，由客户端自己选一个。这种模式适合需要客户端感知具体后端的场景，但缺点也明显：客户端要自己处理负载均衡和故障重试，后端变化时 DNS 缓存可能导致短暂不一致。切换方式是在服务上设置--endpoint-mode dnsrr。

选哪种？绝大多数场景用默认的 VIP 就行，省心。只有当你明确需要客户端直连具体任务（比如某些有状态服务的特定寻址需求）时才考虑 DNSRR。这个选择背后是对"谁来承担负载均衡职责"的权衡，不是随便选的。

4.3 ingress 网络的对外发布路径

对外发布端口时，流量路径和内部通信不一样。外部请求先到任意一个节点的发布端口，然后进入 ingress 网络，再由 ingress 的负载均衡把流量转发到实际运行该服务的节点上的任务。这意味着即使请求打到的节点上没有运行目标服务，也能正常转发——这是 ingress 网络的核心价值，让对外发布不依赖具体节点。

这里有个性能考量：ingress 的转发会多一跳，因为流量可能先到一个没有目标任务的节点再被转走。对延迟敏感的服务，可以用--publish mode=host让端口直接绑定在运行任务的节点上，跳过 ingress 这一跳，但代价是失去了"任意节点都能接流量"的便利，需要外部负载均衡器配合。这个取舍要根据业务的实际延迟要求和架构来定。

5. 从零搭一套可验证的 overlay 环境

5.1 节点准备与基础检查

先准备至少两台能互相通信的节点，装好 Docker 并初始化 Swarm。管理节点执行docker swarm init，工作节点用输出的 join 命令加入。初始化后第一件事是确认节点状态：

docker node ls

所有节点状态应为Ready，管理节点带Leader标记。接着检查节点之间的基础连通性，重点是 UDP 4789 端口。这一步很多人跳过，结果后面跨节点不通又回头查，浪费时间。可以用简单的端口探测工具确认，或者直接看后续 overlay 测试的结果反推。

注意：节点之间的时间同步要做，gossip 协议对时间偏差有一定容忍度，但偏差过大可能导致状态传播异常。这是很多"莫名其妙"问题的隐藏根因。

5.2 创建 overlay 网络并验证子网

创建一个业务用的 overlay 网络，显式指定子网，方便后续排查时对照：

docker network create \ --driver overlay \ --subnet 10.0.9.0/24 \ --attachable \ my-overlay

--attachable的作用是允许普通容器（非服务）也挂到这个网络，方便调试时用临时容器做连通性测试。不加这个参数，只有 swarm 服务能挂上去。创建后用docker network inspect my-overlay确认子网和驱动类型，输出里应该能看到"Driver": "overlay"和你指定的子网。

5.3 部署两个跨节点服务做连通性验证

部署一个后端服务和一个测试客户端，确保它们被调度到不同节点。可以用约束（constraint）强制分布：

docker service create \ --name backend \ --network my-overlay \ --replicas 1 \ --constraint 'node.hostname==node-a' \ --env BACKEND_PORT=8080 \ my-backend-image docker service create \ --name tester \ --network my-overlay \ --replicas 1 \ --constraint 'node.hostname==node-b' \ --tail 100 \ my-tester-image

部署后用docker service ps backend和docker service ps tester确认实际落在哪个节点。然后在 tester 容器里用服务名访问 backend：

docker exec -it <tester-container-id> sh # 容器内执行 nslookup backend curl http://backend:8080/health

nslookup应该返回 backend 服务的 VIP，curl应该能拿到健康检查响应。如果nslookup成功但curl失败，问题在数据面转发；如果nslookup就失败，问题在 DNS 或网络挂载。这个二分法能快速定位问题层次。

5.4 抓包确认封装行为

想真正看清 VXLAN 封装，可以在节点物理网卡上抓包：

tcpdump -i eth0 -n udp port 4789 -c 20

在 tester 里发起请求的同时抓包，应该能看到封装后的 UDP 包，外层是节点 IP，内层才是虚拟网络流量。这一步是理解 overlay 数据面最直观的方式，比看十篇文档都管用。抓包时注意，如果只看到同节点流量，说明测试容器没分布到不同节点，回到上一步检查调度结果。

6. 排查实录：那些让人抓狂的典型故障

6.1 跨节点不通但同节点正常

这是 overlay 网络最高频的故障。现象是同节点容器互访正常，跨节点就超时。排查顺序应该是：先确认两个容器确实在不同节点（docker service ps看节点归属），再确认节点间 UDP 4789 可达，最后看节点防火墙规则。

我遇到过一例，节点间 TCP 全通、UDP 4789 被安全组默认策略拦了，表现就是跨节点 overlay 完全不通。这种问题单看 Docker 日志毫无线索，必须从物理网络层查。所以我在 5.1 里强调先验证端口，就是为了避免走到这一步才发现。

6.2 服务名解析失败

nslookup 服务名返回失败，常见原因有三个：容器没挂到正确的 overlay 网络、服务名拼写或大小写问题、内嵌 DNS 被容器内的自定义 DNS 配置覆盖了。第三个最隐蔽——如果容器启动时指定了--dns或者镜像里改了/etc/resolv.conf，可能绕过 Swarm 的内嵌解析器。

排查方法是在容器内看/etc/resolv.conf，正常情况下应该有nameserver 127.0.0.11。如果没有，说明 DNS 配置被覆盖了，需要检查服务的 DNS 相关参数或镜像的启动脚本。

6.3 扩容后新副本短暂不可达

前面提过，这是控制面收敛的正常现象，不是故障。但如果持续不可达超过合理时间（通常几秒到十几秒），就要查了。可能原因包括：新任务所在节点与控制面通信异常、健康检查配置过严导致任务反复重启、资源不足导致任务起不来。

排查时先看docker service ps里任务的当前状态和历史状态，如果看到反复starting又failed，重点查健康检查和资源限制；如果状态是running但不可达，查节点连通性和数据面规则。

6.4 常见问题速查表

提示：排查 overlay 问题有个通用原则——先分层再定位。物理层（节点连通、端口）、虚拟网络层（子网、VIP）、服务层（DNS、健康检查）逐层排除，比一上来就翻 Docker 日志高效得多。

7. 生产环境里的取舍与经验

7.1 网络规模与性能的平衡

overlay 网络在节点数量增长时，控制面的 gossip 传播和数据面的转发规则规模都会增长。几十个节点的规模通常很稳，上百节点就要开始关注控制面压力和转发效率了。这不是说不能上大规模，而是要在架构上做规划，比如按业务域拆分多个 overlay 网络，避免单个网络过大。

另一个实际考量是封装开销。VXLAN 封装会增加每个包的头部，对吞吐敏感的服务要评估这个开销。大多数 Web 服务无感，但大流量传输类服务可能需要考虑 host 网络模式或者专门的网络方案。

7.2 安全边界不能只靠网络隔离

overlay 网络提供了网络层面的隔离，不同 overlay 网络之间默认不通。但别把网络隔离当成唯一的安全手段。同一 overlay 网络内的服务是互通的，一旦某个服务被攻破，横向移动的风险依然存在。生产环境要配合服务间的认证、最小权限原则、以及必要的网络策略，不能指望 overlay 隔离包打天下。

7.3 我踩过的几个坑

第一个坑是早期用固定 IP 做服务间配置，任务重建后 IP 变了，配置全失效。教训是永远用服务名，别碰虚拟 IP。第二个坑是测试环境单节点、生产多节点，overlay 跨节点路径从没验证过，上线才发现问题。教训是测试环境必须模拟多节点分布。第三个坑是排查时在物理网卡抓包看到封装流量一脸懵，后来才养成先分清抓包位置的习惯。

这些坑的共同点是：它们都不在文档的显眼位置，只有真正在多节点环境里跑过、出过问题，才会形成肌肉记忆。overlay 网络模型不难，难的是把"虚拟网络"和"物理网络"这两层在脑子里分清楚，排查时知道当前在哪一层。

后续如果要把这套环境往更复杂的方向扩展，比如多 overlay 网络互通、跨集群通信、或者和外部负载均衡器集成，核心思路还是这两层分离——先想清楚流量在哪一层、走哪条路径，再动手配。这个思维模型比记住任何具体命令都值钱。