HOMENOC · 实战技术手册 v1.0
这套系统把家庭网络中的路由器、虚拟化宿主机和 NAS 转换成统一、可验证、可追溯的运行状态。本文完整记录 RB5009、Proxmox VE、Synology、Prometheus 与 Grafana 的部署和面板设计过程。
RB5009Proxmox VESynology DS723+Prometheus + Grafana
执行原则:所有配置变更遵循“备份 → 语法验证 → 小范围测试 → 重载或重建 → 结果核验”。文中的密码、API Token 和 SNMPv3 凭据均使用占位符。
文章目录
1. 项目目标与最终成果
HomeNOC 的目标不是简单地堆叠几个图表,而是把家庭网络中的路由器、虚拟化宿主机和存储设备转换成一套可验证、可追溯、可恢复的运行状态模型。最终通过统一的 Prometheus 数据层和 Grafana 可视化层完成日常观察、容量判断和故障定位。
| 成果 |
完成状态 |
说明 |
| RB5009 NOC 面板 |
完成 |
接口、系统、防火墙、路由、WireGuard、邻居、公网IP与连通性 |
| PVE NOC 面板 |
完成 |
节点、VM/LXC、存储、CPU/内存、温度、NVMe和SMART |
| Synology NOC 面板 |
完成 |
系统、CPU/内存、卷、RAID、硬盘、SMART、服务与接口 |
| 开机自动恢复 |
完成 |
全部 homenoc-* 容器使用 restart=always |
| 磁盘保护 |
完成 |
Prometheus 15天+8GiB,Docker日志轮转 |
| 共享文件访问审计 |
规划 |
需要新增 Loki + Alloy + DSM Log Center |
2. 总体架构与资产清单
RB5009SNMP · RouterOS API
Proxmox VEAPI · Node Exporter
Synology DS723+SNMPv3 authNoPriv
→
采集层SNMP Exporter
MKTXP
PVE Exporter
Node / Blackbox
→
Prometheus指标存储
15 天 / 最大 8 GiB
→
GrafanaRB5009 / PVE / NAS
中文 NOC 面板
HomeNOC 指标采集、存储与可视化链路
图 1 HomeNOC 指标采集、存储与可视化链路
2.1 核心资产
| 对象 |
地址/入口 |
采集方式 |
用途 |
| HomeNOC |
192.168.16.240 |
Node Exporter |
承载全部监控容器 |
| RB5009 |
192.168.16.1 |
SNMP + MKTXP API |
核心路由、接口、防火墙与VPN |
| PVE |
192.168.16.220 |
PVE API + Node Exporter |
虚拟化、存储与硬件健康 |
| Synology DS723+ |
192.168.16.55 |
SNMPv3 authNoPriv |
NAS、卷、RAID、硬盘与服务 |
| Grafana |
192.168.16.240:3000 |
Web |
仪表板与查询 |
| Prometheus |
192.168.16.240:9090 |
HTTP |
指标时序数据库 |
2.2 运行容器
| 容器 |
镜像/用途 |
端口 |
| homenoc-grafana |
grafana/grafana:可视化 |
3000 |
| homenoc-prometheus |
prom/prometheus:指标存储 |
9090 |
| homenoc-snmp-exporter |
prom/snmp-exporter:v0.30.1 |
9116 |
| homenoc-node-exporter |
prom/node-exporter:HomeNOC主机 |
9100 |
| homenoc-mktxp |
ghcr.io/akpw/mktxp:RouterOS API |
49090(仅本机) |
| homenoc-blackbox-exporter |
ICMP可用性和延迟 |
9115(仅本机) |
| homenoc-pve-exporter |
prompve/prometheus-pve-exporter |
9221(仅本机) |
3. HomeNOC 基础平台
3.1 目录与配置文件
主要配置目录
命令 / 配置
/opt/homenoc/
├── docker-compose.yml
├── prometheus/prometheus.yml
├── grafana/data/
├── snmp-exporter/snmp.yml
├── mktxp/docker-compose.yml
├── mktxp/config/mktxp.conf
├── blackbox/docker-compose.yml
├── pve-exporter/docker-compose.yml
├── pve-exporter/config/pve.yml
├── secrets/
└── backups/
3.2 Docker 网络
所有核心服务加入 homenoc_default 网络。Prometheus 通过服务名访问 exporter,Grafana 通过 http://prometheus:9090 访问 Prometheus。容器内部通信不依赖宿主机映射端口。
网络与容器核验
命令 / 配置
docker network inspect homenoc_default \
--format '{{range .Containers}}{{println .Name .IPv4Address}}{{end}}'
docker ps --format 'table {{.Names}} {{.Image}} {{.Ports}}'
3.3 Prometheus 基线
全局抓取周期为15秒,部分API型任务使用30秒。所有新增任务先用 promtool 验证,再向 Prometheus 发送 SIGHUP 重载。
Prometheus标准变更流程
命令 / 配置
docker exec homenoc-prometheus \
promtool check config /etc/prometheus/prometheus.yml
docker kill --signal=SIGHUP homenoc-prometheus
curl -fsSG http://127.0.0.1:9090/api/v1/query \
--data-urlencode 'query=count by (job) (up)'
4. RB5009 监控部署
4.1 数据来源设计
| 数据类型 |
来源 |
原因 |
| 接口流量/错误/丢包 |
SNMP if_mib |
标准、稳定、适合高频采集 |
| 系统状态 |
SNMP rb5009_noc + MKTXP |
补充CPU、内存、温度和设备身份 |
| 防火墙/连接数/路由 |
MKTXP API |
RouterOS私有运行数据更完整 |
| WireGuard/邻居/公网IP |
MKTXP API |
SNMP标准MIB不覆盖 |
| WAN延迟/可用性 |
Blackbox ICMP |
从HomeNOC视角主动探测 |
4.2 创建最小权限API账户
RouterOS 创建只读组 homenoc-monitor,只授予 read 和 api;账户 homenoc-mktxp 仅允许 HomeNOC 的 192.168.16.240/32 访问。密码必须在设备与 MKTXP 配置中保持一致。
在 RB5009 Terminal 执行;替换密码占位符
命令 / 配置
:local mktxpPassword "<使用随机长密码>"
:if ([:len [/user group find where name="homenoc-monitor"]] = 0) do={
/user group add name=homenoc-monitor policy=read,api \
comment="HomeNOC MKTXP read-only"
}
/user group set [find where name="homenoc-monitor"] policy=read,api
:if ([:len [/user find where name="homenoc-mktxp"]] = 0) do={
/user add name=homenoc-mktxp group=homenoc-monitor \
address=192.168.16.240/32 password=$mktxpPassword \
comment="HomeNOC MKTXP API"
} else={
/user set [find where name="homenoc-mktxp"] \
group=homenoc-monitor address=192.168.16.240/32 \
password=$mktxpPassword disabled=no
}
/ip service set [find where name="api"] \
disabled=no port=8728 address=192.168.16.240/32
4.3 MKTXP 配置要点
mktxp.conf 关键片段
命令 / 配置
[RB5009]
hostname = 192.168.16.1
username = homenoc-mktxp
password = <从秘密文件安全写入>
port = 8728
enabled = True
use_ssl = False
role = core-router
site = home
firewall = True
routes = True
wireguard_peers = True
neighbor = True
public_ip = True
ipv6_neighbor = False
启动与验证
命令 / 配置
cd /opt/homenoc/mktxp
docker compose config
docker compose up -d --force-recreate
sleep 8
docker logs --tail 100 homenoc-mktxp 2>&1 | \
sed -E 's/(=password=)[^ ]+/\1[REDACTED]/g'
curl -fsS http://127.0.0.1:49090/metrics | \
grep -E '^mktxp_(ip_connections_total|routes_total_routes|firewall_filter)'
4.4 Prometheus 任务
| job |
目标/模块 |
主要指标 |
| mikrotik-interface |
192.168.16.1 / if_mib |
接口流量、状态、错误、丢包 |
| mikrotik-system |
192.168.16.1 / rb5009_noc |
系统和硬件状态 |
| mktxp |
homenoc-mktxp:49090 |
API、防火墙、路由、WG、邻居、公网IP |
| blackbox-icmp |
RB5009/AliDNS/Cloudflare/Google |
可用性、RTT与探测耗时 |
4.5 面板关键指标
- CPU、内存、存储、温度、运行时间与RouterOS身份信息。
- 接口实时收发速率、利用率、丢弃、错误、队列和广播/组播速率。
- IPv4/IPv6防火墙规则累计计数及规则动作。
- IPv4/IPv6路由数量、连接跟踪数量。
- WireGuard Peer收发、最后握手、禁用状态和当前端点。
- 邻居设备、公网IPv4/IPv6、Cloud DDNS名称。
- 活动用户数代表会话数,而不是唯一账号数;Winbox、SSH和API会分别计数。
5. PVE 监控部署
5.1 PVE API Token
在 PVE 创建专用只读用户和 API Token,不使用 root 密码。Token只授予审计/只读权限,创建后立即复制 Token Value,并写入 HomeNOC 的 pve.yml;Token Value 不在手册或聊天记录中长期保存。
- Datacenter → Permissions → Users:创建监控用户。
- Datacenter → Permissions → API Tokens:创建独立Token。
- Datacenter → Permissions:在 / 路径授予 PVEAuditor 或等价只读角色。
- Token泄露时立即删除并重新生成,然后只更新 HomeNOC 配置。
5.2 PVE Exporter
PVE API exporter本地验证
命令 / 配置
curl -fsSG http://127.0.0.1:9221/pve \
--data-urlencode 'target=192.168.16.220' \
--data-urlencode 'module=default' \
--data-urlencode 'cluster=1' \
--data-urlencode 'node=1' | \
grep -E '^pve_(up|version_info|guest_info|storage_info)'
5.3 PVE Node Exporter 与硬件信息
PVE宿主机直接运行 prometheus-node-exporter,HomeNOC 抓取 192.168.16.220:9100。NVMe和SMART由PVE自带的textfile collector定时生成 nvme.prom 与 smartmon.prom。
仅在PVE宿主机执行
命令 / 配置
systemctl start prometheus-node-exporter-nvme.service || true
systemctl start prometheus-node-exporter-smartmon.service || true
find /var/lib/prometheus/node-exporter -maxdepth 1 -type f -printf '%f
'
curl -fsS http://192.168.16.220:9100/metrics | \
grep -E '^(nvme_|smartmon_|node_hwmon_temp_celsius)' | head -n 80
5.4 PVE 面板内容
| 区域 |
观察内容 |
| 平台健康 |
PVE API、Node Exporter、版本、内核、运行时间 |
| 宿主资源 |
CPU、负载、内存、Swap、根分区 |
| 虚拟实例 |
VM/LXC运行状态、CPU、内存、磁盘、网络、开机自启 |
| 存储 |
local、local-lvm、NAS-SMB容量、利用率和在线状态 |
| 硬件健康 |
CPU温度、NVMe温度、SMART、寿命、介质错误、断电次数 |
| I/O |
NVMe读写吞吐、平均延迟、累计读写量 |
6. Synology DS723+ 监控部署
6.1 SNMPv3 安全模式
DSM 实测 authPriv 返回 Unsupported security level,因此最终采用 SNMPv3 authNoPriv:用户名 homenoc-monitor、SHA认证、无隐私加密。尽管没有报文加密,它仍提供身份认证;服务仅允许可信管理网访问,并使用48位随机认证密码。
6.2 最小认证测试
在HomeNOC执行;成功时返回Linux/DSM系统描述
命令 / 配置
timeout 12s snmpget \
-v3 -l authNoPriv \
-u homenoc-monitor \
-a SHA \
-A "$(tr -d '\r\n' </opt/homenoc/secrets/synology-snmpv3-password)" \
-t 3 -r 1 -On \
192.168.16.55 \
1.3.6.1.2.1.1.1.0
6.3 SNMP Exporter 模块
| 模块 |
数据 |
| synology |
型号、DSM版本、温度、风扇、电源、硬盘、RAID、SMART、服务用户 |
| ucd_la_table |
1/5/15分钟系统负载 |
| ucd_memory |
内存、缓存、Swap |
| ucd_system_stats |
CPU用户态/系统态/空闲和原始计数 |
| hrStorage |
内存与存储表 |
| hrSystem |
用户数、进程数和运行时间 |
| system |
sysName、sysDescr、位置和系统时间 |
| if_mib |
eth0、eth1、Docker和Tunnel接口流量与状态 |
6.4 三个 Prometheus Job
| job |
周期 |
模块组合 |
标签 |
| synology-system |
30s |
synology + system |
NAS系统与硬盘 |
| synology-host |
30s |
ucd/HR系统模块 |
CPU、内存、存储、用户 |
| synology-interface |
15s |
if_mib |
网络接口 |
静态标签统一使用 site=home、platform=synology、monitored_device=DS723+、nas=Pengpeng-Data。Grafana查询固定这些标签,避免未来新增NAS后出现重复曲线。
6.5 Synology 面板内容
- NAS系统、主机和网络采集状态。
- DS723+型号、DSM版本、运行时间、CPU、系统负载、内存与Swap。
- Volume 1使用率、总容量、已用/剩余容量、RAID与Storage Pool状态。
- Disk 1/2健康状态、型号、接口、温度、坏扇区、重试、SMART关键错误和通电时间。
- 系统温度、风扇、电源、DSM升级可用状态。
- CIFS、HTTP/HTTPS、SSH等服务当前用户数,以及接口流量和错误。
7. Grafana 面板设计规范
7.1 布局原则
- 第一屏先回答:采集是否正常、设备是否在线、资源是否异常。
- 第二层显示CPU、内存、负载、运行时间和温度趋势。
- 第三层展示存储、接口、实例、硬盘等对象级数据。
- 状态类使用Stat或Bar gauge;趋势使用Time series;清单和事件使用Table。
- 所有标题和说明使用中文,PromQL与原始标签保留英文。
- 单位必须与数据语义一致:bytes、bits/sec、percent、celsius、seconds。
7.2 避免重复数据
Grafana出现两个相同数值,通常不是设备重复,而是查询同时匹配了不同job或重启前后不同label集合。所有查询都应限定唯一数据源,并在必要时使用 max、sum 或 topk 聚合。
PromQL去重示例
命令 / 配置
# 不推荐:可能匹配多个采集来源
node_memory_MemAvailable_bytes
# 推荐:固定PVE节点采集任务
node_memory_MemAvailable_bytes{
job="pve-node",
monitored_device="PVE"
}
# 状态数量:固定job并按对象聚合
sum(pve_up{job="pve-api", id=~"(qemu|lxc)/.*"} == 1)
7.3 数据源与导入
- Prometheus数据源URL使用 http://prometheus:9090。
- 导入JSON后确认数据源映射正确,不要重复创建同名Prometheus数据源。
- 面板JSON升级时使用新的UID或确认覆盖目标,保留上一版本作为回滚。
- 保存前检查过去5分钟和过去6小时两个时间范围,避免只有瞬时值可见。
8. 启动恢复与磁盘保护
8.1 开机自动恢复
一次HomeNOC重启后,Grafana正常启动但Prometheus保持Exited(0),导致数据源查询返回EOF。Prometheus手动启动后数据、网络和TSDB均正常。最终将所有监控容器的重启策略永久调整为 always,并同步修改四个Compose文件。
自动启动策略核验
命令 / 配置
for container in $(docker ps -a --format '{{.Names}}' | awk '/^homenoc-/'); do
docker update --restart=always "$container"
done
docker inspect homenoc-prometheus \
--format '状态={{.State.Status}} 重启策略={{.HostConfig.RestartPolicy.Name}}'
8.2 Prometheus容量保护
追加到 prometheus.yml 顶层;两项任一先达到即清理旧块
命令 / 配置
storage:
tsdb:
retention:
time: 15d
size: 8GB
8.3 Docker日志轮转
/etc/docker/daemon.json
命令 / 配置
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3",
"compress": "true"
}
}
Docker默认日志设置只对新建容器生效,因此修改daemon.json后需验证并安全重建容器。不能删除Prometheus数据卷或Grafana数据目录。
8.4 当前容量基线
| 项目 |
测量值 |
判断 |
| HomeNOC根分区 |
40GB,已用3.9GB(11%) |
充裕 |
| Prometheus |
约25MB,6511条活跃序列 |
预计15天约1-2GB |
| Grafana |
约92MB |
增长缓慢 |
| Docker镜像 |
约2.58GB |
按需清理悬空镜像 |
| Docker容器日志 |
不足2MB;现已轮转 |
理论上约210MB上限 |
9. 验收测试
9.1 容器和端口
预期:全部homenoc-*容器为running且restart=always
命令 / 配置
docker ps --format 'table {{.Names}} {{.Status}} {{.Ports}}'
for c in $(docker ps -a --format '{{.Names}}' | awk '/^homenoc-/'); do
docker inspect "$c" \
--format '容器={{.Name}} 状态={{.State.Status}} 重启={{.HostConfig.RestartPolicy.Name}}'
done
9.2 Prometheus任务
预期任务及数量
命令 / 配置
curl -fsSG http://127.0.0.1:9090/api/v1/query \
--data-urlencode 'query=count by (job) (up)' | \
sed 's/},{"metric"/},\n{"metric"/g'
| job |
预期数量 |
| homenoc |
1 |
| mikrotik-interface |
1 |
| mikrotik-system |
1 |
| mktxp |
1 |
| blackbox-icmp |
4 |
| pve-api |
1 |
| pve-node |
1 |
| synology-system |
1 |
| synology-host |
1 |
| synology-interface |
1 |
9.3 Grafana到Prometheus
预期:Prometheus Server is Ready.
命令 / 配置
docker exec homenoc-grafana sh -c '
wget -qO- -T 10 http://prometheus:9090/-/ready
'
10. 典型故障与处理
| 现象 |
根因 |
处理 |
| Grafana查询Prometheus返回EOF |
Prometheus容器退出但未恢复 |
启动容器;检查ready/API;改restart=always |
| MKTXP invalid user/password |
设备密码与配置不一致或密码为空 |
重新安全写入配置,检查长度,强制重建 |
| SNMPv3 Unsupported security level |
DSM不支持所选authPriv组合 |
改用SHA + authNoPriv并最小化测试 |
| Grafana出现两个相同值 |
PromQL匹配多个job/label集合 |
限定job、instance、monitored_device并聚合 |
| 存储面板无数据 |
指标名或标签连接条件不匹配 |
先查询原始指标,再按实际标签重写PromQL |
| NVMe面板No data |
textfile collector尚未运行或指标名不同 |
启动NVMe/SMART服务并列出实际指标 |
| PVE API接口curl无正文 |
接口需认证或TLS/输出处理问题 |
先验证9221 exporter的pve_up而非匿名PVE API |
| 粘贴脚本后SSH断开 |
set -e或终端粘贴错乱导致shell退出 |
诊断脚本使用set +e;长脚本保存为文件后执行 |
10.1 标准排障顺序
- 先确认当前主机,避免把HomeNOC命令误执行到PVE。
- 确认容器是否存在、是否running、是否持续重启。
- 从宿主机访问Exporter/Prometheus本机端口。
- 从Grafana容器访问Prometheus服务名,验证Docker DNS。
- 检查Prometheus targets和up指标。
- 最后才检查Grafana PromQL和面板转换。
11. 备份、恢复与日常维护
11.1 必须备份的内容
- /opt/homenoc/docker-compose.yml及各子项目Compose文件。
- /opt/homenoc/prometheus/prometheus.yml。
- /opt/homenoc/snmp-exporter/snmp.yml。
- /opt/homenoc/mktxp/config/mktxp.conf。
- /opt/homenoc/pve-exporter/config/pve.yml。
- /opt/homenoc/grafana/data及导出的Dashboard JSON。
- /opt/homenoc/secrets目录;必须加密保存。
11.2 推荐维护周期
| 周期 |
工作 |
| 每日自动 |
检查up、磁盘使用率、温度、存储状态与关键实例 |
| 每周 |
确认备份成功;检查Docker日志和Prometheus空间 |
| 每月 |
导出Dashboard JSON;更新配置备份;检查悬空镜像 |
| 升级前 |
记录镜像版本、备份配置和数据卷、逐项验证回滚 |
| 凭据变更后 |
立即验证Exporter并删除旧Token/密码 |
11.3 恢复顺序
- 恢复目录、Compose文件和秘密文件权限。
- 先启动Prometheus、Grafana、SNMP Exporter和Node Exporter。
- 再启动MKTXP、Blackbox和PVE Exporter。
- 运行promtool和docker compose config验证。
- 检查所有job的up,再打开Grafana面板。
- 最后执行一次重启测试,确认restart=always。
12. 后续扩展:共享文件访问审计
SNMP只能提供CIFS等服务的当前用户数,不能可靠提供具体用户、来源IP、文件路径和删除/重命名记录。要实现共享文件访问审计,需要引入日志系统,而不是继续把高基数文件路径塞进Prometheus。
| 组件 |
作用 |
建议限制 |
| DSM Log Center |
生成并转发SMB/文件传输日志 |
先记录写入、删除、重命名和失败事件 |
| Grafana Alloy |
通过TCP 1514接收Syslog并转发 |
仅在管理网开放 |
| Grafana Loki |
保存和查询日志 |
14天保留,5-8GB预算 |
| Grafana |
用户/IP/共享目录/操作趋势和最近事件 |
路径在查询时解析,不作为高基数标签 |
附录 A:端口矩阵
| 端口 |
协议 |
服务 |
开放范围 |
| 3000 |
TCP |
Grafana |
家庭管理网 |
| 9090 |
TCP |
Prometheus |
家庭管理网/本机 |
| 9100 |
TCP |
Node Exporter |
HomeNOC与PVE采集 |
| 9116 |
TCP |
SNMP Exporter |
HomeNOC |
| 9115 |
TCP |
Blackbox Exporter |
仅127.0.0.1映射 |
| 9221 |
TCP |
PVE Exporter |
仅127.0.0.1映射 |
| 49090 |
TCP |
MKTXP |
仅127.0.0.1映射 |
| 8728 |
TCP |
RB5009 API |
只允许192.168.16.240/32 |
| 161 |
UDP |
SNMP |
只允许管理网/HomeNOC |
| 1514 |
TCP |
计划中的Alloy Syslog |
尚未部署 |
附录 B:快速健康检查
HomeNOC一页式巡检
命令 / 配置
echo '===== 容器 ====='
docker ps --format 'table {{.Names}} {{.Status}} {{.Ports}}'
echo '===== Prometheus ====='
curl -fsS http://127.0.0.1:9090/-/ready
echo '===== Jobs ====='
curl -fsSG http://127.0.0.1:9090/api/v1/query \
--data-urlencode 'query=count by (job) (up)'
echo '===== 磁盘 ====='
df -hT /
echo '===== Prometheus数据 ====='
du -sh /var/lib/docker/volumes/homenoc_prometheus-data/_data
附录 C:敏感数据处理
- RouterOS API密码、PVE Token Value、SNMPv3认证密码不得写入面板JSON。
- 命令输出发给他人前,替换password、token、secret、serial和公网地址。
- 备份中的秘密文件使用chmod 600,并限制备份目录为700。
- Token或密码一旦出现在公开渠道,立即撤销并重新生成,不只是在聊天中删除。
- Dashboard JSON可以保存查询和设备内网地址,但不应包含数据源密码。
附录 D:官方参考资料