Docker Swarm节点标签与调度策略：从约束到放置偏好的完整实践指南

如果你维护过一套上了规模的 Swarm 集群，一定经历过这种场景：所有节点看起来都一样，调度器也“一视同仁”，于是数据库任务被扔到了高负载的 Web 节点上，异步任务跑到了 GPU 机器上，整个集群忙闲不均，排查时还得先搞清楚哪个节点是干嘛的。靠人肉记节点名不是长久之计。Docker Swarm 的节点标签（node labels）和调度策略，就是用来解决这个问题的：先把节点的“身份”写清楚，再用约束（constraints）和放置偏好（placement preferences）让任务按规则落位。这篇文章我会用 10 个完整可复制的例子，把标签从创建、查看、更新、删除，到约束调度、拓扑分布，再到节点下线的整个生命周期串起来，适合正在维护 Swarm 集群、想摆脱“玄学调度”的运维同学参考。

1. 先从一件小事说起：Swarm 调度器凭什么决定任务放哪

1.1 默认调度逻辑其实很“直男”

Swarm 调度器的默认行为很简单：在满足资源需求的节点里挑一个“最空闲”的，然后把任务放上去。所谓最空闲，主要看可用内存，加上一点点随机性避免所有副本挤在同一台机器。这套逻辑在没有特殊诉求的测试环境里够用，可一旦上了生产，问题立刻暴露：你没法告诉调度器“支付服务必须靠近数据库”“有 GPU 的节点只给模型推理任务用”“带 SSD 的机器才准跑 Redis”。节点在调度器眼里仅仅是一个个资源池，没有任何业务语义。

这时候就需要给节点打标签。标签本质上是挂在节点对象上的键值对，它把节点的物理属性或者业务身份变成调度器能理解的语言。加一个role=web，调度器就知道这台机器是干 Web 的；加一个disk=ssd，调度器就知道往这里分配 IO 敏感型任务。整个机制并不复杂，真正的复杂度在于怎么设计标签、怎么让标签和约束配合，以及怎么在节点整个生命周期里维护好这些标签。

1.2 标签才是让调度器读懂拓扑的第一语言

节点标签分两种来源。一种是 Docker 引擎启动时通过--engine-label写入，比如dockerd --engine-label=disk=ssd，这种标签偏“物理属性”，从引擎层面就固定了。另一种是 Swarm 层面的动态标签，通过docker node update --label-add添加，它存储在 Swarm 的节点规格（Spec)里，可以随时改，更适合表达“角色、环境、可用区”这类会发生变化的业务属性。调度器在做放置决策时，这两种标签都能参与约束匹配，但对运维来说，我习惯把物理属性交给引擎标签，把业务属性交给运行时标签，职责干净，后面看标签也不会搞混。

标签在调度里到底怎么起作用，可以类比成人事的简历筛选。约束就是硬性条件，比如“只要带role=web标签的节点”，不满足的节点直接排除。放置偏好则是软性倾向，比如“尽量把副本分散到不同的zone标签里”，实在没有别的选择，调度器也会允许落在同一区域。搞清楚“硬约束”和“软偏好”的区别，是整个调度策略的地基。

1.3 标签生命周期的三个关键阶段

很多人以为标签管理就是“加一下、用一下”，实际上它是有生命周期的：节点加入 Swarm 前或刚加入时，要设计好标签并批量初始化；服务运行期间，标签会随着业务调整不断增删改，同时影响后续任务的调度；节点快要下线时，又得考虑标签对应的服务是否还有依赖，避免清理完标签后任务无处可去。把这三个阶段理顺，调度策略才能稳定。接下来，我按这个顺序逐个演示，每一个例子都是命令行实测过的基础操作，你可以直接照着敲。

2. 节点标签的增删改查：生命周期前半段实操

2.1 示例1：给新节点打上环境、角色、磁盘标签

假设你刚把一台新机器加入 Swarm，节点名是node-01，它要承担线上环境的 Web 服务，并且装了 SSD。先用docker node update把标签写进去：

docker node update \ --label-add env=production \ --label-add role=web \ --label-add disk=ssd \ node-01

这条命令会同步修改 Swarm 里node-01的Spec.Labels。执行完没有任何回显是正常的，需要用docker node inspect确认：

docker node inspect node-01 --format '{{json .Spec.Labels}}'

输出大概是：

{"disk":"ssd","env":"production","role":"web"}

注意一点，--label-add不是先删后加，同一个键如果之前存在，会直接覆盖。所以打标签这个操作天然支持“改了再覆盖”，不需要额外做清理。这里我把环境、角色、磁盘三个维度分开打，是刻意的：环境用来隔离不同业务环境，角色用来决定服务类型归属，磁盘类型则面向资源敏感型应用。你还可以按自己的拓扑结构增加zone=az1、gpu=true这类标签，原则是“标签能准确回答调度问题”。

2.2 示例2：改标签和删标签的正确姿势

线上环境里业务是流动的，这台机器这周跑 Web，下周可能被调去跑 API 网关。节点角色变了，调度约束自然要跟着变。先用一个组合命令把role=web改成role=api，并顺手删掉不再需要的disk=ssd：

docker node update \ --label-rm role \ --label-add role=api \ --label-rm disk \ node-01

--label-rm只需要写键名，不需要写值。它可以跟--label-add写在同一条命令里，Swarm 会先处理删除，再处理新增。用这个方式改标签非常顺滑，不会出现中间状态。不过要提醒一句：改标签只影响“之后新创建或重新调度的任务”，已经在node-01上跑着的容器不会自己搬走。这一条后面我还会展开讲，因为它坑过不少人。

2.3 示例3：用 inspect 加 jq 快速盘点全集群标签

节点多了以后，不可能一台一台 inspect。我常用的一种方式是遍历所有节点 ID，把标签统一拉出来，再用jq整理成表格。下面的命令在 Linux shell 下执行：

docker node ls -q | xargs docker node inspect \ | jq -r '.[] | [.ID[0:12], .Description.Hostname, (.Spec.Labels // {} | to_entries | map("\(.key)=\(.value)") | join(","))] | @tsv'

这条命令的实质是：先拿到所有节点 ID，用xargs批量查询详情，再用jq把节点 ID、主机名、标签拼成一行 TSV。输出效果类似：

abc123def456 node-01 env=production,role=api abc123def789 node-02 env=staging,role=worker

这里用// {}处理了没有标签的节点，避免jq因为空值直接报错。养成定期盘点的习惯很重要，尤其是经历过几次大调整之后，你会发现有些节点的标签已经没人记得是什么含义了，趁早清理掉，后面加约束时才不会误判。

2.4 示例4：批量初始化节点的命名规范

一次性加入几十个节点时，逐个打标签不现实。我会先把节点清单和标签规则写在 shell 循环里，比如给node-01到node-03都打上zone=az1：

for i in 01 02 03; do docker node update \ --label-add zone=az1 \ --label-add role=worker \ "node-$i" done

如果你希望标签信息来自一个文件，也可以用while read：

cat nodes.csv | while IFS=, read node zone role; do docker node update \ --label-add zone="$zone" \ --label-add role="$role" \ "$node" done

nodes.csv里每行是node-01,az1,worker这种格式。批量脚本最适合在节点刚加入 Swarm 时跑一遍，把基础设施“初始化”好。这里我要特别强调命名规范：所有环境用同一个标签键env，值用production/staging/dev；所有角色用同一个标签键role，值用web/api/worker/db。如果一套集群里有人写Environment=prod，有人写env=production，后面写约束时会被活活逼疯。

下面用一张表把标签管理的日常操作整理出来，方便复制：

3. 调度约束实战：把服务“钉”到该去的节点上

3.1 约束的基本写法和运算符

约束（constraints）是docker service create时最常用的调度条件。基本写法是放在--constraint参数里，常见运算符有==（等于）、!=（不等于）。键名可以引用节点标签，比如node.labels.role==web，也可以引用节点的其他属性，比如node.hostname==node-01、node.platform.os==linux、node.role==manager。多个约束条件是“且”的关系，也就是说每个条件都得满足，任务才可能落在某个节点上。

这里我特别想强调一点：约束是硬过滤，不是评分。调度器在选节点时，会先把不满足约束的节点全部划掉，再从剩下的节点里按资源情况挑。所以约束越多，候选节点池越小，如果用了一个只有一台节点满足的约束，调度器几乎没有任何弹性空间，一旦这台节点出问题，服务就会一直 pending。

3.2 示例5：按角色约束部署 Web 服务

接前面的标签场景，我要把nginx服务只调度到打了role=web的节点上：

docker service create \ --name nginx-web \ --constraint 'node.labels.role==web' \ --replicas 3 \ nginx:1.27-alpine

创建之后，用docker service ps看任务落点：

docker service ps nginx-web --format 'table {{.Name}}\t{{.Node}}\t{{.CurrentState}}'

理想状态下三份副本只会在node-01这类带role=web标签的节点上创建。像node-02这种没这个标签的机器，即使资源再多，调度器也不会选择它。这层过滤发生在调度阶段，跟运行时的资源占用无关，所以约束的匹配非常稳定。

常见的一个骚操作是把约束写成node.labels.role!=web，意思是“除了 Web 节点，其他都能跑”。这种写法适合“避开某一类机器”的需求，比如有 GPU 标签的节点只留给训练任务，其他普通服务用!=避开它们。但用!=时务必确认其他节点确实满足服务的资源要求，否则照样 pending。

3.3 示例6：约束+资源限制组合部署缓存服务

约束解决的是“能去哪”，资源限制解决的是“去了之后能用多少”，两者组合起来才是完整的调度策略。下面这个例子要部署一个 Redis 缓存服务，要求只能落在disk==ssd的节点上，并且每个容器最多用 4GB 内存、2 个 CPU：

docker service create \ --name redis-cache \ --constraint 'node.labels.disk==ssd' \ --limit-memory 4g \ --limit-cpu 2 \ --replicas 2 \ redis:7.2-alpine

这里--limit-memory和--limit-cpu不只是运行时的 cgroup 限制，它们也会参与调度计算。调度器在分配节点时，会把候选节点上的已用内存加上这个服务的预估内存，再跟节点总内存比较，放不下就换下一个节点。约束负责圈定范围，资源限制负责在范围内做二次筛选，两手都要抓。

部署完可以通过docker service ps redis-cache查看每个任务落在哪个节点。如果我发现本该落在 SSD 节点的任务出现在普通节点，大概率是节点标签写错了，而不是调度器抽风。排查时要先检查标签，再检查约束，这个顺序能省不少时间。

3.4 示例7：没有任何节点满足约束时，调度器不会静默

这是新手最容易慌的场景。你创建了一个带约束的服务，然后docker service ps看到任务一直显示Pending，下面一行小字写着类似no suitable node的信息。示例 7 就直接演示这种情况：

docker service create \ --name pending-demo \ --constraint 'node.labels.gpu==true' \ --replicas 1 \ busybox:1.36 sleep 3600

如果当前集群没有任何节点带gpu=true标签，这个服务会一直处在 pending 状态。它不会报错退出，也不会自己取消，就这么一直等。这其实是 Swarm 调度器的“诚实”：它决不把任务放到不满足条件的节点上。遇到这种输出，先检查是不是标签键或者值写反了，再看是不是对应节点被drain了。用docker service ps pending-demo --no-trunc能看到完整原因。

4. 放置偏好与拓扑分布：从“能不能跑”到“怎么跑得匀”

4.1 约束和偏好的区别：一硬一软

约束的缺点是太“硬”，一旦条件苛刻，任务就只有极少数节点可选。放置偏好（placement preferences）给了调度器第二层能力：它不限制节点范围，只影响调度器在可选范围内的排序和分布。打个比方，约束是“必须在有 SSD 的机器上跑”，偏好是“三个副本最好落在三个不同的机柜”。约束决定生死，偏好决定质量。

Docker Swarm 里最常用的偏好是spread，它会尽量把任务分散开，避免堆在一起。另一个是maxpernode（Compose 里叫max_replicas_per_node），用来限制单个节点上最多放几个副本，这两个我分别用示例说明。

4.2 示例8：spread 偏好让副本跨区域分布

假设节点都打了zone标签，有的在az1，有的在az2，我要部署一个 6 副本的 API 服务，希望它尽量均匀分布到两个可用区。可以这样：

docker service create \ --name api-gateway \ --replicas 6 \ --placement-pref 'spread=node.labels.zone' \ nginx:1.27-alpine

调度器在放置每个副本时，会优先选择当前“同 zone 副本数最少”的节点，这样 6 个副本大概率会变成 az1 三份、az2 三份。如果某个 zone 里的节点资源不足，调度器也会把任务放去另一个 zone，毕竟偏好不是强制约束，不会因为分布不均就一直 pending。

这里我要提一个容易忽略的点：spread的粒度取决于你给的标签值。如果用spread=node.id，每个节点都会被视为一个独立的“桶”，副本会尽量分散到不同节点上，这相当于节点级别的反亲和。用它做“互不干扰”非常顺手，但副本数远大于节点数时，调度器也只会把任务按顺序轮转放满，别指望它能做复杂的负载均衡。

4.3 示例9：max_replicas_per_node 限制单机密度

有些场景我不关心跨可用区分布，只担心一个节点上被打进太多副本，比如消费者服务，一个节点塞上 5 个进程会互相抢 CPU。这时候可以用max_replicas_per_node在 Compose 文件里控制密度。先写一个stack.yml：

services: worker: image: busybox:1.36 command: sleep 3600 deploy: replicas: 6 placement: max_replicas_per_node: 2

然后执行 stack 部署：

docker stack deploy -c stack.yml worker-app

这个配置的意思是：整个服务最多允许 6 个副本，但是任何一个节点上最多只能有两份。如果集群只有两个节点，每节点两份，正好四份，剩下的两份会处于 pending 状态，因为已经找不到还能再放副本的节点了。这类限制在消息队列消费者、定时任务这类场景里特别有用，能直接避免“热点节点”。

5. 全生命周期组合实操：一个从上线到下线的完整串联

5.1 示例10：完整生命周期脚本化流程

前面 9 个例子都是单项操作，最后一个例子，我把整个生命周期串起来：从新节点加入、打标签、部署受限服务、扩容、改约束、清标签，到最后把节点从 Swarm 移除。假设要扩容一台node-08，专门跑批处理任务：

# 节点加入 Swarm（假设 join token 已准备好） docker swarm join --token <token> manager-ip:2377 # 打上批处理角色标签 docker node update --label-add role=batch node-08 # 部署只能跑在 batch 节点上的服务 docker service create \ --name batch-job \ --constraint 'node.labels.role==batch' \ --replicas 2 \ busybox:1.36 sleep 3600 # 业务高峰扩容 docker service scale batch-job=4 # 业务下线，撤销约束，让服务不再绑定特定节点 docker service update --constraint-rm 'node.labels.role==batch' batch-job # 清理节点标签 docker node update --label-rm role node-08 # 节点下线，排空并移出 Swarm docker node update --availability drain node-08 docker node rm node-08

这个流程里每一步都有讲究。节点打标放到service create之前，是为了防止调度器创建任务时找不到合适节点。scale扩容时，调度器会基于最新标签状态重新分配，所以标签的实时性很重要。下线前先--constraint-rm，是让服务以后不再依赖role=batch这个标签；如果先删了标签再撤约束，某些运行中的副本不会立刻搬走，但新调度会发生混乱。最后drain节点，Swarm 会把该节点上的任务平滑迁移到其他可用节点，再node rm移除节点对象，节点上附带的标签也会一并消失。

5.2 多个命令组合的注意事项

组合操作时最忌讳“以为命令有先后依赖但实际没有”。比如docker node update修改标签是立即生效的，但它不会触发已有任务重新调度；docker service update --constraint-rm改变的是约束，也不会自动让任务搬走，需要配合docker service update --force才会触发滚动重新部署。很多事故就出在这：改了约束以为服务会自动迁移，结果所有副本继续留在原节点，直到节点故障才发现服务没法启动。

所以在全生命周期流程里，我建议每个阶段分开执行、分开验证。加标签后先 validate，加约束后看docker service ps，扩缩容后观察当前状态，撤约束后再决定要不要强制更新。每一步都看得见，出了问题能快速定位到是哪一步引起的，比一口气敲完十条命令要稳妥得多。

6. 运维边界与常见坑：调度器不会自动收拾的烂摊子

6.1 标签改了，运行中的任务不会自己搬家

这是我反复强调的一点，也是很多人对 Swarm 调度的最大误解。docker node update --label-add role=api node-01只影响之后新创建的调度决策，已经跑在node-01上的任务，无论之前是通过什么约束放上去的，都不会因为标签变化而自动迁移。如果你想在所有带role=web标签的节点之间重新均匀分布现有任务，最干脆的办法是：

docker service update --force --constraint-add 'node.labels.role==web' nginx-web

这会触发一次滚动重新部署，每个任务重新走一遍调度流程，然后按最新标签落点。用户对这个操作要有预期：它会先启动新任务，再把旧任务停掉，所以短时间内容器数量会超过副本数，流量较大的服务要注意带宽和端口冲突。

6.2 不要用 node.id 这种一次性标识做约束

我用node.id做过一次约束，后来就被折磨了：节点如果从 Swarm 移除再重新加入，node.id是会变化的，所有依赖旧 ID 的约束全部失效，服务全部 pending。标签比 ID 稳定得多，业务约束应该使用标签这种语义化标识，而不是节点物理 ID。就算节点换了一台新物理机，只要标签不变，服务就能自动落位到新的目标节点上。所以约束里尽量写node.labels.xxx，少写node.id==...，少写node.hostname==...，这两个键值在节点生命周期里都太脆了。

6.3 维护操作与标签的配合顺序

节点要重启或者维护时，正确的顺序是先docker node update --availability drain node-01，把节点上的任务迁移走，再执行物理维护。drain会把这个节点的状态置为不可调度，并把任务挪到其他满足约束的节点。如果这个节点有独占标签，而集群里没有其他同类节点，任务就会 pending，这反而是个有用的信号：它说明你的服务缺少容灾节点，该补了。

维护结束后，执行docker node update --availability active node-01恢复节点调度能力。这时标签还在，服务也不会自动补回来，因为 Swarm 只保证“当前任务数达到期望值”，不保证“每个节点上都均匀铺满任务”。如果你想让恢复后的节点重新分担一些任务，只能通过docker service update --force或者手动扩缩容触发重新调度。

6.4 其他高频误用点

最后集中说一下我在实际运维里见到的几个高频误用点。

约束值一定别带多余空格。node.labels.role == web看起来没啥问题，但 Swarm 会把整串当作一个表达式，空格可能导致匹配失败。建议统一写成node.labels.role==web，不带空格。

多个标签键值别混到同一个约束里。--constraint 'node.labels.role==web' --constraint 'node.labels.env==production'是“且”；如果你把两个条件写进一个约束字符串里，用空格或者逗号分隔，大概率会解析失败。老老实实一个条件一个--constraint，最省心。

还有，给节点打标签时最好有“唯一负责人”。我看到过的混乱集群，多半是不同人按自己的习惯打标签，最后同一套 Swarm 里出现了role=api、type=api、service=api三种写法。标签虽然是运维手段，但它直接决定调度策略的可读性和可维护性，所以建议把标签字典写进团队的运维文档里，字段名、候选值都固定下来，后续新增服务只用查表。

我自己在维护集群时的体会是：节点标签这套东西，设计比执行重要，命名规范比命令熟练更重要。10 个例子跑完，你会对“标签在调度决策中的角色”有更具体的认识，也更容易在出问题时第一眼判断是标签没打对、约束写错，还是调度器正在等一个满足条件的节点。先把标签体系建好，Swarm 调度就没那么玄了。