狸想岛 · AI 实战学习社区

🎯 学 gstack 的部署基础设施配置引导：不是手写复杂的 CI/CD 配置文件，而是通过交互式问答自动检测部署平台、生成配置、测试连通性——一次配置，永久复用。/land-and-deploy 和 /canary 自动读取这些配置来执行部署和验证。 ⏱️ 预计时间：20 分钟

💡 新手提示：部署配置的核心价值是"一次配置，永久复用"。就像你把 Wi-Fi 密码保存后，每次回家手机自动连接——不用每次都输入一遍。setup-deploy 就是帮你的项目做这件事。

[!quote]- 📖 原Skill精要 技能名称：setup-deploy 核心功能：为 [[L6-26-自动部署落地|land-and-deploy]] 配置部署设置。检测部署平台（Fly.io、Render、Vercel、Netlify、Heroku、GitHub Actions、自定义），配置生产 URL、健康检查端点和部署状态命令。将配置写入 CLAUDE.md，之后所有部署全自动。 所属体系：gstack 虚拟工程团队 协作关系：配置完成后 [[L6-26-自动部署落地|land-and-deploy]] 和 [[L6-27-金丝雀监控|canary]] 自动读取配置执行部署与验证

§1 课程概览

setup-deploy 是 gstack 的部署基础设施配置引导系统。它解决的核心问题：每个项目第一次部署时，/land-and-deploy 需要重新检测"部署到哪里、生产 URL 是什么、健康检查端点是哪个"——这些信息每次重新检测既慢又可能不准确。setup-deploy 通过 7 步交互式引导，一次性收集所有部署配置并写入 CLAUDE.md，之后 /land-and-deploy 直接读取——跳过检测，进入执行。配置 hash 机制确保配置变更时自动重新验证——"一次配置，永久复用"不等于"配置永不更新"。

[!tip] 白话小课堂部署配置的核心价值就一句话：一次配置，永久复用。就像你第一次连 Wi-Fi 输入密码后，以后每次回家手机自动连——不用每次都输入一遍。setup-deploy 就是帮你的项目做这件事：自动检测你用的是 Fly.io 还是 Vercel、你的生产 URL 是什么、健康检查端点在哪、CI/CD workflow 是哪个文件——7 步交互式引导，全部写入项目文件。以后 /land-and-deploy 直接读配置，不用每次都重新猜"我部署到哪来着？"关键设计是配置 hash：如果项目文件里的部署配置被人改了，/land-and-deploy 会检测到 hash 不匹配，自动重新验证配置——防止"配置过时但还在用"的静默故障。

§2 setup-deploy 解决什么问题？——部署配置的"一次性成本"

每个项目第一次部署时的未知变量

部署到哪里？（Fly / Render / Vercel / Heroku / K8s？）
生产 URL 是什么？
如何验证部署成功？（是 200 OK 就够，还是需要 db+redis 都 connected？）
有没有 staging 环境？
CI/CD workflow 文件在哪里？
部署后等待多久才算"部署完成"？

这些问题 /land-and-deploy 每次都要重新检测 → 慢（每次都要扫描项目文件、猜测平台、临时构建计划）+ 可能不准确（自动检测可能猜错部署平台）。

setup-deploy 的解决方案

一次性配置 → 写入 CLAUDE.md 的 ## Deploy Configuration 章节
后续 /land-and-deploy 直接读取 → 跳过检测 → 直接进入部署执行
配置变更时自动检测（hash 对比）→ 提示重新配置——不信任"永久有效"的假设

为什么独立成一个 skill？

部署配置是一次性的（可能几个月才变一次）
/land-and-deploy 应该快速（不需要每次都交互式问答）
分离关注点：配置（setup-deploy）vs 执行（land-and-deploy）

§3 配置流程——7 步交互式引导

Step 1: 平台检测

自动扫描项目文件（fly.toml / render.yaml / vercel.json / netlify.toml / heroku.yml / .github/workflows/ 等）。列出检测到的平台——如果检测到多个 → 让用户选择；如果未检测到 → 手动选择或输入（支持自定义平台）。

Step 2: 应用/项目名称

自动从 git remote URL 提取（如 github.com/org/mega-shop → mega-shop），或从平台配置文件中读取。用户确认或修改——自动提取通常正确但有时需要覆盖。

Step 3: 生产环境 URL

从平台配置推断或用户输入：

Fly: <app>.fly.dev
Vercel: <project>.vercel.app
Heroku: <app>.herokuapp.com
自定义域名（用户手动输入）

Step 4: Staging 环境（可选）

是否有 staging 环境？staging URL 是什么？staging deploy workflow 在哪里？这一步是可选的——不是所有项目都有 staging。

Step 5: 部署验证方式

四种验证方式按推荐优先级排序：

GitHub Actions workflow（推荐）→ 自动找到 deploy workflow 文件
Platform CLI（fly status / heroku releases）→ 调用平台命令行检查部署状态
HTTP health check（curl + canary 监控）→ 最通用的方式，但信息量最少
自定义命令→ 完全由用户定义

Step 6: 连接测试

测试所有集成的连通性：

gh auth status——GitHub CLI 是否已认证
platform CLI（如 flyctl status）——平台 CLI 是否可用
curl production URL——生产环境是否可达
生成验证报告——哪些通过、哪些失败、失败的原因

Step 7: 持久化

将所有配置写入 CLAUDE.md 的 ## Deploy Configuration 章节。计算配置内容的 hash → 写入 ~/.gstack/projects/$SLUG/land-deploy-confirmed。以后 /land-and-deploy 通过对比 hash 来判断配置是否仍然有效。

§4 与 /land-and-deploy 的协作——配置消费的三种状态

三种配置状态

/land-and-deploy Step 1.5 检查配置状态：

FIRST_RUN：CLAUDE.md 中没有 Deploy Configuration → 运行内联的 dry-run 检测（临时扫描项目文件、检测平台、构建部署计划）→ 事后建议运行 /setup-deploy 持久化配置
CONFIRMED：有配置 + hash 匹配 → 直接使用配置，跳过检测（效率模式——最快的路径）
CONFIG_CHANGED：有配置但 hash 不匹配 → 配置被人手动修改了 → 重新运行 dry-run 验证新配置的有效性 → 如果验证通过，更新 hash → 回到 CONFIRMED

setup-deploy 的调用时机

新项目接入 gstack 时（首次运行——从 FIRST_RUN 转为 CONFIRMED）
部署平台迁移时（Heroku → Fly——CONFIG_CHANGED）
添加 staging 环境时
自定义部署验证命令变更时
/land-and-deploy 首次运行时建议先运行 /setup-deploy

健康检查设计——不止"返回 200 OK"

API 网关返回 200 但实际功能损坏的典型场景：API 网关本身是一个轻量进程（总是能响应 HTTP），但它依赖后端的数据库连接池。数据库连接断开时，API 网关的 /health 端点如果不检查数据库连接状态，仍然返回 200 OK——部署工具看到 200 以为一切正常，但实际所有需要数据库的请求都会失败。

正确的 health check 响应：GET /health → 200 OK + {"db": "connected", "redis": "connected", "uptime": 3600}。部署工具不仅检查 HTTP 状态码，还检查响应体中关键服务的连接状态。好的 health check 不仅说"我活着"，还说"我能干活"。

§5 结构拆解

setup-deploy 部署配置 Skill 结构模板

核心特征

管理对象: 项目的部署基础设施配置（平台、URL、健康检查、工作流）
核心原则: "一次配置，永久复用"——分离配置和执行，让 /land-and-deploy 快速运行
关键设计:
- 7 步交互式引导（平台检测 → 应用命名 → URL → Staging → 验证 → 连接测试 → 持久化）
- 配置 hash 检测变更：FIRST_RUN / CONFIRMED / CONFIG_CHANGED 三种状态
- 多服务支持：一套配置覆盖所有微服务

通用结构

Step 1-2: 平台自动检测（扫描 fly.toml / vercel.json 等）+ 应用/项目名称提取（git remote URL）
Step 3-4: 生产 URL 推断（平台默认 URL 格式 + 自定义域名）+ Staging 环境配置（可选）
Step 5: 部署验证方式选择：GitHub Actions workflow（推荐）> Platform CLI > HTTP health check > 自定义命令 health check 设计：不仅检查 200，还检查响应体中的服务连接状态（db/redis connected）
Step 6: CLI 认证 + API + 健康检查端点的连通性测试生成验证报告：哪些通过、哪些失败、失败原因
Step 7: 配置写入 CLAUDE.md（## Deploy Configuration 章节） hash 持久化到 ~/.gstack/projects/$SLUG/land-deploy-confirmed
配置消费层: FIRST_RUN: 未配置 → dry-run → 建议 /setup-deploy CONFIRMED: hash 匹配 → 直接使用（最快路径） CONFIG_CHANGED: hash 不匹配 → 重新验证 → 更新 hash

§6 电商 Skill 案例：电商SaaS平台多服务多环境部署配置

🛒 实战案例：某电商SaaS平台有4个后端微服务（api-gateway/Node.js、payment-service/Node.js、inventory-service/Python、notification-service/Go）+1个前端应用（web-frontend/Next.js），分别部署在AWS ECS(Fargate) + Vercel。之前每次部署需要工程师分别操作5个服务，手动切换staging→production环境，平均部署耗时35分钟且容易遗漏服务。使用/setup-deploy建立统一的部署配置中枢。

Step 1-2 基础设施检测：自动检测5个服务的部署平台——api-gateway: ecs-service.json→AWS ECS, App: mega-api；payment-service: ecs-service.json→AWS ECS, App: mega-payment；inventory-service: ecs-service.json→AWS ECS, App: mega-inventory；notification-service: ecs-service.json→AWS ECS, App: mega-notify；web-frontend: vercel.json→Vercel, Project: mega-web。各服务Production URL、Staging URL（web-frontend: staging.mega-shop.com）、Health check端点（api-gateway: GET /health→{db,redis,kafka}:connected、payment-service: GET /health→200 OK等）全部检测并持久化到CLAUDE.md。

Step 3 连接测试：逐一验证——aws ecs describe-services连接成功（确认所有4个ECS服务可操作）、vercel whoami确认Vercel权限、curl https://api.mega-shop.com/health返回200 OK + 全部依赖connected、curl https://mega-shop.com返回200 OK。发现payment-service的health check返回503（Redis连接池耗尽→已自动重启恢复）。

Step 4 多环境配置生成：CLAUDE.md中生成Deploy Configuration完整表格——5个服务的Platform/App/Project、Production URL、Staging URL（如适用）、Health Check端点、Deploy Workflow路径。Post-Deploy验证规则——api-gateway: canary检查/api/products和/api/orders的P99延迟<200ms；web-frontend: canary检查首页+商品页+购物车的LCP<2.5s。

Step 5 跨服务依赖检测：检测服务间的API调用依赖——payment-service调用api-gateway的/api/orders/:id获取订单信息、inventory-service调用api-gateway的/api/products/:id获取商品信息、notification-service消费Kafka消息。在CLAUDE.md中标记跨服务依赖图——当api-gateway变更时，/land-and-deploy自动标记依赖方服务并建议同时部署验证。

🔑 启示：部署配置的"一次性设置"看似简单，但它解决了多服务部署中最隐蔽的问题——服务间的"隐性依赖"。payment-service部署成功但api-gateway还在staging阶段→支付回调打到旧版api-gateway导致订单状态卡住——没有跨服务依赖图，这种故障在部署后几个订单才会暴露。setup-deploy将隐性依赖显式化→/land-and-deploy自动协调部署顺序。

[!info] 参考来源多服务部署配置参考了 AWS ECS Service Connect 和 Vercel monorepo deployment 的配置模式。

§7 掌握检验

Q1：setup-deploy 与 /land-and-deploy 的关系是什么？

A) setup-deploy 是 /land-and-deploy 的替代品，两者功能完全相同
B) setup-deploy 是一次性配置工具（将部署配置写入 CLAUDE.md），/land-and-deploy 是执行工具（读取配置执行部署）——分离"配置"和"执行"的关注点
C) setup-deploy 必须在每次 /land-and-deploy 之前运行
D) /land-and-deploy 自动包含 setup-deploy 的所有功能

Q2：配置 hash 在 setup-deploy 中的作用是什么？

A) 用于加密部署配置防止泄露
B) 用于检测配置是否发生了变更——如果 hash 不匹配，/land-and-deploy 知道需要重新运行 dry-run 检测
C) 用于验证 git commit 的完整性
D) 用于生成随机的部署 URL

Q3：多服务部署配置中，每个 service 的 health check 为什么需要自定义而不仅仅是"检查 HTTP 200"？请给出一个具体场景：一个 API 网关返回 200 OK 但实际功能已损坏（如数据库连接断开时仍返回 200），通用的健康检查如何漏掉这个故障？应该如何设计 health check 的响应内容来避免这个盲区？

Q4：/land-and-deploy 的三种配置状态（FIRST_RUN / CONFIRMED / CONFIG_CHANGED）分别意味着什么？在每种状态下 /land-and-deploy 的行为有何不同？如果项目从 Heroku 迁移到 Fly.io（部署平台变了），配置状态如何变化？

Q5：电商平台的多微服务场景中，如果只修改了 payment-service 的代码，/land-and-deploy 应该如何处理？它是如何判断"只部署有变更的服务"而非全量部署所有服务的？如果 payment-service 的变更依赖于 api-gateway 的一个新端点（api-gateway 也需要重新部署），/land-and-deploy 能否自动检测到这种跨服务依赖？

Q6：setup-deploy 的 Step 6（连接测试）测试了 gh auth status、platform CLI 和 curl production URL。如果连接测试在配置时全部通过，但两个月后 /land-and-deploy 运行时发现部署失败（如 platform CLI 的 API token 过期了），这个失败应该归因于什么？setup-deploy 是否应该设计为"定期重新验证配置"而非"一次性配置 + 永久信任"？请从工程实践的角度分析。

§8 答案

点击查看答案

Q1：B —— setup-deploy 和 /land-and-deploy 分离"配置"和"执行"的关注点。就像设置 Wi-Fi 密码（一次性）和每次自动连接（重复执行）是两个不同的操作。

Q2：B —— 配置 hash 是 Deploy Configuration 内容的哈希值，存储在 ~/.gstack/projects/$SLUG/land-deploy-confirmed 中。如果 hash 不匹配 → 有人手动修改了 CLAUDE.md 中的部署配置 → /land-and-deploy 重新验证而非盲目信任。

Q3：API 网关返回 200 但功能损坏的场景：数据库连接断开时，API 网关的 /health 端点如果不检查数据库连接状态，仍然返回 200 OK——部署工具看到 200 以为一切正常，但实际所有需要数据库的请求都失败。正确的 health check 响应：GET /health → 200 OK + {"db": "connected", "redis": "connected", "uptime": 3600}。好的 health check 不仅说"我活着"，还说"我能干活"。

Q4：①FIRST_RUN——没有配置 → /land-and-deploy 运行内联 dry-run 检测 → 建议 /setup-deploy。②CONFIRMED——配置 + hash 匹配 → 直接使用，最快路径。③CONFIG_CHANGED——配置存在但 hash 不匹配（如 Platform 从 heroku 变为 fly）→ 重新运行 dry-run 验证 → 通过后更新 hash → 回到 CONFIRMED。

Q5：/land-and-deploy 通过 git diff 分析哪些文件发生了变化 → 映射到服务目录（src/payment-service/** → payment-service）。跨服务依赖自动检测非常困难——git diff 不包含"payment-service 调用了 api-gateway 的新端点"的语义信息。解决方案：PR 描述中声明跨服务依赖 → /land-and-deploy 读取并同时部署。

Q6：这是"配置随时间漂移"的问题——外部系统（GitHub token、Platform API key）的状态不在项目控制范围内。定期重新验证方案：①/land-and-deploy 每次运行前做快速连接测试（< 1s）；②setup-deploy --verify 模式供用户定期验证；③CLAUDE.md 中记录配置时间戳，超过 N 天建议重新验证。信任但要定期重新验证——就像 SSL 证书有有效期。

（5/6 通过）

L6-35：一键部署配置 —— 一次配置从此自动部署不再烦