第一次提交

app-instance/backend/guide.md

@@ -0,0 +1,143 @@
+# nanobot 前后端分离启动指南（单用户直连）
+
+本指南对应当前仓库：
+`/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
+```
+
+如果你第一次使用 nanobot，需要先初始化：
+
+```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` 即可停止。