Netdata —— 秒级采集、零配置大盘、Parent 集中与健康告警的分布式可观测代理

分类：03 一体化监控平台 适用：Linux/FreeBSD/macOS 物理机、虚机、云主机、容器宿主机、边缘与 IoT；单机排障到数千节点（Parent 分层） 一句话：每台机器装一个 Agent，1 秒粒度自动发现指标、自带 Web 大盘、就地判定健康告警，再用 Parent 汇聚成统一视图 官方：https://www.netdata.cloud/ ｜ https://github.com/netdata/netdata ｜ https://learn.netdata.cloud/ 授权：Agent 开源（GPLv3+），可完全离线；Netdata Cloud 为商业 SaaS / 私有化控制面，按节点订阅

1. 它解决什么问题

不擅长：年级合规归档与复杂 PromQL 多维聚合（配 VictoriaMetrics/Thanos）、日志全文检索与链路追踪（仅轻量日志关联）、以业务 SLO / 自定义 PromQL 为核心的场景。

2. 核心概念与架构

2.1 术语表

2.2 组件与数据流

 /proc /sys /应用端点 ─▶ collectors（proc/go.d/apps/statsd，每秒采集·自动发现）
                              ▼
 ┌───────────────── 单节点 Agent ─────────────────┐
 │ database（dbengine: tier0秒→tier1分→tier2时）    │
 │  ├─▶ Web/API :19999（大盘 + /api/v1）           │
 │  ├─▶ health（health.d + reload-health）─────────│──▶ alarm-notify ──▶ 通知
 │  └─▶ ML 异常检测（可关）                        │
 └─────────────────────┬──────────────────────────┘
                       │ streaming：stream.conf / tcp:19999 / api key 鉴权
 Child A/B/N ──────────┴──▶ Parent（汇聚存储·统一大盘·集中告警）
   （Child 可设 [db] mode=ram 近无状态）  ─▶ 浏览器 / 二级 Parent / Cloud

1. collectors → database：按 update every（默认 1s）取数写本地 dbengine，采集与存储同进程，无外部 TSDB 依赖。
2. database → health → Web：健康引擎按 health.d 规则与 ML 模型判定状态；Web 直接读本地引擎渲染大盘并暴露 /api/v1/*、/netdata.conf。
3. Child → Parent / 与中心解耦：Child 实时复制指标到 Parent（[<UUID>] 段接受落盘），浏览器只看 Parent 即可纵览全簇；任何中心节点宕机，Child 本地大盘与告警仍可用——区别于"中心轮询式"监控的关键。

3. 安装与部署

版本一律 以官方最新稳定版为准（https://github.com/netdata/netdata/releases）。下列 URL、镜像名与端口均来自官方安装文档；<xxx> 为占位符；不确定参数先 sh /tmp/netdata-kickstart.sh --help。

3.1 环境准备

3.2 多种安装方式

方式 A：官方一键脚本（推荐）

wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh \
  && sh /tmp/netdata-kickstart.sh --stable-channel --disable-telemetry
# 等价历史入口：bash <(curl -Ss https://my-netdata.io/kickstart.sh)
sh /tmp/netdata-kickstart.sh --help   # 离线/认领/不自动启动等参数以 --help 为准

方式 B：Docker run（单机试跑 / 容器宿主机）

docker run -d --name=netdata -p 19999:19999 \
  -v netdataconfig:/etc/netdata -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /etc/passwd:/host/etc/passwd:ro -v /etc/group:/host/etc/group:ro \
  -v /proc:/host/proc:ro -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  --restart unless-stopped --cap-add SYS_PTRACE \
  --security-opt apparmor=unconfined netdata/netdata

用 docker compose 时务必写死 hostname:，否则节点身份漂移、历史被打散；compose 其余挂载与环境变量同方式 B（NETDATA_LISTENER_PORT、DISABLE_TELEMETRY）。

方式 C：发行版包 / 静态二进制 + systemd（离线、信创首选）

sudo apt-get install -y netdata        # Debian/Ubuntu；RHEL/Rocky 用 dnf（必要时启 EPEL）
tar xzf netdata-<version>-linux-<arch>.tar.gz -C /opt/   # 静态二进制解压即用
sudo systemctl enable --now netdata
sudo touch /etc/netdata/.opt-out-from-anonymous-statistics   # 关闭遥测

气隙集中化：内网部署 Parent（见场景二）或 Netdata Cloud On-Prem，不依赖公网 SaaS。

3.3 首次启动与验证

sudo systemctl enable --now netdata && sudo systemctl status netdata
curl -fsS http://127.0.0.1:19999/api/v1/info | grep -o '"version":"[^"]*"'  # 健康检查
curl -fsS http://127.0.0.1:19999/netdata.conf | grep -E 'config directory|health config'
sudo netdatacli ping && sudo tail -n 30 /var/log/netdata/error.log
# 浏览器打开 http://<节点IP>:19999，左上角出现 hostname 与实时图表即成功

4. 配置文件详解

4.1 路径与关键项

版本差异：配置键随版本迁移（如 [global] memory mode → [db] mode、tier 参数按 tier 命名）。不确定的键先访问 http://<节点>:19999/netdata.conf 看本机生效项再照抄，以官方文档为准。

4.2 完整可运行最小示例

# /etc/netdata/netdata.conf —— 用 `sudo ./edit-config netdata.conf` 写入
[global]
    hostname = <node-01>
    update every = 1
[db]
    mode = dbengine
    dbengine tier 0 disk space MB = 512
[web]
    bind to = 127.0.0.1 localhost
    default port = 19999
[ml]
    enabled = no
[health]
    enabled = yes

sudo systemctl restart netdata
curl -fsS http://127.0.0.1:19999/netdata.conf | grep -E 'hostname|update every|mode ='

5. 核心使用方法（CLI / HTTP API / Web UI）

5.1 命令与操作速览（≥20 条）

5.2 /api/v1 查询示例

BASE=http://127.0.0.1:19999
curl -fsS "$BASE/api/v1/info" | jq '.version, .mirrored_hosts'
curl -fsS "$BASE/api/v1/data?chart=system.cpu&after=-300&points=60&group=average&format=json" | jq '.data[0:3]'
curl -fsS "$BASE/api/v1/alarms?all" | jq 'to_entries[] | {chart:.key, status:.value.status}'
curl -fsS "$BASE/api/v1/allmetrics?format=prometheus" | grep '^netdata_' | head

5.3 health.d 告警配置（自定义 / 覆盖内置）

# /etc/netdata/health.d/user_ram.conf —— 用 edit-config 创建；同名 template 覆盖全局阈值
template: 10min_ram_available
      on: system.ram
   class: Utilization
    type: System
   component: Memory
  lookup: average -10m unaligned of available
   units: MiB
   every: 1m
    warn: $this < (($status >= $WARNING) ? 300 : 200)
    crit: $this < (($status >= $CRITICAL) ? 150 : 100)
   delay: down 5m multiplier 1.5 max 1h
    info: 可用内存持续低于阈值，注意 OOM 风险
      to: sysadmin

sudo netdatacli reload-health                                    # 热加载
curl -fsS http://127.0.0.1:19999/api/v1/alarms?all | jq '.["system.ram"]'
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test   # 路径随安装方式变化，以本机为准

关闭吵闹告警：Web UI Alerts 面板对单条 Disable，或把该规则 to: 设为 silent；勿改内置 stock 目录。

6. 告警与通知

6.1 阈值与规则要点

alarm 作用于单 chart、template 作用于同 context 全部实例；lookup 取值（如 average -10m unaligned of available、sum、max）；warn/crit 支持 $this、$status、$WARNING 滞回表达式抑制抖动；delay/repeat 控制延迟与重发；to: 指定接收角色（silent 关闭单条）。ML 异常带与静态阈值并行，可在 UI 查看。

6.2 通知渠道（health_alarm_notify.conf）

# 用 `cd /etc/netdata && sudo ./edit-config health_alarm_notify.conf` 编辑
SEND_EMAIL="YES"
DEFAULT_RECIPIENT_EMAIL="ops@<example.com>"
# 企业微信/钉钉/飞书机器人：官方未内置专用变量时统一走 Webhook/自定义脚本
SEND_WEBHOOK="YES"
WEBHOOK_URL="https://<企业微信或钉钉机器人 webhook>"
DEFAULT_RECIPIENT_WEBHOOK="alerts"
# Slack/Telegram/ntfy 等按文件内 SEND_<CHANNEL> 开关同理

sudo systemctl restart netdata
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test   # warning/critical/clear 各一条

⚠️ Webhook / Token 属敏感信息：chmod 640、属主 netdata，勿入 Git。渠道变量名以本机 health_alarm_notify.conf 注释为准（不同版本渠道集合有增删）。

6.3 静默与升级

7. 实战场景

场景一：单机秒级排障（定位瞬时 CPU 尖峰）

• 目标：抓住每日偶发 3~5 秒 CPU 毛刺并留证。
• 步骤：一键安装 → 确认 1s 粒度 → /api/v1/data 导出窗口 → UI 关联进程/日志。

wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh \
  && sh /tmp/netdata-kickstart.sh --stable-channel --disable-telemetry
curl -fsS "http://127.0.0.1:19999/api/v1/data?chart=system.cpu&after=-600&points=600&group=max&format=csv" > /tmp/cpu-spike.csv
# head /tmp/cpu-spike.csv 应有 600 行；Web UI 拖到尖峰点看 apps.plugin 按进程 CPU 与 journal 日志

• 验证：CSV 有 600 行；UI 悬停可见秒级峰值与对应进程。
• 回滚：sudo systemctl stop netdata && sudo systemctl disable netdata；⚠️ 卸载前 tar czf netdata-backup.tgz /etc/netdata /var/lib/netdata 备份。

场景二：Parent 汇聚 20 台 Child，统一大盘且 Child 近无状态

• 目标：只开放 Parent 的 19999，历史集中、Child 极轻。
• 步骤：Parent 生成 UUID 授权 → Child 配 stream.conf 推送 → Child 设 ram。

# 两端先 `uuidgen` 得 <UUID> 并 `sudo ./edit-config stream.conf`；`allow from` 生产应收紧网段
# Parent：/etc/netdata/stream.conf
[<UUID>]
    enabled = yes
    default memory mode = dbengine
    health enabled by default = auto
    allow from = *

# 每个 Child：/etc/netdata/stream.conf
[stream]
    enabled = yes
    destination = tcp:<PARENT_IP>:19999
    api key = <UUID>
    default memory mode = ram
    health enabled by default = no

sudo ufw allow from <CHILD_CIDR> to any port 19999 proto tcp   # Parent 侧
sudo systemctl restart netdata                                  # 两端都执行
curl -fsS http://<PARENT_IP>:19999/api/v1/info | jq '.mirrored_hosts'

• 验证：http://<PARENT_IP>:19999 节点下拉框出现全部 Child；mirrored_hosts 列出节点。
• 回滚：注释 Child 的 [stream] 并改回 dbengine 重启即恢复独立存储；⚠️ 先确认 Parent 已落盘再删 Child 本地数据。

场景三：磁盘将满告警推送到企业微信 / 钉钉机器人

• 目标：根分区使用率超阈值告警到 IM。
• 步骤：覆盖 health.d 磁盘规则 → 配 Webhook（见 6.2）→ 发测试 → 触发验证。

# /etc/netdata/health.d/disk_space.conf —— 同名 template 覆盖内置阈值
template: disk_fill_rate
      on: disk.space
   lookup: max -1m unaligned of used
   units: %
   every: 1m
    warn: $this > 80
    crit: $this > 90
      to: sysadmin

sudo netdatacli reload-health
sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test
curl -fsS 'http://127.0.0.1:19999/api/v1/alarms?all' | jq '.[] | select(.status=="CRITICAL")'

• 验证：群里收到测试与真实告警，API 可见 CRITICAL 状态。
• 回滚：to: silent 或 SEND_WEBHOOK="NO" → netdatacli reload-health；删除用户 health.d 文件即恢复内置阈值。

8. 日常运维与故障排查

故障「现象 → 原因 → 处置」表

9. 性能、容量与高可用

10. 安全加固、备份与升级

11. 常见坑（现象 → 原因 → 解决）

12. 速查表

13. 选型建议与同类对比

何时选：需要秒级排障、单机/容器宿主机装完即看、边缘或气隙环境要求本地自治、不想维护独立 TSDB 集群、希望零配置大盘与开箱告警。

何时不选：需要年级合规归档与复杂 PromQL 多维聚合（选 Prometheus + VictoriaMetrics/Thanos）、以 SNMP 网络设备与模板化资产为核心（选 Zabbix）、需要日志/链路统一平台（配 Loki/Tempo 或选夜莺等一体化观测平台）、需要成熟多级值班升级与工单闭环（Zabbix/夜莺/Alertmanager）。

常见互补：Netdata 负责"单机秒级现场"，把 /api/v1/allmetrics?format=prometheus 或 Parent 数据远程写入 VictoriaMetrics，再用 Grafana 做长期看板。

14. 参考链接

• 官网与开源 Agent：https://www.netdata.cloud/
• GitHub 仓库：https://github.com/netdata/netdata
• 官方文档 Learn：https://learn.netdata.cloud/docs/
• Docker 安装文档：https://learn.netdata.cloud/docs/netdata-agent/installation/docker
• 官方安装脚本：https://get.netdata.cloud/kickstart.sh
• Releases（版本号以官方最新稳定版为准）：https://github.com/netdata/netdata/releases