ClickHouse 外置（多副本）

适用于 1 分片、2 或 3 副本的外部 ClickHouse。单实例请看 ClickHouse 外置（单副本）。

支持初装时指定外置，也支持初装完成后切换外置。初装后切换不迁移旧数据。 不支持多分片，也不支持阿里云托管 ClickHouse（社区兼容版和企业版）。

1. 通用要求

请数据库管理员确认：

ONES 可以访问外部统一入口，已提供 HTTP/TCP 端口和有建库、建表、读写权限的账号。当前配置使用明文 HTTP/TCP。
支持 EmbeddedRocksDB、Join、Distributed 和 ReplicatedMergeTree 家族引擎；可以执行集群建表、指定表 UUID，以及不带参数的 Replicated 引擎建表。
可以通过配置文件或云控制台管理逻辑集群（remote_servers），并让配置在每个 ClickHouse 节点生效。

需要准备以下两套逻辑拓扑。两套拓扑都只有 1 个分片，包含相同的全部副本，不需要再购买一套数据库。

名称	`internal_replication`	用途
原有集群名，例如 `default_cluster`	`true`	集群建表、复制表相关操作
新增 `ones_external_fanout`	`false`	将本地表的写入发送给每个副本

表中的名称是示例，可以使用其他名称，后续 ONES 配置填写实际名称即可。

阿里云社区兼容版不支持用户自行配置 remote_servers，企业版不支持 ON CLUSTER 等所需能力，因此当前外置多副本方案不支持阿里云的 ClickHouse。

2. 云厂商配置示例

下面以腾讯云 TCHouse-C 和华为云 MRS 为例，说明如何满足上述要求。选择所用平台对应的步骤即可；配置完成后按第 4 节验证。

腾讯云：TCHouse-C

配置入口见腾讯云《参数配置》。

打开 TCHouse-C 控制台 → 集群详情 → 参数配置，使用 XML 模式，打开 metrika.xml。
在 clickhouse_remote_servers 内，找到原有的 default_cluster，完整复制这一段，放在原段后面。
只修改复制出来的新段：

位置修改后
开始标签 <default_cluster> <ones_external_fanout>
结束标签 </default_cluster> </ones_external_fanout>
internal_replication 的值 false

新段中的关键设置为：
```
<internal_replication>false</internal_replication>
```
保留全部 replica 内容，包括原来的 host、port、user、password。两段必须包含相同副本，且各只有一个 shard。
单击 应用到集群 → 查看对比 → 保存并下发，按控制台提示使配置生效。

位置	修改后
开始标签 `<default_cluster>`	`<ones_external_fanout>`
结束标签 `</default_cluster>`	`</ones_external_fanout>`
`internal_replication` 的值	`false`

直接复制原 metrika.xml 的节点 IP 和端口，不要改成“网络信息”里的用户访问 IP。 腾讯云要求这里使用后台管理地址，且不支持修改端口。如果看不到 XML 模式，请联系腾讯云技术支持；启用 XML 模式后不能切回 KV 模式。

华为云：MRS ClickHouse

以下配置入口来自华为云《ClickHouse 集群配置说明》，该文档标明适用于 MRS 3.1.0。其他 MRS 版本需核对实际入口；CloudTable 不使用下面的 MRS 步骤，需先向华为云确认能否增加自定义拓扑。

打开集群 Manager → 集群 → 服务 → ClickHouse → 配置 → 全部配置。
找到 clickhouse-metrika-customize，保留原有配置。
按下表新增配置。表中的节点地址和端口，从原有集群配置复制；不要填写统一访问入口。

参数	填写内容
`clickhouse_remote_servers.ones_external_fanout.shard[1].internal_replication`	`false`
`clickhouse_remote_servers.ones_external_fanout.shard[1].replica[1].host`	原有副本 1 的节点地址
`clickhouse_remote_servers.ones_external_fanout.shard[1].replica[1].port`	原有副本 1 的 TCP 端口
`clickhouse_remote_servers.ones_external_fanout.shard[1].replica[2].host`	原有副本 2 的节点地址
`clickhouse_remote_servers.ones_external_fanout.shard[1].replica[2].port`	原有副本 2 的 TCP 端口

3 副本时，另外增加 replica[3].host 和 replica[3].port 两项，前缀与上表相同。如果原配置中还有每个副本的 user、password 等连接参数，也一并复制到对应的新配置中。

单击保存，按控制台提示使配置生效，再执行第 4 节的拓扑查询。

3. 填写并应用 ONES 配置

在 ONES 安装操作环境中编辑 config/private.yaml；已安装环境可先执行 ones-ai-k8s.sh 进入。

internalComponentClickhouseEnable: false
clickhouseHost: ch.example.com       # 外部统一入口，不带 http:// 或端口
clickhouseWriteHost: ""              # 保持为空，不要列出所有副本
clickhousePortHTTP: 8123             # 改成实际 HTTP 端口
clickhousePortTCP: 9000              # 改成实际 TCP 端口
clickhouseUser: ones                 # 改成实际用户名
clickhousePassword: "实际密码"
clickhouseClusterName: default_cluster # 改成数据库中原有逻辑集群的实际名称
clickhouseLocalFanoutClusterName: ones_external_fanout

两个名称必须与数据库中的逻辑集群名称一致。原集群名不是 default_cluster 时，填写实际名称。已有配置项直接修改，不要重复添加。

初装环境：填好配置后，继续正常的 ONES 安装和数据库初始化流程。
已安装环境：执行 make setup-ones。

4. 验证

检查拓扑

用业务账号连接各 ClickHouse 节点执行以下 SQL；原集群名按实际替换：

SELECT cluster, shard_num, replica_num, host_name, port, internal_replication
FROM system.clusters
WHERE cluster IN ('default_cluster', 'ones_external_fanout')
ORDER BY cluster, shard_num, replica_num;

检查结果：

两个集群的节点列表相同，shard_num 都是 1。
2 副本时每个集群各有 2 行，3 副本时各有 3 行。
原集群的 internal_replication 是 1，ones_external_fanout 是 0。

若提示不存在 internal_replication 字段，从 SQL 中去掉它，并在云控制台检查该设置。

检查业务

确认业务初始化完成，服务日志中没有连接、权限或建表错误。
产生一条新业务操作，确认审计日志、报表等相关功能正常。
请管理员验证：复制表写入后其他副本能读到；通过 fanout 写入本地表后，每个副本都能读到相同结果。不要只通过统一入口重复查询。

false 表示向所有副本发送写入，不会自动修复本地表数据差异。新增副本、丢盘或重建后，需要补齐本地表数据再接入业务。旧内置数据库的停用、备份和数据清理由管理员另行处理。

1. 通用要求​

2. 云厂商配置示例​

腾讯云：TCHouse-C​

华为云：MRS ClickHouse​

3. 填写并应用 ONES 配置​

4. 验证​

检查拓扑​

检查业务​