nodedata — 单机性能展示与百台巡视
把一台 Linux 机器的现状、跟平时比的变化、谁在用资源摆在一屏里,让人自己看出问题。
给出错的推理不如不给推理:它只摆事实和"先看哪儿",不替你下结论。
两个程序,都是单个静态二进制,零依赖,只读 /proc 和 /sys:
| 程序 |
跑在哪 |
默认端口 |
干什么 |
nodedata |
每台被看的机器 |
8888 |
采集、判定、单机页面 |
nodedata-pelican |
一台巡视台机器 |
8776 |
拉各台的状态挂墙看:天空视图(机群是一座城,鹈鹕飞过去照住出问题的机器)和方块列表视图 |
更细的设计和取舍见 DESIGN.md,每版改了什么见 CHANGELOG.md。
源码里另有 nodedata-fleet(只有方块列表的巡视台)和 faultlab(在实验机上制造故障做验收),不进发布包,要用见 §7。
1. 装
从 GitHub Releases 下载 nodedata-vX.Y.Z-linux.tar.gz,解压出来是一个同名目录(不会覆盖当前目录里的文件):
tar xzf nodedata-v7.2.0-linux.tar.gz
cd nodedata-v7.2.0
sha256sum -c SHA256SUMS # 校验
sudo install -m 755 nodedata-linux-amd64 /usr/local/bin/nodedata # ARM 用 -arm64
sudo install -m 755 nodedata-pelican-linux-amd64 /usr/local/bin/nodedata-pelican # 只在巡视台机器上装
nodedata version
从旧版升级的巡视台:以前装过的 /usr/local/bin/nodedata-fleet 不会再更新,换成 nodedata-pelican(同一份 host.list,§4)后可以删掉。
2. 单机:nodedata
# 先试:只本机能看,前台跑,Ctrl-C 停
nodedata serve --data-dir ./data
# 浏览器开 http://127.0.0.1:8888/
# 给别人/巡视台看:对内网开放(记得用防火墙只放行该放行的来源)
nodedata serve --listen 0.0.0.0 --port 8888 --data-dir /var/lib/nodedata
# 带资源硬上限跑(CPU 最多 0.2 核、内存 300M、IO 让路;重启机器后消失)
sudo systemd-run --unit=nodedata -p CPUQuota=20% -p MemoryMax=300M -p Nice=10 \
-p IOSchedulingClass=idle -p Restart=always --setenv=GOMAXPROCS=1 --setenv=GOMEMLIMIT=200MiB \
/usr/local/bin/nodedata serve --listen 0.0.0.0 --data-dir /var/lib/nodedata
systemctl status nodedata # 状态
journalctl -u nodedata -f # 日志
sudo systemctl stop nodedata # 停
开机自启:存成 /etc/systemd/system/nodedata.service,再 sudo systemctl daemon-reload && sudo systemctl enable --now nodedata。
[Unit]
Description=nodedata
After=network.target
[Service]
ExecStart=/usr/local/bin/nodedata serve --listen 0.0.0.0 --port 8888 --data-dir /var/lib/nodedata
Restart=always
RestartSec=5
CPUQuota=20%
MemoryMax=300M
Nice=10
IOSchedulingClass=idle
Environment=GOMAXPROCS=1
Environment=GOMEMLIMIT=200MiB
[Install]
WantedBy=multi-user.target
CentOS 7/8(cgroup v1)上 MemoryMax 不生效,换成 MemoryLimit=300M。
参数
| 参数 |
默认 |
说明 |
--listen |
127.0.0.1 |
监听地址。页面里有进程名和 PID,开放前先想好谁能访问 |
--port |
8888 |
|
--data-dir |
./data |
历史(history/)、事故留证(incidents/)都在这里;升级、重启不会丢 |
--history-dir |
<data-dir>/history |
长期历史:5 分钟一点,保留 14 天 |
--interval |
10s |
采集周期,至少 1s;写错直接报错退出 |
--rootfs |
/ |
要看容量的挂载点 |
--dump-interval |
0 |
把页面数据转储成文件;0 = 不转储,否则至少 1s |
--allow-host |
空 |
除 IP、localhost、本机主机名之外还认哪些 Host 头(防 DNS 重绑定,见 §8);可重复或逗号分隔,*.example.com 认子域,* 关闭检查 |
不开浏览器也能看
curl -s localhost:8888/health.txt # 一行,给监控 grep
curl -s localhost:8888/api/report # 纯文本简报,可以直接贴给大模型
curl -s localhost:8888/api/use # USE 五行(JSON)
curl -s localhost:8888/api/fleet # 巡视台拉的就是这个
curl -s localhost:8888/api/cores # 逐核 CPU
curl -s localhost:8888/api/outbound # 出站连接异常:矿池黑名单、长连接、重连风暴、陌生进程
矿池黑名单(可选)
/api/outbound 的四类判定里,只有 blacklist 会折进 /health.txt(命中 → DOWN,带
culprit=进程名/PID)。它读 Stratum-black.iplist,一行一个 IP 或 CIDR,# 开头或
行内 # 之后都是注释:
sudo mkdir -p /etc/nodedata && sudo tee /etc/nodedata/Stratum-black.iplist >/dev/null <<'EOF'
# 已知矿池 / C2
198.51.100.7
203.0.113.0/24 # 行内注释也可以
EOF
查找顺序是 /etc/nodedata/ 优先,找不到再退回可执行文件同目录(v7.1.0 及以前只有
后者,照旧配好的机器升级后照常命中,不必搬)。文件不存在不算错误。
出站豁免名单(可选)
另外三类判定(长连接、重连风暴、陌生进程)是行为类线索:它们不依赖黑名单、也不进
health(行为类会误报,不拿它判死一台机器),只在 /api/outbound 和页面上可见。内置的
豁免表只认得大机房里普遍跑的东西,机房自己的东西(自研推送 agent、商业备份客户端、
常年挂一条公网长连接的业务进程)要靠 outbound-allow.list 补,查找路径同上:
sudo tee /etc/nodedata/outbound-allow.list >/dev/null <<'EOF'
my-push-agent # 解析不通 → 当进程名(exe 名,不是路径)
203.0.113.0/24 # 解析得通 → 当目的地网段
198.51.100.7 # 单个地址同理
EOF
命中只压掉那三类行为判定,黑名单不受影响——不给运维留一个能静默关掉检测的开关。
接进现有监控
有 Prometheus 就抓 /metrics(文本格式 0.0.4,零依赖手写,不引 client_golang):
curl -s http://127.0.0.1:8888/metrics | head -20
scrape_configs:
- job_name: nodedata
static_configs:
- targets: ['db-01:8888', 'db-02:8888']
导出的是注册表里登记过的全部基础指标(nodedata_cpu_busy_percent、
nodedata_mem_available_bytes、nodedata_disk_util_percent{device="sda"}……)、
USE 五行的级别、出站扫描的异常条数,再加一组自监控。几条约定值得先知道:
- 采不到的不写成 0。 超过 2 分钟没更新的点、没登记的指标、
proc.*(进程名无界,
进标签就是高基数)都不导出,条数记在 nodedata_metrics_skipped{reason} 里。
没测到的东西在告警规则里用 absent() 抓,别拿 == 0 判。
- 死人开关比写死的阈值好。
nodedata_newest_sample_timestamp_seconds 停着不走
= 采集循环卡了。阈值用同样导出的 nodedata_collector_interval_seconds 算,
现场改 -interval 不用再回头改告警规则。
nodedata_use_level 是 -1/0/1/2:-1 无数据 / 0 正常 / 1 偏离 / 2 异常,
跟页面和巡视台同一套编码。
- 巡视台(
nodedata-pelican)自己也有 /metrics,导出的是汇总:nodedata_fleet_*。
各台的明细从各台自己抓,不从巡视台转一手。
deploy/prometheus/ 下有现成的样例:13 条告警规则(节点 7 条、巡视台 6 条)、配套的
promtool 测试,和一份最小抓取配置。每条阈值都是拿进程自己导出的数算的,现场把
-interval / -lost-after 调大了,不用回头再改规则。规则和用例由 CI 跑
(.github/workflows/prom.yml,只在这个目录变了时触发),里面还有一步故意弄红的
反向对照 —— 不然用例写坏了 promtool test rules 照样报 SUCCESS。
没有 Prometheus,grep 一行也够:
curl -s http://127.0.0.1:8888/health.txt | grep -q '^NODEDATA .*status=NORMAL' || echo 告警
# NODEDATA host=db-01 status=WARN cpu=182% load=9.14 mem_avail=1.2GiB disk_util=96 net_drop=0 culprit=rsync/4411 reason="IO 劣化:..." ts=2026-09-12T03:10:51Z
status 是 NORMAL / NODATA / WARN / DOWN,跟页面 USE 五行和巡视台一致(取 L0 硬阈值、线索结论、USE 五行中最严重的):
某行偏离 → WARN,某行异常 → DOWN,某行采不到 → NODATA(采不到绝不当正常)。
不是 NORMAL 时一定带 reason=,指认了进程时带 culprit=(进程名/PID)。
cpu= 是各核之和(8 核满载 = 800%),页面上的"整机忙碌"是 0–100;ts= 是 UTC。
3. 状态怎么判
每台机器按 CPU / 内存 / 磁盘 / 网络 / 系统 五行给状态。大部分时间机器是正常的,所以第一目标是正常的机器不亮黄。
| 状态 |
什么时候 |
| 异常(红) |
绝对判定没过:只读挂载、分区满、OOM…… |
| 偏离(黄) |
① 往坏的方向变 + 变化显著 + 读数落在可能是瓶颈的区间,并持续 60 秒;或 ② 过了绝对线,持续 60 秒(不看历史) |
| 正常 |
其余。变化显著但不是问题的(比如变闲了)只标"高于/低于平时",不变色 |
| 无数据 |
采不到,绝不当正常 |
| 资源 |
瓶颈区间 |
绝对线 |
| CPU |
整机 ≥50%,单核 ≥60%,排队 > 核数,CPU 压力 ≥5%,被偷 ≥5% |
单核 ≥95%,CPU 压力 ≥20%,排队 > 2×核数 |
| 内存 |
已用 ≥80%,换页 ≥1MB/s,内存压力 ≥5%,主缺页 ≥100/s |
内存压力 ≥10%,换出 ≥10MB/s |
| 磁盘 |
IO 压力 ≥5%;延迟:机械盘 50ms / SSD 10ms / 虚拟盘 20ms |
IO 压力 ≥20% |
| 网络 |
丢包/错包 ≥1/s,TCP 重传 ≥10/s |
持续丢包/错包 |
数字的来历写在 cmd/nodedata/concern.go,要调就改那里。
4. 巡视台:nodedata-pelican
一台机器跑巡视台,去各台拉状态(只拉不推,各台不用知道巡视台在哪),iPad 挂墙看。
cp host.list.example host.list # 改成你的机器
nodedata-pelican -hosts host.list -listen 0.0.0.0
# iPad 打开 http://巡视台地址:8776/
nodedata-pelican -hosts host.list -listen 0.0.0.0 -port 9000 # 换端口
# 看拉取情况
curl -s localhost:8776/health.txt # ok hosts=100 ok=93 dev=4 bad=1 lost=2 none=0 last_round=3s
curl -s localhost:8776/api/state | head -c 500
curl -s localhost:8776/metrics # 给 Prometheus 的汇总(nodedata_fleet_*)
none 是"拉得到、但五行里有一行是无数据"的台数:那个资源一次都没被看过(接口在这台上读不到,
或者那台的 nodedata 太旧、根本没报这一行)。它单独一个数,不并进 ok —— 探不到不等于正常。
各台要做的只有:nodedata serve --listen 0.0.0.0,防火墙只放行巡视台的 IP。
上一次没拉到的机器(连不上、超时)在后台单独排队重试,不占正常机器的名额,也不拖慢这一轮:
几十台失联机器不会让其余机器的状态和"失联"判断跟着推迟。
| 参数 |
默认 |
说明 |
-hosts |
host.list |
主机清单,改了自动重读 |
-listen |
127.0.0.1 |
给 iPad 看要设 0.0.0.0 |
-port |
8776 |
|
-interval |
15s |
多久拉一轮 |
-timeout |
5s |
单台超时 |
-lost-after |
3 轮 |
多久没拉到算失联 |
-parallel |
32 |
同时拉几台 |
-allow-host |
空 |
同 nodedata 的 --allow-host:iPad 用域名打开巡视台时把域名加进来 |
多少台
一台巡视台按默认参数管到 1000 台:
- 内存:实测每台留 3KB 上下(五行、25 条已查项),1000 台约 3MB 常驻。
天花板是另一个数:单台响应上限 256KB,一台被改过的 nodedata 把形状顶满,
1000 台约 330MB —— 这是最坏情况,不是日常。
- CPU 和带宽:1000 台一份快照约 3MB。页面每 5 秒轮询,响应体在巡视台这边缓存 2 秒,
所以不管几个人开着大屏,整份 JSON 最多每 2 秒编一次 —— 这笔开销不随看的人数涨。
- 一轮多久:正常一台几十毫秒,1000 台一轮远在
-interval 之内。
连不上的机器要等满 -timeout:1000 台全连不上,第一轮要 1000/32 × 5s ≈ 156s。
这只发生在第一轮或整片断网之后,之后这些机器就走后台慢道,不再拖住每一轮。
再多就按机房拆成几台 pelican,各带一份 host.list,-interval 保持一致才好比。
已知的边界:慢道是按失败分的,不是按慢分的。一千台都答得慢(每台超过 1.4 秒)
但都答得成的话,一台都不算失败、一台都进不了慢道,每一轮都会拖到 45 秒以上 ——
这超过了默认的 -lost-after(3 轮 = 45 秒),机器会在「正常」和「失联」之间翻。
这种情况要加大 -interval(-lost-after 跟着涨),或者拆成多台。
host.list 格式
一台一行:名字 地址 键=值 …,# 后面是注释。
- 地址:
10.1.0.11(补默认端口 8888)、10.1.0.11:9100,或完整 URL(反代、https、基本认证;用户名和密码都不会出现在屏上、报错和失败原因里,但 host.list 本身是明文,注意文件权限)。
- 键:
dc(机房)、rack(机柜)、product(产品线)、group(主机组)、tags(逗号分隔,可多个)。值里不能有空格。
- 改完保存就生效。写错一处,整份不采用,继续用上一版,屏幕顶部提示哪一行错了。
- 地址写 IP 最省事。写域名(
db-01.corp.example)时,nodedata 只认得自己的主机名:域名跟那台的 hostname 不一样的,
在那台加 --allow-host db-01.corp.example(或 --allow-host '*.corp.example'),否则"拉取状况"里会写明被拒的原因。
经反代拉取时,反代转发的 Host 要么是 IP/上游地址(nginx proxy_pass 的默认行为),要么加进 --allow-host。
例子
# 名字 地址 分组
pay-db-01 10.1.0.11:8888 dc=tokyo1 rack=A03 product=支付 group=mysql-主 tags=核心,SSD
pay-java-01 10.1.0.21 dc=tokyo1 rack=A03 product=支付 group=java-app tags=核心
ord-redis-01 10.1.0.31 dc=tokyo1 rack=A04 product=订单 group=redis tags=SSD
log-kafka-01 10.2.0.41 dc=osaka1 rack=B01 product=日志平台 group=kafka # 没有标签
edge-01 https://ops:secret@gw.example.com/nd/edge-01 dc=osaka1 product=基础设施
test-01 10.9.0.5 # 什么都不写也行:只在"主机"那一层出现,其他层归到"(未填)"
列表视图怎么用
顶部"天空 / 列表"切到列表,是方块轮播:
- 顶部选按什么翻页:主机 / 主机组 / 产品线 / 机柜 / 机房 / 标签。
- 左右滑动或点边缘箭头翻页,箭头下的数字 = 那一边还有几页不正常。默认 15 秒一页,手一碰暂停 60 秒。
- 点方块进主机页。右上角"拉取状况"列出没拉到的机器和原因(比如"对方只监听了 127.0.0.1")。
- 巡视台自己断了,整屏变灰并写明最后更新时间——绝不留着一屏旧的绿。
5. 天空视图:鹈鹕巡检
默认打开就是天空视图:一栋楼 = 一个机柜,一扇窗 = 一台主机,窗的颜色就是状态。
| 情况 |
鹈鹕 |
| 全部正常 |
高空巡航,拍几下滑一阵,拖着横幅"全部 N 台正常" |
| 异常 |
俯冲下来,贴着那扇窗快速拍翅悬停,探照灯照住它 |
| 偏离 |
在那栋楼上空盘旋,盯着那扇窗 |
| 失联 |
贴窗悬停,头顶问号 |
| 巡视台断开 |
落在楼顶收翅睡觉,城市变灰 |
停下时左上角"巡检报告"显示这台的 USE 五行。它只去已经亮红、亮黄、变黑的窗,不推断原因。
点楼进这一组,点窗进这台主机;顶部"天空 / 列表"随时切换。
地址 # 后面可以组合,用 - 连接:
http://巡视台:8776/#rack 按机柜分楼(默认)
http://巡视台:8776/#group 按主机组分楼
http://巡视台:8776/#product-list 按产品线、打开就是列表视图
http://巡视台:8776/#rack-night 强制夜景(默认天色跟 iPad 本地时间:白天/霞光/夜)
http://巡视台:8776/#demo 演示模式:不连任何机器,100 台假数据,顶部挂"演示数据"
6. iPad 挂墙
- Safari 打开巡视台地址 → 分享 → 添加到主屏幕(全屏、无地址栏)。
- 设置 → 显示与亮度 → 自动锁定 → 永不。
- 设置 → 辅助功能 → 引导式访问 打开;进页面后连按三下顶部按钮(有主屏幕按钮的机型按主屏幕按钮)锁定。
- 页面不从外网加载任何东西,机房 iPad 上不了外网也能用。
7. 从源码编译
git clone https://github.com/githubflyideas/nodedata && cd nodedata
V=$(git describe --tags --always)
for c in nodedata nodedata-pelican; do
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$V" -o $c ./cmd/$c
done
go test ./... # 含 8 天历史回放和故障语料,约 1 分钟
go test -short ./... # 跳过回放,几秒
bash scripts/package.sh "$V" dist # 打出跟 Releases 上一样的包(需要 file、sha256sum)
不进发布包、要用就自己编的两个:
# 只有方块列表的巡视台(默认端口 8888;鹈鹕的"列表"视图跟它是同一个页面)
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$V" -o nodedata-fleet ./cmd/nodedata-fleet
# 验收工具:在实验机上真的制造 CPU/IO/内存/丢包故障,看 nodedata 能不能按时报出。别放到生产机上
CGO_ENABLED=0 go build -trimpath -o faultlab ./cmd/faultlab
CI 每次 push 都会跑 scripts/package.sh 打包,再用 scripts/verify-install.sh 把上面 §1 的代码块原样执行一遍、
把装好的 nodedata 和巡视台跑起来互相拉取。改 §1 的步骤时,包要跟着改,否则 CI 红。
8. 安全
- 默认只监听
127.0.0.1。页面里有进程名、PID、负载,开放给内网前先用防火墙限制来源,或放在带鉴权的反代后面(程序本身不做鉴权)。
- 只读
/proc、/sys;不连服务、不读配置、不执行命令;不采集进程命令行(参数里常有密码)。
- 页面给的"下一步命令"只填 PID、不拼进程名,只给诊断命令,nodedata 自己从不执行它们。
- HTTP 接口只认 GET / HEAD,响应都带
X-Content-Type-Options: nosniff、禁止被 iframe 嵌入、Referrer-Policy: no-referrer;报告、诊断、热力图、明细这类要现算的接口缓存 10 秒(时间参数按 10 秒对齐,最多缓存 64 份),所有现算同时最多 2 份,排队时客户端断开就不算了——不鉴权的接口被循环 curl 也只占这么多 CPU。连接有读写超时,慢连接占不住文件描述符。
- 巡视台不跟重定向,各台回来的数据按条数和长度裁剪后才上屏。
- 防 DNS 重绑定(v7.0):
Host 头不是 IP、localhost、本机主机名或 --allow-host 给的名字时回 421。
否则坏网页可以把自己的域名解析到 127.0.0.1,借你的浏览器读本机的进程名和 PID。用 IP 访问不受影响。