specsfy-specialist-docker-swarm

Docker Swarm

使用场景

• 当项目使用 docker swarm init/join、docker stack deploy 或带有 deploy: 的 stack 文件编排多个节点时使用。
• 在决定 manager/worker 拓扑、发布、回滚或 quorum 恢复方案时也使用。
• 单机上使用 docker compose up 进行本地开发，或构建镜像时不要使用；此时使用 $specsfy-specialist-docker。Compose 的许多键（profiles、depends_on.condition、运行时的 build）在 docker stack deploy 中不起作用。
• 当发布属于发布流水线的一部分时，与 $specsfy-specialist-delivery-engineering 配合使用；决定哪些信号可授权或触发回滚时，与 $specsfy-specialist-observability 配合使用。

流程

1. 在发布或完整部署时，在 $specsfy-specialist-deploy 的指导下开展工作。检查由 $specsfy-specialist-versioning 准备的 SEMVER，在执行 docker stack deploy 前运行 verify-docker-tag，如果标签不匹配则停止。
2. 在进行任何拓扑更改前，梳理 managers、workers、区域、labels、quorum 和外部依赖（registry、storage、DNS）。
3. 验证已发布的镜像与测试过的镜像相同，并确认 stack 文件仅使用 docker stack deploy 支持的键（而非整个 Compose schema）。
4. 定义 services、网络、ports、volumes、configs 和 secrets，并为每个共享资源指定明确的 owner。
5. 配置 replicas、placement constraints/preferences、resources.limits/reservations、healthcheck 和 restart_policy。
6. 设计 update_config 和 rollback_config（并行度、延迟、start-first/stop-first 顺序、failure_action），确保发布期间新旧版本能够共存，且不会破坏 API/数据契约。
7. 在具有代表性的 swarm 中应用（拓扑等效的 staging 环境，而非单个节点），并使用 docker service ps 和 docker service logs 观察收敛情况。
8. 记录部署、回滚、secret 轮换、Raft 状态备份以及 manager 丢失后的恢复方案。

标准

• 在由 $specsfy-specialist-deploy 协调的部署中，使用 Cloudflare Tunnel 作为默认公共入口。让 cloudflared 和应用处于同一 overlay 网络中，不在主机上发布 Laravel 端口。只有在用户明确要求更换时，才接受使用其他代理。

• 通过挂载为文件的 Docker Secret 提供隧道令牌，并使用 --token-file 启动 cloudflared。切勿将令牌值保存在 stack 中。

• 将依赖项、应用和 ingress 分别放在不同的 stack 中。按依赖顺序发布，等待每项服务达到声明的收敛状态，然后再开放公共访问路径。

• 将 migrations 集中在选定的一个副本上执行。其他服务启动时禁用 migrations，以防 rollout 期间发生并发。

• HTTP、队列、scheduler 和 WebSocket 使用同一不可变镜像，并为各自设置命令和 healthcheck。其他队列 supervisor 处于活动状态时，将备用 worker 的副本数设为 0。

• 在创建 stacks 之前，创建外部加密 overlay 网络。数据服务只加入内部网络；如果符合项目设计，仅出站 tunnel 可以免去在主机上开放公共端口。

• 使用奇数个 manager（1、3 或 5），生产环境中绝不能让 quorum 依赖单个 manager。

• 使用不可变摘要发布镜像（image@sha256:...），确保所有 node 均可访问；不能因本地构建而导致各 node 使用不同镜像。

• 使用按名称版本化的 secrets/configs（app_secret_v2），绝不将机密嵌入 stack 文件的环境变量中。

• 分离 ingress 网络、内部服务网络和数据网络；不要通过已发布的 ports: 暴露内部服务端口。

• 明确设置 resources.limits 和 reservations；不要依赖负载较轻的 node 所隐含的容量。

• 仅使用受管理的 labels（node.labels.*）设置 placement.constraints，绝不硬编码 hostname。

• 不要假设 Compose 选项（profiles、build、develop、带 condition 的 depends_on）会被 stack deploy 支持；依赖这些选项前，先对照受支持字段列表进行验证。

反模式

• 副本较少的服务未设置 update_config.order: start-first 就进行 rolling update：旧副本会在新副本健康之前退出，导致服务短暂失去处理能力。
• 在多副本或可能重新调度的服务中使用本地 volume（bind 或未使用分布式 driver 的命名 volume）：scheduler 将容器重新分配到其他 node 时，数据会“消失”。
• 原地更改 secret，即替换被引用文件的内容：Swarm 将 secrets 视为按名称不可变；正确做法是创建新版本（app_secret_v2），将其附加到服务后，再移除旧版本。
• 混淆用于开发的 docker-compose.yml 和生产 stack 文件：两者的 healthcheck、deploy:、secrets 和 overlay 网络通常缺失或不一致。

验证

• 部署前运行 docker stack config --compose-file <arquivo>（或使用提供商提供的等效验证）以发现插值和 schema 错误。
• 在整个 rollout 期间观察 docker service ps <serviço>、docker service logs、期望副本数与当前副本数，以及 node 事件；不要只在结束时检查。
• 模拟 worker 故障；在获准且备份已验证的环境中，模拟一个 manager 丢失，确认其余 manager 能维持 quorum。
• 验证应用回滚（docker service update --rollback 或 rollback_config），并确认在两个版本共存期间，数据 migrations 彼此兼容。
• 未验证上述四点，不要宣称 stack“已满足生产就绪要求”；“在我的 node 上运行成功”不能证明集群已收敛。

相关技能

• $specsfy-specialist-server-report 汇总日志、服务和磁盘使用情况， 通过 Ansible 以只读方式采集并按主机生成报告。

• $specsfy-specialist-deploy 协调服务器、镜像、Ansible 和栈的发布； 此技能仅负责 Swarm。

• $specsfy-specialist-versioning 准备 SEMVER，并检查镜像和栈清单使用的版本。

• $specsfy-specialist-ansible 准备并维护节点；此技能负责 Swarm 的 quorum、scheduler、services 和网络。

• $specsfy-specialist-laravel 定义应用契约，而 $specsfy-specialist-redis 定义 services 使用的持久化／缓存。

• $specsfy-specialist-docker 负责镜像构建、Dockerfile 和使用 Compose 进行本地开发——边界：当应用开始在多个节点上以集群状态运行时，就进入 Swarm 的范畴。

• 当服务 rollout 属于一个涉及跨环境晋级的发布管道时，使用 $specsfy-specialist-delivery-engineering。

• $specsfy-specialist-observability 用于检测决定继续、暂停或回滚 rollout 的信号（health、错误率、延迟）。

• $specsfy-specialist-debian-server 负责节点的集群端口、内核、 文件系统和 Docker 服务。

请阅读 references/standards.md，了解 Raft 拓扑、secret/config 生命周期、overlay 网络、rollout 策略和灾难恢复， 其中包含 Docker 官方文档的来源。