快速开始

准备

• Bun——这个仓库只用这一个包管理器
• 一个 Google Cloud 项目，用来拿 OAuth 凭据（Google 登录是必需的；GitHub 登录和邮箱验证码登录是可选的补充）
• 一个 Cloudflare 账号——部署时才需要，本地运行用不到

安装

bun install
bun run db:migrate:local
bun run dev            # http://localhost:3000

密钥放在 .dev.vars 里，这个文件已被 gitignore。先用 cp .dev.vars.example .dev.vars 拿到完整的键列表，登录之前至少要填好 BETTER_AUTH_SECRET（openssl rand -base64 32）和两个 Google OAuth 的值。 环境变量在启动时读取，所以改完要重启 dev server。每个密钥都在密码管理器里留一份： 只存在于某个终端或某个后台里的密钥，迟早会丢。

dev server 把你的代码跑在 workerd 里，带本地的 D1 和 R2 绑定，所以本地行为和 线上一致。本地状态在 .wrangler/state 下，同样被 gitignore。

如果你用 Claude Code，/setup 会把上面这些全做完，并创建第一个管理员； /google-oauth、/stripe 和 /deploy 负责那些必须在浏览器里完成的账号配置。

把自己设为管理员

先登录一次，然后改自己那一行：

bunx wrangler d1 execute DB --local \
  --command "UPDATE user SET role='admin' WHERE email='you@example.com';"

之后侧边栏里就能进 /admin 了。

第一次部署之前

把 src/config/app-config.ts 过一遍——名称、规范 URL、客服邮箱和法律主体会出现在 营销页、每一封事务邮件，以及服务条款和隐私政策页面里。然后是 src/config/plans.ts：在你创建好支付商品目录之前，里面的商品 id 都是占位符。

部署

wrangler d1 create shipkit            # 把返回的 id 填进 wrangler.jsonc
wrangler r2 bucket create shipkit-files
bun run db:migrate:remote          # 迁移只能手动执行，CI 永远不会替你跑
wrangler secret put BETTER_AUTH_SECRET   # 其余密钥照此重复
bun run deploy

只要还有未执行的迁移，CI 就会拒绝部署，所以先把迁移跑完。