ClickHouse 外置（多副本）

适用版本：ONES v7.30.0及以上版本。

适用于 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. 配置逻辑拓扑

可以直接编辑服务器配置文件时，使用下面的文件示例；云托管环境使用后面的腾讯云或华为云步骤。选择一种方式即可，配置完成后按第 4 节验证。

直接编辑 ClickHouse 配置文件

适用于有服务器配置权限的 ClickHouse 集群。以下以 1 分片、2 副本为例，假设集群已经可以正常运行，已配置 Keeper / ZooKeeper 和分布式 DDL（ON CLUSTER）。本文不包含从零搭建集群的步骤。

1. 确认配置目录

常见主配置文件为 /etc/clickhouse-server/config.xml，可以在旁边的 config.d/ 目录新增配置文件，无需覆盖整个主配置。若启动时通过 --config-file 指定了其他路径，以实际主配置旁的 config.d/ 为准。容器部署应修改对应的挂载文件或 ConfigMap。

2. 在每个节点配置相同的两套拓扑

新增文件 /etc/clickhouse-server/config.d/ones-clusters.xml，内容如下。将 ch-node-1、ch-node-2、端口、账号和密码替换为实际值；账号需要已在所有节点创建并具备相应权限。

<clickhouse>
    <remote_servers>
        <default_cluster>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>ch-node-1</host>
                    <port>9000</port>
                    <user>ones</user>
                    <password>CHANGE_ME</password>
                </replica>
                <replica>
                    <host>ch-node-2</host>
                    <port>9000</port>
                    <user>ones</user>
                    <password>CHANGE_ME</password>
                </replica>
            </shard>
        </default_cluster>
        <ones_external_fanout>
            <shard>
                <internal_replication>false</internal_replication>
                <replica>
                    <host>ch-node-1</host>
                    <port>9000</port>
                    <user>ones</user>
                    <password>CHANGE_ME</password>
                </replica>
                <replica>
                    <host>ch-node-2</host>
                    <port>9000</port>
                    <user>ones</user>
                    <password>CHANGE_ME</password>
                </replica>
            </shard>
        </ones_external_fanout>
    </remote_servers>
</clickhouse>

host 填写各节点之间可访问的实际节点地址，不能填负载均衡或统一入口；port 是节点的 Native TCP 端口，通常为 9000。
已有原集群配置时保留原配置，只新增 ones_external_fanout 段：完整复制原集群的副本列表并将 internal_replication 改为 false，不要在多个文件中重复定义同名集群。原集群需确认该值为 true。
3 副本时，在两套拓扑的同一个 shard 内各增加一段第 3 个节点的 replica，其余不变。
密码若含 XML 特殊字符，需要转义，例如 & 写成 &、< 写成 <。

3. 检查复制表的默认参数和节点标识

已有集群优先沿用原来的 macros、default_replica_path 和 default_replica_name，不要照抄示例修改现有表使用的复制路径或副本标识。只有缺少这些配置时，才由管理员补齐，例如新增 /etc/clickhouse-server/config.d/ones-replication.xml：

<clickhouse>
    <macros>
        <shard>01</shard>
        <replica>ch-node-1</replica>
    </macros>
    <default_replica_path>/clickhouse/tables/{shard}/{database}/{uuid}</default_replica_path>
    <default_replica_name>{replica}</default_replica_name>
</clickhouse>

所有节点的 shard 都是 01，replica 则分别填写 ch-node-1、ch-node-2，3 副本时再加 ch-node-3。两项默认参数在所有节点保持一致；{uuid} 由 ClickHouse 提供，无需手动添加到 macros。

这些配置让 ReplicatedReplacingMergeTree(__ts) 等建表语句可以省略复制路径和副本名称。Keeper / ZooKeeper 连接及分布式 DDL 配置继续使用原集群的配置。

4. 使配置生效

保存各节点的配置后，由管理员逐个节点重启 ClickHouse，每个节点恢复正常后再处理下一个。使用 systemd 安装的服务可执行：

sudo systemctl restart clickhouse-server

容器或 Kubernetes 部署按原部署方式逐个重启。完成后，在每个节点执行第 4 节的拓扑查询，确认两套拓扑均已生效。

参考：ClickHouse 官方配置示例、复制引擎默认参数、Distributed 拓扑配置。

腾讯云：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. 配置逻辑拓扑​

直接编辑 ClickHouse 配置文件​

腾讯云：TCHouse-C​

华为云：MRS ClickHouse​

3. 填写并应用 ONES 配置​

4. 验证​

检查拓扑​

检查业务​