dashboard-nanobot/README.md

# 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`
- 2D 运维 Dashboard：Bot 列表、启停、命令发送、日志流、遥测。
- UI 全局支持：Light/Dark 切换、中文/English 切换。

## 架构概览

```mermaid
graph TD
    User((User)) --> Frontend[Frontend Control Plane]
    Frontend --> API[FastAPI Backend]
    API --> DB[(SQLite)]
    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`

## 环境变量配置

- 后端：
  - 示例文件：`backend/.env.example`
  - 本地配置：`backend/.env`
  - 关键项：
    - `DATABASE_URL`：数据库连接串（三选一：SQLite / PostgreSQL / MySQL）
    - `DATABASE_ECHO`：SQL 日志输出开关
    - 不提供自动数据迁移（如需升级迁移请离线完成后再切换连接串）
    - `DATA_ROOT`、`BOTS_WORKSPACE_ROOT`：运行数据与 Bot 工作目录
    - `DEFAULT_*_MD`：创建向导默认模板来源（其中默认输出规范已并入 `DEFAULT_AGENTS_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`（位于项目根目录）
   - 配置绝对路径：
     - `HOST_DATA_ROOT`
     - `HOST_BOTS_WORKSPACE_ROOT`
   - 中国网络建议配置加速项：
     - `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 访问。
- 必须挂载 `/var/run/docker.sock`，否则后端无法操作 Bot 镜像与容器。
- `HOST_BOTS_WORKSPACE_ROOT` 必须是宿主机绝对路径，并且在 `docker-compose.prod.yml` 中以“同路径”挂载到后端容器。
  原因：后端通过 Docker API 创建 Bot 容器时，使用的是宿主机可见的 bind 路径。