看清网络连接,及时发现异常。
网脉 NetPulse 是轻量的网络监控与智能诊断工具。常驻系统托盘,把设备、链路、延迟、丢包与现场诊断放在同一个页面。
运行截图
以下为系统在隔离演示环境中的实际运行截图。设备名称和 MAC 为虚构示例,探测地址仅使用本机回环地址;历史曲线使用示例数据,不包含真实机房信息。点击图片可查看大图。
网络拓扑
直观看到交换机、终端与上联关系,以及每台设备的实时探测状态。
监控列表
集中查看在线与离线状态、延迟、抖动、丢包率和最近探测走势。
设备历史曲线
通过平均延迟、最小至最大区间和丢包柱状图,观察异常发生的时间。下图历史样本为虚构演示数据。
从这里开始
- 在 GitHub Releases 下载对应系统版本,或按 开发与发布 从源码构建。
- 在运行程序的电脑上打开管理页面,设置登录密码(至少 6 位)。
- 把虚构演示拓扑替换为自己的设备,再配置告警。
一套工具,覆盖日常运维
| 你想做什么 | 去哪里 |
|---|---|
| 看延迟、抖动、丢包和历史走势 | 监控列表、设备详情 |
| 看设备之间的接线关系 | 拓扑 |
| 查新设备、跟踪 IP 变化 | 扫描发现 |
| 查设备接在哪个交换机端口 | 端口定位 |
| 查看异常记录与配置通知渠道 | 告警、设置 |
| 分析多台同时离线、定位上游故障 | AI 诊断 |
| 汇总可用率与故障情况 | 运维报告 |
| 让外部 AI 客户端查询监控 | MCP |
| 扩展通知渠道、事件钩子与 AI 工具 | 插件 |
部署边界
Windows 7 / Server 2008 R2 及以上和 macOS;Windows 兼容构建使用 Go 1.20.14。管理网页需要现代浏览器。首次运行的拓扑完全虚构,必须替换;扫描与诊断只应针对你有权限管理的网络。
旧名 netPing 保留在可执行文件、数据目录和内部模块中。升级时可继续使用原目录。进一步阅读:安装与首次运行 · 拓扑字段参考 · 插件开发参考。
安装与首次运行
Windows
下载并解压发行包,把 netPing.exe 放入固定目录,例如 D:\NetPulse\,双击运行。程序出现在系统托盘,浏览器自动打开管理页;默认地址是 http://127.0.0.1:8090/。无需安装运行库,ICMP 探测无需管理员权限。
macOS
解压发行包,将 netPing.app 拖入「应用程序」。发行包采用 ad-hoc 签名且未经 Apple 公证,首次打开时可能需要右键「打开」,或在「系统设置 → 隐私与安全性」中点击「仍要打开」。出现本地网络权限提示时请选择允许,否则 MAC 学习与扫描可能不完整。程序显示在菜单栏,数据位于 ~/Library/Application Support/netPing。
第一次配置
- 在运行程序的电脑本机打开管理页设置登录密码(至少 6 位;其它电脑首次访问会提示先到本机设置)。
- 在「拓扑」中删除或修改虚构演示设备,填写自己的交换机、终端和接线位置。
- 在「监控列表」确认设备地址与状态,再给需要关注的设备开启告警。
- 在「设置」填写通知渠道,发送测试消息确认到达。
- 需要长期运行时,在托盘菜单开启「登录后自动启动」。这依赖用户登录,不是系统服务。
数据与备份
Windows 默认在程序目录保存 config.yaml、topology.yaml、data/、logs/(以及自装插件 plugins/);macOS 保存在 ~/Library/Application Support/netPing。多机房配置、版本快照与插件运行状态位于 data/ 下,应备份完整数据目录。搬迁前停止程序,复制完整目录,再用相同或更新版本启动。
不要把运行配置、拓扑、历史数据、日志或机器人地址上传到公开仓库。
拓扑与多机房配置
组织设备
交换机使用唯一 ID;节点用 IP 或 MAC 标识,并通过 attach.switch 和 attach.port 登记接线。端口位置可标注机柜、楼层或面板号。交换机间链路决定上游故障关联与路径分析。
示例数据只演示结构,不表示你的真实设备。用页面编辑最方便;批量迁移可使用 YAML 导入,但应先备份,再检查预览。
多机房
在「设置」新建、复制或改名机房。切换激活机房前先查看预览;同一时间只有一个机房激活。各机房拥有独立拓扑和运行配置,版本快照可用于回滚。回滚后确认监控对象、告警渠道与定时扫描符合当前现场。
参数与时段
默认每秒探测(最小间隔 200ms),超时 1000ms,数据包 32 字节,延迟告警阈值 100ms,丢包告警阈值 20%;设备可以单独覆盖。阈值应根据链路实际情况设置。启用监控时段后,只在指定时段探测和告警;跨午夜时段(如 22:00 到 06:00)受支持,手动暂停独立生效。
字段参考
详细 YAML 字段、完整示例和批量生成提示词见 拓扑字段参考。修改监听地址或拓扑文件路径后需要重启。
监控与告警
看懂状态
当前延迟反映最近一次探测;平均延迟、抖动与丢包应结合时间窗口观察。设备详情提供分钟聚合历史,默认保留 30 天。没有观测样本不等于运行正常。
两层开关
先在设置启用通知并配置渠道,再为需要通知的设备开启告警。设备默认只监控、不告警。支持企业微信、钉钉、飞书、Slack、通用 Webhook 和通知插件。发送测试消息会使用页面当前填写的渠道。
默认规则
| 事件 | 条件 |
|---|---|
| 离线 | 连续 5 次失败 |
| 恢复 | 连续 3 次成功(默认开启 send_recovery) |
| 丢包 | 1 分钟发送 ≥10 次且丢包率达到阈值(默认 20%),持续 2 分钟 |
| 延迟高 | 1 分钟平均延迟达到阈值(默认 100ms),持续 3 分钟 |
| 重复提醒 | 持续故障每 30 分钟 |
| 合并 | 10 秒窗口内合并事件 |
维护窗口可静默整机房或指定设备。多台同时异常时,先检查共同的上游交换机;关联提示提供线索,仍需现场确认。
TCPing
设备详情可扫描常用端口或自定义范围,再选择加入持续监控。单次扫描最多 1024 个端口,并发最多 32;每设备持续监控最多 16 个端口。TCP 连接被拒绝、超时或错误均记失败,历史与 ICMP 独立。连接成功只能证明端口可建立连接,不代表应用业务正常。
设备发现与端口定位
扫描发现
先核对网段,再手动扫描。网段扫描结合 Ping 和 ARP 学习设备,支持按 MAC 跟踪 IP 变化(可设为跟踪全部非静态设备、仅 DHCP 设备或关闭)。新设备可自动添加为「未定位」,也可先查看建议后确认。定时任务各自配置网段、间隔(最小 5 分钟)和标签;单网段最多 /20(总计最多 8192 个地址)。同一 MAC 对应超过 8 个 IP 时视为代理 ARP,不写入设备 MAC。
SNMP 定位
交换机需要启用 SNMP v2c,并配置只读团体名(UDP 161)。填写交换机管理 IP 与团体名后先测试读取,再开始定位(定时定位最小间隔 2 分钟)。系统读取 MAC 地址表,将终端挂到对应端口;已在交换机连线(links)中登记的级联口会自动排除,已有设备端口发生变化时会提示确认。
MAC 可能出现在上联口、聚合口或多级交换机,不能仅凭一条 MAC 表直接判断物理插口。先核对交换机链路、端口别名和终端 MAC。
设备终端
端口定位页提供 Telnet、SSH 和 SFTP。SSH 首次连接需核对主机指纹;指纹变化时先确认设备身份。Telnet 明文传输,仅在可信隔离网络使用。
SFTP 单文件最多 1 GiB,需交换机启用 SFTP 子系统。文件上传后不会自动安装或应用配置;默认不覆盖同名文件。终端命令会直接作用于设备,配置完成后按设备要求保存。
AI 诊断与 MCP
AI 诊断
在页面配置模型协议、接口地址、模型与 API Key,测试连接后再提问。支持 OpenAI Chat Completions、OpenAI Responses、Claude Messages 和 Gemini 协议(默认 DeepSeek deepseek-flash)。默认开启回答前自检,核对证据后再输出结论。
例如:“哪些设备近一小时丢包最严重?”、“这几台设备同时离线,有共同上游吗?”、“检查这台设备是禁 Ping 还是真离线。” 模型可以结合历史、上联路径和现场探测给出依据与建议。
AI 诊断使用只读工具,不能修改配置。不要将凭据放入问题中;实时设备信息和工具结果会发给你配置的模型服务,应按现场要求选择供应商与代理。
MCP 接入
进入「MCP」复制客户端配置。端点为 POST http://主机:8090/mcp(Streamable HTTP,返回 JSON,不使用 SSE 流),建议配置专用令牌(Authorization: Bearer <token>)并优先开启只读。没有令牌时需通过 HTTP Basic 提供管理密码。远程访问应使用受控网络或带 TLS 的反向代理。
只读模式允许概况、设备、历史、告警、插件日志、维护窗口、运维报告以及多机房档案/版本预检等只读查询;关闭只读后,除拓扑、告警、扫描和监控设置外,还支持:
- 多机房与版本:
list_profiles、create_profile、rename_profile、preview_profile(默认不主动探测)、activate_profile/delete_profile(均需confirm=true)、get_profile_settings/set_profile_settings(只修改机房级设置并脱敏敏感字段),以及版本快照与回滚(list_profile_versions、create_profile_version、get_profile_version、preview_profile_version_rollback、rollback_profile_version)。 - 维护窗口:
list_maintenance、create_maintenance、cancel_maintenance(仅作用于当前激活机房)。 - 运维报告:
generate_health_report(纯程序统计,不调 AI)、generate_ai_report(显式调用 AI)、list_reports、get_report(支持 JSON / Markdown / HTML 内容)、delete_report。 - 设备锁定、清理与 AI 优化:
set_device_locked(也可通过upsert_device传locked)、preview_device_cleanup(返回绑定profile_id与epoch)、cleanup_devices(须传入预览匹配的profile_id、epoch与confirm=true);generate_ai_optimize(需非只读模式,调用已配置模型并产生费用,不会自动修改拓扑)、apply_ai_optimize(默认dry_run=true,应用需dry_run=false与confirm=true且绑定profile_id与epoch)、undo_ai_optimize(需confirm=true)。 - 插件只读查看:
get_plugins(在只读模式下可用,不返回本地路径并脱敏密钥与 URL 凭据/查询参数;运行记录仅返回结构化状态摘要,不返回自由文本message/error/stderr,运行详情请查看网页「插件」页)。
先确认客户端信任范围再放开写权限。
运维报告
程序统计报告无需模型,可导出 Markdown、HTML 或打印 PDF;可选 AI 日报、周报、月报。通过 MCP 亦可直接生成确定性报告(generate_health_report)或显式触发 AI 报告(generate_ai_report)。审阅时间范围和采样完整性,再将报告发送给他人。
安全与故障排查
访问控制
首次密码只能在运行程序的电脑(回环地址)上设置,至少 6 位;登录后发 30 天签名 Cookie,同一来源连续失败 5 次触发锁定(1 分钟起翻倍,最长 15 分钟)。默认监听所有网卡(0.0.0.0:8090),局域网设备可访问管理页;仅本机使用时将 listen 改为 127.0.0.1:8090 并重启。公开互联网部署应增加 TLS、网络访问控制与可靠身份管理。
配置文件包含机器人地址、模型密钥、SNMP 团体名和认证信息,应限制文件权限并保存在私有备份中。不要开启不需要的 MCP 写入能力;运行第三方插件前审查其代码和权限。
常见问题
| 现象 | 排查顺序 |
|---|---|
| 网页打不开 | 程序进程、端口占用、listen、防火墙、日志 |
| Ping 不通但设备能用 | 设备是否禁 ICMP,尝试 TCPing,核对 IP 与 ARP |
| MAC 或新设备缺失 | 本地网络权限、网段范围、ARP 可见性 |
| SNMP 失败 | 管理 IP、UDP 161、只读团体名、ACL、SNMP v2c |
| 告警未送达 | 渠道启用、设备告警开关、维护窗口、代理、告警发送结果 |
| AI 连接失败 | 协议、URL、模型名、Key、代理和服务余额 |
| SSH 指纹变化 | 先核实设备身份,再清理旧的信任记录 |
忘记密码
停止程序,私下编辑 config.yaml,删除 auth 下 password_hash 和 password,重启后在运行程序的电脑上重新设置。此操作需要本机文件访问权限。
报告漏洞
遵循仓库 SECURITY.md;不要在公开 Issue 粘贴密钥、真实拓扑或可直接利用的漏洞细节。已经暴露的密钥必须到服务端撤销或轮换;删除 Git 历史不能代替撤销。
开发、测试与发布
本地开发
Windows 兼容发行物必须用 Go 1.20.14。macOS 托盘构建需要 Xcode 命令行工具和 CGO;Linux 测试需要 GTK/AppIndicator 开发库(libgtk-3-dev、libayatana-appindicator3-dev)。
go1.20.14 run . -dir ./devdata -notray -nobrowser
node --test web/charts_test.cjs
python3 examples/plugins/email-notify/test_main.py
go1.20.14 test -count=1 ./...
go1.20.14 test -race -count=1 ./...
go1.20.14 vet ./...
前端为原生 JavaScript,不需要 npm 构建。不要对真实设备或通知渠道运行自动化测试。
打包构建
./build.sh # macOS / Linux 交叉编译 Windows amd64,输出 dist/netPing.exe
./build_mac.sh # macOS 通用二进制(arm64 + amd64)与 ad-hoc 签名
在 Windows PowerShell 上可运行 build.ps1。修改图标后重新生成 Windows 资源:go1.20.14 run ./tools/genicon && go1.20.14 run github.com/tc-hib/go-winres@v0.3.3 make --arch amd64。
Wiki 构建
python3 -m pip install -r wiki/requirements.txt
python3 tools/build_wiki.py
输出 dist/wiki/index.html,样式、脚本与内容内联,可直接打开。源文件是 wiki/ 下的 Markdown,技术参考同步读取 docs/。新增页面后更新生成器的导航列表。
流水线
提交和 Pull Request 执行 Go 测试、竞态检查、vet、前端图表测试、示例插件测试、Windows 兼容编译、Wiki 构建与全历史敏感信息扫描(Gitleaks)。main 分支推送构建并部署 GitHub Pages。打 v* 标签触发发布:先通过验证,再分别构建 Windows amd64 与 macOS 通用包、生成 SHA256SUMS,创建草稿 Release。审阅产物后手动发布。
兼容性
Go 1.20 已停止上游维护;它仅用于旧 Windows 的兼容构建。公开部署应优先使用受支持的操作系统,并评估工具链升级。macOS 包为 ad-hoc 签名,未做 Apple 公证。
贡献
阅读 CONTRIBUTING.md 和 SECURITY.md,提交可复现问题和范围明确的 PR。请使用虚构数据复现,不要上传现场配置、日志、截图中的设备信息或凭据。
topology.yaml 字段说明
topology.yaml 是 netPing 唯一的节点数据源,位于程序目录(可在 config.yaml 的 topology_file 修改)。
网页上的新增、编辑、删除、拖动位置都会写回这个文件;也可以直接编辑它(或交给 AI 修改),
然后在网页「设置 → 从磁盘重新加载」生效。保存和加载都会做校验,校验失败不会生效,并逐条列出问题。
机器可读的校验规则见 schema/topology.schema.json。
整体结构
version: 1 # 固定为 1
site: {...} # 机房信息
switches: [...] # 网络设备(交换机、路由器、防火墙、光猫、AP 等)
links: [...] # 交换机之间的连线
nodes: [...] # 终端节点
通用约定
| 规则 | 说明 |
|---|---|
| id 唯一 | 交换机、链路、节点三者的 id 全局不能重复;只能包含字母、数字、_ . -,以字母或数字开头,最长 64 字符 |
| id 可留空 | 新增时 id 留空,程序按 IP 生成(节点 n-192-168-1-10,交换机 sw-192-168-1-2),没有 IP 时按 MAC 生成 |
| 不要随意改 id | 节点 id 是历史数据目录名,改 id 等于换了一个节点,原历史曲线不再关联 |
| IP | 只支持 IPv4;同一 IP 在所有交换机和节点中只能出现一次;为空则只登记不 ping |
| 端口名 | 纯数字端口请加引号,如 port: "12",避免被当成数字 |
| 未知字段 | 拼错的字段名会直接报错(例如 adress),防止静默丢数据 |
| position | 为空表示按所接端口自动排布;拖动后写入坐标;交换机坐标是左上角 |
site
| 字段 | 类型 | 说明 |
|---|---|---|
| name | 字符串 | 机房名称,显示在网页标题与告警消息 |
| subnet | 字符串 | 网段,如 192.168.50.0/24 |
| gateway | IPv4 | 默认网关;顶栏「网关」显示它的延迟 |
| description | 字符串 | 备注 |
switches[]
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | id | 自动 | 被 links、nodes[].attach.switch 引用 |
| name | 字符串 | 显示名(必填) | |
| type | 枚举 | switch | 设备类型:switch 交换机 / router 路由器 / firewall 防火墙 / gateway 上网行为管理 / modem 光猫 / ap 无线AP / ac 无线控制器 / lb 负载均衡 / other;留空为交换机。各类型都能接终端、互相连线,拓扑图左上角图标和色条区分类型 |
| role | 枚举 | access | core 核心 / aggregation 汇聚 / access 接入 / other;核心与汇聚画成黑色实心 |
| layer | 字符串 | L2、L3 等,仅展示 |
|
| vendor / model | 字符串 | 厂商 / 型号 | |
| ip | IPv4 | 管理地址;填写后交换机本身也会被 ping | |
| mac | 字符串 | ||
| location | 字符串 | 物理位置,如 A01 机柜 U20 |
|
| note | 字符串 | 备注 | |
| port_locations | 映射 | 可选;端口 → 物理位置,如 {"12": "A03 机柜 配线架 2-12"}。端口定位把设备挂到该端口时自动填入设备的 location |
|
| ports | 字符串数组 | 可选;用于网页端口下拉、端口排序和绘制交换机前面板(网页里支持 Gi0/1-24 范围写法,保存时展开)。Te/XGE/SFP/TF 等开头的端口画成光口;纯数字编号时,超出 8 的整数倍的尾部端口画成光口(如 26 口 = 24 电口 + 2 光口)。不填时只画已接设备的端口 |
|
| node_side | left/right | right | 终端卡片画在交换机左侧还是右侧 |
| node_columns | 1~6 | 2 | 每个端口下终端卡片的列数 |
| monitor | 对象 | 同 nodes[].monitor |
|
| position | {x, y} | 拓扑图坐标 |
links[]
| 字段 | 类型 | 说明 |
|---|---|---|
| id | id | 可空,自动生成 |
| from | {switch, port} | 上游一端(靠近核心) |
| to | {switch, port} | 下游一端 |
| kind | 枚举 | uplink(默认)/ stack / other |
| note | 字符串 | 备注,显示在连线上 |
告警时(仅对开启了 monitor.alert 的设备),如果下游交换机本身不可达、或其下挂节点全部同时离线,会合并为一条「交换机故障」消息。
nodes[]
| 字段 | 类型 | 说明 |
|---|---|---|
| id | id | 可空,自动生成 |
| locked | 布尔 | 默认 false;true 表示上锁保护,一键清理始终保留。与 ip_mode: static 的 IP 锁定无关,不影响监控、扫描和手动编辑 |
| name | 字符串 | 显示名,可空 |
| hostname | 字符串 | 主机名,网段扫描自动获得(NetBIOS / mDNS / 反向 DNS),未填 name 时显示它;手工生成拓扑时可不填 |
| ip | IPv4 | 为空则不监控 |
| mac | 字符串 | 大写、冒号分隔;网段扫描按 MAC 识别设备、跟踪 IP 变化,建议尽量填写 |
| ip_mode | 枚举 | IP 分配方式:留空=自动跟踪;dhcp=自动获取(同样自动跟踪);static=固定 IP,锁定不自动修改 |
| vendor | 字符串 | 厂商(一般按 MAC 前缀 OUI 判断),拓扑图按厂商着色 |
| attach.switch | 交换机 id | 接线位置:接在哪台交换机;为空表示未定位 |
| attach.port | 字符串 | 接线位置:交换机端口名;同一端口多台设备表示口后还有交换机/集线器 |
| location | 字符串 | 物理位置(机柜 / U 位 / 房间) |
| flags | 数组 | 标记,见下表 |
| tags | 字符串数组 | 自定义标签,可被检索 |
| note | 字符串 | 备注 |
| monitor | 对象 | 见下表;省略的字段继承 config.yaml 的 ping 默认值 |
| position | {x, y} | 为空则自动排布 |
flags 取值
| 值 | 含义 | 拓扑图表现 |
|---|---|---|
| gateway | 默认网关 | 橙色卡片;告警标注「关键」 |
| critical | 关键设备 | 告警标注「关键」 |
| suspect | 存疑:复扫未见 / ping 不通 / 信息待核实 | 斜纹 |
| unlocated | 未定位:只在 ARP 见到,不知道接在哪个端口 | 放在「未定位」区域 |
| arp_only | 仅 ARP 可见,交换机 MAC 表没有记录 | |
| jump_host | 跳板机 | 黑色标签 |
| no_ipv4 | 没有 IPv4 地址 | |
| discovered | 由网段扫描自动添加 | 「自动发现」标签 |
| ai_discovered | 由「AI 自主发现」添加(撤销时只会删除带此标记的设备) | 「AI 发现」标签 |
monitor
| 字段 | 说明 |
|---|---|
| enabled | 是否 ping,默认 true |
| alert | 是否推送企业微信告警,默认 false;只有设为 true 的设备才会告警 |
| interval_ms | ping 间隔(毫秒,≥200) |
| timeout_ms | 单次超时(毫秒) |
| latency_warn_ms | 1 分钟平均延迟超过此值视为「延迟高」 |
| loss_warn_pct | 1 分钟丢包率超过此值(%)视为「丢包」 |
示例
version: 1
site:
name: 二号机房
subnet: 10.20.0.0/24
gateway: 10.20.0.1
switches:
- id: ont
name: 电信光猫
type: modem
ports: [PON, LAN1, LAN2, LAN3, LAN4]
- id: fw
name: 出口防火墙
type: firewall
role: core
ip: 10.20.0.254
ports: [WAN1, WAN2, LAN1, LAN2, LAN3, LAN4]
- id: core
name: H3C 核心
role: core
layer: L3
ip: 10.20.0.2
ports: [GE1/0/1, GE1/0/2, GE1/0/3, GE1/0/48]
node_side: left
node_columns: 1
- id: acc-a01
name: A01 机柜接入
role: access
ip: 10.20.0.3
location: A01 机柜 U42
links:
- from: {switch: ont, port: LAN1}
to: {switch: fw, port: WAN1}
- from: {switch: fw, port: LAN1}
to: {switch: core, port: GE1/0/2}
- from: {switch: core, port: GE1/0/48}
to: {switch: acc-a01, port: "48"}
nodes:
- ip: 10.20.0.1
vendor: 华为
attach: {switch: core, port: GE1/0/1}
flags: [gateway]
monitor: {alert: true}
- ip: 10.20.0.31
name: 存储控制器 A
mac: 00:11:22:33:44:55
attach: {switch: acc-a01, port: "7"}
location: A01 机柜 U10
flags: [critical]
monitor: {alert: true, interval_ms: 500, latency_warn_ms: 5}
告警开关与监控时段
- 设备默认只监控、不告警。需要推送企业微信告警的设备设置
monitor.alert: true, 也可以在网页的节点/交换机表单里勾选「推送企业微信告警」,或在「监控列表」里逐个勾选、对筛选结果批量开启/关闭。 - 全局监控时段不在本文件中,而在
config.yaml的schedule(网页「设置 → 监控时段」)。时段外暂停 ping 与告警:
schedule:
enabled: true
windows:
- {days: [1, 2, 3, 4, 5], start: "08:00", end: "20:00"} # 工作日白天
- {days: [6], start: "22:00", end: "06:00"} # 周六晚到周日早(跨午夜)
网段扫描与 IP 跟踪
config.yaml 的 discovery.jobs(网页「扫描发现」页,或 MCP 工具 upsert_scan_job)定义自动扫描任务:每个任务按间隔扫描一个或多个网段,可为自动添加的设备附加标签、开启告警:
- 自动添加:扫描到、但拓扑里没有的设备自动加入
nodes,attach.switch为空、带flags: [unlocated, discovered], 有 MAC 时 id 按 MAC 生成(如n-020000000015),之后 IP 变化 id 也不变。 - IP 跟踪:设备以 MAC 为身份。扫描时 ARP 显示某个 MAC 换了 IP,就把该节点的
ip改成新地址(id、历史曲线、告警设置都保留)。ip_mode: static的节点不会被自动修改,只在扫描结果里给出提示。原 IP 被别的 MAC 占用、而本设备不在线时,会清空其ip(等再次出现时自动恢复)。 - 补全 MAC:只登记了 IP 的节点,扫描时会从 ARP 补上 MAC 和厂商。
- 仅 ARP 的设备:不响应 ping、只在 ARP 中出现的设备,自动添加时带
arp_only标记并设monitor.enabled: false。 - 共享 MAC:一个 MAC 对应多个 IP(无线中继 MAC-NAT、桥接)时,这些地址按 IP 分别登记,不写入该 MAC,
note中注明共享关系。 - ARP 只能看到与运行 netPing 的服务器同一二层网段的设备;跨网段只能确认在线,无法取得 MAC。
端口定位
config.yaml 的 locate 段(网页「端口定位」页)用 SNMP v2c 只读读取交换机 MAC 地址表:
attach 为空(未定位)的设备自动填上 attach.switch / attach.port 并去掉 unlocated 标记;
已定位设备的端口变化只提示,确认后修改。交换机的 port_locations 会在定位时填入设备的 location。
links 中登记的交换机间链路端口被视为级联口,不作为设备位置,所以请把交换机之间的连线登记完整。
迁移到新机房:交给 AI 生成
把下面的提示词连同 交换机 MAC 地址表(如 show mac-address-table)和 ARP 表(如 show arp)一起发给 AI:
请按照 netPing 的 topology.yaml 格式(字段说明见附带的 topology-fields.md 和 topology.schema.json)生成新机房的拓扑文件: 1. 每台交换机一个
switches条目,核心交换机role: core、node_side: left;接入交换机role: access。 2. 交换机之间的上联口写入links,from为上游。 3. 用 MAC 表确定每个 MAC 的接入交换机和端口(忽略上联口学到的 MAC),用 ARP 表把 MAC 对应到 IP,写成nodes,attach填交换机 id 和端口。 4. ARP 中有、但 MAC 表里没有的 IP 写成attach.switch: "",并加flags: [unlocated, arp_only]。 5. 按 MAC 前缀判断厂商填vendor;本地管理位 MAC(第一个字节第 2 位为 1)写“本地私有地址”。 6. 默认网关加flags: [gateway]。id 和 position 留空。纯数字端口加引号。 7. 所有设备默认不告警;只给我指定的关键设备(如网关、交换机管理地址、服务器)加monitor: {alert: true}。 只输出 YAML。
把生成的内容粘贴到网页「设置 → 拓扑文件」编辑框,点「校验并保存」;或直接覆盖程序目录下的 topology.yaml 后点「从磁盘重新加载」。若校验失败,把错误列表再发给 AI 修正即可。
netPing 插件开发指南
插件让你在不改动、不重新编译 netPing 的情况下扩展它。目前插件可以做三件事:
| 能力 | 怎么声明 | 典型用途 |
|---|---|---|
| 通知渠道 | hooks: [notify] |
把告警发到邮件、短信、电话、自建 IM、工单系统 |
| 事件处理 | hooks: [alert, discovery, locate] |
告警时自动重启设备、写入 CMDB / 数据库、联动其他系统 |
| AI 工具 | tools: [...] |
让 MCP 客户端和网页「AI 诊断」能查询资产库、机柜图、值班表等外部数据 |
本文适用于插件协议 api_version 1(netPing 1.5.0 起)。运行中的 netPing 也提供本文:
网页「插件」页的「开发指南」,或 MCP 资源 netping://docs/plugin-development.md(可以直接让 AI 助手按它帮你写插件)。
1. 工作方式
插件是一个独立的小程序,用什么语言写都行。netPing 需要它时:
- 启动插件程序(一次调用启动一个进程,处理完就退出,不常驻);
- 把一个 JSON 请求写到它的标准输入(stdin),然后关闭标准输入;
- 从它的标准输出(stdout)读回一个 JSON 响应;
- 插件退出。退出码为 0 表示成功。
没有需要链接的 SDK,也没有网络端口:能读标准输入、写标准输出的程序都能当插件。
netPing ──stdin: {"hook":"notify", "settings":{…}, "payload":{…}}──▶ 插件进程
netPing ◀──stdout: {"ok":true, "message":"已发送"}──────────────── 插件进程(随后退出)
2. 五分钟写一个插件
下面用 Python 写一个最小的通知插件:每收到一条通知就追加到文本文件。
第 1 步:建目录。 在 netPing 数据目录(config.yaml 所在目录;macOS 为 ~/Library/Application Support/netPing)下建
plugins/notify-file/。目录名就是插件 id。
第 2 步:写清单 plugins/notify-file/plugin.yaml:
id: notify-file # 必须与目录名相同
name: 通知存档
version: 1.0.0
description: 把每条通知追加保存到文本文件
command: ["python", "main.py"] # macOS / Linux 上通常是 python3
hooks: [notify]
settings:
- key: filename
label: 文件名
default: notify.log
第 3 步:写程序 plugins/notify-file/main.py:
import json, os, sys
req = json.loads(sys.stdin.buffer.read().decode("utf-8")) # 读请求
path = os.path.join(req["plugin"]["data_dir"], req["settings"]["filename"])
with open(path, "a", encoding="utf-8") as f: # 干活
f.write(req["time"] + " " + req["payload"]["title"] + "\n" + req["payload"]["text"] + "\n\n")
print(json.dumps({"ok": True, "message": "saved to " + path})) # 写响应
第 4 步:启用并测试。 打开管理页面「插件」页 → 点「重新扫描」→ 在「通知存档」里点「测试运行」, 应显示“✓ 成功”;确认无误后点「启用」。之后每条告警通知都会交给它。
只改
main.py立即生效(每次调用都重新启动进程);改了plugin.yaml需要点「重新扫描」。
3. 目录约定
<数据目录>/
plugins/
<插件 id>/ ← 插件目录:只放程序和清单,升级插件时整个覆盖
plugin.yaml ← 清单(必需)
main.py / xxx.exe … ← 插件程序
data/
plugins.json ← 各插件的启用状态与设置(netPing 维护,含密钥,不要提交到版本库)
plugins/<插件 id>/ ← 插件私有数据目录:可写,升级插件不受影响
- 以
.或_开头的目录会被忽略,可用来临时停放插件(如_backup)。 - 插件要保存的文件请写到请求里给出的
plugin.data_dir,不要写到插件目录。 - 插件进程的当前目录是插件目录,所以
command和程序里都可以用相对路径引用自带文件。
4. 清单 plugin.yaml
id: asset-lookup # 必填。小写字母、数字、连字符,2~24 个字符,以字母或数字开头;必须与目录名相同
name: 资产查询 # 显示名,默认同 id
version: 1.0.0 # 版本号,默认 0.0.0
description: 从资产库查询设备的负责人和保修信息
author: 张三
homepage: https://example.com/asset-lookup
api_version: 1 # 插件使用的协议版本,默认 1;高于 netPing 支持的版本时拒绝加载
command: ["./asset-lookup"] # 必填。启动命令,见下
timeout_sec: 15 # 单次调用最长时间(秒),默认 15,最大 120;超时进程会被终止并记为失败
hooks: [alert] # 要接收的钩子:notify / alert / discovery / locate(hooks 与 tools 至少有一项)
tools: # 提供给 AI 的工具(最多 32 个)
- name: lookup # 小写字母、数字、下划线,最多 24 个字符,以字母开头
title: 查资产 # 显示名
description: 按 IP 或 MAC 查询设备的负责人、部门、购买日期和保修状态。 # 必填:AI 靠它判断何时调用,写清楚“能查什么、需要什么参数”
write: false # true = 会修改外部系统或数据(见 §8)
ai: true # true = 允许网页「AI 诊断」调用(只对 write: false 的工具有效),默认 false
input_schema: # 参数的 JSON Schema,type 必须是 object;省略表示无参数
type: object
properties:
ip: {type: string, description: 设备 IP}
mac: {type: string, description: 设备 MAC}
settings: # 设置项(最多 32 个),在网页「插件」页填写,调用时随请求传给插件
- key: api_url # 小写字母、数字、下划线,以字母开头
label: 资产库接口地址 # 显示名,默认同 key
type: string # string(默认)/ secret / text / bool / number / select
help: 如 http://10.0.0.8/api # 输入框下方的说明
default: "" # 默认值,类型须与 type 一致
required: true # 必填:未填写时不能启用插件
- key: api_token
label: 接口令牌
type: secret # 密钥:网页不回显
- key: region
type: select
options: [华东, 华北] # select 类型必须给出 options
command 怎么写
command 是一个数组:第一项是程序,后面是参数。第一项按以下规则查找:
| 写法 | 含义 | 例子 |
|---|---|---|
带路径分隔符或以 . 开头 |
相对插件目录 | ["./asset-lookup"]、["bin/tool.exe", "--fast"] |
| 只有名字 | 先找插件目录下的同名文件,再找系统 PATH |
["python", "main.py"]、["node", "index.js"] |
| 绝对路径 | 原样使用 | ["C:\\Python39\\python.exe", "main.py"] |
Windows 上没写扩展名时会依次尝试 .exe、.bat、.cmd,所以 ["./asset-lookup"] 在 Windows 和 macOS / Linux 上通用。
命令不经过 shell 解析:不能写管道、重定向或 &&;需要时自己包一层脚本(如 ["cmd", "/c", "run.bat"]、["sh", "run.sh"])。
设置项类型
| type | 网页控件 | 传给插件的值 |
|---|---|---|
string |
单行文本 | 字符串(已去掉首尾空格) |
secret |
密码框,不回显;留空保存表示不修改 | 字符串 |
text |
多行文本 | 字符串 |
bool |
开关 | true / false |
number |
数字框 | 数字(JSON number,请按数字而不是整数解析) |
select |
下拉框 | options 中的某个字符串,未选为 "" |
请求里的 settings 总是包含清单中声明的全部 key:用户没填的用 default,没有 default 的是 "" / false / 0。
5. 请求格式
每次调用,标准输入里是一个 UTF-8 编码的 JSON 对象(单行,以换行结束):
{
"api_version": 1,
"hook": "notify",
"id": "20261114-135200-9f3a1c2b4d5e",
"time": "2026-11-14T13:52:00+08:00",
"test": false,
"netping": {"version": "1.5.0", "site": "四号机房", "url": "http://127.0.0.1:8090/"},
"plugin": {
"id": "notify-file", "version": "1.0.0",
"dir": "D:\\netPing\\plugins\\notify-file",
"data_dir": "D:\\netPing\\data\\plugins\\notify-file"
},
"settings": {"filename": "notify.log"},
"payload": { }
}
| 字段 | 说明 |
|---|---|
api_version |
协议版本。以后的版本只会增加字段,请忽略不认识的字段 |
hook |
本次调用的类型:notify / alert / discovery / locate / tool。一个插件声明了多个钩子时靠它区分 |
id |
本次调用的唯一编号,可用于日志或去重 |
time |
调用时间(RFC 3339,服务器本地时区) |
test |
true 表示这是网页「测试运行」发来的示例数据。有副作用的插件(发短信、重启设备、写数据库)应在测试时标明或跳过真实动作 |
netping |
netPing 版本、机房名称、管理页面地址 |
plugin |
插件 id、版本、插件目录 dir、私有数据目录 data_dir(已创建好,可写) |
settings |
设置项的当前值 |
payload |
随 hook 而不同,见 §7 |
另外会设置这些环境变量(不含任何设置项,密钥只走标准输入):NETPING_PLUGIN_ID、NETPING_PLUGIN_DIR、
NETPING_PLUGIN_DATA_DIR、NETPING_HOOK,以及 PYTHONIOENCODING=utf-8、PYTHONUTF8=1。
6. 响应格式
把一个 JSON 对象写到标准输出,然后退出:
{"ok": true, "message": "已发送给 3 人", "result": {"任意": "JSON"}}
{"ok": false, "error": "短信网关返回 403:余额不足"}
| 字段 | 说明 |
|---|---|
ok |
必填。是否成功 |
message |
可选。一句话结果,显示在「插件」页的「最近调用」里 |
error |
失败原因。通知类插件的失败原因会出现在「告警」页该条告警的发送结果里 |
result |
可选,任意 JSON。工具调用的返回值,会原样交给 AI |
判定规则(按顺序):
- 超时 → 失败,进程被终止。
- 标准输出超过 1 MB → 失败。
- 退出码非 0 → 失败。原因取响应里的
error;没有则取标准错误的最后一行。 - 退出码为 0 且输出了带
ok字段的 JSON 对象 → 按ok判定。 - 退出码为 0 但输出的不是上述格式 → 成功,全部输出作为
result(是 JSON 就按 JSON,否则按文本)。 所以简单脚本什么都不输出、只靠退出码表示成败也可以。
标准错误(stderr)是你的调试通道:随便写,netPing 保留最后 8 KB,失败时最后一行记入 logs/netping.log,
「测试运行」时直接显示在网页上。不要把调试信息写到标准输出,那会破坏响应。
7. 各钩子的 payload
7.1 notify — 通知渠道
netPing 要推送一条消息时调用(与企业微信、钉钉等内置渠道并列,收到的是同一条已合并的消息)。
{
"source": "alert",
"title": "机房网络监控 · 四号机房",
"markdown": "### 机房网络监控 · 四号机房\n<font color=\"warning\">● 离线</font> **192.168.50.29** 3楼打印机 **[关键]**\n>位置:接入交换机 Port 12 / A03 机柜\n>连续 5 次无响应\n<font color=\"comment\">2026-11-14 13:52:00</font>",
"text": "### 机房网络监控 · 四号机房\n● 离线 **192.168.50.29** 3楼打印机 **[关键]**\n>位置:接入交换机 Port 12 / A03 机柜\n>连续 5 次无响应\n2026-11-14 13:52:00"
}
| 字段 | 说明 |
|---|---|
source |
来源:alert 告警(含「设置」页的测试消息)、discovery 扫描发现、locate 端口定位、test 插件页「测试运行」 |
title |
标题(消息第一行去掉 #) |
markdown |
企业微信风格的 markdown 原文,颜色用 <font color="warning">、info、comment 标签,最长约 4000 字节 |
text |
去掉 <font> 标签后的文本(仍保留 **加粗**、>引用 等 markdown 符号) |
什么时候会被调用——规则与内置渠道完全相同:
- 「设置」里的告警总开关开启,且设备开启了告警(设备默认只监控、不告警);
- 消息已经过合并(默认 10 秒内的事件合成一条)、上游交换机故障归并和重复提醒间隔控制,插件不需要自己去重;
- 扫描发现、端口定位的通知还需要在各自页面开启“推送通知”。
只启用了通知插件、没有填写任何内置渠道地址时,也可以开启告警总开关。
插件返回失败不影响其他渠道,但这批告警在「告警」页会显示为发送失败并带上你的 error。
调用是同步的:告警引擎会等插件结束(最多 timeout_sec),请尽快返回,网络请求务必设置超时。
7.2 alert — 结构化告警事件
每批告警事件写入告警历史后调用。与 notify 的区别:拿到的是逐条的结构化数据而不是拼好的文字; 不受告警总开关影响(只要设备开启了告警就会产生事件);也不做交换机故障归并。适合做联动而不是发消息。
{
"notified": true,
"events": [
{
"time": "2026-11-14T13:52:00.123+08:00",
"type": "down",
"target_id": "n-192-168-50-29",
"kind": "node",
"name": "3楼打印机",
"ip": "192.168.50.29",
"location": "接入交换机 Port 12 / A03 机柜",
"detail": "连续 5 次无响应",
"sent": true
}
]
}
| 字段 | 说明 |
|---|---|
notified |
这批事件是否已通过通知渠道成功发出 |
events[].type |
down 离线、still_down 仍离线(重复提醒)、recover 恢复、loss 丢包、loss_recover 丢包恢复、slow 延迟高、slow_recover 延迟恢复 |
events[].target_id |
设备 id。TCP 端口监控的目标为 _tcp_<端口>_<设备 id>,此时 name 以 TCP:<端口> 结尾 |
events[].kind |
node 终端设备 / switch 交换机 |
events[].name / ip / location |
名称、IP、接线位置与物理位置 |
events[].detail |
文字说明,如“离线时长 5分12秒,当前延迟 1.20ms” |
events[].sent / error |
该事件的通知发送结果;失败时 error 为原因 |
7.3 discovery — 扫描发现
一次网段扫描产生了变更时调用(没有变化的扫描不调用)。
{
"job": "机房网段",
"changes": [
{"time": "2026-11-14T13:52:00+08:00", "type": "added", "node_id": "n-aabbccddeeff",
"ip": "192.168.50.19", "mac": "AA:BB:CC:DD:EE:FF", "detail": "…", "job": "机房网段"},
{"time": "2026-11-14T13:52:00+08:00", "type": "ip_changed", "node_id": "n-112233445566", "name": "前台电脑",
"old_ip": "192.168.50.50", "ip": "192.168.50.73", "mac": "11:22:33:44:55:66", "detail": "…"}
],
"suggestions": [
{"node_id": "srv-1", "name": "备份存储", "current_ip": "192.168.50.60", "seen_ip": "192.168.50.61",
"mac": "00:11:22:33:44:55", "reason": "…"}
]
}
changes[].type:added 自动添加了新设备、ip_changed 按 MAC 跟踪到新 IP、ip_released IP 被其他设备占用后清空、
mac_learned 补全了 MAC、conflict 无法自动处理的冲突、hostname 识别或更新了主机名。
值为空的字段(如没有名称的新设备的 name)会被省略,读取时请给默认值。
suggestions 是需要人工确认的 IP 变化(当前全部待确认项,不只是新增的)。
7.4 locate — 端口定位
一次端口定位产生了变更时调用。
{
"changes": [
{"time": "2026-11-14T13:52:00+08:00", "type": "located", "node_id": "n-aabbccddeeff", "name": "新打印机",
"ip": "192.168.50.19", "mac": "AA:BB:CC:DD:EE:FF", "from": "未定位", "to": "接入交换机 Port 12",
"location": "A03 机柜 配线架 2-12", "detail": "…"}
],
"suggestions": [
{"node_id": "pc-7", "name": "财务电脑", "ip": "192.168.50.41", "mac": "66:77:88:99:AA:BB",
"from": "接入交换机 Port 5", "to": "接入交换机 Port 9", "switch": "access", "port": "9"}
]
}
changes[].type:located 未定位的设备被自动挂到端口、moved 端口变化已采纳、location 补全了物理位置。
suggestions 是端口变化待确认的设备(当前全部待确认项)。
7.5 tool — 工具调用
MCP 客户端或网页「AI 诊断」调用你在 tools 里声明的工具时触发,hook 为 "tool":
{"tool": "lookup", "arguments": {"ip": "192.168.50.29"}, "remote": "192.168.50.5"}
| 字段 | 说明 |
|---|---|
tool |
工具名(清单里的 name,不带前缀)。一个插件有多个工具时靠它区分 |
arguments |
AI 给出的参数。netPing 不按 input_schema 校验,请自己检查必填项和类型 |
remote |
调用来源:MCP 客户端的 IP,或 AI 诊断的标识 |
把结果放在响应的 result 里(任意 JSON,建议是对象):
{"ok": true, "result": {"ip": "192.168.50.29", "owner": "行政部 李四", "warranty_until": "2027-03-01"}}
查不到、参数不对时返回 {"ok": false, "error": "没有 IP 为 … 的资产"},AI 会看到这句话并据此调整。
工具对 AI 的名字是 plugin_<插件 id>_<工具名>(如 plugin_asset-lookup_lookup),描述前会自动加上“[插件 名称]”。
结果过大时会被截断:AI 诊断单个工具结果最多约 16000 字符,请只返回需要的字段,必要时提供筛选和 limit 参数。
8. 权限与安全
对插件作者:
write: true的工具表示会修改外部系统或数据。它在 MCP 只读模式下不可见,网页「AI 诊断」永远不会调用。 有副作用的工具必须如实标记。ai: true才会开放给网页「AI 诊断」(MCP 客户端不受此限制)。AI 诊断会把工具结果发送给模型服务商, 返回敏感数据(手机号、密码、内部地址)的工具不要开启。- 设置(含密钥)只通过标准输入传递。不要把密钥打印到标准输出或标准错误——它们会进日志。
- 所有来自请求的内容(设备名、主机名、AI 给的参数)都是不可信输入:拼接 shell 命令、SQL、文件路径前必须校验或转义。 设备的主机名来自网络,可以被局域网里的任何设备伪造。
- 插件没有访问 netPing 管理接口的凭据。需要 netPing 的数据时,用请求里已有的字段,或让用户在设置里另填 MCP 令牌。
对使用者(也请写进你的插件说明):
- 插件以 netPing 的系统账号运行,能做这个账号能做的任何事。只安装来源可信的插件。
- 插件只能通过把文件放进
plugins/目录安装;网页和 MCP 都不能上传插件。新插件默认未启用。 - AI 助手(MCP)不能启用、停用或配置插件。
9. 运行时行为
| 项目 | 行为 |
|---|---|
| 进程模型 | 每次调用启动一个新进程,结束即退出。不要常驻,不要等待更多输入 |
| 并发 | 全局最多同时运行 4 个插件进程。同一个插件可能被并发调用(例如 AI 同时调用两次工具),写共享文件时请追加写或加锁 |
| 事件顺序 | alert / discovery / locate 事件异步排队分发,每个插件按产生顺序逐个收到;队列(256 个)满时丢弃新事件并记日志 |
| 超时 | 超过 timeout_sec 进程被终止,本次记为失败,不会重试 |
| 失败 | 任何失败都只记录,不重试、不自动停用插件。需要可靠投递请在插件内自己重试或落盘 |
| 暂停 | 监控暂停或处于非监控时段时不产生告警,因此也不会调用 notify / alert |
| 输出上限 | 标准输出 1 MB;标准错误保留最后 8 KB |
| 窗口 | Windows 上插件进程不显示控制台窗口 |
| 记录 | 每次调用在 logs/netping.log 记一行(插件、类型、成败、耗时);「插件」页显示最近 50 次 |
10. 调试
在网页上测试。 「插件」页每个插件都有「测试运行」:选择钩子(发送 §7 中的示例数据,test: true)或工具(可填 JSON 参数),
结果区会显示成败、耗时、result、标准错误,并可展开查看发给插件的完整请求。未启用的插件也可以测试。
在命令行里测试。 把请求存成文件,直接喂给插件程序,最方便反复调试:
# 在「测试运行」里展开“查看发给插件的请求”,复制保存为 req.json(其中的密钥显示为 ******,需要的话手工改回)
python main.py < req.json # Windows PowerShell: Get-Content req.json | python main.py
echo "退出码 $?"
常见问题:
| 现象 | 原因与处理 |
|---|---|
| 插件页显示“清单无效” | 按红字提示修改 plugin.yaml 后点「重新扫描」。最常见的是 id 与目录名不一致、YAML 缩进错误 |
| “找不到程序 python” | 运行 netPing 的电脑没装 Python,或它不在系统 PATH 里。把 command 第一项改成绝对路径,或改用编译型语言 |
| 中文乱码、JSON 解析失败 | 按 UTF-8 读写。Python 用 sys.stdin.buffer.read().decode("utf-8");PowerShell 脚本开头设置 [Console]::OutputEncoding = [Text.Encoding]::UTF8 |
| 命令行里正常,netPing 调用失败 | netPing 以托盘程序的身份运行,PATH、代理、当前用户可能和你的命令行不同;看「测试运行」里的标准错误 |
| “超过 N 秒未结束” | 给网络请求加超时,或调大 timeout_sec(最大 120)。插件不应等待用户输入 |
| 启用后没有收到 notify | 检查「设置」里的告警总开关、设备是否开启了告警;点「设置」里的「发送测试消息」会同时发给通知插件 |
| 改了 plugin.yaml 没生效 | 点「重新扫描」 |
11. 语言选择与示例
| 语言 | 优点 | 注意 |
|---|---|---|
| Go | 编译成单个 exe,目标机器不需要装任何东西;与 netPing 一样能在 Windows 7 / Server 2008 R2 上运行(须用 Go 1.20 编译) | 改代码要重新编译 |
| Python | 写起来最快,标准库够用 | 目标机器要装 Python;Server 2008 R2 最高只能装 Python 3.8 |
| PowerShell | Windows 自带 | ConvertFrom-Json 需要 PowerShell 3.0+(Server 2008 R2 自带的是 2.0,需升级 WMF) |
| Node.js 等 | 生态丰富 | 目标机器要装运行环境 |
仓库里有两个可以直接使用、也可以照着改的完整示例:
| 示例 | 语言 | 演示内容 |
|---|---|---|
examples/plugins/email-notify |
Python | notify 钩子:SMTP 邮件通知;各种类型的设置项;错误处理;用假 SMTP 服务器写自测 |
examples/plugins/event-log |
Go | alert / discovery / locate 三个钩子;使用 data_dir 保存数据;提供 AI 工具 recent_events;处理 test 标志;单元测试 |
安装示例:
# Python 示例:直接复制目录
cp -r examples/plugins/email-notify <数据目录>/plugins/
# Go 示例:先编译,再复制清单和可执行文件
cd examples/plugins/event-log
GOOS=windows GOARCH=amd64 go1.20.14 build -o event-log.exe . # 目标是 Windows 时
mkdir -p <数据目录>/plugins/event-log
cp plugin.yaml event-log.exe <数据目录>/plugins/event-log/
Go 插件骨架
package main
import (
"encoding/json"
"os"
)
type request struct {
Hook string `json:"hook"`
Test bool `json:"test"`
Plugin struct {
DataDir string `json:"data_dir"`
} `json:"plugin"`
Settings map[string]interface{} `json:"settings"`
Payload json.RawMessage `json:"payload"`
}
type response struct {
OK bool `json:"ok"`
Message string `json:"message,omitempty"`
Error string `json:"error,omitempty"`
Result interface{} `json:"result,omitempty"`
}
func main() {
var req request
resp := response{OK: true}
if err := json.NewDecoder(os.Stdin).Decode(&req); err != nil {
resp = response{Error: "请求无效: " + err.Error()}
} else {
switch req.Hook {
case "alert":
// TODO: 解析 req.Payload,做你的事
resp.Message = "已处理"
default:
resp = response{Error: "不支持的钩子 " + req.Hook}
}
}
_ = json.NewEncoder(os.Stdout).Encode(resp)
if !resp.OK {
os.Exit(1)
}
}
PowerShell 插件骨架(PowerShell 3.0+)
# plugin.yaml: command: ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "main.ps1"]
[Console]::OutputEncoding = [Text.Encoding]::UTF8
$reader = New-Object IO.StreamReader([Console]::OpenStandardInput(), [Text.Encoding]::UTF8)
$req = $reader.ReadToEnd() | ConvertFrom-Json
try {
# TODO: 用 $req.settings / $req.payload 做你的事
@{ ok = $true; message = "已处理 $($req.hook)" } | ConvertTo-Json -Compress
} catch {
@{ ok = $false; error = "$_" } | ConvertTo-Json -Compress
exit 1
}
12. 发布你的插件
- 目录里放一个
README:插件做什么、需要什么运行环境、每个设置项怎么填、有哪些副作用。 - 编译型插件同时提供源码和各平台的可执行文件;
command写成不带扩展名的["./名字"]可跨平台。 - 升级时递增
version。新增设置项要给default,这样老用户升级后不用重新配置; 删除或改名的设置项,旧值会在用户下次保存设置时自动清理。 - 不要依赖本文没有写明的行为;协议有不兼容变化时
api_version会递增,netPing 会继续支持旧版本的插件。
附:管理接口
网页「插件」页使用以下接口(需网页登录):
| 接口 | 作用 |
|---|---|
GET /api/plugins |
插件列表(含清单无效的)、设置项当前值(密钥不返回)、最近调用记录 |
POST /api/plugins/reload |
重新扫描插件目录 |
PUT /api/plugins/<id> |
{"enabled": true} 启停;{"settings": {"key": 值}} 保存设置(未出现的 key 不变,null 恢复默认,密钥传 "" 表示不修改) |
POST /api/plugins/<id>/test |
{"hook": "notify"} 或 {"tool": "lookup", "arguments": {…}},真实运行一次并返回结果 |
GET /api/plugins/guide |
本文(Markdown) |