OpenWRT 路由器远程管理

要解决的问题

管理 OpenWRT 路由器时，很多人习惯通过 SSH 或 telnet 登录 shell。虽然可行，但这会把登录入口暴露到网络中，后续自动化也要处理端口、会话和密钥等细节。

本技能使用路由器自带的 LuCI Web 界面所暴露的 RPC API，以 HTTP Cookie 认证完成远程管理。你只需要一台可以访问路由器的机器和 curl，就能执行查询命令，不必额外开放 SSH 服务。

工作原理

认证流程分为三步：

1. 使用用户名和密码向 LuCI 登录页面发起 POST 请求
2. 保存返回的 sysauth Cookie（新版 LuCI 也可能返回 sysauth_http）
3. 携带该 Cookie 调用 cgi-bin/luci/rpc/sys，通过 exec 方法在路由器 shell 中执行命令

RPC 调用的请求体是 JSON，例如 {"method":"exec","params":["命令字符串"]}。返回结果同样为 JSON，error 字段为 null 表示执行成功。

该技能支持同时管理多台 OpenWRT 路由器。你可以在 TOOLS.md 中用别名（如“家”“租房”）记录不同路由器的 IP 与账号信息。如果路由器之间已经通过 WireGuard、Tailscale 或 FRP 等方案打通网络，只需切换目标 IP 即可从一台机器统一管理。

核心操作

1. 登录路由器

通过认证后，Cookie 文件中会包含 sysauth 或 sysauth_http token，后续每个 RPC 请求都要携带它。

2. 执行命令

所有命令由路由器的 shell 直接执行，支持管道 | 和重定向 > 等操作符。如果需要过滤输出，建议在后端用 Python 或 awk 处理，以减轻路由器的运行负担。

3. 常用查询命令

• 查看联网设备：综合查询 DHCP 动态租约、静态租约、ARP 表和 WiFi 列表，获得完整的设备清单
• 查看 DHCP 动态租约：列出通过 DHCP 获取 IP 的设备及其主机名
• 查看 DHCP 静态租约：读取用户在 LuCI 界面中手动绑定的 IP 与设备备注
• 查看 ARP 表：获取当前局域网中所有已知设备的 IP 与 MAC 对应关系
• 查看 WiFi 连接设备：显示无线客户端及其信号强度、速率等信息
• 查看系统负载、运行时间和活跃连接数

4. 设备发现与在线判定

为了给出可靠的在线状态，需要组合五种数据源：ARP 表、内核邻居表 ip neigh show、WiFi assoclist、DHCP 动态租约和 DHCP 静态租约。

在线判定规则如下：

• MAC 出现在 WiFi assoclist 中 → 在线
• ip neigh show 状态为 REACHABLE、DELAY 或 PROBE → 在线
• ip neigh show 状态为 STALE 或 FAILED → 不在线
• ARP Flags 只表示 MAC 地址已知，不能用来判断设备是否在线

设备名称的优先级为：DHCP 静态租约中的备注 > DHCP 动态租约中设备上报的主机名 > 无名称。

适用边界与注意点

• 路由器上需要有 curl 命令可用
• 用户必须提供路由器 IP、用户名和密码，或将其记录在 TOOLS.md 中
• 密码包含 @、#、$ 等特殊字符时，curl 的 -d 参数需要使用引号包裹
• 部分 OpenWRT 版本可能需要额外的 Cookie 路径设置
• 不同版本 LuCI 的 Cookie 名称可能不同，应使用 sysauth 进行模糊匹配
• 并非所有固件都预装了 iwinfo，新版本可能使用 iw 替代
• RPC API 返回的 \u000a 是 Unicode 换行符转义，在 Python 中需要使用 decode("unicode_escape") 或通过 JSON 反序列化处理