> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> 将 iOS 或 iPadOS 上的 ProbeDeck 连接到 ClickHouse Cloud 或自托管的 ClickHouse 服务器。

# 将 ProbeDeck 连接到 ClickHouse

export const CommunityMaintainedBadge = () => {
  return <div className="CommunityMaintainedBadge">
            <div className="CommunityMaintainedIcon">
            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 256 256">
                <path d="M244.8,150.4a8,8,0,0,1-11.2-1.6A51.6,51.6,0,0,0,192,128a8,8,0,0,1-7.37-4.89,8,8,0,0,1,0-6.22A8,8,0,0,1,192,112a24,24,0,1,0-23.24-30,8,8,0,1,1-15.5-4A40,40,0,1,1,219,117.51a67.94,67.94,0,0,1,27.43,21.68A8,8,0,0,1,244.8,150.4ZM190.92,212a8,8,0,1,1-13.84,8,57,57,0,0,0-98.16,0,8,8,0,1,1-13.84-8,72.06,72.06,0,0,1,33.74-29.92,48,48,0,1,1,58.36,0A72.06,72.06,0,0,1,190.92,212ZM128,176a32,32,0,1,0-32-32A32,32,0,0,0,128,176ZM72,120a8,8,0,0,0-8-8A24,24,0,1,1,87.24,82a8,8,0,1,0,15.5-4A40,40,0,1,0,37,117.51,67.94,67.94,0,0,0,9.6,139.19a8,8,0,1,0,12.8,9.61A51.6,51.6,0,0,1,64,128,8,8,0,0,0,72,120Z"></path>
            </svg>
        </div>
            由社区维护
        </div>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<CommunityMaintainedBadge />

ProbeDeck 是一款适用于 iOS 和 iPadOS 的客户端，可用于检查 ClickHouse server 的健康状况、查看
`system` 表以及运行 SQL。它可通过设备网络或 SSH 堡垒机连接到 ClickHouse HTTP 接口，
无需中继服务器。

<div id="before-you-begin">
  ## 开始之前
</div>

* 从 [App Store 安装 ProbeDeck](https://apps.apple.com/app/id6791261174)。
* 使用 iOS 或 iPadOS 17.0 或更高版本。
* 确保设备可通过网络、VPN 或 SSH 堡垒机访问 ClickHouse 的 HTTP 或 HTTPS 端点。
* 创建一个可访问要查询数据库的 ClickHouse 用户。
* 授予该用户相关 `system` 表的 `SELECT` 权限，以便进行监控。

| ProbeDeck   | ClickHouse Cloud | 自托管 ClickHouse | 说明                                          |
| ----------- | ---------------- | -------------- | ------------------------------------------- |
| 1.1.7 或更高版本 | 当前服务             | 未指定最低服务器版本     | 使用 HTTP(S) 接口。测试连接，并根据您的服务器版本和授权情况验证各个监控部分。 |

某些监控部分依赖可选的日志表或较新的系统表。例如，
ProbeDeck 用于获取已配置内存限制的 `system.server_settings` 需要 ClickHouse
23.3 或更高版本。当其数据源不可用时，ProbeDeck 会将受影响的部分标记为受限。

<div id="how-it-works">
  ## 工作原理
</div>

1. ProbeDeck 向 ClickHouse HTTP(S) 端点发送 SQL 请求。
2. 它使用已配置的 ClickHouse 用户从 `system` 表读取监控数据。
3. 应用会在设备上显示查询结果和监控视图。当设备无法直接访问端点时，可通过 SSH 堡垒机建立相同的 HTTP(S) 连接。

<div id="connect-to-clickhouse-cloud">
  ## 连接 ClickHouse Cloud
</div>

<Steps>
  <Step title="获取服务连接详细信息" id="gather-cloud-details">
    在 ClickHouse Cloud 控制台中，打开您的服务，选择 **Connect**，然后选择 **HTTPS**。

    要通过 HTTP(S) 连接到 ClickHouse，你需要以下信息：

    | Parameter(s)              | Description                                |
    | ------------------------- | ------------------------------------------ |
    | `HOST` and `PORT`         | 通常，使用 TLS 时端口为 8443；不使用 TLS 时端口为 8123。     |
    | `DATABASE NAME`           | 默认情况下，存在一个名为 `default` 的数据库。请使用你要连接的数据库名称。 |
    | `USERNAME` and `PASSWORD` | 默认情况下，用户名为 `default`。请根据你的使用场景使用相应的用户名。    |

    你的 ClickHouse Cloud 服务的连接信息可在 ClickHouse Cloud 控制台中查看。
    选择一个服务，然后点击 **Connect**：

    <div className="ch-image-md">
      <Frame>
        <img src="https://mintcdn.com/private-7c7dfe99/EDr8ydtGBgFPOQea/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=EDr8ydtGBgFPOQea&q=85&s=97d6a020a443f1b365b017488b39d0c8" alt="ClickHouse Cloud 服务连接按钮" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
      </Frame>
    </div>

    选择 **HTTPS**。连接信息会显示在示例 `curl` 命令中。

    <div className="ch-image-md">
      <Frame>
        <img src="https://mintcdn.com/private-7c7dfe99/EDr8ydtGBgFPOQea/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=EDr8ydtGBgFPOQea&q=85&s=80369fc90cd1ac3108fe455f2426c19a" alt="ClickHouse Cloud HTTPS 连接信息" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
      </Frame>
    </div>

    如果你使用的是自管理 ClickHouse，则连接信息由你的 ClickHouse 管理员配置。
  </Step>

  <Step title="在 ProbeDeck 中添加连接" id="add-cloud-connection">
    1. 在 **Connections** 页面中，点击 **+**。
    2. 输入连接名称和主机地址 (不含 `https://`) 。
    3. 将 **Port** 设置为 `8443`，并启用 **TLS**。
    4. 输入 **Connect** 对话框中的数据库用户名和密码。数据库名称为
       可选。
    5. 点击 **Test Connection**。检查成功后，ProbeDeck 会显示服务器版本和往返时间。
    6. 点击 **Save**。

    ProbeDeck 使用这些数据库凭据对发送至服务端点的 SQL 请求进行身份验证。
    ClickHouse Cloud 使用 **API Keys** 页面中的组织级密钥来访问 Cloud API 和查询 API 端点。
    ProbeDeck 的 SQL 连接流程不使用这些密钥。

    <Image img="https://mintcdn.com/private-7c7dfe99/-GwTwl23hJZldEaZ/images/integrations/sql-clients/probedeck-add-connection.png?fit=max&auto=format&n=-GwTwl23hJZldEaZ&q=85&s=ced2eba375eed25880131fd1be03bf23" size="sm" border alt="ProbeDeck 连接表单已配置为通过端口 8443 使用 HTTPS 和 ClickHouse 用户名" width="1320" height="2160" data-path="images/integrations/sql-clients/probedeck-add-connection.png" />
  </Step>
</Steps>

<div id="connect-to-self-hosted-clickhouse">
  ## 连接到自托管 ClickHouse
</div>

<Steps>
  <Step title="选择 HTTP 端点" id="choose-self-hosted-endpoint">
    默认未加密的 HTTP 接口使用端口 `8123`。对于 HTTPS，请启用 **TLS** 并使用
    服务器上配置的端口；常用端口为 `8443`。

    <Note>
      端口 `9000` 和 `9440` 用于原生 ClickHouse 协议。ProbeDeck 使用 HTTP(S)
      接口，因此请输入服务器的 HTTP 端口。
    </Note>
  </Step>

  <Step title="添加并测试连接" id="add-self-hosted-connection">
    1. 在 **Connections** 页面中，点击 **+**。
    2. 输入服务器主机名，不要包含 URL 协议。
    3. 设置 HTTP(S) 端口和 TLS 选项。
    4. 输入 ClickHouse 用户名、密码和可选的数据库。
    5. 点击 **Test Connection**，然后点击 **Save**。

    对于本地网络中的服务器，iOS 可能会请求本地网络访问权限。如果端点只能通过企业网络访问，请先将设备连接到
    企业 VPN。
  </Step>
</Steps>

<div id="connect-through-an-ssh-bastion">
  ## 通过 SSH 堡垒机连接
</div>

在连接表单中启用 **SSH 隧道**，然后输入：

1. 堡垒机主机地址和 SSH 端口 (默认为 `22`) 。
2. SSH 用户名。
3. SSH 密码或私钥。

ProbeDeck 会通过 SSH `direct-tcpip` 通道，从堡垒机连接到 **服务器** 部分中指定的 ClickHouse 主机和 HTTP(S)
端口。首次连接时，在接受前请将堡垒机的 SHA-256 主机密钥指纹与服务器管理员提供的值进行核对。

<div id="configure-authentication-and-tls">
  ## 配置身份验证和 TLS
</div>

ProbeDeck 会通过 `X-ClickHouse-User` 和
`X-ClickHouse-Key` 请求头发送数据库用户名和密码，不会将凭据置于 URL 中。

如需使用双向 TLS，请启用 **TLS Client Certificate**，然后导入包含
客户端证书和私钥的 PKCS#12 (`.p12`) 文件，并输入其密码短语。

当自托管端点提供自签名证书或由私有
CA 签发的证书时，ProbeDeck 会显示其 SHA-256 指纹、签发方、主体和有效期。接受前，请将该
指纹与服务器管理员提供的值进行比对。ProbeDeck 会将此决定绑定到该连接；如果证书发生变更，连接会停止，直至您完成审核。

ProbeDeck 会将连接密钥和导入的密钥材料存储在设备的 iOS Keychain 中。

<div id="monitor-clickhouse">
  ## 监控 ClickHouse
</div>

打开已保存的连接，然后选择 **监控**。该仪表板汇总以下数据源：

| 区域                 | ClickHouse 数据源                                                            |
| ------------------ | ------------------------------------------------------------------------- |
| 正在运行的查询、耗时、内存和读取行数 | `system.processes`                                                        |
| 复制状态和队列            | `system.replicas`, `system.replication_queue`                             |
| 磁盘、parts 和合并       | `system.disks`, `system.parts`, `system.merges`                           |
| 变更                 | `system.mutations`                                                        |
| 内存和服务器指标           | `system.metrics`, `system.asynchronous_metrics`, `system.server_settings` |
| 历史查询和磁盘速率          | `system.metric_log`, `system.asynchronous_metric_log`                     |

<Image img="https://mintcdn.com/private-7c7dfe99/-GwTwl23hJZldEaZ/images/integrations/sql-clients/probedeck-dashboard.png?fit=max&auto=format&n=-GwTwl23hJZldEaZ&q=85&s=e139ac9115a93bbcbca9d344d8c94534" size="sm" border alt="显示正在运行的查询、复制、磁盘、parts、变更、合并、查询速率和内存的 ProbeDeck 监控仪表板" width="1320" height="2868" data-path="images/integrations/sql-clients/probedeck-dashboard.png" />

点击 **正在运行的查询**，按耗时对活动查询排序，并查看内存和读取行数。

<Image img="https://mintcdn.com/private-7c7dfe99/-GwTwl23hJZldEaZ/images/integrations/sql-clients/probedeck-running-queries.png?fit=max&auto=format&n=-GwTwl23hJZldEaZ&q=85&s=b9e6312428cebde1a446e469a702dde4" size="sm" border alt="按耗时排序的 ProbeDeck 正在运行的查询列表" width="1320" height="2868" data-path="images/integrations/sql-clients/probedeck-running-queries.png" />

<div id="query-the-uk-property-price-dataset">
  ## 查询英国房产价格数据集
</div>

本示例使用 [UK property price dataset](/docs/zh/get-started/sample-datasets/uk-price-paid)。
将数据集加载到 `uk_price_paid`，然后：

1. 打开连接，然后选择 **数据**。
2. 打开 SQL 编辑器。
3. 运行以下有界只读查询：

```sql theme={null}
SELECT
    town,
    count() AS sales,
    round(avg(price)) AS average_price
FROM uk_price_paid
GROUP BY town
ORDER BY sales DESC
LIMIT 10
```

结果应包含十个城镇及其交易数量和平均价格。

<div id="known-limits">
  ## 已知限制
</div>

* ProbeDeck 支持 iOS 和 iPadOS 17.0 及更高版本。
* 免费用户一次只能保存一个连接。删除该连接即可释放名额；ProbeDeck Pro 支持
  保存不限数量的连接。
* 它支持 ClickHouse HTTP(S) 接口，不支持原生协议。
* ProbeDeck 会按每页 200 行加载 SQL 查询结果，并将每个请求最多限制为 10,000 行。对于大型表，请使用
  有选择性的 `WHERE` 子句和 `LIMIT`。
* 监控的可见性取决于 ClickHouse 用户的授权以及可选的日志表。
* 设备需要能够通过其网络、VPN 或内置 SSH 隧道访问端点。
* 监控和只读 SQL 无需应用内购买。`KILL QUERY`、`KILL MUTATION`、
  写入和 DDL 语句以及其他运维操作需要 ProbeDeck Pro。

<div id="troubleshooting">
  ## 故障排查
</div>

<Accordion title="身份验证失败">
  重新复制数据库用户名和密码。对于 ClickHouse Cloud 服务端点，请使用服务 **Connect** 对话框中的
  数据库凭据。请勿改用 ClickHouse Cloud **API Keys** 页面中的组织级
  密钥。
</Accordion>

<Accordion title="连接被拒绝或超时">
  确认设备能够访问主机和 HTTP(S) 端口。检查 Cloud IP 访问列表、VPN、
  防火墙和端口映射。请勿使用原生协议端口 `9000` 或 `9440`。
</Accordion>

<Accordion title="监控显示权限受限">
  ClickHouse 用户无法读取一个或多个必需的 `system` 表。请向服务器管理员申请
  使用相应监控区域所需的最低 `SELECT` 授权，然后重新连接。
</Accordion>

<Accordion title="TLS 指纹已更改">
  接受新指纹前，请让服务器管理员确认是否已轮换证书。意外的更改可能表明端点不同，
  或 TLS 拦截路径发生了变化。
</Accordion>

<div id="next-steps">
  ## 后续步骤
</div>

* 有关 ProbeDeck 的详细信息，请访问 [ProbeDeck 网站](https://probedeck.app)。
* 有关服务器配置，请参阅 [ClickHouse HTTP 接口文档](/docs/zh/concepts/features/interfaces/http)。