配置 Netdata Parent 集群并在维护后恢复指标同步

原作：Netdata 官方文档，页面未署可确认的个人作者。本文按研究页边界合并高可用、双 Parent 配置和历史复制说明，并补齐连接设置与排错入口。读取日期为 2026 年 10 月 5 日；主文、历史复制和基础连接页标示 2026 年 8 月 15 日更新，配置样例页标示 7 月 23 日更新。这些是文档更新时间，不等同功能首发日期。本次只静态核验，没有连接或配置任何 Netdata 节点。

Netdata 可以把多个 Child 的指标集中到 Parent。为避免单个 Parent 的维护或故障中断可见性，可以建立含两个或更多 Parent 的集群：Children 配置所有可用目的地，Parents 再互相同步。一个 Child 在任一时刻只连一个 Parent；当前连接失败后，才切换到配置中的另一个可用节点。

先理解集群的数据流

每个 Parent 也会寻找一个可工作的对端 Parent，失败时再换下一个。Children 直接连接哪台 Parent 并不决定最终只有哪台保留指标；通过 Parent 之间的数据转发，集群可以在各节点上保留 Children 的指标。

所有 Parents 都能向 Netdata Cloud 注册所接收的 Children，因此只要仍有合适的 Parent 在线，Cloud 仍可展示这些系统。这不表示任何故障都无数据丢失：链路、复制拓扑、存储与保留时长必须满足条件。Child 至少要保留能覆盖切换间隔的数据，重新连接时双方才有机会补齐缺口。所有副本都已过期的数据，不能靠重连重建。

stream.conf 的发送段与接收段

Children 与 Parents 都在 stream.conf 配置指标流。[stream] 定义向外发送；其他以 API key 命名的段定义接收权限。netdata.conf 与 stream.conf 都是 ini 格式，但后者包含通信密钥和地址，应按敏感配置保护，限制读取权限，不提交到公共仓库。

原文用以下命令打开配置：

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config stream.conf

容器部署需先进入对应容器，例如 docker exec -it netdata bash，再在容器内编辑 /etc/netdata 中的配置。编辑补充：原命令的两个 cd 都失败时，下一行仍可能从错误目录执行相对路径；实际操作应确认当前目录正确再执行 edit-config。这里的 sudo、容器名与安装路径都需匹配自己的部署，不应机械套用。

接收端可用 uuidgen 生成随机连接密钥，把 API_KEY 替换为生成值：

[API_KEY]
    enabled = yes

发送端配置目的地及同一密钥，保存后按部署方式重启服务。重启会短暂中断当前连接，先确认备用节点和 Child 保留时间可承受切换。

双 Parent 的完整基础配置

以下是官方 Active-Active Parents 示例。API_KEY、主机地址都为占位值，不是可复用的生产秘密。原例让 Parent 间与 Child 使用同一个密钥，便于说明拓扑；后面给出维护时更适合的密钥分离方式。

Parent 1 的 stream.conf

[stream]
    enabled = yes
    destination = PARENT_2_HOSTNAME_OR_IP:19999
    api key = API_KEY

[API_KEY]
    enabled = yes

Parent 2 的 stream.conf

[stream]
    enabled = yes
    destination = PARENT_1_HOSTNAME_OR_IP:19999
    api key = API_KEY

[API_KEY]
    enabled = yes

每台 Child 的 stream.conf

[stream]
    enabled = yes
    destination = PARENT_1_HOSTNAME_OR_IP:19999 PARENT_2_HOSTNAME_OR_IP:19999
    api key = API_KEY

Parent 1 向 Parent 2 发，Parent 2 向 Parent 1 发；Child 有两个备选地址，但不会因这一行地址列表就同时向两者各发一份。

需要降低 Child 负担时

官方还给出轻量 Child 配置：仅用 RAM 保留约 20 分钟指标，把机器学习与告警交给 Parent，本地仪表盘只监听 localhost：

[db]
    db = ram
    retention = 1200
    update every = 1

[ml]
    enabled = no

[health]
    enabled = no

[web]
    bind to = localhost

[plugins]
    # 极端 IoT 场景可另行评估是否禁用新外部插件
    # enable running new plugins = no

这是资源与容错的取舍，不是所有生产系统的默认答案。RAM 数据会受进程或主机重启影响，20 分钟也无法覆盖很长维护窗口。原文建议 Children 不直接连 Cloud，以减少生产节点负担；需根据实际运维需求验证。

传输加密：不要忽略证书校验

官方连接页给出自签名证书演示，目的地后加 :SSL，使用 ssl skip certificate verification = yes 接受未受信任证书。该后缀为 Netdata 自己的二进制 TCP 流协议启用 TLS，并不是把它变成 HTTPS。

静态审核发现：跳过证书校验会削弱对端身份验证。本文不把该演示设为生产推荐配置。生产应按 官方安全文档配置受信证书、匹配主机名与信任链，并保留证书校验；也不要把 19999 端口直接无控制地开放到公网。原文示例中的 203.0.113.0 和固定 UUID 为演示值，需替换为真实部署的受控地址与独立随机密钥。

历史复制能补什么，不能补什么

Child 重连 Parent 后，历史复制自动启动，Parent 间也使用相同机制。多级链路按顺序推进：连接先建立；一个连接对在接收端完成复制后，再启动发送侧复制；补到当前时刻后进入实时流。双方协商保留范围，尽量补齐可用数据。

当前机制针对短时断连优化，有三个重要限制：

1. 只追加时间序列末尾缺失的样本。它不能任意回填已经存在后续数据的历史中间空洞。
2. 只复制 tier0。高层 tier 是由 tier0 派生，不支持直接摄入。因此实际能回溯多远，受发送端 tier0 仍保存多少数据限制。
3. 只复制当前活跃采集的指标。归档指标或节点要等再次采集时才进入复制；文档默认在停止采集 1 小时后归档。

这也是为何 Parent 长时间停机之后，直接让历史很短的 Children 抢先连接回来可能形成无法补齐的历史缺口。成功建立 TCP 或指标流连接，只能证明连接存在，不能证明历史已经完整同步。

若维护超过一小时，可以评估增大 cleanup obsolete charts after；在大量短命指标的动态环境中，这会占用更多内存。线程数增加也要结合 CPU、磁盘与网络瓶颈评估，本文没有测量吞吐。

维护后先完成 Parent 回同步

把离线很久的 Parent 恢复上线前，先检查剩余 Parents 是否保留足够 tier0 历史，以及接收端 replication period 是否覆盖缺口。如果 Children 的历史不足，暂时阻止它们连接恢复节点，让该节点先从其他 Parent 补数据。

官方给出两种隔离方法：用防火墙阻止 Children 地址范围访问恢复 Parent 的 19999 端口，但保留 Parent 间访问；或者在 stream.conf 使用不同的 Child 和 Parent 密钥，恢复期间只禁用 Child 对应接收段。

下面是编辑根据官方“分离密钥”建议补出的配置变化。它与前面的原例不同，未在本次环境执行。两个随机密钥必须分别生成并安全分发；省略地址仍需替换：

# Parent 1
[stream]
    enabled = yes
    destination = PARENT_2_HOSTNAME_OR_IP:19999
    api key = PARENT_SYNC_KEY

[PARENT_SYNC_KEY]
    enabled = yes

[CHILD_STREAM_KEY]
    enabled = no
    # 恢复期间暂时关闭；同步完成后改回 yes

Parent 2 的发送密钥同样使用 PARENT_SYNC_KEY，接收段允许该密钥及 CHILD_STREAM_KEY；Children 发送使用 CHILD_STREAM_KEY。恢复 Parent 的 CHILD_STREAM_KEY 段设 no 只为暂时阻止 Child 接入。确认回同步完成后再启用，并复查连接、复制进度和查询结果。TLS 与网络访问限制仍需额外正确配置，密钥分离本身并不会加密链路。

从现有 Parent 创建新节点：先配置保留，再启动

官方指出可通过 rsync 复制 /var/cache/netdata，快速建立有历史数据的新 Parent。但如果新 Parent 以默认容量限制启动，可能立即删除刚复制的数据。必须先把目标 netdata.conf 的保留配置调整到与源节点相匹配，再启动。

编辑补充：原文未给出可保证在线复制一致性的 rsync 命令，本文也不编造。复制前要按实际版本确认一致性/停机或快照流程、目录属主和空间，避免复制凭据及不相关身份文件。没有把“文件复制完成”当成完整性验证结论。

分层存储样例

官方配置样例以 10 个 Children、每个约 2,000 条指标为例，说明 1 秒一周、1 分钟一月、1 小时一年三层保留。给出的资源参考为总磁盘 25GB、常见 RAM 3.5GB（内存压力下约 2.5GB），不是对任意指标量的保证。每层同时受容量和时间限制，哪个先到就以哪个为准：

[db]
    db = dbengine
    dbengine tier backfill = new
    storage tiers = 3
    dbengine page cache size = 1.4GiB

    update every = 1
    dbengine tier 0 retention size = 12GiB
    dbengine tier 0 retention time = 7d

    dbengine tier 1 update every iterations = 60
    dbengine tier 1 retention size = 4GiB
    dbengine tier 1 retention time = 1mo

    dbengine tier 2 update every iterations = 60
    dbengine tier 2 retention size = 2GiB
    dbengine tier 2 retention time = 1y

Parents 保留机器学习与告警默认开启。样例里的仪表盘绑定可能允许远程访问；应结合官方安全文档与网络策略限制访问。更高 tier 的一年保留并不意味着可把一年历史作为 tier0 跨节点回放。

检查连接与回同步进度

当前连接设置页没有给出一行通用于所有版本的“成功连接”日志内容，因此本文不捏造成功输出。可以在 UI 的 Logs 中检查 MESSAGE_ID 对应的 Netdata connection from child 和 Netdata connection to parent；或在使用该 journald namespace 的系统上查询：

# Parent：接收 Child 的连接记录
journalctl -r --namespace=netdata MESSAGE_ID=ed4cdb8f1beb4ad3b57cb3cae2d162fa

# Child：向 Parent 的连接记录
journalctl -r --namespace=netdata MESSAGE_ID=6e2e3839067648968b646045dbf28d66

结合日志里的连接状态、失败原因和实际目的地确认链路，不把“有日志”当成成功。历史复制进度可在 Live 选项卡中的 Netdata-streaming Function 查看，也可读取 Parents 和 Children 的 http://agent-ip:19999/api/v2/node_instances。API 地址是原文示意，实际读取应放在可信网络或已有的受保护管理通道。

在解除维护隔离前，核对回同步已完成、目标数据时间范围符合预期，并确认 Child 已回到期望的目的地。还应按实际负载规划 Parent 资源、保留周期、主机标签和安全配置。持续可见性来自健康副本与正确配置，不能简化为“填两个地址就永不丢数据”。

合并来源：Configuration Examples、Replication of Past Samples、Configuring Metrics Centralization Points。均为 Netdata 官方文档。

来源与归属：Netdata 官方文档维护者（原页未署个人作者）；中文译编：未完纪编辑部。阅读原文。全文翻译、转载及配图按权利人授权使用；原作者及项目归属保留。