DataStoria
面向 ClickHouse 集群诊断、查询生成与优化的 AI 原生控制台。
- Star 数
- ★ 328
- 最近更新
- 4 个月前
- License
- NOASSERTION
- 主语言
- TypeScript
- FA 评分
- 45/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台
- 费用
- 有免费版,另有付费云服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 数据工程师排查慢查询:在 System Log 检查器中查看执行时间线与拓扑,再用 AI 优化建议评估改写方案。
- 不适合
- 不使用 ClickHouse、也没有集群诊断需求的团队
- 要求界面完全离线、不希望接入任何 LLM 提供商的团队
- 需要通用数据库管理工具而非 ClickHouse 专用控制台的场景
- 官网
- datastoria.app ↗ 来自 GitHub 仓库设置
- 维护状态
- 近半年有提交最近提交 2026-07-21
这个 Agent 能做什么,适合哪些场景?
DataStoria 是一个基于 Next.js 16 与 React 19 构建的 AI 原生 ClickHouse 控制台,把 SQL 编辑器、集群监控面板与图表可视化整合到同一个 Web 界面中。用户可以直接用自然语言描述数据需求,由模型生成经过校验的 ClickHouse SQL,并根据 schema 与查询证据给出具体的性能优化建议。控制台同时提供执行计划可视化、依赖图、System Log 检查器以及多节点、多集群监控面板。所有 SQL 查询都在浏览器端直接发往 ClickHouse 服务器,AI 生成图表时模型只输出 SQL 与图表配置,数据抓取与渲染在本地完成。部署方式包括官网在线体验、从源码本地构建,以及使用官方 Docker 镜像自托管。
核心流程是:用户在 SQL 编辑器中直接向已连接的 ClickHouse 实例发送查询,或输入自然语言需求,由接入的模型(通过 Vercel AI SDK,支持 OpenAI、Anthropic Claude、Gemini、GitHub Copilot、OpenRouter、Groq、Cerebras、Nebius 等)生成 ClickHouse SQL。查询优化模式会读取 schema、校验 SQL、收集执行证据,再输出具体优化建议。可视化模式下模型只产出 SQL 与图表规格(时序、柱状、饼图、表格),浏览器端拉取数据并渲染。控制台还提供一键 Explain 的 AST 与执行流水线视图、表与物化视图的依赖图、System Log 时间线与拓扑视图,以及多节点、多集群的实时指标、merge 与复制状态面板。SKILL 式 Agent 架构与官方 ClickHouse Agent Skills 可复用以在多轮对话中节省 token。
- 数据工程师排查慢查询:在 System Log 检查器中查看执行时间线与拓扑,再用 AI 优化建议评估改写方案。
- 分析师不懂 SQL:用自然语言描述想要的指标和时间范围,直接得到可运行的 ClickHouse 查询与图表。
- SRE 巡检集群:通过多节点仪表盘查看实时指标、merge 进度与复制状态,跨多个集群统一观察。
- 数仓维护者梳理血缘:用依赖图追踪物化视图、分布式表与外部系统之间的数据流向。
- 需要保护凭据的团队:把查询放在浏览器直连 ClickHouse、只自带 LLM API Key,避免数据经中间服务器转发。
- 已经订阅 GitHub Copilot 的开发者:用 GitHub device flow 登录,直接复用现有 Copilot 订阅做查询辅助。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
npm install --forcedocker run -d -p 3000:3000 frankchen021/datastoria:latest
- 端口
3000- 安装说明涉及
- Linux · Docker
如何安装或部署这个 Agent?
方式一,从源码构建(需要 Node.js v22 及以上与 pnpm):
git clone --recurse-submodules https://github.com/FrankChen021/datastoria.git
cd datastoria
npm install --force
npm run dev启动后打开 http://localhost:3000 并连接 ClickHouse 实例。
方式二,使用官方 Docker 镜像自托管(镜像同时支持 linux/amd64 与 linux/arm64):
docker run -d -p 3000:3000 frankchen021/datastoria:latestAI 功能需要配置 LLM 提供商的 API Key,配置方式见 doc/dev/llm-provider-api-key.md;Google、GitHub、Microsoft 的 OAuth 登录配置见 doc/dev/authentication.md。
如何使用这个 Agent?
打开控制台(本地 http://localhost:3000 或 dataStoria.app 在线体验)后,先添加 ClickHouse 连接信息,之后 SQL 会在浏览器端直接发往该实例。AI 功能需在设置中填入自有 API Key,或通过 GitHub device flow 登录以使用 Copilot 订阅。
典型用法:
1. 在 SQL 编辑器中编写并格式化查询,语法错误会被定位到具体行列
2. 输入自然语言需求,例如“过去 7 天每小时请求数趋势”,获取生成的 SQL 与图表
3. 对查询点击 Explain,查看 AST 与执行流水线视图
4. 在优化模式中请求建议,模型读取 schema 与查询证据后给出改进项
5. 打开集群仪表盘与依赖图,检查节点指标、merge、复制状态与表血缘关系这个 Agent 有哪些优点和局限?
- 查询在浏览器端直连 ClickHouse,凭据与结果不经过第三方服务器,隐私边界清晰。
- AI 优化不止于改写 SQL,而是读取 schema、校验语句并收集执行证据后再给建议。
- 模型提供商选择面广,涵盖 OpenAI、Anthropic、Gemini、Copilot、OpenRouter、Groq、Cerebras、Nebius。
- 把 SQL 编辑、执行计划、System Log、依赖图与集群监控放在同一界面,减少工具切换。
- 提供 Docker 镜像并同时支持 amd64 与 arm64,自托管门槛较低。
- 只服务 ClickHouse,无法管理其他数据库,已有多库环境的团队需要额外工具。
- AI 功能依赖外部 LLM 服务与自有 API Key,涉及按键计费与网络可达性。
- 源码构建要求 Node.js v22+ 且需使用 npm install --force,存在依赖冲突的处理成本。
- 仓库 License 字段显示为 NOASSERTION,与 README 声明的 Apache License 2.0 不一致,合规审查需先确认。
- 未提供关于权限分级、多用户隔离等企业治理能力的明确说明。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| DataStoria 当前 | 45 · 缺口较多 | 网页应用免费版 + 付费版 | ★ 328 | 4 个月前 | TypeScript | — |
| WhoDB | 54 · 缺口较多 | 自托管服务免费版 + 付费版 | ★ 5.1k | 1 天前 | Go | — |
| Lumen 数据探索框架 | 46 · 缺口较多 | 命令行工具 | ★ 355 | 1 天前 | Python | — |
| ChatLab 聊天记录分析工具 | 70 · 存在缺口 | 桌面应用免费 + 模型费 | ★ 7.7k | 2 天前 | TypeScript | — |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
least_privilege:AGENTS.md 要求服务端逻辑不泄漏密钥、在 API 边界校验输入,但未给出具体权限模型或最小权限实现,仅属原则性表述,扣分。user_confirmation:AGENTS.md 明确要求 push/PR 前展示变更文件并等待用户显式批准,属可核实的确认机制,但仅覆盖开发流程而非产品运行时,故给 2。data_flow_transparency:README 声明 SQL 在浏览器直连 ClickHouse、凭据与结果不离开本机、自带 API Key,方向清晰,但缺少对 LLM 请求具体发送内容的说明,扣分。sensitive_data_handling:authentication.md 给出 NEXTAUTH_SECRET、OAuth 密钥与不提交 .env 的建议,但默认 ALLOW_ANONYMOUS_USER=true 且无数据脱敏说明,扣分。dependency_security:CI 生成 SLSA provenance 与 SBOM、有 overrides 固定部分依赖,但存在 next-auth beta、file: 本地依赖、npm install --force,且无漏洞扫描步骤,扣分。external_effects:产品会向 ClickHouse 执行查询、向 LLM 提供商发送请求,属外部副作用,但未见对写操作或破坏性 SQL 的拦截说明,扣分。rollback:未见任何回滚或撤销机制说明,给 0。source_attribution:SKILL.md 有 author 元数据、LICENSE 有版权人,但发布者身份未经验证,扣分。
self_consistency:README、AGENTS.md、package.json 脚本与 CI 步骤基本一致(dev/build/test/lint/typecheck 均存在),但 README 要求 Node v22 而 authentication.md 写 Node 18+,存在不一致,扣分。dependency_availability:依赖大量 file: 本地子模块与 external/ 构建脚本,需 --recurse-submodules 与 --force 安装,可用性依赖外部子模块,扣分。failure_messages:SKILL.md 与 authentication.md 有部分错误处理指引(如 skill_resource 返回空则尽力回答、常见问题排查),但产品级错误提示证据有限,扣分。
audience_and_scenarios:README 明确面向 ClickHouse 运维与查询场景,SKILL.md 覆盖系统表查询、集群诊断、错误诊断、SQL 优化,场景清晰,给 2。capability_boundaries:多个 SKILL.md 明确 When Not To Use、工具边界与回退到其他 skill,边界处理较好,给 2。trigger_precision:SKILL.md 的 description 与触发词较具体(system tables、query_log、error code 等),但部分触发依赖模型判断,扣分。environment_fit:支持 Docker 多架构与本地构建,但依赖 Node 22、pnpm、子模块与 --force 安装,环境适配成本较高,扣分。
information_architecture:README 分节清晰,docs 目录与 AGENTS.md 结构说明完整,给 2。install_notes:README 与 authentication.md 提供构建、Docker、OAuth 配置步骤,较完整,给 2。naming_stability:package.json version 为 0.0.0,未见版本策略,命名稳定性证据不足,扣分。examples_and_faq:有 SQL 示例与 troubleshooting 小节,但整体示例与 FAQ 偏少,扣分。known_limitations:SKILL.md 提到 Phase 1 仅支持部分 RCA 症状,属局部限制说明,但产品级已知限制缺失,扣分。license:LICENSE 为完整 Apache 2.0,README 声明一致,给 2。versioning_changelog:未见 CHANGELOG 或版本发布说明,给 0。maintenance_responsibility:有 CI 与发布流程,但发布者身份未验证、无维护者说明,扣分。
output_usability:SKILL.md 规定了强制输出格式(表格、RCA 结构、SQL 示例),输出可直接使用,给 2。marginal_value:面向 ClickHouse 的 AI 控制台结合诊断、优化与可视化,相对通用工具有一定增量价值,给 2。cost_benefit:需自建 Next.js 应用、配置多个 LLM Key 与 OAuth,部署与维护成本较高,扣分。
claim_traceability:README 的功能声明多无对应代码或测试引用,仅 SKILL.md 与工具名可部分追溯,扣分。cross_source_corroboration:README、AGENTS.md、package.json 与 CI 在脚本与技术上互相印证,但功能声明缺少跨源佐证,扣分。fact_inference_separation:文档中事实与宣传性表述混杂(如 100% 本地执行),未见明确区分,扣分。
- 源码中未见:回滚或恢复路径运行前先备份,或在 git 分支、快照上操作,确保改动可以撤销。
- 默认 ALLOW_ANONYMOUS_USER=true,未配置 OAuth 时应用可匿名访问,生产部署前应显式关闭。
- README 声称 100% 本地执行,但 AI 功能会将查询与 schema 上下文发送给第三方 LLM 提供商,需自行评估数据外发范围。
- 依赖包含 next-auth beta、file: 本地子模块与 npm install --force,供应链与可复现性风险需自行核查。
- 未见对写操作或破坏性 SQL 的拦截与回滚机制说明,连接生产集群时需谨慎。
- 发布者身份未经验证,Docker 镜像与在线站点 dataStoria.app 的使用需自行评估信任。
常见问题
DataStoria 用哪个端口?
DataStoria 官网是什么?
DataStoria 免费吗?
DataStoria 开源吗?
DataStoria 安全吗?
DataStoria 还在维护吗?
DataStoria 是谁开发的?
谢谢反馈,我们会据此改进页面。