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

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

## 1. 环境准备

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

在项目根目录执行：

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

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

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

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

- `~/.nanobot/config.json`

## 2. 启动后端（Web API）

在项目根目录执行：

```bash
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`

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

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

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

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

```bash
export NANOBOT_AUTH_FILE=/your/path/users.json
```

## 3. 启动前端（Next.js）

新开一个终端，执行：

```bash
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 前显式设置主前端公开地址：

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

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

```bash
uv sync
```

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

```bash
uv sync --extra dev
```

## 6. 停止服务

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