bourdon
23843493b8
主要改动： - 重构目录结构：合并子目录到根目录，简化项目结构 - 添加完整的查询 API：支持复杂条件查询、字段选择、游标模式 - 实现 LSM-Tree Compaction：7层结构、Score-based策略、后台异步合并 - 添加 Web UI：基于 Lit 的现代化管理界面，支持数据浏览和 Manifest 查看 - 完善文档：添加 README.md 和 examples/webui/README.md 新增功能： - Query Builder：链式查询 API，支持 Eq/Lt/Gt/In/Between/Contains 等操作符 - Web UI 组件：srdb-app、srdb-table-list、srdb-data-view、srdb-manifest-view 等 - 列选择持久化：自动保存到 localStorage - 刷新按钮：一键刷新当前视图 - 主题切换：深色/浅色主题支持 代码优化： - 使用 Go 1.24 新特性：range 7、min()、maps.Copy()、slices.Sort() - 统一组件命名：所有 Web Components 使用 srdb-* 前缀 - CSS 优化：提取共享样式，减少重复代码 - 清理遗留代码：删除未使用的方法和样式
414 lines
12 KiB
Markdown
414 lines
12 KiB
Markdown
# SRDB WebUI - 数据库管理工具
|
||
|
||
一个功能强大的 SRDB 数据库管理工具，集成了现代化的 Web 界面和实用的命令行工具。
|
||
|
||
## 📋 目录
|
||
|
||
- [功能特性](#功能特性)
|
||
- [快速开始](#快速开始)
|
||
- [Web UI 使用指南](#web-ui-使用指南)
|
||
- [命令行工具](#命令行工具)
|
||
- [技术架构](#技术架构)
|
||
- [开发说明](#开发说明)
|
||
|
||
---
|
||
|
||
## 🎯 功能特性
|
||
|
||
### Web UI
|
||
|
||
#### 📊 数据管理
|
||
- **表列表** - 查看所有表及其 Schema 信息
|
||
- **数据浏览** - 分页浏览表数据，支持自定义列选择
|
||
- **列持久化** - 自动保存列选择偏好到 localStorage
|
||
- **数据详情** - 点击查看完整的行数据（JSON 格式）
|
||
- **智能截断** - 长字符串自动截断，点击查看完整内容
|
||
- **时间格式化** - 自动格式化 `_time` 字段为可读时间
|
||
|
||
#### 🌳 LSM-Tree 管理
|
||
- **Manifest 视图** - 可视化 LSM-Tree 层级结构
|
||
- **文件详情** - 查看每层的 SST 文件信息
|
||
- **Compaction 监控** - 实时查看 Compaction Score 和统计
|
||
- **层级折叠** - 可展开/收起查看文件详情
|
||
|
||
#### 🎨 用户体验
|
||
- **响应式设计** - 完美适配桌面和移动设备
|
||
- **深色/浅色主题** - 支持主题切换
|
||
- **实时刷新** - 一键刷新当前视图数据
|
||
- **移动端优化** - 侧边栏抽屉式导航
|
||
|
||
### 命令行工具
|
||
|
||
提供多个实用的数据库诊断和管理工具：
|
||
|
||
| 命令 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| `serve` | Web UI 服务器 | 启动 Web 管理界面 |
|
||
| `check-data` | 数据检查 | 检查表数据完整性 |
|
||
| `check-seq` | 序列号检查 | 验证特定序列号的数据 |
|
||
| `dump-manifest` | Manifest 导出 | 导出 LSM-Tree 结构信息 |
|
||
| `inspect-sst` | SST 文件检查 | 检查单个 SST 文件 |
|
||
| `inspect-all-sst` | 批量 SST 检查 | 检查所有 SST 文件 |
|
||
| `test-fix` | 修复测试 | 测试数据修复功能 |
|
||
| `test-keys` | 键测试 | 测试键的存在性 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 启动 Web UI
|
||
|
||
```bash
|
||
cd examples/webui
|
||
|
||
# 使用默认配置（数据库：./data，端口：8080）
|
||
go run main.go serve
|
||
|
||
# 自定义配置
|
||
go run main.go serve --db /path/to/database --port 3000
|
||
|
||
# 启用自动数据插入（用于演示）
|
||
go run main.go serve --auto-insert
|
||
```
|
||
|
||
### 2. 访问 Web UI
|
||
|
||
打开浏览器访问：http://localhost:8080
|
||
|
||
### 3. 命令行工具示例
|
||
|
||
```bash
|
||
# 检查表数据
|
||
go run main.go check-data --db ./data --table users
|
||
|
||
# 检查特定序列号
|
||
go run main.go check-seq --db ./data --table users --seq 123
|
||
|
||
# 导出 Manifest
|
||
go run main.go dump-manifest --db ./data --table users
|
||
|
||
# 检查 SST 文件
|
||
go run main.go inspect-sst --db ./data --table users --file 000001.sst
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Web UI 使用指南
|
||
|
||
### 界面布局
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ SRDB Tables [🌙/☀️] │ ← 侧边栏
|
||
│ ├─ users │
|
||
│ ├─ orders │
|
||
│ └─ logs │
|
||
├─────────────────────────────────────────────────┤
|
||
│ [☰] users [🔄 Refresh] │ ← 页头
|
||
│ [Data] [Manifest / LSM-Tree] │ ← 视图切换
|
||
├─────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Schema (点击字段卡片选择要显示的列) │ ← Schema 区域
|
||
│ ┌──────────┬──────────┬──────────┐ │
|
||
│ │⚡ id │● name │⚡ email │ │
|
||
│ │[int64] │[string] │[string] │ │
|
||
│ └──────────┴──────────┴──────────┘ │
|
||
│ │
|
||
│ Data (1,234 rows) │ ← 数据表格
|
||
│ ┌─────┬──────┬───────────┬─────────┐ │
|
||
│ │ _seq│ name │ email │ Actions │ │
|
||
│ ├─────┼──────┼───────────┼─────────┤ │
|
||
│ │ 1 │ John │ john@... │ Detail │ │
|
||
│ │ 2 │ Jane │ jane@... │ Detail │ │
|
||
│ └─────┴──────┴───────────┴─────────┘ │
|
||
│ │
|
||
├─────────────────────────────────────────────────┤
|
||
│ [10/page] [Previous] Page 1 of 5 [Go] [Next] │ ← 分页控件
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 功能说明
|
||
|
||
#### 1. 表列表（侧边栏）
|
||
- 显示所有表及其字段信息
|
||
- 点击表名切换到该表
|
||
- 展开/收起查看字段详情
|
||
- 字段图标：⚡ = 已索引，● = 未索引
|
||
|
||
#### 2. Data 视图
|
||
- **Schema 区域**：点击字段卡片选择要显示的列
|
||
- **数据表格**：显示选中的列数据
|
||
- **系统字段**：
|
||
- `_seq`：序列号（第一列）
|
||
- `_time`：时间戳（倒数第二列，自动格式化）
|
||
- **Detail 按钮**：查看完整的行数据（JSON 格式）
|
||
- **分页控件**：
|
||
- 每页大小：10/20/50/100
|
||
- 上一页/下一页
|
||
- 跳转到指定页
|
||
|
||
#### 3. Manifest 视图
|
||
- **统计卡片**：
|
||
- Active Levels：活跃层数
|
||
- Total Files：总文件数
|
||
- Total Size：总大小
|
||
- Compactions：Compaction 次数
|
||
- **层级卡片**：
|
||
- 点击展开/收起查看文件列表
|
||
- Score 指示器：
|
||
- 🟢 绿色：健康（< 50%）
|
||
- 🟡 黄色：警告（50-80%）
|
||
- 🔴 红色：需要 Compaction（≥ 80%）
|
||
- **文件详情**：
|
||
- 文件编号、大小、行数
|
||
- Seq 范围（min_key - max_key）
|
||
|
||
#### 4. 刷新按钮
|
||
- 点击刷新当前视图的数据
|
||
- Data 视图：重新加载表数据
|
||
- Manifest 视图：重新加载 LSM-Tree 结构
|
||
|
||
#### 5. 主题切换
|
||
- 点击右上角的 🌙/☀️ 图标
|
||
- 切换深色/浅色主题
|
||
- 自动保存到 localStorage
|
||
|
||
---
|
||
|
||
## 🛠️ 命令行工具
|
||
|
||
### serve - Web UI 服务器
|
||
|
||
启动 Web 管理界面。
|
||
|
||
```bash
|
||
go run main.go serve [flags]
|
||
```
|
||
|
||
**参数**：
|
||
- `--db` - 数据库目录（默认：`./data`）
|
||
- `--port` - 服务端口（默认：`8080`）
|
||
- `--auto-insert` - 启用自动数据插入（用于演示）
|
||
|
||
**示例**：
|
||
```bash
|
||
# 基本使用
|
||
go run main.go serve
|
||
|
||
# 自定义端口
|
||
go run main.go serve --port 3000
|
||
|
||
# 启用自动插入（每秒插入一条随机数据到 logs 表）
|
||
go run main.go serve --auto-insert
|
||
```
|
||
|
||
### check-data - 数据检查
|
||
|
||
检查表数据的完整性。
|
||
|
||
```bash
|
||
go run main.go check-data --db ./data --table <table_name>
|
||
```
|
||
|
||
### check-seq - 序列号检查
|
||
|
||
验证特定序列号的数据。
|
||
|
||
```bash
|
||
go run main.go check-seq --db ./data --table <table_name> --seq <sequence_number>
|
||
```
|
||
|
||
### dump-manifest - Manifest 导出
|
||
|
||
导出 LSM-Tree 层级结构信息。
|
||
|
||
```bash
|
||
go run main.go dump-manifest --db ./data --table <table_name>
|
||
```
|
||
|
||
### inspect-sst - SST 文件检查
|
||
|
||
检查单个 SST 文件的内容和元数据。
|
||
|
||
```bash
|
||
go run main.go inspect-sst --db ./data --table <table_name> --file <file_name>
|
||
```
|
||
|
||
### inspect-all-sst - 批量 SST 检查
|
||
|
||
检查表的所有 SST 文件。
|
||
|
||
```bash
|
||
go run main.go inspect-all-sst --db ./data --table <table_name>
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 前端技术栈
|
||
|
||
- **Lit** - 轻量级 Web Components 框架
|
||
- **ES Modules** - 原生 JavaScript 模块
|
||
- **CSS Variables** - 主题系统
|
||
- **Shadow DOM** - 组件封装
|
||
|
||
### 组件架构
|
||
|
||
```
|
||
srdb-app (主应用)
|
||
├── srdb-theme-toggle (主题切换)
|
||
├── srdb-table-list (表列表)
|
||
├── srdb-page-header (页头)
|
||
│ └── [🔄 Refresh] (刷新按钮)
|
||
├── srdb-table-view (表视图容器)
|
||
│ ├── srdb-data-view (数据视图)
|
||
│ │ ├── Schema 区域
|
||
│ │ │ ├── srdb-field-icon (字段图标)
|
||
│ │ │ └── srdb-badge (类型标签)
|
||
│ │ └── 数据表格
|
||
│ └── srdb-manifest-view (Manifest 视图)
|
||
│ └── srdb-badge (Score 标签)
|
||
└── srdb-modal-dialog (模态对话框)
|
||
```
|
||
|
||
### 后端架构
|
||
|
||
```
|
||
webui.go
|
||
├── API Endpoints
|
||
│ ├── GET /api/tables - 获取表列表
|
||
│ ├── GET /api/tables/{name}/schema - 获取表 Schema
|
||
│ ├── GET /api/tables/{name}/data - 获取表数据（分页）
|
||
│ ├── GET /api/tables/{name}/data/{seq} - 获取单条数据
|
||
│ └── GET /api/tables/{name}/manifest - 获取 Manifest 信息
|
||
├── Static Files
|
||
│ └── /static/* - 静态资源服务
|
||
└── Index
|
||
└── / - 首页
|
||
```
|
||
|
||
### 数据流
|
||
|
||
```
|
||
用户操作
|
||
↓
|
||
组件事件 (CustomEvent)
|
||
↓
|
||
app.js (事件总线)
|
||
↓
|
||
API 请求 (fetch)
|
||
↓
|
||
webui.go (HTTP Handler)
|
||
↓
|
||
SRDB Database
|
||
↓
|
||
JSON 响应
|
||
↓
|
||
组件更新 (Lit reactive)
|
||
↓
|
||
UI 渲染
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发说明
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
webui/
|
||
├── commands/
|
||
│ └── webui.go # Web UI 服务器实现
|
||
├── static/
|
||
│ ├── index.html # 主页面
|
||
│ ├── css/
|
||
│ │ └── styles.css # 全局样式
|
||
│ └── js/
|
||
│ ├── app.js # 应用入口和事件总线
|
||
│ ├── components/ # Web Components
|
||
│ │ ├── app.js # 主应用容器
|
||
│ │ ├── badge.js # 标签组件
|
||
│ │ ├── data-view.js # 数据视图
|
||
│ │ ├── field-icon.js # 字段图标
|
||
│ │ ├── manifest-view.js # Manifest 视图
|
||
│ │ ├── modal-dialog.js # 模态对话框
|
||
│ │ ├── page-header.js # 页头
|
||
│ │ ├── table-list.js # 表列表
|
||
│ │ ├── table-view.js # 表视图容器
|
||
│ │ └── theme-toggle.js # 主题切换
|
||
│ └── styles/
|
||
│ └── shared-styles.js # 共享样式
|
||
└── webui.go # Web UI 后端实现
|
||
```
|
||
|
||
### 添加新组件
|
||
|
||
1. 在 `static/js/components/` 创建组件文件
|
||
2. 继承 `LitElement`
|
||
3. 定义 `static properties` 和 `static styles`
|
||
4. 实现 `render()` 方法
|
||
5. 使用 `customElements.define('srdb-xxx', Component)` 注册
|
||
6. 在 `app.js` 中导入
|
||
|
||
### 添加新 API
|
||
|
||
1. 在 `webui.go` 中添加 handler 方法
|
||
2. 在 `setupHandler()` 中注册路由
|
||
3. 返回 JSON 格式的响应
|
||
4. 在前端组件中调用 API
|
||
|
||
### 样式规范
|
||
|
||
- 使用 CSS Variables 定义颜色和尺寸
|
||
- 组件样式封装在 Shadow DOM 中
|
||
- 共享样式定义在 `shared-styles.js`
|
||
- 响应式断点：768px
|
||
|
||
### 命名规范
|
||
|
||
- **组件名**：`srdb-xxx`（kebab-case）
|
||
- **类名**：`ComponentName`（PascalCase）
|
||
- **文件名**：`component-name.js`（kebab-case）
|
||
- **CSS 类**：`.class-name`（kebab-case）
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 性能优化
|
||
|
||
1. **列选择**：只加载选中的列，减少数据传输
|
||
2. **字符串截断**：长字符串自动截断，按需加载完整内容
|
||
3. **分页加载**：大表数据分页加载，避免一次性加载全部
|
||
4. **Shadow DOM**：组件样式隔离，避免全局样式污染
|
||
|
||
### 浏览器兼容性
|
||
|
||
- Chrome 90+
|
||
- Firefox 88+
|
||
- Safari 14+
|
||
- Edge 90+
|
||
|
||
需要支持：
|
||
- ES Modules
|
||
- Web Components
|
||
- Shadow DOM
|
||
- CSS Variables
|
||
|
||
### 已知限制
|
||
|
||
1. **大数据量**：单页最多显示 1000 条数据
|
||
2. **字符串长度**：超过 100 字符自动截断
|
||
3. **并发限制**：同时只能查看一个表的数据
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|