beaver_project/app-instance/backend-old/guide.md

Boardware Genius 前后端分离启动指南（单用户直连）

本指南对应当前仓库： /home/ivan/xuan/steven_project/nanobot

1. 环境准备

• Python: >=3.11
• Node.js: >=18
• 包管理工具: uv、npm

在项目根目录执行：

cd /home/ivan/xuan/steven_project/nanobot
uv sync

如果你第一次使用 Boardware Genius，需要先初始化：

./.venv/bin/python -m nanobot onboard

然后编辑配置文件（至少配置一个可用模型）：

• ~/.nanobot/config.json

2. 启动后端（Web API）

在项目根目录执行：

cd /home/ivan/xuan/steven_project/nanobot
./.venv/bin/python -m nanobot web --host 127.0.0.1 --port 10000

启动成功后会看到类似日志：

• Uvicorn running on http://127.0.0.1:10000

可用接口示例：

• GET http://127.0.0.1:10000/api/status

2.1 准备登录账号 JSON（必需）

Web 登录会读取本地账号文件，默认路径：

• /home/ivan/xuan/steven_project/nanobot/web_auth_users.json

示例内容（任选一种格式）：

{
  "users": [
    { "username": "admin", "password": "123456" }
  ]
}

{
  "admin": "123456",
  "alice": "alice_pwd"
}

也可通过环境变量指定自定义路径：

export NANOBOT_AUTH_FILE=/your/path/users.json

3. 启动前端（Next.js）

新开一个终端，执行：

cd /home/ivan/xuan/steven_project/nanobot/frontend
cp env_template .env.local
npm install
npm run dev

前端默认地址：

• http://127.0.0.1:3080

前端默认会请求：

• NEXT_PUBLIC_API_URL=http://127.0.0.1:10000

注意：如果你之前已经有 frontend/.env.local，请确认里面不是旧地址（例如 localhost:8080）。

如果你要改后端地址，修改：

• frontend/.env.local

4. 访问与验证

1. 打开 http://127.0.0.1:3080
2. 首屏应进入登录页
3. 使用 web_auth_users.json 中正确的账号密码登录
4. 登录成功后进入对话页并可正常收发消息

5. 常见问题

5.1 前端显示“未连接/服务离线”

按顺序检查：

1. 后端是否在运行（终端是否有 Uvicorn running ...）
2. 前端 NEXT_PUBLIC_API_URL 是否指向正确地址
3. 端口是否被占用（10000 / 3080）

5.2 后端启动报 No module named fastapi

在项目根目录重新执行：

5.3 反向代理下登录后跳错前端域名

如果 API 域名和主前端域名不同，启动 backend 前显式设置主前端公开地址：

export NANOBOT_FRONTEND_PUBLIC_BASE_URL=https://nanobot.bwgdi.com

这样登录/注册成功后，backend 返回的 frontend_base_url 会固定为这个公开域名，而不是按 API 域名去拼 :3080。

uv sync

5.3 需要开发测试工具（pytest/ruff）

uv sync --extra dev

6. 停止服务

• 在各自终端按 Ctrl + C 即可停止。