ghcr.io/duyet/clickhouse-monitoring:sha-f41066c5b7071eb901b6f53acb62b7630e19af75

chmonitor Dashboard

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

从 v0.2 升级？v0.3 基于 TanStack Start 重构了应用。ClickHouse 连接变量保持不变；浏览器变量前缀从 NEXT_PUBLIC_* 迁移至 VITE_*（旧名称仍可作为回退使用）。详见下方升级至 v0.3 或完整的https://duyet.github.io/clickhouse-monitoring/migrating/v0-3 指南。

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

功能特性：

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

部署

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 设置密钥
bun run cf:build # Next.js 构建 + OpenNext
wrangler deploy --minify
opennextjs-cloudflare populateCache remote

[!IMPORTANT] 重要说明：

• 由于 Cloudflare Workers 兼容性限制，构建使用 Webpack（而非 Turbopack）
• Next.js 版本固定为 15.5.x（React 19）以确保稳定性
• 静态页面在边缘节点预渲染，以实现最佳性能
• 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

发布版本

标签化发布由 GitHub Actions 从匹配 v* 的标签构建。发布页面包含：

• 发布到 ghcr.io/duyet/chmonitor 的 Docker 镜像（带版本标签）
• 用于 Node.js 部署的 Next.js 独立归档包
• 用于手动检查或部署的 Cloudflare Workers/OpenNext 归档包
• 生成的发布说明，包含 CLI 命令用法、Docker 标签、部署步骤和校验和

为确保 Docker 部署的可重复性，建议使用发布页面中的版本化镜像标签，而非 latest。

升级至 v0.3

v0.3 基于 TanStack Start 重构了仪表板。功能、路由和 ClickHouse 配置保持不变。唯一的环境变量变化是浏览器变量前缀，旧名称仍可使用：

VITE_* 变量是构建时内联的 — 需在构建镜像/Worker 时设置，而非仅在运行时设置。各平台完整步骤：https://duyet.github.io/clickhouse-monitoring/migrating/v0-3%E3%80%82

使用 AI 助手迁移配置

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

You are migrating a chmonitor deployment from v0.2 (Next.js) to v0.3 (TanStack Start).
Here is my current environment (.env / docker-compose / wrangler / k8s manifest):

Rewrite it for v0.3 applying EXACTLY these rules, and output the migrated config
plus a short list of what you changed:

1. Rename every client var prefix NEXT_PUBLIC_ -> VITE_. Specifically:
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
(any other NEXT_PUBLIC_X -> VITE_X). The old names still work as a fallback.
2. Add server-side auth var CHM_AUTH_PROVIDER (none|clerk|proxy) mirroring the
client provider. It is authoritative on the server; keep VITE_AUTH_PROVIDER too.
3. Do NOT rename server vars: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
CLICKHOUSE_NAME, CLICKHOUSE_MAX_EXECUTION_TIME, CLERK_SECRET_KEY, *_API_KEY — keep as-is.
4. VITE_* vars are build-time inlined: ensure they are present at image/Worker BUILD
time (Docker build-args or CI build env), not only at container runtime.
5. If this is a Docker deployment, change the container start command from
`node server.js` to `node server/index.mjs`. Port 3000 and the /api/healthz
healthcheck are unchanged.
6. Flag anything that has no v0.3 equivalent instead of silently dropping it.

文档

• /docs - 完整文档站点（本地/docs）
• llms.txt - 用于 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
• https://duyet.github.io/clickhouse-monitoring/advanced

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 或拉取请求。

许可证

详见 LICENSE。