ClickHouse

ClickHouse Cloud通过在你的组织设置中创建的API密钥连接。一个API密钥恰好属于一个组织，所以一个密钥连接一个组织，每个组织只连接到一个工作区一次。密钥在存储前加密，智能体永远看不到它们。

1. 打开ClickHouse Cloud，进入你组织的API Keys。
2. 点击New API key并选择Developer（只读）角色：Polylane在同步期间只读取。
3. 复制key ID和key secret两个值；密钥只显示一次。
4. 把两个值粘贴到Polylane中。
5. Polylane验证密钥并开始同步。

Polylane发现你的服务，包括状态、层级、区域、云提供商、ClickHouse版本、副本规格和连接端点。连接主机名用于跨云链接，所以通过环境变量访问某个服务的应用会在地图上关联到它。

当服务处于退化、失败、已停止或部分运行状态时，监控会提出一个问题；空闲和唤醒中的服务是空闲缩放服务的正常生命周期，保持健康。ClickHouse Cloud控制面以没有历史的实时快照报告指标，所以智能体按需读取当前值，服务不带指标图表。

故障排除

“Invalid API key”错误

• 密钥ID和密钥都是必需的；任何一个单独都无法验证身份。
• 检查该密钥没有在ClickHouse Cloud的API密钥设置中被删除或禁用。
• 带有效期的密钥到期后停止工作；创建一个新密钥并在Polylane中轮换。

缺少资源

• ClickHouse Cloud可能需要几分钟才能同步一切。
• 从账户头部触发一次手动Sync以刷新。

速率限制

• ClickHouse Cloud允许每个密钥每10秒10个API请求。为Polylane准备一个专用密钥可以避免与其他工具共享这份预算。

断开连接

在Polylane中断开该账户，然后从你的ClickHouse Cloud组织设置中删除该API密钥。

连接ClickHouse Cloud不需要浏览器：控制台调用的同一个端点可以放进CI作业。一次经过身份验证的POST创建连接并启动第一次同步。

前提条件

• 一个具有cloud_accounts:write和cloud_accounts:read权限范围的Polylane API密钥。参见API密钥与OAuth。
• 你的工作区ID，以ws_开头。用同一个密钥从GET /v1/workspaces读取它。
• 一个来自你组织的API Keys、以Developer（只读）角色创建的ClickHouse Cloud API密钥ID和密钥。

创建连接

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clickhouse",
    "workspaceId": "ws_0abc123",
    "keyId": "<key-id>",
    "keySecret": "<key-secret>"
  }'

API密钥恰好属于一个组织，所以一次调用连接一个组织。

响应列出已连接的内容，第一次同步已经在运行。精简为流程其余部分读取的两个字段：

{
  "success": true,
  "result": {
    "provider": "clickhouse",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

已经连接的账户会落在failures而不是accounts中，所以重复调用永远不会产生重复的连接。

等待第一次同步

按id轮询每个返回的账户，直到status达到ready（注册时为new，资源流入时为syncing）：

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

给循环一个截止时间，让失败的连接使作业失败而不是挂起。账户变为ready后，它的资源已在拓扑中，Polylane已经开始它的第一次检查。

从API断开连接

删除连接会停止所有同步和检查，并删除Polylane持有的凭据。该调用需要cloud_accounts:delete权限范围：

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

然后按下方Disconnect所述在提供商侧撤销ClickHouse Cloud凭据。