---
url: /docs/agentbuff-stack/quick-start.md
---
# 快速开始

## 本地准备

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

```sh
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。

```sh
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，不建立生产数据库。

## 看配置文档

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

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

## 改完后检查

```sh
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` 统一派生，详见[环境变量](./env.md)。

## 本机演示与新站的区别

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

## 官网与独立演示

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