配置 Netdata Parent 与 Child 指标集中采集并排查连接-未完纪

Netdata Parent 并不是另一种专用服务端软件。它仍然是普通 Netdata Agent，只是启用了接收其他 Agent 指标流的配置。业务机器上的 Child 继续采集指标，Parent 负责集中保存和展示；在需要时，Parent 也可以把数据继续送往上一级。

本文根据 Netdata 官方的 Parent 部署说明与指标集中采集配置页合并整理，覆盖双方配置、TLS、应用变更、看板访问和日志排查。范围是已经安装的 Agent，集群高可用拓扑和容量调优只交代边界，不展开为部署教程。核对日期为 2026 年 10 月 5 日；两页分别标注更新于 2026 年 8 月 12 日与 8 月 15 日，本次没有执行配置或重启。

Parent/Child 的指标与排障路径。原创技术示意图，未完纪整理。

先分清指标方向与配置位置

Streaming 传输实时样本，Replication 补充近期历史样本，Parent 根据保留策略存储这些数据。一个 Child 同一时间只连接一个 Parent；配置多个目的地址时，选择其中可用的一个，并不意味着 Child 同时向所有 Parent 发送。Parent 可以接收多个 Child，也可把收到的数据再转发，形成层级。

默认完整模式的 Child 仍可运行本地机器学习、告警、通知和看板。Thin 模式主要负责采集与转发，保留少量本地数据以应对连接中断。Parent 可以是独立节点、向上转发的 Proxy，或高可用集群的一部分；是否压缩 Child 功能、集中保留多少数据，取决于故障期间仍需保留的观测能力。

双方都使用 INI 格式的 stream.conf：

[stream] 控制发送方向。Child 使用它，向更高层发送的 Parent 也使用它。
以 API key 为段名的配置控制接收方向。Parent 通过这些段接受持有相同 key 的 Child。

stream.conf 含有通信凭据、IP 等敏感配置，不能像普通示例文件一样随意分享。原页明确区分了它与通常被视为非敏感配置的 netdata.conf；后者在实际环境中也应检查是否包含不宜公开的信息。

编辑正确的配置文件

原指南通过随安装提供的 edit-config 编辑配置。为避免两个安装目录都不存在时继续在错误目录操作，下面把原来的目录回退片段改成显式成功检查；这是整理版增加的错误处理。

if cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata; then
    sudo ./edit-config stream.conf
else
    printf '%s\n' '未找到 Netdata 配置目录' >&2
    exit 1
fi

如果 Agent 在 Docker 容器中，原文先进入目标容器，再编辑容器内配置：

docker exec -it netdata bash
cd /etc/netdata && ./edit-config stream.conf

netdata 是示例容器名，必须对应实际目标。Parent 使用标准 netdata/netdata 镜像，不需要“Parent 专用镜像”或特别开关。部署页指出，配置、数据库与缓存卷应持久化，以保留重启后的设置和指标；这里只调整现有容器，不重新展开 Docker 安装参数。

在 Parent 上建立接收身份

按原文使用 uuidgen 生成新的随机 UUID，作为此连接配置的 API key。不要采用文档里的固定示例 UUID，也不要把这个 key 与 Netdata Cloud 的其他令牌混为一谈。

uuidgen

将同一个实际生成值填入 Parent 的段名与 Child 的 api key。下面的 REPLACE_WITH_GENERATED_UUID 明确是待替换字段；203.0.113.10 是文档演示地址，应换成 Parent 实际看到的 Child 出站地址。若经过 NAT，需按连接到达 Parent 时的地址设置。

[REPLACE_WITH_GENERATED_UUID]
    type = api
    enabled = yes
    allow from = 203.0.113.10

最小原例只有 enabled = yes。上面的 type = api 与 allow from 来自官方 Parent-Child 参考页，是本稿标明的补充：显式表明段类型，并将接收来源缩小为预期机器。不要把 allow from = * 作为无需考虑的通用生产设置；key 也应受控保存和轮换。

在 Child 上指定 Parent

基本连接只需要启用发送、指定目的地址和匹配的 API key。下面忠实保留原指南的明文基础片段，用来解释字段；如果连接跨越不可信网络，应使用下一节的 TLS 配置。

[stream]
    enabled = yes
    destination = PARENT_HOSTNAME_OR_IP:19999
    api key = REPLACE_WITH_GENERATED_UUID

目的地址可以是主机名、FQDN 或 IP。19999 是默认端口；如果 Parent 改了监听端口，Child 必须一致。配置保存后，要让 Parent 与 Child 都重新载入配置；原文要求重启 Agent。systemd 安装可使用 sudo systemctl restart netdata，Docker 安装可使用 docker restart netdata。这些操作会短暂中断采集或连接，应按目标机器的维护流程执行。

TLS 要同时考虑加密、证书信任与接收策略

原配置页的 TLS 示例使用自签名证书，并设置 ssl skip certificate verification = yes。它能演示加密传输，却关闭了用于确认对端身份的证书验证，不能当作生产安全配置。参考页还把该字段的默认值列为 yes，因此只加 :SSL 并不足以表达“严格验证证书”。

与原 TLS 示例的差异：下面显式设置 no，并通过 CAfile 指向经过管理的信任 CA 文件。主机名、CA 路径与 UUID 都必须替换成实际值；证书应覆盖所用主机名，完整证书链必须可验证。不要把证书错误通过重新设置 yes 长期绕过去。

[stream]
    enabled = yes
    destination = parent.example.internal:19999:SSL
    api key = REPLACE_WITH_GENERATED_UUID
    ssl skip certificate verification = no
    CAfile = /etc/netdata/ssl/stream-ca.pem

:SSL 表示为 Netdata 的 TCP 流式协议加上 TLS。它不是把指标发送地址换成一个普通 HTTPS 网页，也不是让任意 HTTP 反向代理天然理解流式协议。目的地址写成 主机:端口:SSL 的形式来自官方参考页。

Parent 一侧需在 netdata.conf 的 [web] 中配置证书与私钥：

[web]
    ssl key = /etc/netdata/ssl/privkey.pem
    ssl certificate = /etc/netdata/ssl/fullchain.pem

这些文件必须能被 Netdata 服务用户读取，同时私钥权限应限制为所需主体。Web Server 参考页提醒，证书缺失或不可读可能回退到 HTTP，而且仅配置证书时，接收端仍允许加密和未加密的流。若要求所有 Child 强制使用 TLS，必须在合适监听端点的 bind to 策略中使用 ^SSL=force，并验证现有看板和其他服务的监听边界；本文不提供会覆盖既有监听设置的通配配置。

修改双方 TLS 配置后重新启动，并检查日志，确认实际使用了预期连接。源页的 OpenSSL 自签名例仅适合试验；本稿没有生成证书、读取私钥或测试握手。

应用变更后，从 Parent 看板核对结果

Parent 收到 Child 指标后，内置看板可以查看连接节点的指标、自定义仪表板和告警。部署页用 http://parent-ip:19999 示范入口；启用 TLS 后应按实际入口访问，不应为了方便把 19999 直接开放到公网。远程访问可以使用受控网络或按官方指南配置的访问入口，并单独控制看板/API 与指标流的可达范围。

部署页说明，部分非敏感功能支持匿名访问，进程与网络连接等敏感功能需要登录 Netdata Cloud；这些权限行为应以使用版本和当前服务设置为准。将 Parent 连接到 Cloud 会自动登记其连接的 Child，并提供跨 Parent 的统一视图等能力；这属于另一个可选择的账号操作，不是完成本地指标汇聚的前提。

验收时选择一个已知 Child，核对节点身份、图表时间和最近样本是否持续推进，而不只是看“连接过一次”。确认原有本地保留与告警策略符合预期，再逐步接入更多节点。Parent 的存储、内存和处理能力应按接入量及保留时间规划；本文没有测量其容量。

把连接日志的两端对应起来

配置页以 systemd-journald 作为当前默认日志路径。在 UI 的 Logs 页，通过 MESSAGE_ID 查找 Netdata connection from child 或 Netdata connection to parent。终端上可使用原文给出的两个不同消息标识，按最近日志倒序读取：

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

# Child：连接 Parent
journalctl -r --namespace=netdata MESSAGE_ID=6e2e3839067648968b646045dbf28d66

这里的十六进制串是日志消息类别，不是 API key。若环境没有对应 journal namespace，应先确认 Agent 的日志后端与权限；不能把空结果当作没有连接错误。部分较旧参考示例仍展示 /var/log/netdata/error.log，应以实际部署配置为准。

观察到的情况	优先核对
Child 不断重连，Parent 没有接收记录	主机名解析、路由、防火墙、端口和 Parent 是否在预期接口监听
Parent 接收后立即拒绝	双方 key 是否完全一致，接收段是否启用，Child 到达地址是否被 allow from 或更高优先级访问规则拒绝
TLS 或“不是 Netdata”类协议错误	是否连到正确服务，:SSL 是否匹配，证书链、信任 CA、主机名和期限是否正确，代理是否改变了连接
连接建立但图表不更新	发送过滤、Child 实际采集状态、历史复制和保留设置、节点时间；不要直接推定为 API key 问题

不要把完整 stream.conf 或包含 key 的日志复制进公共工单。先保留故障时间和双方节点对应关系，再对凭据做脱敏；如果 key 已泄露，需要按范围更换。排障时放宽网络或关闭证书校验可能暂时改变症状，也会改变安全边界，不能拿它代替原因定位。

出处与审查范围

维护与发布方：Netdata。原页未见可确认的个人作者，本文不补造个人署名。中文翻译整理、显式标注的配置加固与原创图：未完纪。来源页未另行声明独立文章许可。

静态审核已核对方向、字段、端口、API key、TLS 和日志 ID；补充改动包括目录失败即停止、接收来源限制及严格证书校验。没有执行任何安装、配置、重启、握手或指标查询，也没有声明本稿可直接覆盖现有生产配置。未见真实硬编码秘密不意味着完整部署不存在漏洞。

Parent 与 Child 的补充功能对照

原部署页的功能表说明：Child 可用 ram 或 alloc 模式保留少量本地指标；机器学习、告警通知、API 与看板都可关闭，但默认开启；指标导出也是可选且默认开启。Parent 按自身保留设置保存所有相连系统的指标，执行异常检测、健康监控、告警和导出，并提供看板。Netdata Functions 请求由 Parent 转发，目标 Child 必须在线。Child 本身无需连接 Cloud；将 Parent 接入 Cloud 会登记相连节点。

连接 Cloud 后可以获得多 Parent 统一视图；原文将移动告警通知标为付费套餐功能，并说明多 Parent 评估同一 Child 时可以去重通知，实际权益仍需按所用服务核验。独立 Parent、Proxy 与 Cluster 是不同拓扑：Proxy 保存数据后继续向上转发；集群由相互作为 Parent 的循环 Proxy 组成，多级结构中只允许最顶层配置为集群。具体故障转移、维护和容量规划需查对应指南，本文未部署这些拓扑。

文章版权归作者所有，未经允许请勿转载。

THE END