CLI开发工具【免费下载链接】cliThe Docker CLI项目地址https://gitcode.com/gh_mirrors/cli5/cli点击查看免费下载导读本文围绕 Docker CLI 的docker stack deploy别名docker stack up命令系统讲解如何将一个或多个 Compose 文件转换为 Swarm 服务并完成栈stack的创建与更新。你将掌握该命令的全部选项语义含默认值与适用版本、从 stdin 与多文件合并的三种 Compose 输入方式、服务收敛等待机制以及其背后的源码级部署流程——从命名空间机制、网络/密钥/配置的创建到镜像摘要解析与清理策略。文中所有结论均可在当前仓库gh_mirrors/cli5/cli的源码与测试用例中得到印证。命令概览用途、别名与运行前提docker stack deploy的核心职责是基于 Compose 文件在 Swarm 上创建或更新一个栈。它的语义与docker compose up不同它面向 Swarm 集群编排services、overlay 网络、secrets、configs而非单机容器编排。命令定义位于 cli/command/stack/deploy.go在 cli/command/stack/cmd.go 中作为stack子命令注册。命令形态源码中的Use字段为docker stack deploy [OPTIONS] STACKSTACK栈名称必填唯一的位置参数也是所有资源的命名空间前缀详见下文命名空间机制。别名docker stack up源码中通过Aliases: []string{up}注册二者完全等价。运行前提这是集群管理命令必须运行在 Swarm 管理节点manager上。源码中的checkDaemonIsSwarmManagercli/command/stack/deploy.go通过调用InfoAPI 检查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该检查在部署的第一步执行见 cli/command/stack/deploy_composefile.go因为后续创建 overlay 网络前必须先确认 swarm 上下文。关于 manager/worker 的更多概念可参考仓库中 Swarm 初始化命令的实现 cli/command/swarm/init.go。选项参数详解deploy命令的全部选项由newDeployCommand中的 pflag 定义cli/command/stack/deploy.go含义如下名称类型默认值说明-c, --compose-filestringSlice空Compose 文件路径-表示从 stdin 读取可重复指定实现多文件合并-d, --detachbooltrue立即退出不再等待栈中服务收敛converge--pruneboolfalse清理不再被 Compose 文件引用的旧服务-q, --quietboolfalse抑制进度输出--resolve-imagestringalways是否查询 registry 解析镜像摘要与支持的平台可选always/changed/never--with-registry-authboolfalse将 registry 认证信息发送给 Swarm 工作节点以下逐一展开说明并给出源码依据。-c, --compose-fileCompose 文件输入支持 Compose 文件版本3.0 及以上。支持stringSlice可多次传入实现 base override 的合并部署。传-时从 stdin 读取适合管道输入或动态生成的配置。源码为--compose-file注册了.yaml/.yml的文件名补全Bash 下生效并将该选项标注为version: 1.25起可用cli/command/stack/deploy.go。未指定任何 Compose 文件时加载器直接报错specify a Compose file (with --compose-file)cli/command/stack/loader.go。-d, --detach等待还是立即返回默认值为true立即返回。源码中有一个值得注意的细节cli/command/stack/deploy.go当--detach为默认值true且用户没有显式传入该选项时命令会向 stderr 输出提示告知任务将在后台创建并预告未来版本中--detachfalse将成为默认行为Since --detachfalse was not specified, tasks will be created in the background. In a future release, --detachfalse will become the default.当--detachfalse时部署完成后会调用waitOnServicescli/command/stack/deploy_composefile.go逐个服务等待收敛--quiet则用于抑制等待期间的进度输出。--prune清理失效服务--prune自 1.27 起可用会在部署前收集当前 Compose 文件声明的服务集合然后调用pruneServicescli/command/stack/deploy.go先按命名空间标签列出该栈下所有现存服务凡是不在最新 Compose 声明集合中的服务一律删除。测试 cli/command/stack/deploy_test.go 验证了仅移除不再被引用的服务这一行为。--resolve-image镜像解析策略该选项控制服务部署/更新时是否向 registry 查询镜像摘要digest和受支持的平台。三个取值常量定义在 cli/command/stack/deploy.go取值行为always默认创建与更新服务时都设置QueryRegistry true由 daemon 查询 registry 解析镜像摘要changed仅当 Compose 文件中的镜像与上次部署记录的镜像标签com.docker.stack.image不一致时才查询 registrynever从不查询 registry若镜像未变则复用服务上已有的镜像摘要信息传入非法值时会在runDeploy中报错invalid option ... for flag --resolve-imagecli/command/stack/deploy.go。changed与never分支的镜像未变则沿用既有摘要、避免触发错误更新逻辑详见 cli/command/stack/deploy_composefile.go并由测试TestServiceUpdateResolveImageChangedcli/command/stack/deploy_test.go覆盖验证同时该测试还确认了栈部署无--force选项时ForceUpdate值会被保留。--with-registry-auth私有镜像仓库认证启用后CLI 会从本地 Docker 配置文件中提取镜像对应的认证信息command.RetrieveAuthTokenFromImage并通过EncodedRegistryAuth随创建/更新请求一并发送给 Swarm 调度器使工作节点能拉取私有镜像cli/command/stack/deploy_composefile.go。未启用时Swarm 代理只能拉取公开镜像或已缓存的认证信息。-q, --quiet与--detachfalse配合使用抑制服务收敛等待期间的进度输出。基础用法从 Compose 文件部署栈最简单的方式是直接指定 Compose 文件与栈名。以下示例来自命令文档docs/reference/commandline/stack_deploy.md部署名为vossibility的栈$ 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 支持属性的善意提醒加载器会收集不支持属性并打印到 stderrIgnoring unsupported options: ...同时继续部署cli/command/stack/loader.go。从 stdin 读取 Compose 配置将--compose-file指定为-即可从标准输入读取配置适合与cat、模板渲染或 CI 管道配合$ cat docker-compose.yml | docker stack deploy --compose-file - 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从源码看stdin 模式的工作目录取当前目录os.Getwd()而文件模式的工作目录取 Compose 文件所在目录filepath.Abs后取Dir这决定了文件中相对路径如.env、build 上下文的解析基准cli/command/stack/loader.go。加载器还会把宿主环境变量注入配置插值环境buildEnvironmentWindows 下会过滤以开头的 cmd.exe 兼容变量保证${VAR}插值可用。多 Compose 文件合并部署若配置按基础配置 环境覆盖拆分在多个文件中可重复传入--compose-file$ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.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加载器按传入顺序依次解析各文件再交由 Compose loader 统一合并cli/command/stack/loader.go后出现的文件对同名键覆盖前者。注意多文件场景下要求各文件版本一致deploy取第一个文件的版本作为整体版本details.Version schema.Version(...)。验证部署结果部署完成后可用docker service ls查看栈内的服务与镜像摘要。由于默认--resolve-imagealways镜像列展示的是解析后的摘要形式sha256:...而非 tag$ docker service ls ID NAME MODE REPLICAS IMAGE 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsqsha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsqsha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearchsha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa 7563uuzr9eys vossibility_kibana replicated 1/1 kibanasha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03 9gc5m4met4he vossibility_logstash replicated 1/1 logstashsha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collectorsha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba注意服务名均带有vossibility_前缀——这正是命名空间机制的外在表现。源码视角一次stack deploy的完整执行链路deployComposecli/command/stack/deploy_composefile.go串联了如下步骤校验 manager 身份调用InfoAPI 确认当前节点具备 swarm 控制能力。可选清理--prune时收集声明服务集合并删除失效服务。网络准备将 Compose 网络转换为引擎 API 类型convert.Networks见 cli/compose/convert/compose.go。其中未指定 driver 的网络默认使用overlay常量defaultNetworkDriver见 cli/command/stack/deploy.go声明为external: true的网络必须已经存在且 scope 为swarm否则部署失败validateExternalNetworks报错提示需要先创建 swarm 作用域网络该逻辑由 cli/command/stack/deploy_composefile_test.go 的TestValidateExternalNetworks覆盖。Secrets 与 Configs按需创建或更新已存在则用新 spec 更新不存在则新建并打印Creating secret/config ...。服务转换与部署将每个 Compose service 转换为swarm.ServiceSpec再逐个ServiceCreate或ServiceUpdate。更新已有服务时输出Updating service name (id: id)同时保留既有ForceUpdate值避免任务被无谓重建。收敛等待--detachfalse时对每个新建/更新服务调用WaitOnService等待收敛出错时聚合返回所有服务的错误。命名空间机制与资源追踪栈中的所有资源都以栈名_资源名命名并打上标签com.docker.stack.namespace栈名。命名空间实现位于 cli/compose/convert/compose.goScope(name)将名称加上栈名_前缀Descope(name)去掉前缀用于比较原始服务名LabelNamespace常量即com.docker.stack.namespace。这一标签机制是docker stack ls/stack ps/stack rm/stack services等命令定位栈内资源的统一手段见 cli/command/stack/common.go 中的getStackFilter所有资源查询都基于该标签过滤。同时它也是--prune判定服务是否仍被引用的依据用Descope后的名称与 Compose 声明比对。Compose 加载与校验环节在进入部署流程前loadComposeFilecli/command/stack/loader.go已完成三类校验镜像引用合法性每个服务必须显式指定镜像且可通过reference.ParseAnyReference解析否则报错invalid image reference for service ...不支持属性提示打印Ignoring unsupported options弃用属性提示打印Ignoring deprecated options。相关命令stack deploy只是栈生命周期管理的一环与其配套的命令还包括stack ls列出当前 swarm 上的所有栈stack ps查看栈内服务的任务列表stack rm移除栈及其管理的资源stack services列出栈内的服务stack config校验并输出 Compose 文件转换后的配置其中stack ps/stack services/stack rm与deploy共享同一套命名空间标签查询逻辑cli/command/stack/common.go因此只要用deploy创建的栈均可被这些命令准确识别与管理。小结docker stack deploy是 Docker CLI 将声明式 Compose 配置交付给 Swarm 编排器的核心入口一条命令即可完成网络、密钥、配置与服务的全量创建或增量更新并通过--resolve-image、--with-registry-auth、--prune等选项覆盖镜像解析、私有仓库认证与清理等生产场景需求。理解其命名空间标签机制与deployCompose的执行顺序有助于在实际排障中快速定位网络未创建服务未更新外部网络作用域不符等典型问题。赞分享CLI开发工具【免费下载链接】cliThe Docker CLI项目地址https://gitcode.com/gh_mirrors/cli5/cli点击查看免费下载相关推荐Drawnix Docker 部署3分钟跑起私有白板Drawnix Docker 部署3分钟跑起私有白板 Drawnix 是一款开源一体化白板工具覆盖思维导图、流程图与自由画。用 Docker 部署它一条命前端协同办公PraisonAI Agents Stack 部署指南基于 Docker Compose 与 pgvector Postgres 的生产级 Agent API 栈PraisonAI Agents Stack 部署指南基于 Docker Compose 与 pgvector Postgres 的生产级 Agent API人工智能AI AgentAgent 框架多智能体工作流自动化RAGMCP 服务GetQzonehistory一键导出你的QQ空间完整记忆档案GetQzonehistory一键导出你的QQ空间完整记忆档案 你是否还记得十年前在QQ空间写下的第一条说说那些记录着青春点滴的文字和图片随着时间流逝正在网页爬虫数据分析上一篇rrweb/record 实战指南rrweb 2.x 独立录制包的安装、事件采集与隐私配置下一篇Easy-Vibe 前端类型安全实战TypeScript 从类型注解到泛型让 vibe coding 生成的代码更可靠创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考