DataStoria：AI 原生 ClickHouse 管理控制台

想象一下：你是一家电商公司的 DBA，凌晨两点收到告警——某个查询突然变慢，用户页面加载超时。你登录 ClickHouse 控制台，面对几十张表和密密麻麻的 SQL 日志，眼睛都花了。而 DataStoria 想做的事，就是让这段排查过程变得像"和 AI 聊天"一样自然。

背景：从运维痛点出发的 AI 工具

ClickHouse 是 OLAP 领域的明星数据库，以高速聚合查询著称，广泛应用于日志分析、用户行为分析、实时报表等场景。然而 ClickHouse 的管理和诊断，长期依赖原始的 clickhouse-client 命令行或第三方 GUI 工具，这些工具在 AI 时代显得格外原始。

FrankChen021 在 2025 年 11 月启动了 DataStoria 项目，将自然语言处理能力直接引入 ClickHouse 管理场景。用户在界面中用自然语言描述问题（如"最近 7 天订单量趋势如何"或"找出哪些查询耗时超过 5 秒"），DataStoria 自动生成 ClickHouse SQL 并执行，同时提供可视化结果。

核心功能：四个维度的 AI 增强

自然语言查询

用户无需记忆 ClickHouse 语法，用英文描述数据需求即可获得优化后的 SQL 语句。系统内置查询验证和语法错误诊断，错误位置精确到行列，并提供 AI 驱动的修复建议。

智能查询优化

这是 DataStoria 最有价值的功能之一。当用户输入一条 SQL 时，AI 会：

1. 检查表结构：理解 schema 和数据类型
2. 收集证据：分析历史查询计划，找出性能瓶颈
3. 给出具体建议：基于 ClickHouse 执行计划，推荐索引、重写或配置调整

智能可视化

自然语言描述想要的图表类型（折线图、柱状图、饼图、表格），AI 同时生成 SQL 和可视化配置，数据直接渲染。

Agent SKILLs 架构

DataStoria 采用了基于 SKILL 的 Agent 架构，支持加载官方 ClickHouse Agent Skills（GitHub 上由 ClickHouse 官方维护）。这套架构允许 AI 在多轮对话中复用上下文，节省 Token 消耗，并且支持多模型提供商（OpenAI、Anthropic Claude、Google Gemini、GitHub Copilot、OpenRouter、Groq、Cerebras、Nebius 等）。

架构解析：Next.js 全栈 + AI SDK

DataStoria 采用典型的前后端分离架构：

前端：基于 Next.js 14 App Router，使用 TypeScript + Tailwind CSS 构建 UI。核心组件包括：

• 高级 SQL 编辑器：支持语法高亮、自动补全和格式化
• 系统日志检查器：时间轴视图、拓扑图、执行分析
• 依赖图：可视化表关系，追踪 Materialized Views 和分布式表的数据流
• 多集群仪表板：实时节点指标、合并操作、副本状态
• Schema 浏览器：树形导航数据库、表和列

外部依赖（git submodules）：项目通过 git submodules 引入多个自研库：

• number-flow：数字动画渲染
• vizlayer：图表可视化核心库（分 core 和 react 两部分）
• cmdk：命令菜单组件

后端：Next.js API Routes 作为 BFF 层，数据直连 ClickHouse。关键 API 包括 /api/chat（AI 对话路由，连接多模型）和 /api/connection/templates（连接模板管理）。可选接入 ClickHouse 源码仓库，实现代码级诊断。

AI 集成：使用 Vercel AI SDK（@ai-sdk/react）统一封装多模型调用，代码结构清晰，便于切换模型提供商。

隐私与安全：浏览器直连，数据不落第三方

DataStoria 特别强调隐私保护：所有 SQL 查询从浏览器直接发往用户的 ClickHouse 服务器，API Key 由用户自持，不经过 DataStoria 服务端。这意味着即使使用 AI 生成查询，数据也完全在自有网络中流转，不会进入第三方系统。

部署体验

DataStoria 提供两种部署路径：

Vercel 部署（推荐）：克隆仓库后配置环境变量（主要是 LLM API Key 和 ClickHouse 连接信息），Vercel 自动检测 Next.js 并完成构建。官方提供 vercel.json，构建命令为 npm run release。

Docker 部署：官方 Dockerfile 采用三阶段多阶段构建：

1. deps 阶段：安装 Node.js 依赖（含 pnpm）
2. builder 阶段：执行 npm run build，生成 standalone 输出
3. runner 阶段：使用 node:22-alpine 运行 server.js

Dockerfile 支持 BUILD_FROM_SOURCE=0 模式，使用预编译产物构建，镜像体积更小、构建更快，适合 CI 场景。健康检查配置完善（HEALTHCHECK），生产可用。

部署门槛低，无需 GPU，2GB RAM 足够，适合在服务器或本地机器上长期运行。

局限与挑战

1. LLM API Key 依赖：没有内置免费 AI 模型，需要用户自备 API Key，对非 AI 开发者有一定门槛
2. ClickHouse 专用：功能高度绑定 ClickHouse，其他数据库用户无法使用
3. 中文社区活跃度待观察：目前 Star 以英文用户为主，中文文档和社区支持有限
4. Submodule 管理成本：3 个 git submodules 增加了更新维护复杂度

行业意义

DataStoria 代表了一个新兴趋势——将 AI 能力深度嵌入专业工具，而非做一个通用 AI 助手。它精准切入了 DBA 和数据工程师的日常工作：用自然语言替代 SQL 记忆，用 AI 分析替代人工排查执行计划。

其 Agent SKILLs 架构也值得关注——它为特定领域的 Agent 能力复用提供了一种可复制的范式，未来可以扩展到 PostgreSQL、MySQL、BigQuery 等其他数据库。

图1：DataStoria 可视化演示——自然语言生成图表

图2：DataStoria 项目 Logo