ghcr.io/duyet/clickhouse-monitoring:sha-72c6273873c123cb205c1bc55105f07599e808e5-arm64

chmonitor Dashboard

一个现代化的仪表板（截至 v0.3 版本基于 TanStack Start 构建），通过系统表提供 ClickHouse 集群的实时洞察。每个页面在构建时预渲染，结合客户端数据获取，以实现最佳性能和 CDN 缓存。

[!NOTE] 从 v0.2 版本升级？v0.3 版本基于 TanStack Start 重构了应用。ClickHouse 连接变量保持不变；浏览器变量前缀从 NEXT_PUBLIC_* 改为 VITE_*（旧名称仍可作为回退使用）。请参见下方的升级至 v0.3 版本部分或完整的迁移至 v0.3 版本指南。

从 v0.2 版本升级？v0.3 版本基于 TanStack Start 重构了应用。ClickHouse 连接变量保持不变；浏览器变量前缀从 NEXT_PUBLIC_* 改为 VITE_*（旧名称仍可作为回退使用）。请参见下方的升级至 v0.3 版本部分或完整的迁移至 v0.3 版本指南。

NEXT_PUBLIC_* VITE_*

在线演示：dash.chmonitor.dev | chmonitor.dev | 截图

功能特性：

• 查询监控：运行中的查询、查询历史、资源（内存、读取的部分、file_open）、昂贵查询、慢查询、失败查询、查询分析器
• 集群概览：内存/CPU 使用率、分布式队列、全局设置、MergeTree 设置、指标、异步指标
• 数据浏览器：交互式数据库树状浏览器，支持快速标签切换和列级详情、投影、字典
• 表分析：大小、行数、压缩率、列级粒度的部分大小、分离的部分、只读表、视图刷新
• 可视化：30+ 个指标图表，涵盖查询、资源、合并、性能和系统健康状况
• 合并与复制：合并操作、合并性能、复制队列、副本
• 安全与访问：用户、角色、安全设置
• 开发工具：Zookeeper 浏览器、查询 EXPLAIN、查询终止、分布式 DDL 队列、突变
• 多主机支持：从单个仪表板监控多个 ClickHouse 实例
• AI 代理：内置 AI 聊天功能，可对 ClickHouse 集群进行自然语言查询
• MCP 服务器：用于 AI 工具集成（Claude、Cursor 等）的模型上下文协议（Model Context Protocol）端点
• Rust CLI：独立的终端和 TUI 监控工具

文档

• /docs - 完整文档站点（local/docs）
• llms.txt - 用于自动化代码理解的AI代理发现文件
• [***]
• https://duyet.github.io/clickhouse-monitoring
  • 快速开始
  • 本地开发
  • 用户角色与配置文件
  • 启用系统表
• 部署
  • Vercel
  • Docker
  • Kubernetes Helm Chart
  • 一键部署 — Railway / Render / Fly.io 社区模板
• 高级遥测 — 可选启用、隐私优先的使用指标（默认关闭）
• 版本 — 开源核心模型：GPL-3.0 社区版永久免费；企业功能由CHM_EDITION控制
• 参考
  • 平台支持矩阵 — ClickHouse 版本和发行版（支持 / 尽力支持 / 未测试）
  • 连接预设 — ClickHouse OSS、Altinity 和 Cloud 的最小权限只读用户设置
  • 贡献配置/检查 — 如何向目录添加声明式监控检查
  • MCP 客户端 — 连接 Claude Desktop、Cursor 或任何 MCP 客户端
  • Grafana 桥接 — 从 Grafana 读取 chmonitor 的 ClickHouse 数据（社区方案）

Cloudflare Workers

本项目支持部署到Cloudflare Workers，包含静态站点生成和API路由。

前提条件：

• Node.js 18+ 和 Bun
• Cloudflare Workers 账户
• Wrangler CLI：npm install -g wrangler

设置步骤：

1. 克隆仓库并安装依赖：

git clone https://github.com/duyet/clickhouse-monitoring.git
cd clickhouse-monitoring
bun install

2. 在 .env.local 中配置环境变量：

CLICKHOUSE_HOST=https://your-clickhouse-host.com
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=yourpassword
CLICKHOUSE_TZ=UTC

可选：为 /api/v1/* 路由配置API密钥保护：

CHM_API_KEY_SECRET=your-signing-secret

可选：Clerk UI/会话支持：

CHM_AUTH_PROVIDER=clerk
NEXT_PUBLIC_AUTH_PROVIDER=clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_your_key
CLERK_SECRET_KEY=sk_live_your_key

功能权限默认启用且公开。当部署需要隐藏或保护某个功能时，可添加稀疏覆盖配置：

# /etc/clickhouse-monitor/config.toml
[features.agent]
access = "authenticated"

[features.metrics]
enabled = false

access = "guest" 可作为 access = "public" 的别名。

CHM_CONFIG_FILE=/etc/clickhouse-monitor/config.toml
# 或仅使用环境变量：
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_DISABLED_FEATURES=settings,metrics

对于无需身份验证的自托管部署，保留身份验证提供程序环境变量未设置或将其设为 none。

3. 部署到Cloudflare Workers：

# 在 .env.prod 中设置 CLOUDFLARE_API_TOKEN 或导出该变量
# 或使用OAuth：npx wrangler login

# 统一部署（配置、构建、部署、缓存 — 与CI流程相同）
bun run cf:deploy

手动部署步骤：

# 分步操作（与CI流程相同）
bun run cf:config # 从 .env.prod 设置密钥
cd apps/dashboard
bun run build # Vite构建 → 原生Workers bundle（+ tsc --noEmit）
wrangler deploy --minify

重要说明：

• 使用 Vite + @cloudflare/vite-plugin 构建为 原生Workers bundle — 无需OpenNext，无需KV/R2/D1缓存填充步骤
• TanStack Start + React 19（v0.2版本的Next.js应用在v0.3中已停用）
• 静态外壳在构建时预渲染；数据在客户端获取以进行边缘CDN缓存
• API路由使用Fetch API在Workers上运行
• 支持通过查询参数路由进行多主机监控（?host=0）

Docker

docker run -d \
-p 3000:3000 \
-e CLICKHOUSE_HOST=https://your-clickhouse-host.com \
-e CLICKHOUSE_USER=default \
-e CLICKHOUSE_PASSWORD=yourpassword \
ghcr.io/duyet/chmonitor:latest

将您当前的配置（.env、docker-compose.yml、Helm values.yaml 或 k8s 清单）粘贴到任何 AI 助手中，并使用以下提示。它会应用 v0.3 重命名规则，返回迁移后的配置以及更改摘要。此提示随每个破坏性变更 GitHub Release 一同发布，并与 .github/release-migration-prompt.md 保持同步。

您正在将 chmonitor 部署从 v0.2（Next.js）迁移到 v0.3（TanStack Start）。
这是我当前的环境配置（.env / docker-compose / wrangler / k8s 清单）：

请按照以下规则为 v0.3 重写配置，并输出迁移后的配置及简短的更改列表：

1. 将所有客户端变量前缀 NEXT_PUBLIC_ 重命名为 VITE_。具体包括：
NEXT_PUBLIC_AUTH_PROVIDER -> VITE_AUTH_PROVIDER
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY -> VITE_CLERK_PUBLISHABLE_KEY
NEXT_PUBLIC_FEATURE_CONVERSATION_DB-> VITE_FEATURE_CONVERSATION_DB
（其他任何 NEXT_PUBLIC_X 均改为 VITE_X）。旧名称仍可作为回退使用。
2. 添加服务端认证变量 CHM_AUTH_PROVIDER（none|clerk|proxy），与客户端提供程序对应。它在服务端具有权威性；同时保留 VITE_AUTH_PROVIDER。
3. 不要重命名服务端变量：CLICKHOUSE_HOST、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD、
CLICKHOUSE_NAME、CLICKHOUSE_MAX_EXECUTION_TIME、CLERK_SECRET_KEY、*_API_KEY — 保持原样。
4. VITE_* 变量在构建时内联：确保它们在镜像/Worker 构建时（Docker build-args 或 CI 构建环境）存在，而不仅仅是在容器运行时。
5. 如果是 Docker 部署，将容器启动命令从 `node server.js` 改为 `node server/index.mjs`。端口 3000 和 /api/healthz 健康检查保持不变。
6. 对于没有 v0.3 等效项的内容，需标记出来，而不是静默删除。

文档

• /docs - 完整文档站点（local/docs）
• llms.txt - 用于自动化代码理解的 AI 代理发现文件
• [***] (AI 生成)
• https://duyet.github.io/clickhouse-monitoring
• https://duyet.github.io/clickhouse-monitoring/getting-started
• https://duyet.github.io/clickhouse-monitoring/getting-started/local
• https://duyet.github.io/clickhouse-monitoring/getting-started/clickhouse-requirements
• https://duyet.github.io/clickhouse-monitoring/getting-started/clickhouse-enable-system-tables
• https://duyet.github.io/clickhouse-monitoring/deploy
• https://duyet.github.io/clickhouse-monitoring/deploy/vercel
• https://duyet.github.io/clickhouse-monitoring/deploy/docker
• https://duyet.github.io/clickhouse-monitoring/deploy/k8s
• 一键部署 — Railway / Render / Fly.io 社区模板
• https://duyet.github.io/clickhouse-monitoring/advanced
• 遥测 — 可选加入，隐私优先的使用指标（默认关闭）
• 版本 — 开源核心模型：GPL-3.0 社区版永久免费；企业功能通过 CHM_EDITION 控制
• https://duyet.github.io/clickhouse-monitoring/reference
• 平台支持矩阵 — ClickHouse 版本和发行版（支持 / 尽力支持 / 未测试）
• 连接预设 — 为 ClickHouse OSS、Altinity 和 Cloud 设置最低权限只读用户
• 贡献配置/检查 — 如何向目录添加声明式监控检查
• MCP 客户端 — 连接 Claude Desktop、Cursor 或任何 MCP 客户端
• Grafana 桥接 — 从 Grafana 读取 chmonitor 的 ClickHouse 数据（社区方案）

AI 代理访问

llms.txt — 标准化文件，帮助 AI 编码代理发现和理解代码库结构。可通过 https://your-domain.com/llms.txt 访问，或在本地开发中通过 /llms.txt 访问。

MCP 服务器 — 在 /api/mcp 公开 Model Context Protocol 端点，供 AI 工具直接查询您的 ClickHouse 集群。设置方法参见 docs/knowledge/mcp-server.md。

知识图谱 — docs/knowledge/ 中的开发者笔记，包含决策、约定和架构文档。索引参见 docs/knowledge/README.md。

截图

反馈与贡献

欢迎提供反馈和贡献！随时提出 issue 或提交 pull 请求。

许可协议

参见 LICENSE。