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 切换。

架构概览

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

目录

/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 注册到 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 工作目录
    • PANEL_ACCESS_PASSWORD、CORS_ALLOWED_ORIGINS：仍属于部署层安全参数
    • DEFAULT_BOT_SYSTEM_TIMEZONE：新建 Bot 默认注入的 TZ
• 前端：
  • 示例文件：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
   • deploy-prod.sh 现在要求使用外部 PostgreSQL，且目标库必须提前执行 scripts/sql/create-tables.sql 与 scripts/sql/init-data.sql
   • 只需要配置绝对路径：
     • 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 访问。
• deploy-prod.sh 仅负责前后端容器部署，不会初始化外部数据库；外部 PostgreSQL 需要事先建表并导入初始化数据。
• 如果启用 Redis，REDIS_URL 必须从 backend 容器内部可达；在 docker-compose.prod.yml 里使用 127.0.0.1 只会指向后端容器自己，不是宿主机。
• Redis 不可达时，通用缓存健康检查会显示 degraded；面板登录认证会自动回退到数据库登录态，不再因为缓存不可达直接报错。
• UPLOAD_MAX_MB 仅用于 Nginx 入口限制；后端业务校验值来自 sys_setting.upload_max_mb。
• 必须挂载 /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/create-tables.sql
• scripts/sql/init-data.sql
• 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 权限
  • 执行 scripts/sql/create-tables.sql 创建业务表
  • 执行 scripts/sql/init-data.sql 初始化 sys_setting 与默认 skill 市场数据
• 后端启动时只做初始化完整性校验，不再自动补表、补列、补数据或迁移旧结构；缺库表、缺 sys_setting、缺模板文件都会直接报错。

停止

• ./scripts/stop-full.sh

注意事项

• deploy-prod.sh 和 deploy-full.sh 使用的是两套 compose 文件，但复用了相同容器名，不能同时在同一台机器上并行启动。
• PostgreSQL 数据默认落盘到宿主机项目根目录 ./data/postgres，Redis 数据默认落盘到 ./data/redis。
• 如果你只想保留前后端容器，继续使用 deploy-prod.sh；如果希望把依赖也打包进来，使用 deploy-full.sh。