快速开始

本地准备

安装 Bun 1.4.2+、Python 3 和本地 PostgreSQL，使用隔离数据库。新站从模板复制，不能复用已有站的密钥或数据库。

bun install --frozen-lockfile
cp .env.example .env.local
bun -e 'console.log(crypto.randomUUID()+crypto.randomUUID())'

把生成的字符串填入 .env.local 的 BETTER_AUTH_SECRET。设置独立本地 DATABASE_URL，使 APP_ORIGIN 和 PUBLIC_SITE_URL 同为 http://localhost:4410。preview:start 和 bun dev 都使用本地 Workers 运行器，将邮件捕获到 .local/outbox.jsonl，不会调用真实 Resend。

bun run config:check
# 只对刚准备好的隔离数据库执行：
bun db:migrate
bun preview:build
bun run preview:start
bun run preview:status

产品演示、工具及工作台：http://localhost:4410。停止：bun run preview:stop。启动器不安装 PostgreSQL，不建立生产数据库。

看配置文档

bun run docs:dev --host 127.0.0.1 --port 4406

文档地址：http://localhost:4406。文档与客户工具站分开构建；bun run docs:build 后，preview:start 会同时启动 4406 文档预览。文档目录是维护者入口，产品页面不展示技术配置。

改完后检查

bun run config:check
bun typecheck
bun web:check
bun run test -- --run
bun lint
bun format:check
bun preview:build
bun run docs:build

bun typecheck 会先生成 Astro 内容集合类型，再检查项目引用图，首次安装后可直接运行；无需先启动预览或构建官网。生成产品只同步自己的公开站。.astro 为生成目录，不提交；这个步骤不代替 bun web:check 的页面模板检查，也不会迁移数据库或调用外部服务。

预览使用构建产物：前端修改后重建并刷新，API 修改后停止再启动。bun dev 可用于热更新；本地数据库连接由 loopback DATABASE_URL 统一派生，详见环境变量。

本机演示与新站的区别

本机已有独立 launchkit 数据库，端口 54329，及演示账号。新复制的站没有这些账号或历史数据，不应把演示密码作为上线默认账号。

官网与独立演示

本仓库 localhost:4400 为模板官网，完整产品演示位于 localhost:4410。端口由 preview.config.json 管理，preview:build 与 preview:start 自动使用同一配置。文档仍在 localhost:4406。详见官网、案例与演示。