srdb/examples/webui/README.md

SRDB Web UI Example

这个示例展示了如何使用 SRDB 的内置 Web UI 来可视化查看数据库中的表和数据。

功能特性

• 📊 表列表展示 - 左侧显示所有表及其行数
• 🔍 Schema 查看 - 点击箭头展开查看表的字段定义
• 📋 数据分页浏览 - 右侧以表格形式展示数据，支持分页
• 🎨 响应式设计 - 现代化的界面设计
• ⚡ 零构建 - 使用 HTMX 从 CDN 加载，无需构建步骤
• 💾 大数据优化 - 自动截断显示，悬停查看，点击弹窗查看完整内容
• 📏 数据大小显示 - 超过 1KB 的单元格自动显示大小标签
• 🔄 后台数据插入 - 自动生成 2KB~512KB 的测试数据（每秒一条）

运行示例

# 进入示例目录
cd examples/webui

# 运行
go run main.go

程序会：

1. 创建/打开数据库目录 ./data
2. 创建三个示例表：users、products 和 logs
3. 插入初始示例数据
4. 启动后台协程 - 每秒向 logs 表插入一条 2KB~512KB 的随机数据
5. 启动 Web 服务器在 http://localhost:8080

使用界面

打开浏览器访问 http://localhost:8080，你将看到：

左侧边栏

• 显示所有表的列表
• 显示每个表的字段数量
• 点击 ▶ 图标展开查看字段信息
• 点击表名选择要查看的表（蓝色高亮显示当前选中）

右侧主区域

• Schema 区域：显示表结构和字段定义
• Data 区域：以表格形式显示数据
  • 支持分页浏览（每页 20 条）
  • 显示系统字段（_seq, _time）和用户字段
  • 自动截断长数据：超过 400px 的内容显示省略号
  • 鼠标悬停：悬停在单元格上查看完整内容
  • 点击查看：点击单元格在弹窗中查看完整内容
  • 大小指示：超过 1KB 的数据显示大小标签

大数据查看

1. 表格截断：单元格最大宽度 400px，超长显示 ...
2. 悬停展开：鼠标悬停自动展开，黄色背景高亮
3. 模态框：点击单元格弹出窗口
   • 等宽字体显示（适合查看十六进制数据）
   • 显示数据大小
   • 支持滚动查看超长内容

API 端点

Web UI 提供了以下 HTTP API：

获取所有表

GET /api/tables

返回示例：

[
  {
    "name": "users",
    "rowCount": 5,
    "dir": "./data/users"
  }
]

获取表的 Schema

GET /api/tables/{name}/schema

返回示例：

{
  "fields": [
    {"name": "name", "type": "string", "required": true},
    {"name": "email", "type": "string", "required": true},
    {"name": "age", "type": "int", "required": false}
  ]
}

获取表数据（分页）

GET /api/tables/{name}/data?page=1&pageSize=20

参数：

• page - 页码，从 1 开始（默认：1）
• pageSize - 每页行数，最大 100（默认：20）

返回示例：

{
  "page": 1,
  "pageSize": 20,
  "totalRows": 5,
  "totalPages": 1,
  "rows": [
    {
      "_seq": 1,
      "_time": 1234567890,
      "name": "Alice",
      "email": "alice@example.com",
      "age": 30
    }
  ]
}

获取表基本信息

GET /api/tables/{name}

在你的应用中使用

你可以在自己的应用中轻松集成 Web UI：

package main

import (
    "net/http"
    "code.tczkiot.com/srdb"
)

func main() {
    // 打开数据库
    db, _ := database.Open("./mydb")
    defer db.Close()

    // 获取 HTTP Handler
    handler := db.WebUI()

    // 启动服务器
    http.ListenAndServe(":8080", handler)
}

或者将其作为现有 Web 应用的一部分：

mux := http.NewServeMux()

// 你的其他路由
mux.HandleFunc("/api/myapp", myHandler)

// 挂载 SRDB Web UI 到 /admin/db 路径
mux.Handle("/admin/db/", http.StripPrefix("/admin/db", db.WebUI()))

http.ListenAndServe(":8080", mux)

技术栈

• 后端: Go + 标准库 net/http
• 前端: HTMX + 原生 JavaScript + CSS
• 渲染: 服务端 HTML 渲染（Go 模板生成）
• 字体: Google Fonts (Inter)
• 无构建: 直接从 CDN 加载 HTMX，无需 npm、webpack 等工具
• 部署: 所有静态资源通过 embed.FS 嵌入到二进制文件中

测试大数据

logs 表自动生成

程序会在后台持续向 logs 表插入大数据：

• 频率：每秒一条
• 大小：2KB ~ 512KB 随机
• 格式：十六进制字符串
• 字段：
  • timestamp - 插入时间
  • data - 随机数据（十六进制）
  • size_bytes - 数据大小（字节）

你可以选择 logs 表来测试大数据的显示效果：

1. 单元格会显示数据大小标签（如 245.12 KB）
2. 内容被自动截断，显示省略号
3. 点击单元格在弹窗中查看完整数据

终端会实时输出插入日志：

Inserted record #1, size: 245.12 KB
Inserted record #2, size: 128.50 KB
Inserted record #3, size: 487.23 KB

注意事项

• Web UI 是只读的，不提供数据修改功能
• 适合用于开发、调试和数据查看
• 生产环境建议添加身份验证和访问控制
• 大数据量表的分页查询性能取决于数据分布
• logs 表会持续增长，可手动删除 ./data/logs 目录重置

Compaction 状态

由于后台持续插入大数据，会产生大量 SST 文件。SRDB 会自动运行 compaction 合并这些文件。

检查 Compaction 状态

# 查看 SST 文件分布
./check_sst.sh

# 观察 webui 日志中的 [Compaction] 信息

Compaction 改进

• 触发阈值: L0 文件数量 ≥2 就触发（之前是 4）
• 运行频率: 每 10 秒自动检查
• 日志增强: 显示详细的 compaction 状态和统计

详细说明请查看 COMPACTION.md

常见问题

invalid header 错误

如果看到类似错误：

failed to open table logs: invalid header

快速修复：

./fix_corrupted_table.sh logs

详见：QUICK_FIX.md 或 TROUBLESHOOTING.md

更多信息

• FEATURES.md - 详细功能说明
• COMPACTION.md - Compaction 机制和诊断
• TROUBLESHOOTING.md - 故障排除指南
• QUICK_FIX.md - 快速修复常见错误