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 ノードがありません（Enterprise プランと JD Cloud の提携を除く）。アクセスが安定しない場合があります。references/cn-access.md を参考に、切り替え方法をご検討ください（EdgeOne／Vercel + 国内 CDN／二重デプロイ）
• ドメインの状態（必須）：<domain> は Cloudflare でホストされていますか？3 つの選択肢：ホスト済み／未ホスト（まずはデフォルトの *.workers.dev を使用）／まだ購入していない
• D1／R2 リソース（フル版のみ）：Cloudflare で作成済みですか？未作成の場合、今すぐ wrangler d1 create／wrangler r2 bucket create を実行してもよいですか？
• オプション機能：Giscus／分析／Webhook／Crisp を今回有効にしますか？
• CI の自動化：GitHub Actions の自動デプロイも設定しますか？

判断ツリーの調整については 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 にエイリアスを追加して、一度に解決する方法をおすすめします：

"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. トークンの権限を確認します。有効なコンポーネントに応じて、references/components.md の §API Token 権限の完全なマトリックスを確認します（Workers Scripts／D1／R2／Workers Routes／Email／KV など）。権限が足りない場合は、Dashboard → My Profile → API Tokens で既存のトークンを編集し、権限を追加します（作り直す必要はありません）
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>

想定結果：

指標	初回	2 回目（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 がないこと
• カスタムドメインへの初回アクセスでは、CDN への反映に 30s かかる場合があります

公開後 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 ローテーションに関する注意（重要）： 今回のデプロイ中に、以下のいずれかの経路で token／API key／database secret が露出したことがある場合：

• Claude／ChatGPT などの会話履歴
• Slack／Lark／WeChat のメッセージ
• スクリーンショット／画面録画
• コードコメント／commit message

→ 直ちに Cloudflare Dashboard／サードパーティサービスの管理画面でローテーションしてください（新しい値を生成して古い値と置き換えます）。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

最終チェックリスト（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 文件改动可粘贴版本）