---
url: /docs/getting-started/quick-start.md
---
# 启动项目

## 使用哪种启动方式

首次排查建议使用完整的 [本地预览流程](../agentbuff-stack/quick-start.md)。它使用构建产物，在 `http://localhost:4400` 提供公开站、登录、工作台和接口；邮件写入本地收件记录。文档使用 `http://localhost:4406`。

准备 Bun 1.4.2 或更新版本、Python 3 和独立 PostgreSQL 数据库。先复制 `.env.example` 为 `.env.local`，设置数据库地址、独立认证密钥及本地站点地址，再执行：

```sh
bun install --frozen-lockfile
bun run config:check
# 确认连接的是新建的隔离数据库后再迁移
bun db:migrate
bun build
bun run docs:build
bun run preview:start
bun run preview:status
```

启动器不会安装数据库。已有本机演示数据库和账号不属于复制新站的默认配置。

## 开发时热更新

```sh
bun dev
```

此方式并行启动公开站、工作台和接口开发服务，实际端口以终端输出为准。接口走 Wrangler 的本地代理，需要配置两条 Hyperdrive 本地连接变量；邮件使用真实 Resend，配置见 [环境变量说明](./environment-variables.md)。不要把它和捕获邮件的完整预览流程混淆。

只改文档时可单独运行：

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

若 4406 已由预览管理器占用，先停止该预览再启动开发服务。

## 常见问题

* 页面无法访问：检查 `bun run preview:status`，再看 `.local` 中对应服务日志，确认端口未被其他程序占用。
* 页面没有更新：预览读取构建产物。先重建，再停止并启动预览；文档预览同样需要重启。
* 接口提示缺表：检查 `DATABASE_URL` 目标及迁移记录，不要直接对未知数据库执行结构推送。
* 登录成功后跳回登录页：检查 `APP_ORIGIN`、浏览器地址与会话请求，详见 [会话与访问控制](../auth/sessions.md)。