Skip to main content
借助 Grafana，您可以通过仪表盘探索并共享所有数据。 Grafana 需要通过插件连接到 ClickHouse，您可以在其 UI 中轻松完成安装。
1

收集您的连接详细信息

要通过原生 TCP 连接到 ClickHouse，你需要以下信息：你的 ClickHouse Cloud 服务的详细信息可在 ClickHouse Cloud 控制台中查看。 选择要连接的服务，然后点击 Connect：
ClickHouse Cloud 服务连接按钮
选择 Native，即可在示例 clickhouse-client 命令中看到详细信息。
ClickHouse Cloud 原生 TCP 连接详细信息
如果你使用的是自管理 ClickHouse，连接详细信息由你的 ClickHouse 管理员设置。
2

创建只读用户

将 ClickHouse 连接到 Grafana 这类数据可视化工具时，建议创建一个只读用户，以防止数据被意外修改。Grafana 不会验证查询是否安全。查询中可以包含任何 SQL 语句，包括 DELETE 和 INSERT。要配置只读用户，请按照以下步骤操作：
  1. 按照在 ClickHouse 中创建 Users and Roles指南创建一个 readonly 用户 profile。
  2. 确保 readonly 用户拥有足够的权限，以修改底层 clickhouse-go client 所需的 max_execution_time setting。
  3. 如果您使用的是公网 ClickHouse instance，不建议在 readonly profile 中设置 readonly=2。请改为保留 readonly=1，并将 max_execution_time 的约束类型设置为 changeable_in_readonly，以允许修改此 setting。
3

为 Grafana 安装 ClickHouse 插件

在 Grafana 连接到 ClickHouse 之前，您需要安装相应的 Grafana 插件。假设您已登录 Grafana，请按照以下步骤操作：
  1. 在侧边栏的 Connections 页面中，选择 Add new connection 选项卡。
  2. 搜索 ClickHouse，然后点击由 Grafana Labs 提供的已签名插件：
  3. 在下一个页面中，点击 Install 按钮：
4

定义 ClickHouse 数据源

  1. 安装完成后，点击 Add new data source 按钮。 (您也可以在 Connections 页面中的 Data sources 选项卡中添加数据源。)
  2. 向下滚动找到 ClickHouse 数据源类型，或者在 Add data source 页面的搜索栏中搜索它。选择 ClickHouse 数据源后，将显示以下页面：
  1. 输入服务器设置和凭据。关键设置包括：
  • Server host address: 您的 ClickHouse 服务的主机名。
  • Server port: 您的 ClickHouse 服务所使用的端口。具体端口取决于服务器配置和所用协议。
  • Protocol：用于连接到您的 ClickHouse 服务的协议。
  • Secure connection：如果您的服务器要求安全连接，请启用此项。
  • Username 和 Password：输入您的 ClickHouse 用户凭据。如果您尚未配置任何用户，可尝试使用 default 作为用户名。建议配置只读用户。
有关更多设置，请参阅插件配置文档。
  1. 点击 Save & test 按钮，验证 Grafana 是否能够连接到您的 ClickHouse 服务。如果连接成功，您将看到 Data source is working 消息：
5

后续步骤

您的数据源现已可以使用！如需了解如何使用query builder构建查询，请参阅相关文档。有关配置的更多详细信息，请参阅插件配置文档。如果您想了解这些文档中未包含的更多信息，请查看 GitHub 上的插件 repository。

​
升级插件版本

从 v4 开始，配置和查询可随着新版本的发布进行升级。 v3 中的配置和查询会在打开时迁移到 v4。虽然旧版配置和仪表盘可以在 v4 中加载，但迁移结果在新版中重新保存之前不会被保留。如果你在打开旧配置/查询时发现任何问题，请放弃更改，并在 GitHub 上报告该问题。 如果配置/查询是使用较新版本创建的，插件将无法降级到旧版本。
最后修改于 2026年7月24日