144 lines
2.9 KiB
Markdown
144 lines
2.9 KiB
Markdown
# 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` 即可停止。
|