better-chatbot

环境要求

• 已安装 pnpm（项目推荐的包管理器）
• 可用的 PostgreSQL 数据库（本地或 docker 启动）
• 至少一个 AI 提供商的 API Key（OpenAI、Claude、Gemini 等）
• 使用 Docker Compose 方式时需已安装 Docker

安装与启动步骤

1. 1获取项目源码

   从 GitHub 克隆仓库并进入项目目录，后续命令都在该目录下执行。

   git clone https://github.com/keinsaasforever/better-chatbot.git
   cd better-chatbot

   复制

2. 2安装依赖

   用 pnpm 安装全部依赖；执行后项目会自动生成 .env 文件，稍后按需修改。

   pnpm i

   复制

3. 3配置环境变量

   在 .env 中填写至少一个 AI 提供商 API Key（如 OPENAI_API_KEY）以及要使用的数据库地址。

   POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name

   复制

4. 4启动本地数据库

   本地没有 PostgreSQL 时用该命令启动一个；已有自己的数据库可跳过这一步。

   pnpm docker:pg

   复制

5. 5本地启动应用

   构建并启动本地版本；开发调试阶段也可以改用 pnpm dev 启动。

   pnpm build:local && pnpm start

   复制

6. 6Docker Compose 启动

   一步拉起应用与 PostgreSQL 等全部服务，适合不想在本地单独装数据库的场景。

   pnpm docker-compose:up

   复制

7. 7打开界面

   浏览器访问 http://localhost:3000 即可开始使用聊天界面。

关键配置

如何确认成功

浏览器打开 http://localhost:3000 能正常加载聊天界面并能发送消息即启动成功。

常见问题

注意事项

• 项目推荐使用 pnpm 作为包管理器，不要随意换成 npm/yarn。
• 执行 pnpm i 时会自动创建 .env 文件，填好配置后再启动应用。
• 自托管 Docker 的完整环境变量说明见 docs/tips-guides/docker.md。
• 本地开发推荐 pnpm dev，正式本地运行用 pnpm build:local && pnpm start。