specsfy-specialist-deploy

部署

何时使用

• 当用户要求在服务器上发布或部署应用时触发。
• 当用户要求通过 Ansible 准备一台将接收 Docker Swarm 堆栈的服务器时触发。
• 当用户要求注册、添加、替换或检查环境中的服务器时触发。
• 未明确指定目标并获得授权时，不执行推送、配置或远程更改。

流程

展示计划，逐步报告进度，并在结束时列出已更改的文件、验证结果和待办事项。对于公开文本，请遵循适用于使用方项目的《共享编辑规范》。

1. 确认用户系统的根目录，并调用 $specsfy-specialist-versioning 读取或准备 SEMVER。

2. 检查现有的 Dockerfile、Compose、stack 和 ansible/。将 PHP、扩展、依赖项、assets、entrypoint、内部用户、端口、healthcheck 和 Octane 命令与当前应用进行比较。保留自定义片段；替换没有托管标记的文件前，先展示 diff。

3. 仅在首次准备且所有目标位置均不存在时运行生成器：

   node scripts/scaffold.mjs --project <raiz> --image <registry>/<aplicacao>
   

   默认配置会在 stack 中包含 Cloudflare Tunnel。如果用户要求使用其他代理，则通过 --proxy external 生成，不包含 cloudflared，并在单独步骤中配置所要求的替代方案。

4. 调用 $specsfy-specialist-debian-server，每轮配置一台机器。将 hostname、地址、SSH 端口、连接用户和 manager 或 worker 角色记录到 ansible/inventory.yml，同时保留已注册的主机。新增机器时，只添加该主机。

5. 进行任何远程更改前，先测试所有已声明的主机。该 skill 会运行实用程序，也会展示在 Herdr 中使用的简写形式：

   ./deploy check-hosts
   

6. 仅在控制端机器上查找 ~/.ssh/*.pub 公钥，并将其添加到 deploy 用户的 authorized_keys 中。绝不读取、复制或传输私钥。保留已注册的远程访问。

7. 询问应用会使用哪些密码、令牌、密钥和 keys，并将名称记录到 ansible/vault-fields.txt。不要在对话中索要这些值。该实用程序会通过隐藏输入提示用户输入各个值，并将加密后的 YAML 写入文件：

   ./deploy secrets
   

   重复运行会保留现有字段，并且只询问缺失的字段。

   使用默认 Cloudflare Tunnel 时，加入 vault_cloudflare_tunnel_token。该服务会通过文件 /run/secrets/cloudflare_tunnel_token 读取令牌。

8. 使用 docker-tag 生成镜像引用。拒绝任何与 SEMVER 中的值不同的 Docker 标签。

9. 调用 $specsfy-specialist-debian-server 和 $specsfy-specialist-docker，确定主机和 Docker Engine 的状态。

10. 调用 $specsfy-specialist-ansible，创建或检查幂等 roles，以创建 deploy 用户、安装 Docker Engine、配置 daemon、防火墙、权限和应用目录。

11. 调用 $specsfy-specialist-docker-swarm，确定 managers、workers、网络和 stacks。仅当 manager 尚未加入 swarm 时，playbook 才会执行 docker swarm init；加入时使用受保护的令牌。

12. 通过 syntax check、lint、check mode 和在一次性目标上运行两次来验证 Ansible。使用 docker stack config 验证 stack。

13. 获得对指定目标的授权后，如果由 Agent 执行部署，则使用 ./deploy run --non-interactive。密码来自已配置的外部来源。如果没有该来源，请指导用户在自己的终端中运行 ./deploy configure-vault；不要在对话中索要、读取或打印密码。保留 ./deploy run 作为手动方式。 应用 playbook、发布带版本号的镜像，并通过 manager 执行 docker stack deploy。

14. 检查副本数、healthchecks、日志、版本和 digest。保存回滚到上一版本的命令。

规范

• 在配置密码、迁移现有脚本或由 Agent 执行之前，先阅读 references/vault.md。显式来源优先于环境和 ansible.cfg；如果没有原生来源，则使用本地凭据库作为替代方案。任何来源失败都会终止执行。

• 不要让 AI 运行 configure-vault 来填写密码。此命令用于人工准备，必须在输入内容隐藏的终端中执行。

• 通过差异更新现有项目，并保留自定义内容。脚手架仍会拒绝覆盖，更新技能也不会自动迁移 ./deploy 或 ansible/。

• 用户系统根目录中的 SEMVER 决定镜像、清单、Git 标签和发布版本。

• 开发环境生成 compose.yaml，生产环境生成 stack.yaml。所有生产部署都必须通过 Docker Swarm 使用 stack；不要将 Compose 用作生产运行时。

• Laravel 必须使用 laravel/octane 和 Open Swoole。镜像安装 openswoole；Compose 和 stack 使用 --server=swoole 运行 Octane。

• 默认建议使用 Cloudflare Tunnel 作为公共入口。在 stack 中将 cloudflared 作为服务运行，并连接到应用所在的同一 overlay 网络；Laravel 服务不开放公共端口。隧道主机名指向 http://app:8000。

• 只有在用户要求使用其他代理时才更改默认设置。在这种情况下，不要生成 cloudflared 服务或令牌 secret。

• Ansible 负责配置服务器和 Swarm 状态。不要将一系列手动 SSH 命令作为主要流程。

• 创建服务用户 deploy，仅将该用户加入 docker 组，并将应用目录分配给该用户。该组可授予对主机的广泛管理权限，不应包含不承担此职责的账户。

• 将 ansible/inventory.yml 作为已知服务器的映射。添加主机时保留现有主机，先测试新连接，然后再配置节点及其在 Swarm 中的角色。

• 当用户需要将操作复制到 Herdr 的其他面板时，显示 ./deploy check-hosts、./deploy secrets、./deploy sync-keys 或 ./deploy run。技能会执行这些实用工具，无需用户记住命令。

• 每次新调用时，重新读取应用，并仅协调发生变化的部分。生成器用于首次引导，不应通过覆盖现有文件来模拟更新。

• 使用幂等模块和 community.docker；启动或加入 swarm 所需的命令必须根据当前状态设置条件。

• Manager 节点数量应保持为奇数，并限制 Swarm 端口仅供授权节点访问。

• 只发布一次镜像，并在不同环境之间推广同一 digest。

• 密码、令牌和密钥应存入通过安全提示创建的 Ansible Vault。Ansible 使用 no_log: true 将解密后的值转换为 Docker Secrets；stack 仅保存名称和外部挂载。

反模式

• 使用 latest 或其他无法复现 SEMVER 的标签。
• 每次运行 playbook 都执行 docker swarm init。
• 在日志、明文变量或已提交的文件中暴露 join 令牌。
• 在 stack.yaml、明文变量或镜像中存储密码、令牌或密钥。
• 通过参数、明文变量或已版本控制的文件传递 Cloudflare Tunnel 令牌。
• 在未经确认确有必要时，向用户 deploy 授予不受限制的 sudo 权限。
• 在服务器上构建，或为每个环境重新构建镜像。
• 仅凭命令返回零退出码就认定部署已完成。

验证

• 在一次性目标上检查手动提示词、外部文件、保险库脚本和原生配置。没有有效密码时，执行应在连接主机之前停止。检查权限 700 和 600、覆盖确认提示，以及配置器输出中不包含任何机密值。

• 通过版本管理技能运行 current、docker-tag 和 verify-docker-tag。

• 确认 deploy 用户存在、属于 docker 组、可以访问守护进程，并且是应用目录的所有者。

• 确认 Docker Engine 已启动、manager 可访问，且 swarm 处于 active 状态。

• 运行两次 playbook；第二次运行应以未做任何更改结束。

• 将每个服务的镜像与 SEMVER 以及已发布的 digest 进行比较。

• 观察收敛情况，并在兼容环境中演练回滚。

相关技能

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

• $specsfy-specialist-versioning 管理用户系统的版本。

• $specsfy-specialist-debian-server 定义主机的基础状态。

• $specsfy-specialist-docker 准备并发布镜像。

• $specsfy-specialist-ansible 自动化服务器和集群。

• $specsfy-specialist-docker-swarm 管理服务、滚动更新和回滚。

• $specsfy-specialist-delivery-engineering 管理流水线和环境间的晋级流程（仅当这些组件属于交付内容时）。

创建或修改配置和部署 playbook 之前，请阅读 references/standards.md。