186 lines
6.9 KiB
Markdown
186 lines
6.9 KiB
Markdown
# Dashboard Nanobot
|
||
|
||
Dashboard Nanobot 是面向 `nanobot` 的控制平面项目，提供镜像管理、引导创建和运行运维能力。
|
||
|
||
## 当前实现特性
|
||
|
||
- 零侵入引擎接入：通过 Docker 容器 + workspace 文件管理，不改 nanobot 源码。
|
||
- 镜像登记流：只从 `docker images` 获取本地 `nanobot-base:*`，手工登记后才可用于创建。
|
||
- 引导式创建：支持 provider/model 配置、模型连通性测试、标准模型参数配置。
|
||
- Bootstrap 文件配置：支持创建时配置并持久化：
|
||
- `AGENTS.md`
|
||
- `SOUL.md`
|
||
- `USER.md`
|
||
- `TOOLS.md`
|
||
- `IDENTITY.md`
|
||
- 模板管理：系统级模板改为文件化配置（`data/templates/agent_md_templates.json` 与 `data/templates/topic_presets.json`）。
|
||
- 2D 运维 Dashboard：Bot 列表、启停、命令发送、日志流、遥测。
|
||
- UI 全局支持：Light/Dark 切换、中文/English 切换。
|
||
|
||
## 架构概览
|
||
|
||
```mermaid
|
||
graph TD
|
||
User((User)) --> Frontend[Frontend Control Plane]
|
||
Frontend --> API[FastAPI Backend]
|
||
API --> DB[(PostgreSQL)]
|
||
API --> Docker[Docker Daemon]
|
||
|
||
Docker --> BotA[Bot Container A]
|
||
Docker --> BotB[Bot Container B]
|
||
|
||
BotA --> WS[WebSocket State Stream]
|
||
BotB --> WS
|
||
WS --> Frontend
|
||
```
|
||
|
||
## 目录
|
||
|
||
```text
|
||
/dashboard-nanobot
|
||
├── backend/
|
||
│ ├── core/
|
||
│ ├── models/
|
||
│ └── main.py
|
||
├── frontend/
|
||
│ └── src/
|
||
├── design/
|
||
│ ├── dashboard-nanobot.md
|
||
│ ├── architecture.md
|
||
│ └── database.md
|
||
└── data/
|
||
```
|
||
|
||
## 文档
|
||
|
||
- 技术规范书：`design/dashboard-nanobot.md`
|
||
- 架构设计：`design/architecture.md`
|
||
- 数据库设计：`design/database.md`
|
||
|
||
## 默认资源
|
||
|
||
- 项目根目录 `data/templates/` 保存默认模板资源，会在初始化时同步到运行时数据目录。
|
||
- 项目根目录 `data/skills/` 保存默认 skill 包，会在数据库初始化阶段自动注册到 `skill_market_item`。
|
||
- `data/model/` 不包含语音识别模型文件；模型需要用户自行下载放入该目录或 `STT_MODEL_DIR` 指向的目录。
|
||
- 如果语音模型缺失，后端启动时会打印明确告警，但不会阻断服务启动。
|
||
|
||
## 环境变量配置
|
||
|
||
- 后端：
|
||
- 示例文件：`backend/.env.example`
|
||
- 本地配置：`backend/.env`
|
||
- 关键项：
|
||
- `DATABASE_URL`：数据库连接串（建议使用 PostgreSQL）
|
||
- `DATABASE_ECHO`：SQL 日志输出开关
|
||
- 不提供自动数据迁移（如需升级迁移请离线完成后再切换连接串）
|
||
- `DATA_ROOT`、`BOTS_WORKSPACE_ROOT`：运行数据与 Bot 工作目录
|
||
- `DEFAULT_*_MD`：可选覆盖值（一般留空，推荐走模板文件）
|
||
- 前端：
|
||
- 示例文件：`frontend/.env.example`
|
||
- 本地配置：`frontend/.env`
|
||
- 关键项：
|
||
- `VITE_API_BASE`：后端 API 地址
|
||
- `VITE_WS_BASE`：后端 WS 地址
|
||
|
||
创建向导中的 `soul_md / agents_md / user_md / tools_md / identity_md`
|
||
已改为后端统一下发（`GET /api/system/defaults`），前端不再写死。
|
||
|
||
## Docker 生产部署（推荐）
|
||
|
||
### 目标
|
||
|
||
- 前后端均容器化部署
|
||
- 后端 Python 3.12
|
||
- 前端由 Nginx 托管静态资源并反代后端 API/WS
|
||
- 仅暴露 Nginx 端口（后端不对外暴露）
|
||
- 后端容器可通过 Docker Socket 启停 Bot 容器
|
||
|
||
### 文件
|
||
|
||
- `docker-compose.prod.yml`
|
||
- `backend/Dockerfile`（Python 3.12）
|
||
- `frontend/Dockerfile`（Nginx Web Server）
|
||
- `frontend/docker/nginx.conf`
|
||
- `.env.prod.example`
|
||
- `scripts/deploy-prod.sh`
|
||
- `scripts/stop-prod.sh`
|
||
|
||
### 启动步骤
|
||
|
||
1. 准备部署变量
|
||
- 复制 `.env.prod.example` 为 `.env.prod`（位于项目根目录）
|
||
- `data/` 会自动映射到宿主机项目根目录下的 `./data`
|
||
- 只需要配置绝对路径：
|
||
- `HOST_BOTS_WORKSPACE_ROOT`
|
||
- 如启用本地语音识别，请将 Whisper `.bin` 模型文件放到宿主机项目根目录的 `data/model/`
|
||
并让 `STT_MODEL` 指向完整文件名，例如 `ggml-small-q8_0.bin`
|
||
- 中国网络建议配置加速项：
|
||
- `PIP_INDEX_URL`、`PIP_TRUSTED_HOST`
|
||
- `NPM_REGISTRY`
|
||
- 如需基础镜像加速，覆盖 `PYTHON_BASE_IMAGE` / `NODE_BASE_IMAGE` / `NGINX_BASE_IMAGE`
|
||
2. 启动服务
|
||
- `./scripts/deploy-prod.sh`
|
||
- 或：`docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build`
|
||
3. 访问
|
||
- `http://<host>:${NGINX_PORT}`（默认 `8080`）
|
||
|
||
### 关键说明
|
||
|
||
- `backend` 不开放宿主机端口，仅在内部网络被 Nginx 访问。
|
||
- 上传大小使用单一参数 `UPLOAD_MAX_MB` 控制（后端校验 + Nginx 限制）。
|
||
- 必须挂载 `/var/run/docker.sock`，否则后端无法操作 Bot 镜像与容器。
|
||
- `data/` 始终绑定到宿主机项目根目录下的 `./data`，其中模板、默认 skills、语音模型和运行数据都落在这里。
|
||
- `HOST_BOTS_WORKSPACE_ROOT` 必须是宿主机绝对路径，并且在 `docker-compose.prod.yml` 中以“同路径”挂载到后端容器。
|
||
原因：后端通过 Docker API 创建 Bot 容器时，使用的是宿主机可见的 bind 路径。
|
||
- 语音识别当前基于 `pywhispercpp==1.3.1` + Whisper `.bin` 模型文件，不使用 `faster-whisper`。
|
||
|
||
## Docker 完整部署（内置 PostgreSQL / Redis）
|
||
|
||
这套方案和 `deploy-prod.sh` 并存，适合目标机器上直接把前端、后端、PostgreSQL、Redis 一起拉起。
|
||
|
||
### 文件
|
||
|
||
- `docker-compose.full.yml`
|
||
- `.env.full.example`
|
||
- `scripts/deploy-full.sh`
|
||
- `scripts/init-full-db.sh`
|
||
- `scripts/stop-full.sh`
|
||
- `scripts/sql/init-postgres-bootstrap.sql`
|
||
- `scripts/sql/init-postgres-app.sql`
|
||
|
||
### 启动步骤
|
||
|
||
1. 准备部署变量
|
||
- 复制 `.env.full.example` 为 `.env.full`
|
||
- `data/` 会自动映射到宿主机项目根目录下的 `./data`
|
||
- 必填修改：
|
||
- `HOST_BOTS_WORKSPACE_ROOT`
|
||
- `POSTGRES_SUPERPASSWORD`
|
||
- `POSTGRES_APP_PASSWORD`
|
||
- `PANEL_ACCESS_PASSWORD`
|
||
- 如启用本地语音识别，请将 Whisper `.bin` 模型文件放到宿主机项目根目录的 `data/model/`
|
||
2. 启动完整栈
|
||
- `./scripts/deploy-full.sh`
|
||
3. 访问
|
||
- `http://<host>:${NGINX_PORT}`（默认 `8080`）
|
||
|
||
### 初始化说明
|
||
|
||
- `scripts/deploy-full.sh` 会先启动 `postgres` / `redis`，然后自动调用 `scripts/init-full-db.sh`。
|
||
- `scripts/init-full-db.sh` 负责：
|
||
- 等待 PostgreSQL 就绪
|
||
- 创建或更新业务账号
|
||
- 创建业务库并授权
|
||
- 修正 `public` schema 权限
|
||
- Dashboard 业务表本身仍由后端启动时自动执行 `SQLModel.metadata.create_all(...)` 与补列/索引对齐。
|
||
|
||
### 停止
|
||
|
||
- `./scripts/stop-full.sh`
|
||
|
||
### 注意事项
|
||
|
||
- `deploy-prod.sh` 和 `deploy-full.sh` 使用的是两套 compose 文件，但复用了相同容器名，不能同时在同一台机器上并行启动。
|
||
- PostgreSQL 数据默认落盘到宿主机项目根目录 `./data/postgres`，Redis 数据默认落盘到 `./data/redis`。
|
||
- 如果你只想保留前后端容器，继续使用 `deploy-prod.sh`；如果希望把依赖也打包进来，使用 `deploy-full.sh`。
|