部署到 Cloudflare

把应用部署到 Cloudflare 的全球边缘网络。整套栈(Workers + D1 + KV + R2)在 Cloudflare 免费额度内就能跑起来。

前置准备

• 一个 Cloudflare 账号(免费):dash.cloudflare.com 注册。
• 已在本地跑通(见 本地安装与启动)。
• 本项目自带 wrangler(Cloudflare 的命令行工具),用 npx wrangler 调用,无需单独安装。
• 已生成本地 Wrangler 配置:cp wrangler.example.jsonc wrangler.jsonc。wrangler.jsonc 含真实资源 id,已被 git 忽略;仓库里提交的是占位模板 wrangler.example.jsonc。

1. 登录 Cloudflare

npx wrangler login

会打开浏览器让你授权,点同意即可。

2. 创建线上资源

应用要用到三种存储资源,逐条创建:

npx wrangler d1 create flarestarter-db-prod          # D1 数据库
npx wrangler kv namespace create CACHE               # KV(会话/缓存)
npx wrangler r2 bucket create flarestarter-files-prod # R2 对象存储(头像上传)

3. 回填资源 id

打开 wrangler.jsonc,找到 env.production,把上一步打印的 database_id 与 KV id 填进去(替换掉占位的全 0 值)。

4. 配置生产环境 Secrets

密钥类配置不进代码库,用 wrangler secret put 单独写入(命令执行后会提示你粘贴值):

# 必填 —— 会话加密密钥(openssl rand -base64 32 生成)
npx wrangler secret put BETTER_AUTH_SECRET --env production
# 邮件发送(Resend)—— 正式对外强烈建议配置,原因见下方 Callout
npx wrangler secret put RESEND_API_KEY --env production
npx wrangler secret put EMAIL_FROM --env production   # 发信地址,如 noreply@your-domain.com
# 社交登录(可选,留空则按钮不显示)
npx wrangler secret put GOOGLE_CLIENT_ID --env production
npx wrangler secret put GOOGLE_CLIENT_SECRET --env production
npx wrangler secret put GITHUB_CLIENT_ID --env production
npx wrangler secret put GITHUB_CLIENT_SECRET --env production
# Stripe 计费
npx wrangler secret put STRIPE_SECRET_KEY --env production
npx wrangler secret put STRIPE_WEBHOOK_SECRET --env production
# 可选:Turnstile bot 防护(两个 key 都设才生效;见 安全加固)
npx wrangler secret put TURNSTILE_SECRET_KEY --env production
# 可选:Sentry 错误上报(见 可观测性)
npx wrangler secret put SENTRY_DSN --env production

公开值(非机密)则直接写进 wrangler.jsonc 的 env.production.vars,留空即关闭对应功能:

• TURNSTILE_SITE_KEY(Turnstile 站点 key)
• CF_ANALYTICS_TOKEN(Web Analytics beacon token)
• STRIPE_PRICE_PRO_MONTHLY/YEARLY(线上 price ID;写 vars 或 secret put 均可)
• BETTER_AUTH_URL —— 设为你的线上域名,例如 https://flarestarter.example.com。首次只发 workers.dev 时还没有自定义域,可先填可预测的 https://flarestarter-production.<你的子域>.workers.dev, 之后绑定自定义域再改回来。

Stripe webhook:在 Stripe Dashboard 为线上域名创建 endpoint https://<域名>/api/webhooks/stripe,订阅事件 customer.subscription.created、 customer.subscription.updated、customer.subscription.deleted、 checkout.session.completed、checkout.session.async_payment_succeeded、 charge.refunded、invoice.payment_failed(启用赞助墙再加 invoice.paid、 charge.dispute.created);创建后把签名密钥(whsec_…)用上面的 STRIPE_WEBHOOK_SECRET 命令写入。

运营后台:npx wrangler secret put ADMIN_EMAILS --env production(逗号分隔的管理员 邮箱);详见 基础 Admin。

5. 对生产库应用迁移

pnpm db:migrate:prod
# 等价于:npx wrangler d1 migrations apply flarestarter-db-prod --env production --remote

这会在线上库建好所有表(含 auth 表)。

6. 构建并部署

pnpm deploy:prod
# 等价于:CLOUDFLARE_ENV=production pnpm build && npx wrangler deploy

部署完成后 wrangler 会打印 https://<name>.<subdomain>.workers.dev。首次需要在 Dashboard 启用 workers.dev 子域,DNS 传播可能要等 ~1 分钟。

环境与 CI/CD

环境分三层:local(Miniflare/workerd)/ staging / production。CI/CD 在 .github/workflows/:ci.yml 跑 lint + typecheck + test + build;deploy.yml 在 push 到 main 时以 CLOUDFLARE_ENV=production build 后自动部署 —— 需在仓库 Secrets 配好 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID(未配则整个部署优雅跳过,不留红叉)。

wrangler.jsonc 不入库(含真实资源 id),两个 workflow 都会从提交的占位模板 wrangler.example.jsonc 在 CI 里重新生成它:

• ci.yml——直接 cp wrangler.example.jsonc wrangler.jsonc,占位值足够通过 build 检查 (CI 不部署,占位符只被烘焙进产物、不校验真实性),fork/PR 无需任何配置即可绿。

• deploy.yml——跑 .github/scripts/gen-wrangler.mjs,把真实生产 id 注入 production 段。 这些 id 不是机密,用仓库 Variables(Settings → Secrets and variables → Actions → Variables)传入:

  名称	必填	说明
  CF_PROD_D1_ID	✅	生产 D1 的 database_id
  CF_PROD_KV_ID	✅	生产 KV 命名空间 id
  CF_PROD_DOMAIN	可选	自定义域名(如 example.com),设了才注入 routes

  新增 binding/vars 时记得同步改 wrangler.example.jsonc,别让模板与实际配置漂移。