node-red-contrib-ikuai 1.2.2

爱快路由器节点：查询在线终端与系统状态、维护 MAC 访问控制，内置 400 多个 v4.0 接口并支持自定义扩展

npm install node-red-contrib-ikuai

node-red-contrib-ikuai

Node-RED 节点，用来读写爱快路由器的 v4.0 REST API：查询在线终端、系统状态和 MAC 规则，维护 MAC 访问控制，也可以直接调用接口。

内置接口清单覆盖爱快官方文档里的接口，也可以在配置节点里追加自己的条目。

节点

节点	类型名	说明
爱快	`ikuai-config`	配置节点，保存 API 地址、令牌和自定义接口
ikuai	`ikuai`	查询、封禁/解封，或调用指定接口

管理节点在面板的 network 分类下。

安装

环境要求：Node-RED 3.0 及以上，Node.js 18 及以上。没有第三方依赖。

从 npm 安装：

cd ~/.node-red
npm install node-red-contrib-ikuai

从本地源码安装：

cd ~/.node-red
npm install /path/to/node-red-contrib-ikuai

Docker 部署时在容器内执行，~/.node-red 对应镜像里的 /data。安装完成后重启 Node-RED。

配置节点

字段	说明
地址	API 根地址。内网直连填路由器地址，例如 `http://192.168.1.1`；通过爱快云访问填 `https://ikuai.work`。不要带路径
API 令牌	爱快后台生成的 API 令牌，请求时以 `Bearer` 发送。保存在 Node-RED 凭据文件里，不写进流程 JSON
超时	单次请求超时，默认 10000 毫秒
规则名前缀	封禁时创建的 MAC 规则名前缀，默认 `NR_`。完整规则名不超过 15 个字符
自定义接口	JSON 数组，用来补充内置清单之外的接口，格式见下文

「测试连接」会读取一次转发模式、规则数和在线终端数，不需要部署就能验证地址和令牌是否正确。

同一台路由器只建一个配置节点，多个管理节点共用它的客户端和接口清单。

操作方式

管理节点有三种操作。

方式	用法
便捷操作	选一个封装好的动作，见下表
调用接口	从内置清单里挑，或手填 key、`/api/v4.0/...` 路径，按接口定义带上方法、默认查询参数，输出 `results`
自定义请求	方法和路径自己填，用于临时调试

便捷操作

动作	结果
`online`	在线终端数组：`mac`、`ip`、`name`、`vendor`、`model`、`ssid`、`apName`、`signal`、`interface`、`wireless`
`terminals`	当日流量汇总：`mac`、`ip`、`name`、`up`、`down`、`total`
`static`	静态分配列表：`termname`、`mac`、`ip`、`blocked`、`online`、`hostname`、`enabled`。结果缓存 20 秒
`rules`	MAC 规则数组：`id`、`mac`、`enabled`、`tagname`、`comment`、`expires`
`mode`	`{ mode, name }`，`mode` 为 0 是黑名单，1 是白名单
`block`	封禁 MAC，返回 `{ ok, action, mac, ruleId }`
`unblock`	解封 MAC，返回 `{ ok, action, mac, ruleId }`
`test`	`{ ok, ms, mode, modeName, rules, blocked, online }`
`catalog`	当前生效的接口清单，可以在流程里动态生成下拉框

调用接口

选中接口后，接口列表下方会显示它的调用信息：

PUT  /api/v4.0/interfaces/lan-config/{id}
路径参数  id（msg.params.id）
查询参数  无
请求体    需要（JSON，用 msg.body 传，字段见官方文档）

路径参数从路径里的 {xxx} 解析，运行时漏传会报错并指出缺哪个
查询参数列出内置默认值，例如 page=1、limit=1000，可以用 msg.query 覆盖
请求体只标注需要或不需要。清单里没有字段级定义，具体字段以爱快官方文档为准
手填 /api/v4.0/... 裸路径也会显示，方法取「自定义请求」里的方法或 msg.method

输入

字段	说明
`msg.action`	覆盖节点里选的便捷操作
`msg.mac` / `msg.name`	封禁或解封的目标，也可以放在 `msg.payload.mac`
`msg.macs`	批量封禁或解封，MAC 字符串数组，或 `[{mac, name}]`
`msg.api`	覆盖节点里选的接口 key，也可以是完整路径
`msg.method` / `msg.path`	自定义请求用的方法和路径，覆盖节点里的填写
`msg.query` / `msg.body` / `msg.params`	查询参数、请求体、路径参数，`msg.params` 对应路径里的 `{id}`
`msg.full`	为 `true` 时输出完整返回体，默认只输出 `results`
`msg.refresh`	`static` 动作用，为 `true` 时跳过缓存重新取数
`msg.autoPage`	为 `false` 时关闭自动翻页，列表接口只返回第一页

输出

字段	说明
`msg.payload`	动作结果
`msg.ikuai`	`{ op, action/method/path/status, ms }`
`msg.error`	出错时包含 `message`、`code`、`status`、`path`

编辑面板里的 MAC 列表

编辑面板里有一个带搜索的 MAC 列表，数据来自静态分配接口，显示终端名和 MAC，并标出封禁与在线状态。

动作选「封禁 MAC」或「解封 MAC」时列表变成多选框：

勾选终端，部署后触发节点就对勾选项批量执行
勾选结果保存在节点配置里，和流程一起保存
「全选」只作用于当前筛选结果，「清空」清掉全部

其他动作下列表只读，用来对照终端名和地址，点任意一行复制它的 MAC。

支持按终端名、MAC、IP 搜索。IP 不占列表宽度，鼠标悬停可以看到
展开时读一次数据，点「刷新」从路由器重新取。服务端另有 20 秒缓存
列表只负责浏览和选择，不会修改路由器。需要按运行时的条件决定封谁，用 msg.macs，优先级高于面板里勾选的项

自定义接口

内置清单覆盖官方文档里的接口。遇到文档之外或固件新增的接口，在配置节点的「自定义接口」里追加：

[
  {
    "key": "mynet.wan",
    "name": "WAN 线路状态",
    "group": "我的接口",
    "method": "GET",
    "path": "/api/v4.0/monitoring/interfaces-status",
    "query": { "page": 1 }
  }
]

字段	必填	说明
`key`	是	唯一标识，管理节点里保存的就是它
`method`	是	`GET`、`POST`、`PUT`、`PATCH`、`DELETE`
`path`	是	以 `/api/` 开头，可以含 `{id}` 占位符
`name`	否	下拉框显示的文字，默认用 `key`
`group`	否	分组名，默认「自定义」
`query`	否	默认查询参数，运行时被 `msg.query` 覆盖
`body`	否	默认请求体，运行时被 `msg.body` 覆盖

写完点「校验 JSON」，语法或字段有问题会指出是第几条。

限制与处理方式

封禁只在黑名单模式下执行。 白名单模式下新增一条 MAC 规则等于放行，节点会拒绝执行并返回原因。
解封是停用规则，不删除。 规则保留着有记录，下次封同一个 MAC 会复用同一条，不会越积越多。
规则名必须唯一。 批量封禁传入相同备注名时，第二条起自动追加 MAC 尾号，例如 NR_批量自检_0012。
列表接口不传 limit 只返回 20 条。 爱快按 Web 后台一页的条数返回，total 是真实值，所以 32 条静态分配只看得到 20 条。节点对所有带 limit 的接口自动翻页取满，msg.autoPage=false 可以关掉；内置清单里的默认 limit 已统一为 1000。
列表接口不要传 order_by。 这类查询下固件会返回 total 正常但 data 为空数组，内置清单因此不预置排序参数。
规则名 15 个字符上限，备注和终端名里的特殊字符由节点自动清理。
MAC 访问控制在转发面生效，写操作不会中断 Wi-Fi，和无线接入控制那种需要重启射频的操作不同。
terminals 会把已下线终端一直列着，判断终端是否在线用 online。
online 的 wireless 字段依赖 SSID 和 AP 信息，只有 AP 由这台爱快做 AC 管理时才准确。独立 AP 下的无线终端在爱快看来同样是有线接入。

自检

不装 Node-RED 也能直接验证连通性和接口：

IKUAI_TOKEN=xxx node test/selftest.js
IKUAI_TOKEN=xxx node test/selftest.js write 02:00:00:00:00:01

第一条只读。第二条会对指定 MAC 建规则、解封、再删除，用来验证写链路。地址默认取 https://ikuai.work，内网直连时用 IKUAI_BASE_URL 指定。

License

MIT

Node Info

Version: 1.2.2

Updated 14 hours ago

License: MIT

Rating: not yet rated

View on npm

View on GitHub

View Scorecard 12

Actions

Downloads

0 in the last week

Nodes

ikuai-config
ikuai

Keywords

node-red
node-red-contrib
ikuai
router
firewall
mac
acl
network

Maintainers

kiven86