ghcr.io/duyet/clickhouse-monitoring:0
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
设置步骤:
- 克隆仓库并安装依赖:
git clone https://github.com/duyet/clickhouse-monitoring.git
cd clickhouse-monitoring
bun install
- 在
.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。
- 部署到 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 配置保持不变。唯一的环境变量变化是浏览器变量前缀,旧名称仍可使用:
| 事项 | v0.2(Next.js) | v0.3(TanStack Start) |
|---|---|---|
| 浏览器变量前缀 | NEXT_PUBLIC_* | VITE_*(旧名称仍可使用) |
| 身份验证提供程序(客户端) | NEXT_PUBLIC_AUTH_PROVIDER | VITE_AUTH_PROVIDER |
| Clerk 密钥(客户端) | NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | VITE_CLERK_PUBLISHABLE_KEY |
| 身份验证提供程序(服务器) | 从客户端变量推导 | CHM_AUTH_PROVIDER(none|clerk|proxy) |
| Docker 入口点 | node server.js | node server/index.mjs |
| ClickHouse 变量 | CLICKHOUSE_HOST/USER/PASSWORD/NAME | 保持不变 |
VITE_* 变量是构建时内联的 — 需在构建镜像/Worker 时设置,而非仅在运行时设置。各平台完整步骤:https://duyet.github.io/clickhouse-monitoring/migrating/v0-3。
使用 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 代理自动理解代码的发现文件
- [***](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。
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务