掌握 `docker stack`:用 Compose 编排并运维 Swarm 集群栈

原创2026-10-12 01:19:302,961 阅读
文章标签:容器运行时云原生

掌握 docker stack:用 Compose 编排并运维 Swarm 集群栈

docker stack 是 Docker CLI 提供的集群级编排命令,它把一份 Compose 文件转化为运行在 Swarm 集群上的一组服务、网络、密钥与配置,并支持部署、查看、删除的完整生命周期管理。本文以 stack.md 为主线,结合仓库中 components/cli/cli/command/stack/ 的源码实现,系统讲解 stack 家族五个子命令的用法、参数含义与底层工作原理,读完即可独立完成一次从部署到清理的完整栈运维。

docker stack 命令概览

docker stack 是 Docker 1.25+ 引入的集群管理命令,核心思想是“用一个 Compose 文件定义一整套应用”,随后由 CLI 把其中的服务、网络、密钥、配置转换为 Swarm 集群中的对应资源,并统一打上命名空间标签以便追踪与回收。

命令总览(来自 stack.md):

Usage:  docker stack [OPTIONS] COMMAND

Manage Docker stacks

Options:
      --help                  Print usage
      --kubeconfig string     Kubernetes config file
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)

Commands:
  deploy      Deploy a new stack or update an existing stack
  ls          List stacks
  ps          List the tasks in the stack
  rm          Remove one or more stacks
  services    List the services in the stack

Run 'docker stack COMMAND --help' for more information on a command.

其中 deploy(别名 up)、rm(别名 remove、down)、ls(别名 list)都提供了符合直觉的别名,方便从 Compose 生态迁移。

编排器(orchestrator)的解析逻辑

--orchestrator 决定 CLI 把栈部署到哪种编排平台。从源码 cmd.go 看,NewStackCommand 在 PersistentPreRunE 中调用 getOrchestrator,最终交给 dockerCli.StackOrchestrator(orchestratorFlag) 解析出 command.Orchestrator 枚举:

  • swarm:默认值,栈被部署为 Swarm 服务;
  • kubernetes:需要 Docker CLI 启用了 Kubernetes 集成功能(仓库内对应 stack/kubernetes 目录);
  • all:仅在 stack ls 中有效(同时汇总两个平台的栈),其余子命令会直接返回错误 no orchestrator specified: use either "kubernetes" or "swarm"(见 cmd.go 中的 errUnsupportedAllOrchestrator)。

checkSupportedFlag(cmd.go)会检查用户显式传入的 flag 是否与当前编排器匹配:例如在未启用 Kubernetes 的 CLI 上使用 --namespace,会报 "--namespace" is only supported on a Docker cli with kubernetes features enabled;同理 Swarm 专属的 --with-registry-auth 在 Kubernetes 编排下不可用。hideOrchestrationFlags 则会在帮助输出中隐藏不相关编排器的专属 flag。

注意:当前源码中 --kubeconfig、--namespace、--orchestrator 等编排相关 flag 均被标记为 deprecated(见 cmd.go 与 kubernetes/cli.go 的 SetAnnotation),即后续版本可能移除,推荐通过 Docker context 配置选择目标编排平台。

栈命名与命令入口

所有接受 STACK 参数的子命令都会先经过 validateStackName(common.go)校验——栈名不能为空,也不能只由空白字符或引号组成。每个子命令最终通过 runOrchestratedCommand(common.go)按编排器分派到 swarm.RunXxx 或 kubernetes.RunXxx 实现。

前置条件:在 Swarm 管理器节点上执行

stack 是一组集群管理命令,文档中明确要求必须在 Swarm manager 节点上执行。这一约束在源码层面也有强制校验:deployCompose 首先调用 checkDaemonIsSwarmManager(swarm/deploy.go),通过 /info API 检查 info.Swarm.ControlAvailable,若当前节点不是 manager 则直接报错:

this node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again

这是因为部署流程必须先创建全局(swarm 作用域)网络,而网络创建 API 在失败时无法返回正确的状态码,所以必须提前确认节点身份。关于 Swarm 模式的初始化与节点角色,可参考仓库内的 swarm.md。

docker stack deploy:部署或更新栈

用法与全部选项

Usage:  docker stack deploy [OPTIONS] STACK

Aliases:
  deploy, up

Options:
  -c, --compose-file strings  Path to a Compose file, or "-" to read from stdin
      --help                  Print usage
      --kubeconfig string     Kubernetes config file
      --namespace string      Kubernetes namespace to use
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)
      --prune                 Prune services that are no longer referenced
      --resolve-image string  Query the registry to resolve image digest and supported platforms
                              ("always"|"changed"|"never") (default "always")
      --with-registry-auth    Send registry authentication details to Swarm agents

各选项的源码定义集中在 deploy.go,其中 --compose-file(别名 -c,可重复)要求 API 1.25+,--prune 要求 1.27+,--resolve-image 要求 1.30+:

  • --compose-file:Compose 文件路径;传 - 表示从标准输入读取,支持一次传多个文件做配置合并;
  • --prune:部署完成后删除 Compose 中已不再引用的旧服务;
  • --resolve-image:控制是否查询镜像仓库解析 digest 与支持的平台,取值为 always(默认)、changed(仅镜像变更时解析)、never(不解析);
  • --with-registry-auth:把本地登录的私有仓库凭据一并下发给 Swarm agent,供拉取镜像使用。

三种部署方式

方式一:指定 Compose 文件(deploy 支持 Compose 3.0 及以上版本):

$ docker stack deploy --compose-file docker-compose.yml vossibility

Ignoring unsupported options: links

Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd

注意输出中的 Ignoring unsupported options: links:Compose 中不被 Swarm 支持的字段(如 links)会被安全忽略,而不是中止部署。

方式二:从标准输入读取,适合与 cat、模板引擎等管道配合:

$ cat docker-compose.yml | docker stack deploy --compose-file - vossibility

方式三:多文件合并,适合“基础配置 + 环境覆盖”的场景(例如 docker-compose.yml 定义通用服务、docker-compose.prod.yml 覆盖生产参数):

$ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml vossibility

部署后可用 docker service ls 验证服务是否创建成功(输出中的 REPLICAS 列展示“运行副本数/期望副本数”):

$ docker service ls

ID            NAME                               MODE        REPLICAS  IMAGE
29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
...

底层部署流程

源码 deployCompose 完整揭示了 deploy 的执行顺序:

  1. 校验当前节点为 Swarm manager;
  2. 用 convert.NewNamespace 建立命名空间(compose.go),后续所有资源名都会被前缀为 栈名_资源名;
  3. 若指定 --prune,先删除栈内不再引用的旧服务(pruneServices,见 swarm/deploy.go);
  4. 处理并创建网络(默认 driver 为 overlay,见 swarm/deploy.go),对 external 网络会先做存在性与 swarm 作用域校验;
  5. 创建/更新 secrets 与 configs(已存在则更新,不存在则创建);
  6. 转换并创建服务,最后 deployServices(deploy_composefile.go)依据 --resolve-image 与 --with-registry-auth 决定是否设置 QueryRegistry、是否携带 EncodedRegistryAuth。

一个关键实现细节:Compose 中的镜像会以 com.docker.stack.image 标签记录在服务上,changed 与 never 模式通过对比该标签判断镜像是否变化,从而决定是否向 registry 重新查询 digest(见 convert/service.go)。另外,当客户端 API 版本低于 1.30 时,RunDeploy 会强制把 ResolveImage 置为 never,避免向旧版 daemon 发送不支持的查询(见 swarm/deploy.go)。

Compose 文件的加载细节

CLI 通过 loader/loader.go 加载并解析 Compose 文件:

  • 未提供任何 --compose-file 时报错 Please specify a Compose file (with --compose-file);
  • - 从 stdin 读取,其余从文件读取;工作目录取首个 Compose 文件所在目录,用于解析相对路径的 build 上下文;
  • 多个文件依次解析,且要求首个文件的 Compose 版本生效;
  • 解析出的“不支持选项”会输出 Ignoring unsupported options: ... 警告,“废弃选项”会输出 Ignoring deprecated options: ... 警告,均不阻断部署。

docker stack ls:列出栈

用法与选项

Usage:  docker stack ls [OPTIONS]

Aliases:
  ls, list

Options:
      --format string         Pretty-print stacks using a Go template
      --kubeconfig string     Kubernetes config file
      --namespace string      Kubernetes namespace to use
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)

基础用法直接列出当前所有栈及其服务数量、编排器:

$ docker stack ls

ID                 SERVICES            ORCHESTRATOR
myapp              2                   Kubernetes
vossibility-stack  6                   Swarm

ls 是唯一支持 orchestrator=all 的子命令:RunList(list.go)会同时调用 swarm.GetStacks 与 kubernetes.GetStacks 并合并结果。

Swarm 侧的栈识别原理

swarm.GetStacks(swarm/list.go)通过过滤器 label=com.docker.stack.namespace 拉取全部栈服务,再按该标签值聚合计数得到每个栈的服务数量。这个标签正是部署时由 convert.AddStackLabel 写入的(compose.go),是整个 stack 体系识别、检索、回收资源的基石。

Go 模板格式化

--format 使用 Go 模板对输出进行格式化,合法占位符如下:

占位符 描述
.Name 栈名称
.Services 服务数量
.Orchestrator 编排器名称
.Namespace 命名空间(Kubernetes 编排)

不带表头、用冒号分隔输出的示例:

$ docker stack ls --format "{{.Name}}: {{.Services}}"
web-server: 1
web-cache: 4

表头与占位符的映射定义在 formatter/formatter.go:Swarm 默认表格格式为 table {{.Name}}\t{{.Services}}\t{{.Orchestrator}},启用 Kubernetes 后追加 \t{{.Namespace}} 列。源码中还额外暴露了 --namespace 与 --all-namespaces(Kubernetes 专属,标记为 deprecated)用于筛选命名空间,排序则采用自然排序(sortorder.NaturalLess,如 stack2 排在 stack10 之前)。

docker stack ps:查看栈中的任务

用法与选项

Usage:  docker stack ps [OPTIONS] STACK

Options:
  -f, --filter filter         Filter output based on conditions provided
      --format string         Pretty-print tasks using a Go template
      --kubeconfig string     Kubernetes config file
      --namespace string      Kubernetes namespace to use
      --no-resolve            Do not map IDs to Names
      --no-trunc              Do not truncate output
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)
  -q, --quiet                 Only display task IDs

docker stack ps <STACK> 列出指定栈中的所有任务(task,即服务的运行实例)。例如查看 voting 栈(来自 stack_ps.md):

$ docker stack ps voting

ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE          ERROR  PORTS
xim5bcqtgk1b        voting_worker.1       dockersamples/examplevotingapp_worker:latest   node2  Running        Running 2 minutes ago
q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 2 minutes ago
rx5yo0866nfx        voting_vote.1         dockersamples/examplevotingapp_vote:before     node3  Running        Running 2 minutes ago
tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 2 minutes ago
w48spazhbmxc        voting_redis.1        redis:alpine                                   node2  Running        Running 3 minutes ago
...

底层实现 swarm.RunPS(swarm/ps.go)用 label=com.docker.stack.namespace=<STACK> 过滤 TaskList,若栈内无任务则报错 nothing found in stack: <STACK>,随后复用 task.Print 完成格式化输出,其中 --no-resolve 通过 idresolver.New(client, opts.NoResolve) 决定是否将任务名、节点 ID 解析为可读名称。

过滤(-f / --filter)

过滤参数格式为 key=value,多个过滤条件以空格分隔的多个 flag 传入,且多个 filter 之间是 OR 关系(例如 -f name=redis.1 -f name=redis.7 会同时返回两个任务)。当前支持四种过滤器:

过滤器 说明 示例
id 匹配任务 ID 的全部或前缀 docker stack ps -f "id=t" voting
name 匹配任务名 docker stack ps -f "name=voting_redis" voting
node 匹配节点名或节点 ID docker stack ps -f "node=node1" voting
desired-state 取值为 running、shutdown、ready 或 accepted docker stack ps -f "desired-state=running" voting

格式化占位符

--format 支持以下任务占位符:

占位符 描述
.ID 任务 ID
.Name 任务名
.Image 任务镜像
.Node 节点 ID
.DesiredState 任务期望状态(running、shutdown、accepted)
.CurrentState 任务当前状态
.Error 错误信息
.Ports 任务发布端口

示例(无表头,输出 Name: Image):

$ docker stack ps --format "{{.Name}}: {{.Image}}" voting

voting_worker.1: dockersamples/examplevotingapp_worker:latest
voting_result.1: dockersamples/examplevotingapp_result:before
...

--no-resolve、--no-trunc 与 -q

  • --no-resolve:不做 ID 到名称的映射,任务名与节点直接显示为原始 ID:
$ docker stack ps --no-resolve voting

ID                  NAME                          IMAGE                                          NODE                        DESIRED STATE  CURRENT STATE            ERROR  PORTS
xim5bcqtgk1b        10z9fjfqzsxnezo4hb81p8mqg.1   dockersamples/examplevotingapp_worker:latest   qaqt4nrzo775jrx6detglho01   Running        Running 30 minutes ago
...
  • --no-trunc:不截断输出。由于部署时 Docker 会把服务镜像固定(pin)到 digest,默认不展示,使用 --no-trunc 后镜像列会显示完整的 镜像@sha256:... 摘要,同时展示完整的任务 ID 与错误信息:
$ docker stack ps --no-trunc voting

ID                          NAME                  IMAGE                                                                                                                 NODE   DESIRED STATE  CURREN STATE           ERROR  PORTS
xim5bcqtgk1bxqz91jzo4a1s5   voting_worker.1       dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed   node2  Running        Runnin 32 minutes ago
...
  • -q / --quiet:只输出任务 ID,适合批量操作——例如把结果直接作为 docker inspect 的输入:
$ docker stack ps -q voting
xim5bcqtgk1b
q7yik0ks1in6
...

$ docker inspect $(docker stack ps -q voting)

docker stack services:查看栈中的服务

用法与选项

Usage:  docker stack services [OPTIONS] STACK

Options:
  -f, --filter filter         Filter output based on conditions provided
      --format string         Pretty-print services using a Go template
      --kubeconfig string     Kubernetes config file
      --namespace string      Kubernetes namespace to use
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)
  -q, --quiet                 Only display IDs
$ docker stack services myapp

ID            NAME            REPLICAS  IMAGE                                                                          COMMAND
7be5ei6sqeye  myapp_web       1/1       nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f
dn7m7nhhfb9y  myapp_db        1/1       mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539

多过滤条件同样是 OR 语义:

$ docker stack services --filter name=myapp_web --filter name=myapp_db myapp

过滤器及其双编排器支持矩阵

过滤器 用法示例 Swarm Kubernetes
id / ID --filter id=7be5ei6sqeye 支持 不支持
label --filter label=key=value 支持 支持
mode --filter mode=replicated / mode=global 不支持 支持
name --filter name=myapp_web 支持 支持
node --filter node=mynode 不支持 支持
service --filter service=web 不支持 支持

格式化占位符

占位符 描述
.ID 服务 ID
.Name 服务名
.Mode 服务模式(replicated / global)
.Replicas 服务副本数
.Image 服务镜像
$ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}"

0zmvwuiu3vue: replicated 10/10
fm6uf97exkul: global 5/5

实现细节

swarm.GetServices(swarm/services.go)在非 -q 模式下会请求 API v1.41+ 的 Status 字段获取任务统计;旧 API 版本则由 service.AppendServiceStatus 通过额外请求补齐“运行/期望副本数”。若栈内没有任何服务,会输出 Nothing found in stack: <STACK> 并以退出码 0 结束(services.go),这与 stack ps 的报错行为不同。另外 formatWrite 支持读取 CLI 配置文件(~/.docker/config.json)中自定义的 servicesFormat 作为默认输出模板。

docker stack rm:删除一个或多个栈

用法与选项

Usage:  docker stack rm [OPTIONS] STACK [STACK...]

Aliases:
  rm, remove, down

Options:
      --help                  Print usage
      --kubeconfig string     Kubernetes config file
      --namespace string      Kubernetes namespace to use
      --orchestrator string   Orchestrator to use (swarm|kubernetes|all)

删除单个栈:

$ docker stack rm myapp

Removing service myapp_redis
Removing service myapp_web
Removing service myapp_lb
Removing network myapp_default
Removing network myapp_frontend

一次删除多个栈:

$ docker stack rm myapp vossibility

Removing service myapp_redis
Removing service myapp_web
Removing service myapp_lb
Removing network myapp_default
Removing network myapp_frontend
Removing service vossibility_nsqd
Removing service vossibility_logstash
...
Removing network vossibility_vossibility

文档明确指出:删除栈时,与该栈关联的服务、网络和 secrets 都会被一并移除。从源码 swarm/remove.go 看,RunRemove 对每个栈按命名空间标签收集四类资源:

  1. services(服务);
  2. networks(网络);
  3. secrets(仅当 API ≥ 1.25 时);
  4. configs(仅当 API ≥ 1.30 时)。

删除顺序依次为服务、secrets、configs、网络;若栈中四类资源总数均为 0,则输出 Nothing found in stack: <STACK> 并继续处理下一个栈。服务按名称排序后逐个调用 ServiceRemove,任何单项失败都会累加汇总为 Failed to remove some resources from stack: <STACK>。其测试用例 remove_test.go 也验证了空栈场景下该提示的输出。

实战:一个完整的栈生命周期

将上述命令串联起来,一次完整的栈运维流程如下:

# 1. 初始化集群(若无 Swarm)
$ docker swarm init

# 2. 部署栈(多 Compose 文件合并 + 私有仓库凭据下发)
$ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml \
    --with-registry-auth --resolve-image changed myapp

# 3. 查看栈与服务
$ docker stack ls
$ docker stack services myapp

# 4. 查看任务分布与运行状态
$ docker stack ps myapp

# 5. 仅格式化输出关键字段
$ docker stack services --format "{{.Name}}: {{.Replicas}}" myapp

# 6. 清理:移除栈(连同其服务、网络、secrets 与 configs)
$ docker stack rm myapp

源码阅读地图

docker stack 的实现集中在 components/cli/cli/command/stack/ 目录下,按编排器拆分为 swarm/(默认路径)与 kubernetes/(需启用 Kubernetes 集成)两个子包,可按需深入:

关注点 参考文件
命令注册、编排器解析与 flag 校验 cmd.go
五个子命令的选项结构与分派 options/opts.go、common.go
Compose 文件加载与警告输出 loader/loader.go
Swarm 部署流程与镜像解析策略 swarm/deploy.go、swarm/deploy_composefile.go
命名空间标签定义(栈资源追踪的基石) compose/convert/compose.go
栈/任务/服务的过滤与列出 swarm/list.go、swarm/ps.go、swarm/services.go
栈删除的资源收集与顺序 swarm/remove.go
输出模板与表头映射 formatter/formatter.go
Kubernetes 编排的 namespace flag 与客户端封装 kubernetes/cli.go

子命令各自的官方参考页还分布在 stack_deploy.md、stack_ls.md、stack_ps.md、stack_rm.md、stack_services.md,其中包含更完整的示例输出与边界行为说明,适合作为命令手册随时查阅。

小结

docker stack 把“Compose 定义、CLI 转换、Swarm 执行”串成一条完整的声明式部署链路:deploy 负责资源创建与更新,ls/services/ps 分别从栈、服务、任务三个粒度观察运行状态,rm 负责一键回收。理解其背后的命名空间标签(com.docker.stack.namespace)、镜像 digest 解析策略(--resolve-image)以及编排器分派机制,将帮助你更精准地在生产集群中排障与调优。

登录后查看全文
docker-ce