网脉 NETPULSE / WIKI
NETPULSE / KNOWLEDGE BASE

看清网络连接,及时发现异常。

网脉 NetPulse 是轻量的网络监控与智能诊断工具。常驻系统托盘,把设备、链路、延迟、丢包与现场诊断放在同一个页面。

运行截图

以下为系统在隔离演示环境中的实际运行截图。设备名称和 MAC 为虚构示例,探测地址仅使用本机回环地址;历史曲线使用示例数据,不包含真实机房信息。点击图片可查看大图。

网络拓扑

直观看到交换机、终端与上联关系,以及每台设备的实时探测状态。

网脉 NetPulse 网络拓扑:交换机、终端与上联关系

监控列表

集中查看在线与离线状态、延迟、抖动、丢包率和最近探测走势。

网脉 NetPulse 监控列表:设备状态、延迟、丢包与最近走势

设备历史曲线

通过平均延迟、最小至最大区间和丢包柱状图,观察异常发生的时间。下图历史样本为虚构演示数据。

网脉 NetPulse 设备详情:延迟区间与丢包历史曲线

从这里开始

  1. 在 GitHub Releases 下载对应系统版本,或按 开发与发布 从源码构建。
  2. 在运行程序的电脑上打开管理页面,设置登录密码(至少 6 位)。
  3. 把虚构演示拓扑替换为自己的设备,再配置告警。

一套工具,覆盖日常运维

你想做什么 去哪里
看延迟、抖动、丢包和历史走势 监控列表、设备详情
看设备之间的接线关系 拓扑
查新设备、跟踪 IP 变化 扫描发现
查设备接在哪个交换机端口 端口定位
查看异常记录与配置通知渠道 告警、设置
分析多台同时离线、定位上游故障 AI 诊断
汇总可用率与故障情况 运维报告
让外部 AI 客户端查询监控 MCP
扩展通知渠道、事件钩子与 AI 工具 插件

部署边界

Windows 7 / Server 2008 R2 及以上和 macOS;Windows 兼容构建使用 Go 1.20.14。管理网页需要现代浏览器。首次运行的拓扑完全虚构,必须替换;扫描与诊断只应针对你有权限管理的网络。

旧名 netPing 保留在可执行文件、数据目录和内部模块中。升级时可继续使用原目录。进一步阅读:安装与首次运行 · 拓扑字段参考 · 插件开发参考。

NETPULSE / KNOWLEDGE BASE

安装与首次运行

Windows

下载并解压发行包,把 netPing.exe 放入固定目录,例如 D:\NetPulse\,双击运行。程序出现在系统托盘,浏览器自动打开管理页;默认地址是 http://127.0.0.1:8090/。无需安装运行库,ICMP 探测无需管理员权限。

macOS

解压发行包,将 netPing.app 拖入「应用程序」。发行包采用 ad-hoc 签名且未经 Apple 公证,首次打开时可能需要右键「打开」,或在「系统设置 → 隐私与安全性」中点击「仍要打开」。出现本地网络权限提示时请选择允许,否则 MAC 学习与扫描可能不完整。程序显示在菜单栏,数据位于 ~/Library/Application Support/netPing。

第一次配置

  1. 在运行程序的电脑本机打开管理页设置登录密码(至少 6 位;其它电脑首次访问会提示先到本机设置)。
  2. 在「拓扑」中删除或修改虚构演示设备,填写自己的交换机、终端和接线位置。
  3. 在「监控列表」确认设备地址与状态,再给需要关注的设备开启告警。
  4. 在「设置」填写通知渠道,发送测试消息确认到达。
  5. 需要长期运行时,在托盘菜单开启「登录后自动启动」。这依赖用户登录,不是系统服务。

数据与备份

Windows 默认在程序目录保存 config.yaml、topology.yaml、data/、logs/(以及自装插件 plugins/);macOS 保存在 ~/Library/Application Support/netPing。多机房配置、版本快照与插件运行状态位于 data/ 下,应备份完整数据目录。搬迁前停止程序,复制完整目录,再用相同或更新版本启动。

不要把运行配置、拓扑、历史数据、日志或机器人地址上传到公开仓库。

NETPULSE / KNOWLEDGE BASE

拓扑与多机房配置

组织设备

交换机使用唯一 ID;节点用 IP 或 MAC 标识,并通过 attach.switch 和 attach.port 登记接线。端口位置可标注机柜、楼层或面板号。交换机间链路决定上游故障关联与路径分析。

示例数据只演示结构,不表示你的真实设备。用页面编辑最方便;批量迁移可使用 YAML 导入,但应先备份,再检查预览。

多机房

在「设置」新建、复制或改名机房。切换激活机房前先查看预览;同一时间只有一个机房激活。各机房拥有独立拓扑和运行配置,版本快照可用于回滚。回滚后确认监控对象、告警渠道与定时扫描符合当前现场。

参数与时段

默认每秒探测(最小间隔 200ms),超时 1000ms,数据包 32 字节,延迟告警阈值 100ms,丢包告警阈值 20%;设备可以单独覆盖。阈值应根据链路实际情况设置。启用监控时段后,只在指定时段探测和告警;跨午夜时段(如 22:00 到 06:00)受支持,手动暂停独立生效。

字段参考

详细 YAML 字段、完整示例和批量生成提示词见 拓扑字段参考。修改监听地址或拓扑文件路径后需要重启。

NETPULSE / KNOWLEDGE BASE

监控与告警

看懂状态

当前延迟反映最近一次探测;平均延迟、抖动与丢包应结合时间窗口观察。设备详情提供分钟聚合历史,默认保留 30 天。没有观测样本不等于运行正常。

两层开关

先在设置启用通知并配置渠道,再为需要通知的设备开启告警。设备默认只监控、不告警。支持企业微信、钉钉、飞书、Slack、通用 Webhook 和通知插件。发送测试消息会使用页面当前填写的渠道。

默认规则

事件 条件
离线 连续 5 次失败
恢复 连续 3 次成功(默认开启 send_recovery)
丢包 1 分钟发送 ≥10 次且丢包率达到阈值(默认 20%),持续 2 分钟
延迟高 1 分钟平均延迟达到阈值(默认 100ms),持续 3 分钟
重复提醒 持续故障每 30 分钟
合并 10 秒窗口内合并事件

维护窗口可静默整机房或指定设备。多台同时异常时,先检查共同的上游交换机;关联提示提供线索,仍需现场确认。

TCPing

设备详情可扫描常用端口或自定义范围,再选择加入持续监控。单次扫描最多 1024 个端口,并发最多 32;每设备持续监控最多 16 个端口。TCP 连接被拒绝、超时或错误均记失败,历史与 ICMP 独立。连接成功只能证明端口可建立连接,不代表应用业务正常。

NETPULSE / KNOWLEDGE BASE

设备发现与端口定位

扫描发现

先核对网段,再手动扫描。网段扫描结合 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 子系统。文件上传后不会自动安装或应用配置;默认不覆盖同名文件。终端命令会直接作用于设备,配置完成后按设备要求保存。

NETPULSE / KNOWLEDGE BASE

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)。审阅时间范围和采样完整性,再将报告发送给他人。

NETPULSE / KNOWLEDGE BASE

安全与故障排查

访问控制

首次密码只能在运行程序的电脑(回环地址)上设置,至少 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 历史不能代替撤销。

NETPULSE / KNOWLEDGE BASE

开发、测试与发布

本地开发

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。请使用虚构数据复现,不要上传现场配置、日志、截图中的设备信息或凭据。

NETPULSE / KNOWLEDGE BASE

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 修正即可。

NETPULSE / KNOWLEDGE BASE

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 需要它时:

  1. 启动插件程序(一次调用启动一个进程,处理完就退出,不常驻);
  2. 把一个 JSON 请求写到它的标准输入(stdin),然后关闭标准输入;
  3. 从它的标准输出(stdout)读回一个 JSON 响应;
  4. 插件退出。退出码为 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. 超时 → 失败,进程被终止。
  2. 标准输出超过 1 MB → 失败。
  3. 退出码非 0 → 失败。原因取响应里的 error;没有则取标准错误的最后一行。
  4. 退出码为 0 且输出了带 ok 字段的 JSON 对象 → 按 ok 判定。
  5. 退出码为 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. 发布你的插件

  1. 目录里放一个 README:插件做什么、需要什么运行环境、每个设置项怎么填、有哪些副作用。
  2. 编译型插件同时提供源码和各平台的可执行文件;command 写成不带扩展名的 ["./名字"] 可跨平台。
  3. 升级时递增 version。新增设置项要给 default,这样老用户升级后不用重新配置; 删除或改名的设置项,旧值会在用户下次保存设置时自动清理。
  4. 不要依赖本文没有写明的行为;协议有不兼容变化时 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)