mcpField
C
clickhousectl-cloud-deploy

clickhousectl-cloud-deploy

github.com/clickhouse云与 DevOps5624.3k 次安装1 周前更新
代码仓库

关于 clickhousectl-cloud-deploy

通过 `clickhousectl` 将应用部署到 ClickHouse Cloud 的分步技能，面向开发者，涵盖账号、CLI 认证、服务创建、架构迁移、验证及应用凭据配置。

主要功能

  1. 01ClickHouse Cloud 账号设置
  2. 02CLI 认证指导
  3. 03创建云服务
  4. 04迁移架构和视图
  5. 05验证部署结果
  6. 06配置应用用户

适用场景

  1. 01将本地 ClickHouse 应用迁至生产环境
  2. 02创建 ClickHouse Cloud 服务
  3. 03迁移架构和物化视图
  4. 04配置应用数据库凭据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/clickhouse/agent-skills --skill clickhousectl-cloud-deploy

安装后在 Claude Code 中输入/clickhousectl-cloud-deploy确认已加载。

附带文件metadata.json

详细介绍

部署到 ClickHouse Cloud

本技能将介绍如何使用 clickhousectl 部署到 ClickHouse Cloud，涵盖账户设置、CLI 身份验证、服务创建、架构迁移以及连接应用程序。请按顺序完成以下步骤。

适用场景

当用户希望执行以下操作时，使用此技能：

  • 将 ClickHouse 应用程序部署到生产环境
  • 将 ClickHouse 托管为云服务
  • 从本地 ClickHouse 设置迁移到 ClickHouse Cloud
  • 创建 ClickHouse Cloud 服务
  • 首次设置 ClickHouse Cloud

步骤 1：注册 ClickHouse Cloud

使用任何云端命令之前，用户需要拥有 ClickHouse Cloud 账户。

询问用户：“您已经有 ClickHouse Cloud 账户了吗？”

如果用户没有账户，请说明：

ClickHouse Cloud 是一项全托管服务，可代您运行 ClickHouse——无需维护基础设施，并包含自动扩缩、备份和升级。您可以免费试用，无需信用卡即可开始使用。

创建账户，请访问：https://clickhouse.cloud

使用电子邮件、Google 或 GitHub 账户注册。进入控制台后，请告诉我，我们将继续下一步。

等待用户确认已完成注册或已有账户后再继续。

步骤 2：对 CLI 进行身份验证

首先，确保已安装 clickhousectl。使用以下命令检查：

which clickhousectl

如果未找到，请安装：

curl -fsSL https://clickhouse.com/cli | sh

使用 ClickHouse Cloud API 密钥对 clickhousectl 进行身份验证。

创建 API 密钥

引导用户在 ClickHouse Cloud 控制台中创建密钥：

  1. 点击左侧栏中的齿轮图标（设置）
  2. 前往 API Keys
  3. 点击 Create API Key
  4. 为密钥命名（例如 “clickhousectl”）
  5. 为密钥选择 Admin 角色。需要 Admin 权限，因为 cloud service query 首次使用时会自动为每项服务创建一个查询端点 API 密钥，这需要创建密钥的权限。Developer 范围的密钥可以管理服务，但可能无法完成自动创建步骤。
  6. 点击 Generate API Key
  7. 复制 Key ID 和 Key Secret——密钥 Secret 只会显示一次
使用密钥验证 clickhousectl

请用户在同一工作目录中打开一个新的终端标签页，并在其中使用他们的 Key ID 和 Secret 运行登录命令——这样密钥就不会出现在聊天会话中。请他们完成后回来告知您。

clickhousectl cloud login --api-key <key> --api-secret <secret>

--api-key 和 --api-secret 都是必需的——如果用户只有其中一个，请告知他们两者都需要。

验证身份验证是否成功：

clickhousectl cloud org list

此命令应返回用户所属的组织。

步骤 3：创建云服务

创建新的 ClickHouse Cloud 服务：

clickhousectl cloud service create --name <service-name>

从输出中获取 HTTPS 主机和端口，将它们添加到 .env 中，分别设为 CLICKHOUSE_HOST 和 CLICKHOUSE_PORT。确保 .env 已加入 gitignore。

然后持续轮询，直到服务状态为 running：

clickhousectl cloud service get <service-id>

步骤 4：迁移架构

如果用户有本地表定义（例如，使用 clickhousectl-local-dev 技能创建的定义），请将它们迁移到云服务。

使用 cloud service query 通过 HTTP 对云服务运行 SQL。只需传入服务名称（或 --id）。

读取 clickhouse/tables/ 中的本地架构文件，并将每个文件应用到云服务：

clickhousectl cloud service query --name <service-name> \
  --queries-file clickhouse/tables/<table>.sql

请按依赖顺序应用——物化视图引用的表应先创建。

如果存在物化视图，也请应用它们：

clickhousectl cloud service query --name <service-name> \
  --queries-file clickhouse/materialized_views/<view>.sql

如需指定数据库，请传入 --database <name>。

步骤 5：验证部署

连接到云服务并确认表已存在：

clickhousectl cloud service query --name <service-name> --query "SHOW TABLES"

运行测试查询，确认架构正确：

clickhousectl cloud service query --name <service-name> --query "DESCRIBE TABLE <table-name>"

步骤 6：为应用创建专用用户

default 用户拥有完整的管理员权限，不应供应用使用。创建一个专用用户，将其权限限定在步骤 4 中部署的架构范围内。

生成一个强随机密码，并在创建用户之前将凭据追加到 .env，这样即使后续步骤失败，密码也已保存：

PASSWORD=$(openssl rand -base64 32)
echo "CLICKHOUSE_USER=app_user" >> .env
echo "CLICKHOUSE_PASSWORD=$PASSWORD" >> .env

然后创建用户，并授予应用所需的最低权限。将 <database> 替换为架构所在的数据库（通常为 default）：

clickhousectl cloud service query --name <service-name> --query \
  "CREATE USER app_user IDENTIFIED BY '$PASSWORD'"

clickhousectl cloud service query --name <service-name> --query \
  "GRANT SELECT, INSERT ON <database>.* TO app_user"

根据应用的需求调整授权：

  • 只读应用 → 移除 INSERT
  • 需要创建或删除自己的表 → 还要在数据库上授予 CREATE TABLE, DROP TABLE 权限（但最好以管理员用户身份运行迁移）
  • 多个数据库 → 对每个数据库重复执行 GRANT，或通过 ON <database>.<table> 将权限限定到具体表

验证用户存在且拥有预期的授权：

clickhousectl cloud service query --name <service-name> --query "SHOW GRANTS FOR app_user"

ClickHouse 无法在之后显示密码，因此如果 .env 丢失，必须通过 ALTER USER app_user IDENTIFIED BY '<new>' 重置用户密码。

现在，应用可以使用 .env 中的凭据连接到 ClickHouse Cloud。

评论

支持 Markdown