dashboard-nanobot/design/database.md

# Dashboard Nanobot 数据库设计文档

数据库默认使用 PostgreSQL（推荐使用 psycopg3 驱动）。

## 1. ERD

```mermaid
erDiagram
    bot_instance ||--o{ bot_message : "messages"
    bot_instance ||--o{ bot_request_usage : "usage"
    bot_instance ||--o{ bot_activity_event : "events"
    bot_image ||--o{ bot_instance : "referenced by"

    bot_instance {
        string id PK
        string name
        boolean enabled
        string access_password
        string workspace_dir UK
        string docker_status
        string current_state
        string last_action
        string image_tag
        datetime created_at
        datetime updated_at
    }

    bot_message {
        int id PK
        string bot_id FK
        string role
        text text
        text media_json
        string feedback
        datetime feedback_at
        datetime created_at
    }

    bot_image {
        string tag PK
        string image_id
        string version
        string status
        string source_dir
        datetime created_at
    }

    bot_request_usage {
        int id PK
        string bot_id FK
        string request_id
        string channel
        string status
        string provider
        string model
        int input_tokens
        int output_tokens
        int total_tokens
        datetime started_at
        datetime completed_at
        datetime created_at
    }

    bot_activity_event {
        int id PK
        string bot_id FK
        string request_id
        string event_type
        string channel
        string detail
        text metadata_json
        datetime created_at
    }

    sys_setting {
        string key PK
        string name
        string category
        string description
        string value_type
        text value_json
        boolean is_public
        int sort_order
        datetime created_at
        datetime updated_at
    }
```

## 2. 设计原则

- 数据库保留运行索引、历史消息、用量统计与运维事件。
- Bot 核心配置（渠道、资源配额、5 个 MD 文件）统一持久化在文件系统：
  - `.nanobot/config.json`
  - `.nanobot/workspace/*.md`
  - `.nanobot/env.json`

## 3. 表说明

### 3.1 `bot_instance`
存储 Bot 基础索引与运行态。

### 3.2 `bot_message`
Dashboard 渠道对话历史（用于会话回放与反馈）。

### 3.3 `bot_image`
基础镜像登记表。

### 3.4 `bot_request_usage`
模型调用用量详细记录。

### 3.5 `bot_activity_event`
运维事件记录（如容器启动/停止、指令提交、系统告警等）。

### 3.6 `sys_setting`
平台全局参数设置。

## 4. 初始化与迁移策略

服务启动时（`backend/core/database.py`）：

1. 使用 PostgreSQL Advisory Lock 确保多节点部署时的单实例初始化。
2. `SQLModel.metadata.create_all(engine)` 自动创建缺失表。
3. 执行列对齐检查，确保旧表结构平滑升级。
4. 自动对齐 PostgreSQL Sequences 以防 ID 冲突。