ghcr.io/duyet/clickhouse-monitoring:sha-11e92758cc43461e6647172b6f68c055bf6c3578

ClickHouse 监控仪表板

基于 Next.js 15 的现代仪表板，通过系统表提供 ClickHouse 集群的实时洞察。具备静态站点生成与客户端数据获取功能，可实现最佳性能与 CDN 缓存。

功能特性：

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

演示

运行在家庭实验室的 ClickHouse 服务器，有时可能响应较慢：

• chmonitor.dev（Cloudflare Workers）
• clickhouse-monitoring.duyet.net
• clickhouse-monitor.duyet.workers.dev（Cloudflare Workers 旧版）

部署

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

重要说明：

• 由于 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/clickhouse-monitoring:latest

版本发布

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

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

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

文档

• /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
• https://duyet.github.io/clickhouse-monitoring/advanced

AI 代理访问

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

MCP 服务器 — 在 /api/mcp 暴露模型上下文协议端点，供 AI 工具直接查询 ClickHouse 集群。详见 docs/knowledge/mcp-server.md 中的设置说明。

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

截图

反馈与贡献

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

许可证

详见 LICENSE。