mkfast-deploy

Mkfast Deploy

把 mkfast-template（TanStarter 系）项目部署到 Cloudflare Workers。核心价值：根据项目实际启用的组件动态裁剪部署步骤，避免照搬完整版文档导致裁剪版项目跑空命令甚至报错。

适用范围

是：基于 mkfast-template 模板派生的项目，包括完整 SaaS 形态、裁剪版博客、或任意中间形态。

不是：任意 Cloudflare Workers 项目（这种情况用 wrangler skill 就够）。

判断标志（满足任一即可）：

• 根目录有 wrangler.jsonc + package.json
• package.json 含 wrangler + @cloudflare/vite-plugin + @tanstack/react-start 中任一
• 目录里有 mkfast 特征文件：drizzle.config.ts / src/server.ts / src/db/auth.schema.ts

重要原则

1. 先评估再执行 — 任何 deploy 命令前必须完成 Phase 1，生成裁剪后的步骤清单。直接 pnpm run deploy 不算工作完成
2. 不要照搬官方文档 — mkfast 完整版文档假设了 D1 + R2 + secret bulk，裁剪版项目跑这些步骤会报错或浪费（例如无 drizzle 配置时跑 db:migrate:remote 会找不到 migrations 目录）
3. secret bulk 是 gating step — 项目有服务端 secret（.env.production 含非 VITE_* 变量）必须在 deploy 前推到 Cloudflare，否则运行时崩溃
4. 生产部署需明确确认 — Phase 3 执行 pnpm run deploy 前必须用 AskUserQuestion 让用户最终确认（影响生产域名）
5. 域名状态决定 routes 策略 — 域名未托管 Cloudflare 时不能直接 deploy 含 routes 的配置，需先去掉 routes、deploy 拿默认域名、再到 Dashboard 绑定（详见 references/tailoring.md Routes 配置策略表）
6. 安全优先 — .env* 必须进 .gitignore；对话 / 截图 / Slack / commit message 中出现过的 secret 一律视为已泄漏，立即 rotate（见 Phase 1.5 安全 baseline + Phase 4 Secret rotation 提醒）
7. 模板占位符必查 — mkfast-template 派生项目的 wrangler.jsonc 有 4 处模板默认值必改（name / routes.pattern / database_id / bucket_name）+ 1 处必关（logpush: true 在 Free/Pro plan 必报 code 10023）。见 references/components.md §0 占位符识别表；不查就 deploy 会写到模板原作者的 D1 或 deploy 失败

工作流（4 阶段）

Phase 1 — 自动评估（只读）

Step 1.0（必做，block 后续进度）：对照 references/components.md §0 模板默认占位符识别表做 wrangler.jsonc + package.json diff。任何未替换的模板默认值——name="mkfast-template" / routes[0].pattern="demo.tanstarter.dev" / database_id="dc34f04a-3445-4b5c-bf61-c4ec2328e239" / r2.bucket_name="mkfast-template" / logpush: true——都直接 block 进 Phase 2。

这是本 skill 最重要的前置关：不查就 deploy 会（a）写到模板原作者的 D1 数据库；（b）deploy 失败报 code 10023（logpush 企业功能）；（c）routes 冲突。所有这些都是 mkfast-template 派生项目首次部署几乎必踩的坑。

读取项目状态，识别"项目画像"。最少读这 5 个文件：

读什么	提取什么
wrangler.jsonc	name / routes / d1_databases / r2_buckets / send_email / 其他 binding
package.json	name + 依赖中是否含 drizzle-orm / better-auth / stripe / creem / @beehiiv/sdk
.env.example	全部支持的变量分类（参照 references/components.md 检测信号表）
.env.production（若存在）	已配的变量 vs 未填（空字符串）的变量
.env.local（若存在）	CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN 是否就绪

按 references/components.md 的 12 类组件逐一判断启用与否，生成"项目画像"输出（格式参照 templates/deploy-checklist.md）：

• 项目形态：完整 SaaS / 裁剪版博客 / 中间形态
• 启用组件勾选表
• 环境变量缺口表
• 裁剪后的待执行步骤清单（步数）

Phase 1.5 — 安全 baseline（只读 + 必要时新建 .gitignore）

部署前必查 4 项，缺哪个补哪个，不让 secret 流出仓库是底线：

项	检查命令	不通过时的修复
.gitignore 存在且含 .env*	grep -E "\.env" .gitignore	不存在则立即创建含 .env、.env.local、.env.*.local、.env.production、.dev.vars
.env.local 不在 git history	git log --all --full-history -- .env.local 输出为空	已被 commit 过 → 用 git filter-repo 清掉 + 立即 rotate 涉及的所有 secret
wrangler.jsonc 无硬编码 secret	grep 不应见 sk_live_ / re_live_ / whsec_ 等	删硬编码，全走 wrangler secret put
.env.production 无明文 production secret 准备 commit	`cat .gitignore	grep .env.production`

裁剪版项目无 .gitignore 时（见过项目还没 git init 但已经写了 .env.local 的情况），先建 .gitignore 再继续 Phase 2。

Phase 2 — 决策点（AskUserQuestion）

基于 Phase 1 / 1.5 画像问用户，按情况选 1-5 题：

• 目标用户地域（强烈推荐先问）：全球 / 仅海外 / 主要面向中国大陆 / 国内+海外都要
  • 若选中国大陆 → ⚠️ 警告：Cloudflare 在中国大陆没有 PoP 节点（除非企业版 + 京东云合作），访问体验时通时不通；建议参考 references/cn-access.md 切换方案（EdgeOne / Vercel + 国内 CDN / 双部署）
• 域名状态（必问）：<domain> 是否托管在 Cloudflare？三选项：已托管 / 未托管（先用默认 *.workers.dev）/ 还没买
• D1 / R2 资源（仅完整版）：是否已在 Cloudflare 创建？如未创建，是否同意现在 wrangler d1 create / wrangler r2 bucket create？
• 可选功能：Giscus / 分析 / Webhook / Crisp 是否本次启用？
• CI 自动化：是否同步配 GitHub Actions auto-deploy？

裁剪决策树详见 references/tailoring.md。

Phase 3 — 执行（按裁剪后清单）

Step 0 — Sanity（强烈推荐）：

# 清掉过往 dev 留下的 dist + .vite 缓存
# 避免 chokidar 在 dev 中 EINTR 报错（曾导致 dev server 起不来）
rm -rf dist .vite node_modules/.vite

# 验证 wrangler 凭证已加载（推荐用 .env.local + 一次 source 而非 wrangler login）
# wrangler 不会自动读 vite 系的 .env.local，必须 export 到当前 shell：
set -a && . ./.env.local && set +a && pnpm wrangler whoami

推荐在 package.json 里加 alias 一次解决：

"deploy:cf": "set -a && . ./.env.local && set +a && pnpm run build && wrangler deploy"

之后用 pnpm deploy:cf 即可，避免每条 wrangler 命令都要 export。

所有项目都要做：

1. pnpm wrangler whoami 验证登录（未登录时检查 .env.local 凭证或提示 wrangler login）
2. 检查 token 权限：按启用组件查 references/components.md 的 §API Token 权限完整矩阵（Workers Scripts / D1 / R2 / Workers Routes / Email / KV 等），缺权限直接到 Dashboard → My Profile → API Tokens 编辑现有 token 加权限（不用重建）
3. AskUserQuestion 最终确认 → pnpm run deploy

仅当检测到对应组件时做（按 references/components.md 详细步骤）：

• (有 D1) pnpm wrangler d1 create <name> → 写回 wrangler.jsonc 的 database_id → pnpm db:migrate:remote
• (有 R2) pnpm wrangler r2 bucket create <name> → 写回 bucket_name
• (有 send_email) Cloudflare Dashboard 启用 Email Routing + 验证 from 邮箱
• (有 Better Auth) pnpm dlx @better-auth/cli@latest secret 生成 → wrangler secret put BETTER_AUTH_SECRET
• (有服务端 secret) pnpm wrangler secret bulk .env.production
• (有支付) Stripe/Creem live key + price ID + webhook endpoint 配置

仅当用户在 Phase 2 选了 CI：

• 创建 .github/workflows/deploy.yml + 提示去 GitHub Settings → Secrets 加 CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN / 全部 VITE_*

Phase 4 — 验证

# 在线验证（首次）
curl -s -o /dev/null -w "HTTP %{http_code} | size %{size_download}B | time %{time_total}s\n" https://<domain>

# 5-10 秒后再跑一次（验证缓存 + 二次访问性能）
curl -s -o /dev/null -w "HTTP %{http_code} | size %{size_download}B | time %{time_total}s\n" https://<domain>

预期：

指标	首次	二次（warm）
HTTP code	200	200
size	> 几 KB（SSR 渲染成功）	同首次或更小（命中缓存）
time	< 3s（含冷启动 + CDN 传播）	< 500ms（PoP 命中）

附加检查：

• deploy 输出里 Total Upload: X KiB / gzip: Y KiB → Y < 3072（3 MB 免费计划上限）
• Cloudflare Dashboard → Workers & Pages → <worker-name> → Logs → 无 runtime error
• 自定义域名首次访问可能有 30s CDN 传播延迟

上线后 30 分钟观察清单：

检查项	命令 / 位置	预期
5xx 响应率	Dashboard → Workers & Pages → <worker> → Logs → 筛 status >= 500	0 条
版本号匹配	Dashboard → <worker> → Deployments	最新 Version ID 与 deploy 输出一致
Analytics 流量	Dashboard → <worker> → Analytics（或第三方 RUM）	有正常请求进入
D1 表访问（若启用）	wrangler d1 execute <name> --remote --command "SELECT COUNT(*) FROM user"	返回数字不报错
R2 bucket 访问（若启用）	wrangler r2 object list <bucket>	列表返回不报错

回滚方案：

# 列出历史版本
pnpm wrangler deployments list

# 回滚到上一版（不传 id）
pnpm wrangler rollback

# 回滚到指定版本
pnpm wrangler rollback <version-id>

注意：

• D1 migrations 是 forward-only，schema 回滚需要手动写 down migration 并 wrangler d1 execute 应用
• R2 无版本概念，按需从备份恢复（部署前做过 wrangler r2 object get 备份才行）
• Secret 回滚：wrangler secret put <KEY> 覆盖为旧值，或 wrangler secret delete <KEY> 清除

Secret rotation 提醒（重要）： 如果本次部署过程中 token / API key / database secret 在以下任一渠道出现过：

• Claude / ChatGPT 等对话历史
• Slack / Lark / WeChat 消息
• 截图 / 录屏
• 代码注释 / commit message

→ 立即去 Cloudflare Dashboard / 第三方服务后台 roll（生成新值替代旧值）。token 字符串变了的，记得更新 .env.local 和 GitHub Secrets。

报错排查见 references/troubleshoot.md。

输出格式

每阶段结束后给用户简洁汇报，例：

Phase 1 项目画像输出（example）

## Phase 1 — 项目画像

**形态**：裁剪版博客
**启用组件**：无（纯 SSR + 博客）
**待执行步骤**：2 步（whoami + deploy）
**跳过**：D1 / R2 / Email / Auth / Pay / Secret bulk / Migrate

最终 checklist（example）

✅ wrangler 登录（账户 zhihui）
✅ pnpm run deploy（gzip 471 KB / 17ms 启动）
✅ HTTP 200 验证通过
⚠️ 可选未启用：Giscus / Plausible

工具文件

• references/components.md — mkfast-template 12 类组件检测信号 → 部署步骤映射表

  • §0 模板默认占位符识别表（Phase 1 Step 1.0 必查）
  • §API Token 权限完整矩阵（按启用组件勾权限的速查表）
  • §没 .env.example 时如何反推 secret 列表（读 src/env/*.ts 反推）

• references/tailoring.md — 完整版 vs 裁剪版 vs 中间形态裁剪决策树 + 决策矩阵速查表

  • §陷阱：enable=false 仍需保留 D1 binding（module-load-time 调用 getDb()）
  • §澄清：enable=false ≠ tree-shake（enable 只控 UX，bundle 仍含 SDK）

• references/troubleshoot.md — 11 个常见报错 + 排查命令 + 修复（含 #10 Logpush / #11 already exists）

• references/cn-access.md — 中国大陆访问优化 4 档方案（Cloudflare 设置 / 图床 / EdgeOne 反代 / 双部署）

• templates/deploy-checklist.md — Phase 1 项目画像输出模板 + 最终汇报模板 + AskUserQuestion 模板

• templates/stub-no-d1-r2.md — 彻底关闭 D1/R2 的代码 stub 模板（4 文件改动可粘贴版本）