Docker Swarm Manager节点深度解析：Raft共识与高可用实战

聊Docker Swarm，与其一上来就纠结怎么把几十台机器批量拉进集群，不如先把Swarm Manager这个角色彻底吃透。这个系列上一篇从整体架构看过集群的全貌，这一篇就把Manager节点单独拎出来讲——它到底管什么、凭什么选Leader、挂了以后会发生什么、生产环境里又该怎么搭怎么排查。适合刚接触Swarm的人，也适合已经在用但想把集群弄扎实的运维同学。

很多人在Swarm上栽跟头，不是不会敲那几条命令，而是没搞清Manager和Worker的分工边界。Manager不是简单地在机器上多跑一个进程，而是整个集群的决策中枢。如果这个中枢的选型和运维思路不对，后面不管加多少Worker节点，都是在给一个不稳定的地基添砖加瓦。

1. Swarm Manager到底在管什么——集群控制面核心拆解

1.1 一台Manager机器上到底跑着哪些控制逻辑

一个Swarm集群可以配置多个Manager节点，但无论有多少个，从外部看它们都像一个整体。Manager是集群的API入口：你敲的docker service create、docker node ls、docker network create这类命令，请求首先打在Manager上，由它决定怎么处理。Manager会把一个service的期望状态翻译成一个个具体的task，然后根据节点资源、标签约束、可用性状态，把task调度到合适的节点上执行。

这个调度的过程不是随机分配，背后有一套调度器逻辑。比如你声明一个服务需要3个副本，调度器会尽量把副本分散到不同节点上，避免单点故障。如果某个节点负载太高或被标记为Drain，调度器会绕开它，把task安排到其他可用的Worker上。副本挂了一个，调度器会立刻重新调度补齐，这就是Swarm作为编排器的核心自愈能力。

同时Manager负责维护整个集群的状态真相。这个“真相”包括：集群里有哪些节点、每个节点是什么角色、哪些service在运行、每个service下有几个副本、分别落在哪台机器上、overlay网络怎么划分、哪些secret已经下发到了哪些节点。这些数据不是放在某个集中式数据库里，而是全部走Raft协议复制到各Manager节点上。

这个设计初看有点绕，但背后逻辑很硬核：所有Manager读到的集群状态必须一致，否则调度就会乱套。假设Manager A认为某个节点是活的，Manager B认为它已经宕机，两边开始各干各的，整个集群就分裂了。Raft就是用来消灭这种不一致的。

我用一个生活化类比来解释。Manager团队类似公司的管理层，Worker是奔在一线干活的人。管理层负责接单、排计划、管人事、做决策，一线员工按指令执行。如果管理层里所有人同时失联，公司就失去了决策能力——哪怕一线员工还在照常劳动，也没人知道下一步该干什么、谁该去哪里。Swarm集群出现“节点明明活着但服务却没人调度”的怪象，多半就是Manager的quorum出了问题，这是后面要重点讲的部分。

1.2 Raft共识机制：Manager之间怎么保证状态一致

Raft是Swarm内部采用的共识算法，用来在所有Manager之间同步集群状态。它把service定义、网络配置、secret、节点注册信息这些控制面数据，全部以追加日志的形式记录。Leader节点负责接收所有写请求，把一条日志复制给其他Manager，超过半数确认后才真正提交。任何读请求看到的都是已经提交过的状态，因此不会出现某台Manager还在拿旧数据做决策的情况。

不需要你把Raft的所有论文细节背下来，但有两个关键词必须清楚：term和quorum。term是选举任期，Leader挂了或失联后，其他Manager会在心跳超时后发起新一轮选举，获得多数选票的节点成为新Leader。quorum则是法定多数，一个写请求必须得到超过半数的Manager确认才能真正生效。

日常运维中你会观察到一件事：Manager节点数量必须保持奇数，这和安全一点关系没有，纯粹是数学问题。两个Manager各持己见时，谁也凑不齐多数，集群会直接拒绝服务。三个Manager时，任何一个挂了，剩余两个能凑出2/3的多数，继续干活。五个Manager时，允许同时挂两个，剩余三个仍然过半。这个规则后面会列表展开。

1.3 Manager默认也是Worker，这个双重身份很微妙

有一个很容易忽略的点：每个Manager节点默认都会参与task运行。也就是说，swarm-manager这台机器上既能做控制面，也能跑你的业务容器，和普通Worker一样参与工作负载。这意味着如果业务负载很高，会挤占控制面资源；反过来控制面一旦抖动，也会影响上面跑着的业务容器。

生产上常见的做法是把Manager节点的Availability设为Drain，让它不再接收新task，也不执行业务容器。命令很简单：

docker node update --availability drain swarm-manager-01

不过在小规模环境里，尤其节点总数只有三五台时，很多人不舍得把这台机器完全空置，也会在Manager上跑一些轻量服务。这种做法不是不行，但前提是你要明白自己在做什么：Manager节点上跑的负载越重，控制面响应越容易被拖慢，Raft心跳和数据同步的稳定性都会受影响。我见过一个小团队在Manager上跑了一堆批处理任务，结果集群状态同步经常延迟，service变更要等半天才生效。后来把负载挪走，问题立刻消失。

2. 动手之前先把这几个概念吃透：quorum、节点状态与选举机制

2.1 为什么Manager数量总是奇数

先给出一张最实用的对照表，建议直接存下来：

先说两节点的情况，这是我最想劝退的配置。两台Manager看起来是冗余，实际是个坑：任何一个挂了，剩下那台永远凑不齐2/2的多数，控制面直接锁死。两节点不比单节点可靠，却比单节点多一倍的维护量，还要处理两台之间的状态同步。

三节点是最常用的生产形态，能容忍一台Manager故障。故障发生时，剩余两台可以达成多数，选出新Leader继续服务。五节点适合对可用性极其敏感的部署，能容忍两台同时挂掉，但每次写操作都要复制到至少三台机器，Raft同步的次数翻倍，网络开销和响应延迟都会上升。个人经验是，绝大多数业务用到三Manager已经非常稳，盲目上五节点只会给自己添麻烦。

2.2 看懂docker node ls的状态列

很多新手看到docker node ls的输出就懵，其实只要把四列状态剥开，集群健康状况一眼就能看清。

Leader就是当前集群的决策者；Reachable表示这是一台在线且能参与投票的Manager；Unreachable表示这台Manager已经和其他Manager失去联系，哪怕它本机上的docker进程还活着，控制面也认为它不可用。如果你看到某个节点的MANAGER STATUS变成了Unreachable，优先检查网络而不是急着重启。

有一个细节容易踩坑：当一个集群丢失quorum后，docker node ls这条命令本身都可能执行不了，会直接报错。这不是命令坏了，而是控制面已经进入自我保护模式。后面第3节会专门演示这个场景。

2.3 安全机制：证书轮换与自动锁

Swarm从初始化起就内置了一套CA体系。Manager节点保存CA根证书和私钥，并为每个节点签发短期证书。节点证书默认有效期是90天，到期前会自动轮换。如果节点长期处于Down状态再恢复，或者整机时间出现跳变，证书可能已经过期，这时重新加入集群就会报证书校验错误。

对于安全要求高的环境，建议开启autolock。开启后，Swarm用于加密Raft日志和通信的密钥不会明文落在磁盘上，Manager节点重启时必须输入解锁密钥才能恢复参与集群。命令如下：

docker swarm init --autolock # 或者对已有集群 docker swarm update --autolock=true

记得把解锁密钥保存到安全的地方，比如密码管理器或离线存储。一旦弄丢，节点重启后就再也无法解锁，只能重建整个集群。这个教训是用钱换来的。

2.4 顺带澄清一个高频混淆项

搜索Swarm相关资料时，会看到一些前后端开发框架也管自己叫Swarm，经常出现agent、handoff、上下文变量这类词。这和Docker Swarm完全是两码事。后者是容器编排调度系统，agent指的是Swarm节点上负责拉取并启动task的执行组件，不需要单独安装，docker引擎内部就集成了。而某些AI编程框架里的agent、handoff和上下文变量，是模型调度和任务移交的概念。读资料时先分清技术栈，不然会被带偏。

3. 三节点Manager集群实测：初始化、扩容与故障演练

3.1 初始化第一个Manager节点

准备三台Ubuntu服务器，IP分别是192.168.1.10、192.168.1.11、192.168.1.12，登入第一台执行：

docker swarm init --advertise-addr 192.168.1.10

--advertise-addr这个参数非常关键。如果机器上有多个网卡，不指定的话Docker可能选错IP，导致其他节点根本找不到它。初始化成功后屏幕上会直接给出一段docker swarm join命令和token。

token分两种：worker token用来加入普通Worker节点，manager token用来扩容Manager。不要把token当普通文本随手扔进聊天记录或代码仓库，拿到manager token的人等于拿到了往集群里加机器并参与控制面决策的入场券。

验证当前节点状态：

docker node ls docker info --format '{{.Swarm.LocalNodeState}}'

docker node ls输出里，第一台节点会同时显示为Leader，这是Swarm集群刚刚诞生时的默认状态。

3.2 扩容到三个Manager

在第二台和第三台上分别执行：

docker swarm join --token <manager-token> 192.168.1.10:2377

回到第一台再执行docker node ls，会看到三台都处于Ready状态，MANAGER STATUS列分别显示Leader和两个Reachable。这时三节点控制面正式形成。

扩容后建议顺手验证一下节点间的Raft同步状态，可以在任意Manager上查看：

docker system info | grep -A 5 Swarm

正常输出会包含"Managers: 3"这类信息。如果显示的数量不对，说明join过程有问题，或者某个Manager没有完全完成初始化。

3.3 模拟Leader故障：观察选举过程

三节点就绪后，我习惯做一次故障演练。先在当前Leader节点上执行：

sudo systemctl stop docker

然后到另一台Manager上执行docker node ls。第一次刷新时，原来的Leader可能还显示为Ready或Unreachable，需要等待心跳超时后才能看到状态变化。再过一段时间，会发现原来的Leader变成Down，MANAGER STATUS变成Unreachable，同时剩下两台Manager中有一台被提升为新的Leader。

这个实验能治疗“Leader挂了一切完蛋”的焦虑。只要剩余Manager能凑出多数，新Leader会在几十秒内产生。已经调度好的业务容器会继续运行，只有正在等待调度的task会暂停，等新Leader产生后继续处理。

这里要说清楚一点：我用systemctl stop docker来模拟故障，属于比较极端的场景，因为docker引擎停止后，这台机器上跑着的容器也会一起停。如果只想模拟Manager进程不可用而不影响业务容器，可以制造网络分区或用防火墙阻断2377端口，实际生产环境中要区分故障类型，不要上来就重启一切。

3.4 主动制造一次丢quorum：把集群锁死再恢复

接着刚才的实验继续往下做。此时集群只剩两台Manager在线，Leader已经从原节点切换到其中一台。现在在剩余两台Manager中再停掉一台：

sudo systemctl stop docker

这时在线Manager只剩一台。它永远无法凑出多数，控制面进入quorum保护状态。在唯一存活的Manager上执行docker node ls，大概率会看到类似报错：

Error response from daemon: rpc error: code = Unknown desc = The swarm does not have a leader. It can be restarted with --quorum-loss-recovery, but only if it is the last remaining manager.

第一次遇到这个报错的人基本都会慌，以为集群废了。其实Swarm是在主动防脑裂：控制面宁可不可用，也不能让多个Manager各执一词做出不一致的决策。恢复方法很简单，把停掉的节点逐个拉起来：

sudo systemctl start docker

等节点重新加入、quorum恢复，docker node ls会自动恢复正常。这个实验建议每个Swarm管理员都亲手做一次，体会“锁死—恢复”的感觉，真出问题时你就不会手足无措。

4. 生产环境最常见的Manager故障排查实录

4.1 节点Join失败、互相失联，先查端口清单

Swarm集群控制面依赖三个端口，缺一个都可能出现诡异问题：

我排查过多起“join命令明明执行了却没反应”的案例，基本都是2377端口被防火墙拦了。另外还有一种很隐蔽的情况：两个节点能正常join，节点状态也是Ready，但跨宿主机的容器之间就是ping不通。这种大概率是4789这个VXLAN端口不通导致的，节点状态健康，但数据面已经断了。

逐个检查端口的命令如下：

nc -vz -w 3 192.168.1.10 2377 nc -uvz -w 3 192.168.1.10 4789

放行端口命令，Ubuntu用ufw，CentOS/RHEL用firewalld，云主机还要同步检查安全组规则：

ufw allow 2377/tcp ufw allow 7946/tcp ufw allow 7946/udp ufw allow 4789/udp

4.2 Raft日志报错与磁盘空间

Manager节点的日志里会出现一些让人头大的信息，常见几类包括：心跳超时、leader缺失、raft日志无法提交、快照压缩失败。这些问题的根源高度集中在两个地方：磁盘空间不足和IO延迟过高。

Raft日志会定期做快照压缩，但如果磁盘写满，日志就写不进去，集群表现为所有写操作卡住，service scale、node update这类命令全部超时。这类故障的排查方法不复杂，先看磁盘：

df -h df -i

第一行看空间，第二行看inode。很多容器把日志直接写到宿主机目录，时间久了inode耗尽，df显示还有空间，但什么都写不进去。给Manager节点规划独立的日志目录并配置轮转，是非常值得做的预防措施。

4.3 节点证书过期

Swarm节点证书默认有效期90天，到期前会自动轮换。但如果一个节点长期处于Down状态，重新恢复时证书可能已经过期，表现为节点状态在Ready和Down之间反复横跳，Manager日志报证书校验失败。

遇到这种情况，先把节点从集群中摘除再重新join是比较快的办法。不过更建议从源头控制：把证书有效期调到更合适的周期。

docker swarm update --cert-expiry 720h

注意这个命令修改的是后续轮换周期，已经签发的证书不会立刻更新。所以在节点证书即将到期之前调整才有意义，等证书已经过期再去改，解决不了眼下的问题。

4.4 Docker Desktop与虚拟化支持问题

不少人在Windows上用Docker Desktop做本地开发，顺手想练Swarm。结果经常卡在一个经典报错上：

Docker Desktop failed to start because virtualisation support was not detected

这个报错的高频原因有三个：BIOS里没开虚拟化、Windows功能里没启用虚拟机平台、WSL2环境不完整。排查顺序建议先重启进BIOS开启VT-x或AMD-V，然后在“启用或关闭Windows功能”里勾选“虚拟机平台”和“适用于Linux的Windows子系统”，再安装或更新WSL2内核，最后重启电脑再启动Docker Desktop。

有一点要说清楚：Docker Desktop只会把本机当作单个Swarm节点，本地开发验证单Manager没问题，但想练多Manager高可用，还是老老实实开三台虚拟机或物理机。在Docker Desktop里强行模拟多节点集群，只会学到一堆错觉。

5. Manager节点规模怎么定：从单节点到五节点

5.1 不同规模的选择表与反直觉结论

核心结论一句话：Manager数量不要贪多，根据风险承受能力和集群规模来定。参考选择表：

“高可用”三个字不是免费午餐。每增加一个Manager，所有写操作都要复制到更多的节点上，网络延迟和磁盘IO的负担都会上升。个人经验，三节点Manager跑几十个Worker、几百个service的集群完全够用。五节点更多的是一种姿态上的高可用，实际使用中，两个Manager同时故障的概率极低，真正需要关注的是把三个Manager的稳定性维护好。

5.2 值得长期坚持的运维习惯

第一，生产环境默认把所有Manager节点设为Drain。控制面资源要纯净，不要让业务容器去抢占Manager的CPU和磁盘IO。这个原则在规模变大之后尤其重要。

第二，把token和备份当成资产管理。manager token泄露就等于把集群钥匙交出去，备份则主要覆盖Manager节点的数据目录和autolock解锁密钥。关键信息丢了，恢复成本往往会高过重建。

第三，定期做故障演练。每季度人为停一台Manager，确认选举能自动完成。没演练过的集群，故障真正发生时，你在恐慌中敲出的命令往往只会让局面更糟。演练的意义不只是验证Swarm，更是训练自己在异常状态下保持冷静。

最后再分享一个实际体会。有一次我在三节点集群上做演练，直接把Leader机器的docker服务停掉，结果新Leader迟迟没有出现，查日志发现那台机器磁盘快写满了，Raft日志提交超时，快照压缩也卡着不工作。清理磁盘、配好日志轮转之后，再演练就非常顺利。从那次以后，我看任何Swarm集群的第一动作永远是三件事：确认Manager数量是奇数、检查磁盘和inode、再看一遍节点状态。这三条比任何高深的调优都管用。