tinyship-cloudflare

TinyShip Cloudflare 配置

一站式向导，用于配置 TinyShip（TanStack Start）的完整 Cloudflare 技术栈。

这是一个对话式的分步向导。每当遇到决策点时，你都必须询问用户，并等待对方回答后再继续。绝对不要替用户做决定。

步骤 0：检测模板并选择流程

首先，阅读 ../../references/template-detection.md 并检测当前项目所用的模板。

如果项目是 tinyship-cf（仅适用于 Cloudflare 的模板）

项目已经原生支持 Cloudflare——绑定、D1 和 Workers 配置均已预先设置。不要运行框架清理或 Wrangler 脚手架命令。直接进入下方的快速流程。

如果项目是 shipeasy（多框架模板）

⛔ 停止——继续之前，必须告知用户并征求同意。

TinyShip 现在有专为 Cloudflare 打造的模板（tinyship-cf），已预先配置好 Workers（无需变通方案，也无需清理框架）。对于新的 Cloudflare 项目，建议从 tinyship-cf 开始。

• 继续使用当前项目——在此 shipeasy 项目中配置 Cloudflare（如果你已经基于它开发了功能，这样做很合理）
• 切换到 tinyship-cf——从专用模板重新开始，并手动迁移你的改动

如果用户选择继续，请按照下方的完整向导操作。

---

快速流程（tinyship-cf 项目）

1. Wrangler 登录

cd apps/tanstack-app
npx wrangler login
npx wrangler whoami   # capture the Account ID

如果已经登录，请跳过此步骤并告知用户。

2. 本地环境变量

cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars

设置 BETTER_AUTH_SECRET（openssl rand -hex 32）。验证本地开发环境：

pnpm dev   # http://localhost:7001

3. 远程数据库

D1 数据库已在 wrangler.jsonc 中绑定。应用迁移并验证：

npx wrangler d1 migrations apply tinyship-db --remote

如果要使用 Hyperdrive + PostgreSQL 而非 D1，请阅读并按照 references/hyperdrive-setup.md 操作。

4. 密钥

⛔ 停止——询问用户使用了哪些功能，然后只设置对应的密钥。

npx wrangler secret put BETTER_AUTH_SECRET      # required
# Payments (as needed): STRIPE_SECRET_KEY, PAYPAL_CLIENT_ID/SECRET,
#   DODO_PAYMENTS_API_KEY/WEBHOOK_KEY, CREEM_API_KEY/WEBHOOK_SECRET
# AI image/video (as needed): QWEN_API_KEY, FAL_API_KEY,
#   GOOGLE_GENERATIVE_AI_API_KEY, VOLCENGINE_ACCESS_KEY_ID
# Email: RESEND_API_KEY

注意：

• 聊天 AI 无需密钥——它运行在 Workers AI + AI Gateway 上。第三方聊天密钥（OpenAI/DeepSeek）在 AI Gateway 控制面板中管理（BYOK）。
• AI_GATEWAY_ID 默认为 default；如果用户的网关名称不同，请在 wrangler.jsonc 的 vars 中设置。
• 各服务提供商控制面板中的支付 webhook URL 必须指向生产环境域名。

5. 可选扩展

逐项询问用户，然后阅读并按照相应的参考文档操作：

• R2 存储——references/r2-setup.md（存储桶已绑定）
• 邮件发送——references/email-setup.md
• Turnstile——references/turnstile-setup.md

6. 部署

pnpm deploy:cf

验证：首页返回 200，/en/pricing 返回 200，登录功能正常。如果 pricing_plan 表为空且 PRICING_MODE=dynamic，请以管理员身份登录 → Admin → Pricing Plans → Import Static，以填充套餐。

前往步骤 8：摘要。

---

完整向导（shipeasy 项目）

**范围：**此向导为 TanStack Start（apps/tanstack-app）配置 Cloudflare Workers 部署。Next.js 和 Nuxt.js 面向 Node.js 环境，不支持部署到 Workers。

前置条件

1. Node.js >= 22.20.0——运行 node -v
2. pnpm >= 9.0.0——运行 pnpm -v
3. 已安装依赖——如果缺少 node_modules/，运行 pnpm install
4. Cloudflare 账户——https://dash.cloudflare.com/sign-up

步骤 1：Wrangler 登录

运行以下命令以通过 Cloudflare 身份验证：

cd apps/tanstack-app
npx wrangler login

这会打开浏览器进行授权。成功后，验证：

npx wrangler whoami

从输出中记下账户 ID——后续配置 R2 和邮件时会再次使用。

如果用户已登录（wrangler whoami 显示账户信息），请跳过此步骤并告知用户。

步骤 2：清理框架

⛔ 停止 — 继续之前必须先询问用户。

由于 Cloudflare Workers 仅支持 TanStack Start，因此面向纯 Cloudflare 部署时不需要 Next.js 和 Nuxt.js 应用。询问用户：

你已选择全套使用 Cloudflare 的方案，该方案仅使用 TanStack Start。 你要从项目中移除 Next.js 和 Nuxt.js 应用吗？

选项	操作
是 — 清理	移除 apps/next-app 和 apps/nuxt-app，更新工作区配置
否 — 保留	保留这些应用（如果你也计划部署到 Node.js，则很有用）

如果用户选择是：

按照 tinyship-setup 技能中的清理流程操作： 阅读并遵循 ../tinyship-setup/references/framework-cleanup.md， 并保留 TanStack Start 作为框架。

操作摘要：

1. rm -rf apps/next-app apps/nuxt-app
2. 更新 turbo.json — 从构建输出中移除 .nuxt/**、.output/**、.next/**
3. 更新根目录 package.json — 移除 dev:next、build:next、dev:nuxt、build:nuxt 等， 将 dev:tanstack → dev、build:tanstack → build 等
4. 更新 docker-compose.yml — 移除 next-app 和 nuxt-app 服务
5. 更新 .github/workflows/ci.yml — 移除已删除应用的构建步骤
6. 运行 pnpm install 清理锁文件

清理完成后，运行 pnpm typecheck 和 pnpm build（现在指向 TanStack）进行验证。

如果用户选择否：

跳过此步骤。其他应用仍保留在项目中，但不会部署到 Workers。

步骤 3：数据库 — D1 或 Hyperdrive

⛔ 停止 — 继续之前必须先询问用户。

列出以下选项并等待用户回复：

选项	数据库	最适用于
A	Cloudflare D1（SQLite）	全套使用 Cloudflare、无外部依赖、成本低
B	Hyperdrive + PostgreSQL	复用现有 PG、较高的写入并发、与 Next/Nuxt 数据一致

说明各自的权衡：

• D1：全托管，包含在 Workers 计费中，限制为 5-10 GB，单写入器限制
• Hyperdrive：需要外部 PostgreSQL，但没有存储限制，3 个应用共用同一个数据库

如果用户选择 D1：

阅读并遵循 references/d1-setup.md。

如果用户选择 Hyperdrive：

阅读并遵循 references/hyperdrive-setup.md。

配置好数据库后，在本地验证：

cd apps/tanstack-app
pnpm dev:cf

检查应用能否加载，以及依赖数据库的页面能否正常工作。将结果告知用户。

步骤 4：R2 存储（可选）

⛔ 停止 — 继续之前必须先询问用户。

询问：你要设置 Cloudflare R2 来存储文件（图片、上传文件）吗？

• 是 — 阅读并遵循 references/r2-setup.md
• 否 — 跳过（之后也可以配置）

步骤 5：发送电子邮件（可选）

⛔ 停止 — 继续之前必须先询问用户。

询问：你要使用 Cloudflare Email Sending 发送事务性电子邮件 （验证码、密码重置邮件）吗？

• 是 — 阅读并遵循 references/email-setup.md
• 否 — 跳过（默认使用 Resend，也可以之后配置）

步骤 6：Turnstile 机器人防护（可选）

⛔ 停止 — 继续之前必须先询问用户。

询问：你要启用 Cloudflare Turnstile（CAPTCHA）来保护登录/注册吗？

• 是 — 阅读并遵循 references/turnstile-setup.md
• 否 — 跳过（默认禁用，之后可以安全地添加）

步骤 7：部署到 Workers

⛔ 停止 — 继续之前必须先询问用户。

询问：你要现在部署到 Cloudflare Workers，还是仅完成本地设置？

• 现在部署 — 阅读并遵循 references/workers-deploy.md
• 稍后部署 — 告知用户，他们随时可以通过 cd apps/tanstack-app && pnpm run deploy:cf 进行部署

步骤 8：总结

设置完成后，请总结已配置的内容：

✅ Cloudflare Setup Complete
─────────────────────────────
Template:   [tinyship-cf (fast path) / shipeasy (full wizard)]
Frameworks: TanStack Start only [Next/Nuxt removed / kept]
Workers:    TanStack Start on Cloudflare Workers
Database:   [D1 / Hyperdrive+PG] — configured and verified
Storage:    [R2 / skipped]
Email:      [Cloudflare Email / skipped]
Turnstile:  [enabled / skipped]
Deployment: [deployed to <url> / ready for deploy]

Next steps:
- tinyship-cf: `pnpm dev` for local dev, `pnpm deploy:cf` to deploy
- shipeasy: `cd apps/tanstack-app && pnpm dev:cf` / `pnpm run deploy:cf`
- Use `npx wrangler tail` to view live logs

TinyShip 仓库中的参考文件

执行此技能时，请读取用户项目中的以下文件以获取上下文：

• apps/tanstack-app/wrangler.jsonc — 当前的 Wrangler 配置
• apps/tanstack-app/CF-NOTES.md — 已知的 Cloudflare 易踩问题
• apps/tanstack-app/.dev.vars.example — 本地开发变量模板（tinyship-cf）
• env.example — 所有环境变量（仅 shipeasy）
• apps/tanstack-app/vite.config.ts — CF 插件的条件加载
• docs/user-guide/deployment/cloudflare-workers.md — 完整的部署指南
• config/storage.ts — R2 配置结构
• config/email.ts — Email 配置结构
• config/captcha.ts — Turnstile 配置结构