FanchmWrt ubus API 文档

FanchmWrt是完全开源的系统，可玩性非常高，并且具备商用路由器的功能，比如上网行为管理，为了方便AI接入系统，这里将核心功能的API接口文档开放出来，有了该接口文档，可以通过AI配置管理FanchmWrt，实时监控系统和终端状态，通过第三方聊天工具，甚至可以实现聊天式配置，只需要发送一条指令就可以完成系统状态的获取或者下发配置。比如可以让AI每天发送小孩的上网报告到家长的飞书，可以通过指令禁止小孩玩游戏、断网等，而不用登录路由器后台，可以随时随地非常灵活的配置管理。

1. 调用约定

fwxd是fanchmwrt中核心服务，用于维护终端列表、接口分发等。

fwxd 注册的 ubus 对象名为 fwx，业务接口统一通过 common 方法调用。请求体中的 api 用于指定业务接口，data 用于传递业务参数。

ubus call fwx common '{"api":"<api_name>","data":{}}'

可以通过ssh登录后台后调用ubus命令配置管理相关模块，同时也可以通过rpc方式请求ubus接口实现远程调用，而不用ssh登录路由器后台，只需要首次提取session id即可。

1.1 通用请求字段

字段类型必填取值范围示例描述
apistring是已注册的 API 名称get_dashboard_common业务接口名称
dataobject否JSON 对象{}业务参数；省略时处理器会使用整个请求对象作为参数

1.2 通用响应字段

字段类型取值范围示例描述
codeinteger2000 或 400020002000 表示成功，4000 表示请求、参数或处理失败
dataobject由具体接口定义{}成功时的业务数据；无数据或失败时可能不返回该字段

通用失败响应：

{
  "code": 4000
}

2. get_dashboard_common

获取 Dashboard 首页的系统状态、网络状态、活跃应用、活跃网址和接口速率数据。

  • 注册顺序：1
  • 接口类型：GET
  • 业务参数：无

2.1 请求示例

ubus call fwx common '{"api":"get_dashboard_common","data":{}}'

2.2 返回字段

system_status

字段类型取值范围/单位示例描述
data.system_status.modelstring设备型号或 UnknownFanchmWrt x86_64设备型号
data.system_status.cpu_model_namestringCPU 型号或 UnknownIntel(R) N100CPU 型号
data.system_status.hostnamestring主机名或 UnknownFanchmWrt系统主机名
data.system_status.openwrt_versionstringOpenWrt 版本或 UnknownFanchmWrt 26.05系统版本
data.system_status.archstringOpenWrt 架构或 Unknownx86_64软件包架构
data.system_status.fwx_versionstring版本号或 Unknown1.0.0FWX 版本
data.system_status.release_typeinteger当前实现默认为 00/etc/fwx_release 中的 RELEASE_TYPE
data.system_status.snapshotinteger通常为 0 或 10是否为快照版
data.system_status.release_datestring发布日期或空字符串26.05/etc/fwx_release 中的 RELEASE_DATE
data.system_status.expand_rootinteger通常为 0 或 11是否启用根分区扩展
data.system_status.kernel_versionstring内核版本或 Unknown6.6.93Linux 内核版本
data.system_status.uptimeinteger>= 0，秒86400系统运行时长
data.system_status.total_meminteger>= 0，KB4012340总内存
data.system_status.used_meminteger>= 0，KB862412已使用内存
data.system_status.cpustring0-10018CPU 使用率百分比，当前返回类型为字符串
data.system_status.connectionsinteger>= 0326当前 conntrack 连接数
data.system_status.client_numinteger>= 012当前在线终端数
data.system_status.storage.tmp.total_kbinteger>= 0，KB2019320/tmp 总容量
data.system_status.storage.tmp.used_kbinteger>= 0，KB18240/tmp 已使用容量
data.system_status.storage.root.total_kbinteger>= 0，KB1048576/ 总容量
data.system_status.storage.root.used_kbinteger>= 0，KB286720/ 已使用容量
data.system_status.storage.boot.total_kbinteger>= 0，KB131072/boot 总容量，未挂载时为 0
data.system_status.storage.boot.used_kbinteger>= 0，KB32768/boot 已使用容量，未挂载时为 0
data.system_status.flow.today_upinteger>= 0，KB153600今日上行流量
data.system_status.flow.today_downinteger>= 0，KB1048576今日下行流量
data.system_status.cpu_tempinteger有效时约 1-150，摄氏度48CPU 温度；获取失败时不返回该字段
data.system_status.wifi_tempinteger有效时约 1-150，摄氏度45Wi-Fi 温度；获取失败时不返回该字段

network_status

字段类型取值范围/单位示例描述
data.network_status.work_modeinteger由 appfilter.global.work_mode 定义1当前工作模式
data.network_status.internetinteger0 或 11互联网连接状态
data.network_status.lan.ipstringIPv4/IPv6 地址或空字符串192.168.1.1LAN IP 地址
data.network_status.lan.maskstring子网掩码或空字符串255.255.255.0LAN 子网掩码
data.network_status.lan.gatewaystringIP 地址或空字符串``LAN 网关
data.network_status.lan.dns[]array<string>0-2 项[]LAN DNS 服务器列表
data.network_status.wan.ipstringIPv4/IPv6 地址或空字符串10.0.0.2WAN IP 地址
data.network_status.wan.maskstring子网掩码或空字符串255.255.255.0WAN 子网掩码
data.network_status.wan.gatewaystringIP 地址或空字符串10.0.0.1WAN 网关
data.network_status.wan.dns[]array<string>0-2 项["223.5.5.5"]WAN DNS 服务器列表
data.network_status.port_status[]array<object>0 项或多项[]物理网口状态列表
data.network_status.port_status[].namestring网口名eth0物理网口名称
data.network_status.port_status[].rolestringlan/wan/unknownwan网口角色
data.network_status.port_status[].upinteger0 或 11链路是否连接
data.network_status.port_status[].speedinteger>= 0，Mbps1000网口协商速率
data.network_status.port_status[].macstringMAC 地址或空字符串00:11:22:33:44:55网口 MAC 地址
data.network_status.port_status[].duplexstringfull/half/空字符串full双工模式
data.network_status.port_status[].rx_bytesinteger>= 0，字节104857600累计接收字节数
data.network_status.port_status[].tx_bytesinteger>= 0，字节52428800累计发送字节数
data.network_status.port_status[].rx_packetsinteger>= 0120000累计接收包数
data.network_status.port_status[].tx_packetsinteger>= 086000累计发送包数
data.network_status.port_status[].rx_error_packetsinteger>= 00累计接收错误包数
data.network_status.port_status[].tx_error_packetsinteger>= 00累计发送错误包数

active_app、active_host 和 interface_traffic

字段类型取值范围/单位示例描述
data.active_app.totalinteger>= 01180 秒内更新的活跃应用记录数
data.active_app.list[]array<object>0 项或多项[]活跃应用列表
data.active_app.list[].idinteger>= 01002应用 ID
data.active_app.list[].namestring应用名或空字符串微信应用名称
data.active_app.list[].macstringMAC 地址14:d1:9e:7b:85:e4终端 MAC 地址
data.active_app.list[].hostnamestring主机名或空字符串phone终端主机名
data.active_app.list[].nicknamestring备注或空字符串我的手机终端备注
data.active_app.list[].src_ipstringIP 地址192.168.1.167源 IP
data.active_app.list[].dst_ipstringIP 地址203.0.113.10目的 IP
data.active_app.list[].src_portinteger0-6553552134源端口
data.active_app.list[].dst_portinteger0-65535443目的端口
data.active_app.list[].protocolstring传输层协议TCP协议名称
data.active_app.list[].app_protointeger由内核识别模块定义2应用层协议类型
data.active_app.list[].dropinteger0 或 10是否丢弃
data.active_app.list[].domainstring域名或空字符串weixin.qq.com识别到的域名
data.active_app.list[].uristringURI 或空字符串``HTTP URI，仅 app_proto=1 时可能返回
data.active_app.list[].timestampintegerUnix 时间戳，秒1782221547最后更新时间
data.active_host.totalinteger>= 01180 秒内的有效活跃网址总数
data.active_host.list[]array<object>最多 10 项[]按最后更新时间降序返回的活跃网址
data.active_host.list[].macstringMAC 地址14:d1:9e:7b:85:e4终端 MAC 地址
data.active_host.list[].namestring备注、主机名或 MAC我的手机优先使用备注，其次主机名，最后使用 MAC
data.active_host.list[].hostnamestring主机名或空字符串phone终端主机名
data.active_host.list[].nicknamestring备注或空字符串我的手机终端备注
data.active_host.list[].urlstringURL 或主机名https://www.example.com根据 app_proto 生成的访问地址
data.active_host.list[].hoststring有效主机名www.example.com原始主机名；undefined、null 等无效值会被过滤
data.active_host.list[].app_protointeger1 表示 HTTP，2 表示 HTTPS，其他值原样返回主机名2应用层协议类型
data.active_host.list[].timestampintegerUnix 时间戳，秒1782221547最后更新时间
data.interface_traffic.interfacestring网口名eth0Dashboard 当前监控的网口
data.interface_traffic.traffic[]array<object>固定 60 项[]网口速率采样列表，数据不足时补 0
data.interface_traffic.traffic[].upinteger>= 0，B/s24576上行速率
data.interface_traffic.traffic[].downinteger>= 0，B/s131072下行速率

2.3 返回示例

{
  "code": 2000,
  "data": {
    "system_status": {
      "model": "FanchmWrt x86_64",
      "cpu_model_name": "Intel(R) N100",
      "hostname": "FanchmWrt",
      "openwrt_version": "FanchmWrt 26.05",
      "arch": "x86_64",
      "fwx_version": "1.0.0",
      "release_type": 0,
      "snapshot": 0,
      "release_date": "26.05",
      "expand_root": 1,
      "kernel_version": "6.6.93",
      "uptime": 86400,
      "total_mem": 4012340,
      "used_mem": 862412,
      "cpu": "18",
      "connections": 326,
      "client_num": 12,
      "storage": {
        "tmp": { "total_kb": 2019320, "used_kb": 18240 },
        "root": { "total_kb": 1048576, "used_kb": 286720 },
        "boot": { "total_kb": 131072, "used_kb": 32768 }
      },
      "flow": { "today_up": 153600, "today_down": 1048576 },
      "cpu_temp": 48,
      "wifi_temp": 45
    },
    "network_status": {
      "work_mode": 1,
      "internet": 1,
      "lan": {
        "ip": "192.168.1.1",
        "mask": "255.255.255.0",
        "gateway": "",
        "dns": []
      },
      "wan": {
        "ip": "10.0.0.2",
        "mask": "255.255.255.0",
        "gateway": "10.0.0.1",
        "dns": ["223.5.5.5"]
      },
      "port_status": [
        {
          "name": "eth0",
          "role": "wan",
          "up": 1,
          "speed": 1000,
          "mac": "00:11:22:33:44:55",
          "duplex": "full",
          "rx_bytes": 104857600,
          "tx_bytes": 52428800,
          "rx_packets": 120000,
          "tx_packets": 86000,
          "rx_error_packets": 0,
          "tx_error_packets": 0
        }
      ]
    },
    "active_app": {
      "total": 1,
      "list": [
        {
          "id": 1002,
          "name": "微信",
          "mac": "14:d1:9e:7b:85:e4",
          "hostname": "phone",
          "nickname": "我的手机",
          "src_ip": "192.168.1.167",
          "dst_ip": "203.0.113.10",
          "src_port": 52134,
          "dst_port": 443,
          "protocol": "TCP",
          "app_proto": 2,
          "drop": 0,
          "domain": "weixin.qq.com",
          "uri": "",
          "timestamp": 1782221547
        }
      ]
    },
    "active_host": {
      "total": 1,
      "list": [
        {
          "mac": "14:d1:9e:7b:85:e4",
          "name": "我的手机",
          "hostname": "phone",
          "nickname": "我的手机",
          "url": "https://www.example.com",
          "host": "www.example.com",
          "app_proto": 2,
          "timestamp": 1782221547
        }
      ]
    },
    "interface_traffic": {
      "interface": "eth0",
      "traffic": [
        { "up": 24576, "down": 131072 },
        { "up": 20480, "down": 98304 }
      ]
    }
  }
}

示例中仅列出 2 个速率采样点，实际 traffic 数组固定返回 60 项。

3. get_history_session

获取 conntrack 连接数历史采样。服务每 5 秒采样一次，并每分钟保留一个长期采样点。

  • 注册顺序：2
  • 接口类型：GET

3.1 请求字段

字段类型必填取值范围示例描述
data.rangestring否5min/5m/hour/dayhour统计范围，默认为 hour
data.minutesinteger否1-1440120自定义分钟数；5min/5m 模式会忽略该字段，大于 1440 时按 1440 处理

3.2 请求示例

ubus call fwx common '{"api":"get_history_session","data":{"range":"hour"}}'

3.3 返回字段

字段类型取值范围/单位示例描述
data.rangestring5min/hour/dayhour实际返回的范围
data.minutesinteger5 或 1-1440，分钟60实际统计时长
data.currentinteger>= 0326当前 conntrack 连接数
data.avginteger>= 0301返回采样点的平均连接数
data.peakinteger>= 0412采样峰值，同时会与当前连接数比较
data.list[]array<integer>每项 >= 0[280, 301, 326]连接数采样；5min 最多 60 项，hour 默认最多 60 项，day 最多 1440 项

3.4 返回示例

{
  "code": 2000,
  "data": {
    "range": "hour",
    "minutes": 60,
    "current": 326,
    "avg": 301,
    "peak": 412,
    "list": [280, 295, 301, 318, 326]
  }
}

4. get_hourly_top_apps

获取指定终端某一天的每小时常用应用、流量和上网时长统计。每个小时最多返回 3 个应用。

  • 注册顺序：3
  • 接口类型：GET

4.1 请求字段

字段类型必填取值范围示例描述
data.macstring是已存在终端的 MAC 地址14:d1:9e:7b:85:e4目标终端 MAC 地址
data.dateinteger否当地时区当日 00:00:00 的 Unix 时间戳1782144000目标日期；省略时使用今天

4.2 请求示例

ubus call fwx common '{"api":"get_hourly_top_apps","data":{"mac":"14:d1:9e:7b:85:e4","date":1782144000}}'

4.3 返回字段

字段类型取值范围/单位示例描述
data.macstringMAC 地址14:d1:9e:7b:85:e4终端 MAC 地址
data.dateintegerUnix 时间戳，秒1782144000统计日期的当地 00:00:00
data.is_todayinteger0 或 11是否为今日实时数据
data.hourly_stats[]array<object>通常为 24 项[]0-23 时的逐小时统计
data.hourly_stats[].hourinteger0-2320小时
data.hourly_stats[].apps[]array<object>0-3 项[]该小时常用应用
data.hourly_stats[].apps[].appidinteger> 01002应用 ID
data.hourly_stats[].apps[].namestring应用名或 unknown微信应用名称
data.hourly_stats[].apps[].timeinteger0-3600，秒1260应用在该小时内的使用时长
data.hourly_stats[].traffic.up_bytesinteger>= 0，字节5242880该小时上行流量
data.hourly_stats[].traffic.down_bytesinteger>= 0，字节52428800该小时下行流量
data.hourly_stats[].online_timeinteger通常为 0-3600，秒3600该小时终端在线时长
data.hourly_stats[].active_timeinteger通常为 0-3600，秒2840该小时终端活跃时长

4.4 返回示例

{
  "code": 2000,
  "data": {
    "mac": "14:d1:9e:7b:85:e4",
    "date": 1782144000,
    "is_today": 1,
    "hourly_stats": [
      {
        "hour": 0,
        "apps": [],
        "traffic": {
          "up_bytes": 0,
          "down_bytes": 0
        },
        "online_time": 0,
        "active_time": 0
      },
      {
        "hour": 20,
        "apps": [
          { "appid": 1002, "name": "微信", "time": 1260 },
          { "appid": 3003, "name": "腾讯视频", "time": 720 }
        ],
        "traffic": {
          "up_bytes": 5242880,
          "down_bytes": 52428800
        },
        "online_time": 3600,
        "active_time": 2840
      }
    ]
  }
}

示例中仅列出 2 个小时的数据，实际当日响应会按 0-23 时返回 24 项。查询历史日期时，数据来自终端目录下的 stats/hourly_YYYY-MM-DD.json。

5. get_daily_top_apps

获取指定终端某天使用时长最长的应用。注册顺序：4，类型：GET。

字段方向类型必填/取值范围示例描述
data.mac请求/返回string请求必填，已存在的 MAC14:d1:9e:7b:85:e4目标终端
data.date请求/返回integer请求可选，当地 00:00:00 Unix 时间戳1782144000省略时为今天
data.is_today返回integer0/11是否为今日数据
data.count返回integer0-102返回应用数
data.apps[]返回array<object>最多 10 项[]应用列表
data.apps[].appid返回integer> 01002应用 ID
data.apps[].name返回string应用名或 unknown微信应用名称
data.apps[].total_time返回integer>= 0，秒7200当日使用时长
ubus call fwx common '{"api":"get_daily_top_apps","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"mac":"14:d1:9e:7b:85:e4","date":1782144000,"is_today":1,"count":2,"apps":[{"appid":1002,"name":"微信","total_time":7200},{"appid":3003,"name":"腾讯视频","total_time":3600}]}}

6. delete_record_files

按终端和日期范围删除上网记录文件。注册顺序：5，类型：POST。

字段方向类型必填/取值范围示例描述
data.mac请求string可选，MAC 或空14:d1:9e:7b:85:e4省略时处理所有终端
data.start_date请求string可选，YYYY-MM-DD 或 Unix 时间戳字符串2026-06-01起始日期，包含边界
data.end_date请求string可选，YYYY-MM-DD 或 Unix 时间戳字符串2026-06-30结束日期，日期格式包含当天
data.type请求string可选，visits/stats/allall删除类型，默认全部
data.message返回string固定提示Delete request processed请求已处理
ubus call fwx common '{"api":"delete_record_files","data":{"mac":"14:d1:9e:7b:85:e4","start_date":"2026-06-01","end_date":"2026-06-30","type":"all"}}'

{"code":2000,"data":{"message":"Delete request processed"}}

7. get_global_app_type_stats

获取全局应用分类使用时长排名。注册顺序：6，类型：GET。

字段方向类型必填/取值范围示例描述
data.type请求/返回string可选，daily/hourlydaily默认 daily；非 hourly 均按日统计
data.limit请求/返回integer1-1610默认 10，越界时使用 16
data.total_count返回integer0-168存在数据的分类总数
data.types[]返回array<object>最多 limit 项[]按使用时长排序
data.types[].app_type返回integer1-163应用分类 ID
data.types[].name返回string分类名社交应用分类名称
data.types[].total_time返回integer>= 0，秒28800分类使用时长
ubus call fwx common '{"api":"get_global_app_type_stats","data":{"type":"daily","limit":10}}'

{"code":2000,"data":{"type":"daily","limit":10,"total_count":2,"types":[{"app_type":3,"total_time":28800,"name":"社交"},{"app_type":5,"total_time":14400,"name":"视频"}]}}

8. get_global_traffic_stats

获取指定日期的全局逐小时流量。注册顺序：7，类型：GET。

字段方向类型必填/取值范围示例描述
data.date请求/返回integer可选，当地 00:00:00 Unix 时间戳1782144000省略时为今天
data.is_today返回integer0/11是否为实时数据
data.hourly_traffic[]返回array<object>今日固定 24 项[]逐小时流量
data.hourly_traffic[].hour返回integer0-2320小时
data.hourly_traffic[].traffic.up_bytes返回integer>= 0，字节5242880上行流量
data.hourly_traffic[].traffic.down_bytes返回integer>= 0，字节52428800下行流量
ubus call fwx common '{"api":"get_global_traffic_stats","data":{}}'

{"code":2000,"data":{"date":1782144000,"is_today":1,"hourly_traffic":[{"hour":0,"traffic":{"up_bytes":0,"down_bytes":0}},{"hour":20,"traffic":{"up_bytes":5242880,"down_bytes":52428800}}]}}

9. get_daily_top_users

获取今日总流量最高的终端。注册顺序：8，类型：GET，无业务参数。

字段类型取值范围/单位示例描述
data.dateinteger当地 00:00:00 Unix 时间戳1782144000今日日期
data.total_countinteger>= 012今日产生流量的终端总数
data.users[]array<object>最多 8 项[]按总流量降序排列
data.users[].macstringMAC14:d1:9e:7b:85:e4终端 MAC
data.users[].ipstringIP 或空192.168.1.167终端 IP
data.users[].hostnamestring主机名或空phone主机名
data.users[].nicknamestring备注或空我的手机终端备注
data.users[].up_bytesinteger>= 0，字节10485760今日上行
data.users[].down_bytesinteger>= 0，字节104857600今日下行
data.users[].total_bytesinteger>= 0，字节115343360今日总流量
ubus call fwx common '{"api":"get_daily_top_users","data":{}}'

{"code":2000,"data":{"date":1782144000,"total_count":1,"users":[{"mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","hostname":"phone","nickname":"我的手机","up_bytes":10485760,"down_bytes":104857600,"total_bytes":115343360}]}}

10. get_active_users

获取当前在线终端的速率、无线信号和今日流量。注册顺序：9，类型：GET。

字段方向类型必填/取值范围示例描述
data.count请求integer可选，1-10010返回数，默认 10，越界时回退到 10
data.total_count返回integer>= 012在线终端总数
data.users[]返回array<object>最多 count 项[]按当前总速率排序
data.users[].mac返回stringMAC14:d1:9e:7b:85:e4终端 MAC
data.users[].ip返回stringIP 或空192.168.1.167IP 地址
data.users[].hostname返回string主机名或空phone主机名
data.users[].nickname返回string备注或空我的手机备注
data.users[].up_rate返回integer>= 0，B/s20480当前上行速率
data.users[].down_rate返回integer>= 0，B/s131072当前下行速率
data.users[].rssi返回integerdBm，有线终端可为 0-48Wi-Fi 信号强度
data.users[].rx_rate返回integer>= 0，驱动上报单位866Wi-Fi 接收速率
data.users[].tx_rate返回integer>= 0，驱动上报单位780Wi-Fi 发送速率
data.users[].band返回string2.4G/5G/6G/空5GWi-Fi 频段
data.users[].wifi_ifname返回string无线网口或空phy0-ap0接入的 Wi-Fi 网口
data.users[].is_wireless返回integer0/11是否为无线终端
data.users[].terminal_type返回stringwired/wirelesswireless终端接入类型
data.users[].today_up_bytes返回integer>= 0，字节10485760今日上行流量
data.users[].today_down_bytes返回integer>= 0，字节104857600今日下行流量
data.users[].app返回string应用名或空微信当前访问应用
data.users[].url返回stringURL/域名或空weixin.qq.com当前访问网址
ubus call fwx common '{"api":"get_active_users","data":{"count":10}}'

{"code":2000,"data":{"total_count":1,"users":[{"mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","hostname":"phone","nickname":"我的手机","up_rate":20480,"down_rate":131072,"rssi":-48,"rx_rate":866,"tx_rate":780,"band":"5G","wifi_ifname":"phy0-ap0","is_wireless":1,"terminal_type":"wireless","today_up_bytes":10485760,"today_down_bytes":104857600,"app":"微信","url":"weixin.qq.com"}]}}

11. get_active_app_records

分页获取当前正在访问的应用记录。注册顺序：10，类型：GET。

字段方向类型取值范围示例描述
data.page请求/返回integer>= 1，默认 11页码
data.page_size请求/返回integer1-200，默认 1515每页数
data.total_num返回integer>= 05总记录数
data.total_page返回integer>= 11总页数
data.list[].mac返回stringMAC14:d1:9e:7b:85:e4终端 MAC
data.list[].hostname返回string主机名或空phone主机名
data.list[].nickname返回string备注或空我的手机备注
data.list[].name / appname返回string应用名微信新旧兼容字段，值相同
data.list[].id / appid返回integer> 01002新旧兼容应用 ID
data.list[].act / latest_action返回integer内核上报动作值0最新动作
data.list[].online返回integer固定 11当前活跃记录
data.list[].ft / first_time返回integerUnix 时间戳1782221235首次访问时间
data.list[].lt / latest_time返回integerUnix 时间戳1782221547最后访问时间
data.list[].tt / total_time返回integer>= 1，秒312访问时长
ubus call fwx common '{"api":"get_active_app_records","data":{"page":1,"page_size":15}}'

{"code":2000,"data":{"total_num":1,"total_page":1,"page":1,"page_size":15,"list":[{"mac":"14:d1:9e:7b:85:e4","hostname":"phone","nickname":"我的手机","name":"微信","id":1002,"act":0,"online":1,"ft":1782221235,"lt":1782221547,"tt":312,"appname":"微信","appid":1002,"latest_action":0,"first_time":1782221235,"latest_time":1782221547,"total_time":312}]}}

12. get_app_history_records

从 SQLite 历史库分页获取应用访问记录。注册顺序：11，类型：GET。

字段方向类型取值范围示例描述
data.mac请求string可选，MAC14:d1:9e:7b:85:e4按终端精确过滤
data.appid请求integer可选，> 01002按应用 ID 过滤，非正数表示不过滤
data.start_time请求integer可选，Unix 时间戳1782144000开始时间
data.end_time请求integer可选，Unix 时间戳1782230399结束时间；早于开始时会自动交换
data.page请求/返回integer>= 11页码
data.page_size请求/返回integer1-20015每页数
data.total_num返回integer>= 05总记录数
data.total_page返回integer>= 11总页数
data.list[]返回array<object>最多 page_size 项[]按结束时间降序列表
data.list[].mac返回stringMAC14:d1:9e:7b:85:e4终端 MAC
data.list[].hostname / nickname返回string字符串phone当前内存中的主机名和备注
data.list[].name / appname返回string应用名微信兼容别名
data.list[].id / appid返回integer> 01002兼容应用 ID
data.list[].act / latest_action返回integer动作值0兼容动作字段
data.list[].online返回integer固定 00历史记录
data.list[].ft / first_time返回integerUnix 时间戳1782221235开始时间
data.list[].lt / latest_time返回integerUnix 时间戳1782221547结束时间
data.list[].tt / total_time返回integer>= 0，秒312访问时长
ubus call fwx common '{"api":"get_app_history_records","data":{"mac":"14:d1:9e:7b:85:e4","page":1,"page_size":15}}'

{"code":2000,"data":{"total_num":1,"total_page":1,"page":1,"page_size":15,"list":[{"mac":"14:d1:9e:7b:85:e4","hostname":"phone","nickname":"我的手机","name":"微信","id":1002,"act":0,"online":0,"ft":1782221235,"lt":1782221547,"tt":312,"appname":"微信","appid":1002,"latest_action":0,"first_time":1782221235,"latest_time":1782221547,"total_time":312}]}}

13. get_filter_rules

获取全部应用过滤规则。注册顺序：12，类型：GET，无业务参数。

字段类型取值范围示例描述
data.list[]array<object>0 项或多项[]应用过滤规则
data.list[].idinteger> 01782221547规则 ID，新增时使用当前时间戳
data.list[].namestring字符串工作时间禁用视频规则名称
data.list[].modeinteger1/221适用所有终端，2适用指定终端
data.list[].user_macstringMAC 或空14:d1:9e:7b:85:e4指定终端 MAC
data.list[].user_namestring字符串我的手机终端显示名
data.list[].enabledinteger0/11规则开关
data.list[].filter_quicinteger0/11是否同时过滤 QUIC
data.list[].time_rules[]array<object>0 项或多项[]生效时间段
data.list[].time_rules[].weekdaysarray<integer>每项 0-6[1,2,3,4,5]星期，0为周日
data.list[].time_rules[].start_timestringHH:MM09:00开始时间
data.list[].time_rules[].end_timestringHH:MM18:00结束时间
data.list[].app_ids[]array<string>正整数或 start-end["3001-3099"]应用 ID 或 ID 范围
ubus call fwx common '{"api":"get_filter_rules","data":{}}'

{"code":2000,"data":{"list":[{"id":1782221547,"name":"工作时间禁用视频","mode":2,"user_mac":"14:d1:9e:7b:85:e4","user_name":"我的手机","enabled":1,"filter_quic":1,"time_rules":[{"start_time":"09:00","end_time":"18:00","weekdays":[1,2,3,4,5]}],"app_ids":["3001-3099"]}]}}

14. add_filter_rule

新增应用过滤规则。注册顺序：13，类型：POST。

字段类型必填/取值范围示例描述
data.namestring必填工作时间禁用视频规则名称
data.modeinteger必填，1/22全部/指定终端
data.user_mac / data.user_namestring指定终端时可选14:d1:9e:7b:85:e4终端 MAC/显示名
data.enabledinteger可选，0/1，默认 11规则开关
data.filter_quicinteger可选，0/1，默认 01QUIC 过滤开关
data.time_rulesarray<object>必填[{"weekdays":[1],"start_time":"09:00","end_time":"18:00"}]时间规则，子字段见 get_filter_rules
data.app_idsarray<string>必填["3001-3099","1002"]非法、非正数或倒置范围会被忽略
ubus call fwx common '{"api":"add_filter_rule","data":{"name":"工作时间禁用视频","mode":2,"user_mac":"14:d1:9e:7b:85:e4","user_name":"我的手机","enabled":1,"filter_quic":1,"time_rules":[{"weekdays":[1,2,3,4,5],"start_time":"09:00","end_time":"18:00"}],"app_ids":["3001-3099"]}}'

{"code":2000}

15. update_filter_rule

更新应用过滤规则。注册顺序：14，类型：POST。

字段类型必填/取值范围示例描述
data.idinteger必填，已存在规则 ID1782221547目标规则
data.name / mode / user_mac / user_name与新增接口相同可选2传入时更新
data.enabled / filter_quicinteger可选，0/11开关字段
data.time_rulesarray<object>可选[]新的时间规则
data.app_idsarray<string>可选["3001-3099"]新的应用列表

当前实现会在更新时先删除原 time_rule 和 app_id 列表；如果省略 time_rules 或 app_ids，对应原列表会被清空。

ubus call fwx common '{"api":"update_filter_rule","data":{"id":1782221547,"enabled":0,"time_rules":[{"weekdays":[1,2,3,4,5],"start_time":"09:00","end_time":"18:00"}],"app_ids":["3001-3099"]}}'

{"code":2000}

16. delete_filter_rule

删除应用过滤规则。注册顺序：15，类型：POST。

字段类型必填/取值范围示例描述
data.idinteger必填，已存在规则 ID1782221547目标规则
ubus call fwx common '{"api":"delete_filter_rule","data":{"id":1782221547}}'

{"code":2000}

17. get_user_basic_info

获取单个终端的实时基本信息和今日统计。注册顺序：16，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求/返回string请求必填，MAC14:d1:9e:7b:85:e4终端 MAC
data.ip / data.ipv6返回stringIP 或空192.168.1.167IPv4/IPv6 地址
data.nickname / data.hostname返回string字符串我的手机备注和主机名
data.online / data.active返回integer0/11在线和活跃状态
data.af_whitelist / data.mf_whitelist返回integer0/10应用过滤/MAC 过滤白名单命中状态
data.up_rate / data.down_rate返回integer>= 0，B/s20480当前上下行速率
data.rssi返回integerdBm-48Wi-Fi 信号
data.rx_rate / data.tx_rate返回integer>= 0866Wi-Fi 收发速率
data.band / data.wifi_ifname返回string字符串5GWi-Fi 频段和接口
data.is_wireless返回integer0/11是否无线
data.terminal_type返回stringwired/wirelesswireless接入类型
data.today_up_bytes / data.today_down_bytes返回integer>= 0，字节10485760今日上下行流量
data.today_online_time / data.today_active_time返回integer>= 0，秒21600今日在线/活跃时长
ubus call fwx common '{"api":"get_user_basic_info","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","ipv6":"","nickname":"我的手机","hostname":"phone","online":1,"active":1,"af_whitelist":0,"mf_whitelist":0,"up_rate":20480,"down_rate":131072,"rssi":-48,"rx_rate":866,"tx_rate":780,"band":"5G","wifi_ifname":"phy0-ap0","is_wireless":1,"terminal_type":"wireless","today_up_bytes":10485760,"today_down_bytes":104857600,"today_online_time":21600,"today_active_time":18000}}

18. get_online_offline_records

获取单个终端的上下线记录。注册顺序：17，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求/返回string必填，已存在的 MAC14:d1:9e:7b:85:e4终端 MAC
data.count返回integer>= 02记录数
data.records[].type返回integer由记录产生端定义1上下线记录类型
data.records[].timestamp返回integerUnix 时间戳1782221547事件时间
data.records[].duration返回integer>= 0，秒3600持续时长
data.records[].time_str返回stringYYYY-MM-DD HH:MM:SS2026-06-23 21:05:47本地化时间
data.records[].duration_str返回stringh/m/s 组合1h0m0s可读持续时长
ubus call fwx common '{"api":"get_online_offline_records","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"mac":"14:d1:9e:7b:85:e4","records":[{"type":1,"timestamp":1782221547,"duration":3600,"time_str":"2026-06-23 21:05:47","duration_str":"1h0m0s"}],"count":1}}

19. get_user_records

分页获取终端上下线汇总记录。注册顺序：18，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求string可选14:d1MAC 子串过滤
data.start_time / data.end_time请求integer可选，Unix 时间戳1782144000记录时间范围
data.page请求/返回integer>= 11页码
data.page_size请求/返回integer1-20015每页数
data.total_num / data.total_page返回integer>= 0 / >= 11总记录数/总页数
data.list[].timestamp返回integerUnix 时间戳1782221547事件时间
data.list[].time_str返回stringYYYY-MM-DD HH:MM:SS2026-06-23 21:05:47本地化时间
data.list[].action返回integer0/110上线，其他值按下线文案返回
data.list[].action_str返回stringonline/offlineoffline事件文案
data.list[].mac / nickname / hostname返回string字符串14:d1:9e:7b:85:e4终端标识信息
data.list[].up_bytes / down_bytes返回integer>= 0，字节10485760该会话上下行流量
data.list[].online_duration / active_duration返回integer>= 0，秒3600在线/活跃时长
data.list[].recent_apps[]返回array<object>最多 5 项[]最近应用
data.list[].recent_apps[].id / name返回integer/string应用 ID/名称1002应用信息
ubus call fwx common '{"api":"get_user_records","data":{"page":1,"page_size":15}}'

{"code":2000,"data":{"total_num":1,"total_page":1,"page":1,"page_size":15,"list":[{"timestamp":1782221547,"time_str":"2026-06-23 21:05:47","action":1,"action_str":"offline","mac":"14:d1:9e:7b:85:e4","nickname":"我的手机","hostname":"phone","up_bytes":10485760,"down_bytes":104857600,"online_duration":3600,"active_duration":3200,"recent_apps":[{"id":1002,"name":"微信"}]}]}}

20. get_appfilter_whitelist

获取应用过滤白名单。注册顺序：19，类型：GET，无业务参数。

字段类型取值范围示例描述
data.list[]array<object>0 项或多项[]白名单
data.list[].macstringMAC14:d1:9e:7b:85:e4终端 MAC
data.list[].nickname / hostnamestring字符串我的手机当前终端备注/主机名，终端不存在时为空
ubus call fwx common '{"api":"get_appfilter_whitelist","data":{}}'

{"code":2000,"data":{"list":[{"mac":"14:d1:9e:7b:85:e4","nickname":"我的手机","hostname":"phone"}]}}

21. add_appfilter_whitelist

批量添加应用过滤白名单。注册顺序：20，类型：POST。

字段类型必填/取值范围示例描述
data.mac_listarray<string>必填["14:d1:9e:7b:85:e4"]需添加的 MAC 列表
ubus call fwx common '{"api":"add_appfilter_whitelist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

22. del_appfilter_whitelist

删除应用过滤白名单项。注册顺序：21，类型：POST。

字段类型必填/取值范围示例描述
data.macstring必填，MAC14:d1:9e:7b:85:e4需删除的终端
ubus call fwx common '{"api":"del_appfilter_whitelist","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000}

23. get_app_filter_adv

获取应用过滤总开关。注册顺序：22，类型：GET，无业务参数。

字段类型取值范围示例描述
data.enableinteger通常为 0/11应用过滤总开关
ubus call fwx common '{"api":"get_app_filter_adv","data":{}}'

{"code":2000,"data":{"enable":1}}

24. set_app_filter_adv

设置应用过滤总开关。注册顺序：23，类型：POST。

字段类型必填/取值范围示例描述
data.enableinteger必填，建议 0/11应用过滤总开关
ubus call fwx common '{"api":"set_app_filter_adv","data":{"enable":1}}'

{"code":2000}

25. get_system_info

获取 FWX 基础系统配置。注册顺序：24，类型：GET，无业务参数。

字段类型取值范围示例描述
data.fwx.lan_ifnamestring接口名br-lanFWX 监听的 LAN 接口，未配置默认 br-lan
data.fwx.theme_modeinteger0/10主题模式，0浅色，1深色
ubus call fwx common '{"api":"get_system_info","data":{}}'

{"code":2000,"data":{"fwx":{"lan_ifname":"br-lan","theme_mode":0}}}

26. get_system_base_info

获取内核功能能力状态。注册顺序：25，类型：GET，无业务参数。

字段类型取值范围示例描述
data.user_session_enableinteger0/11/proc/net/fwx_user 是否存在
data.wireless_supportinteger可选，存在时固定 11系统支持无线功能；不支持时不返回该字段
ubus call fwx common '{"api":"get_system_base_info","data":{}}'

{"code":2000,"data":{"user_session_enable":1,"wireless_support":1}}

27. set_system_info

设置 FWX 基础系统配置。注册顺序：26，类型：POST。

字段类型必填/取值范围示例描述
data.fwxobject必填{}FWX 配置对象
data.fwx.lan_ifnamestring必填，长度 2-16br-lanLAN 接口名
data.fwx.theme_modeinteger/string可选，0/10主题模式，默认 0
ubus call fwx common '{"api":"set_system_info","data":{"fwx":{"lan_ifname":"br-lan","theme_mode":0}}}'

{"code":2000}

28. get_mac_filter_rules

获取 MAC 过滤规则。注册顺序：27，类型：GET，无业务参数。

字段类型取值范围示例描述
data.list[]array<object>0 项或多项[]MAC 过滤规则
data.list[].idinteger> 01782221547规则 ID
data.list[].namestring字符串儿童设备时长限制规则名称
data.list[].modeinteger1/221适用全部终端，2适用指定终端
data.list[].user_mac / user_namestringMAC/字符串14:d1:9e:7b:85:e4指定终端及显示名
data.list[].enabledinteger0/11规则开关
data.list[].time_modeinteger1/2/321时间段，2每日时长，3每日流量
data.list[].time_rules[].weekdaysarray<integer>每项 0-6[1,2,3,4,5]星期，0为周日
data.list[].time_rules[].start_time / end_timestringHH:MM，仅模式 109:00时间段起止
data.list[].time_rules[].duration_minutesinteger0-1440，仅模式 2120当日限制分钟数
data.list[].time_rules[].flow_mbinteger0-1048576，仅模式 31024当日限制流量，MB
data.list[].time_list[]array<string>模式 1 使用["1,2,3,4,5,09:00,18:00"]兼容的时间段字符串
data.list[].time_limitstring模式 2 使用1:120,2:120,3:120,4:120,5:120,6:0,0:0星期:分钟 列表
data.list[].flow_limitstring模式 3 使用1:1024,2:1024,3:1024,4:1024,5:1024,6:0,0:0星期:MB 列表
ubus call fwx common '{"api":"get_mac_filter_rules","data":{}}'

{"code":2000,"data":{"list":[{"id":1782221547,"name":"儿童设备时长限制","mode":2,"user_mac":"14:d1:9e:7b:85:e4","user_name":"我的手机","enabled":1,"time_limit":"1:120,2:120,3:120,4:120,5:120,6:0,0:0","flow_limit":"","time_mode":2,"time_rules":[{"weekdays":[1],"duration_minutes":120}],"time_list":[]}]}}

29. add_mac_filter_rule

新增 MAC 过滤规则。注册顺序：28，类型：POST。

字段类型必填/取值范围示例描述
data.namestring必填儿童设备时长限制规则名称
data.modeinteger必填，1/22全部/指定终端
data.time_modeinteger可选，1/2/3，默认 12限制模式
data.user_mac / user_namestring可选14:d1:9e:7b:85:e4指定终端
data.enabledinteger可选，0/1，默认 11规则开关
data.time_listarray<string>模式 1 时与 time_rules 二选一必填["1,2,3,4,5,09:00,18:00"]时间段列表
data.time_rulesarray<object>可替代对应模式的字符串字段[{"weekdays":[1],"duration_minutes":120}]结构化规则
data.time_limitstring模式 2 时与 time_rules 二选一必填1:120,2:120,3:120,4:120,5:120每日分钟限制
data.flow_limitstring模式 3 时与 time_rules 二选一必填1:1024,2:1024,3:1024,4:1024,5:1024每日 MB 限制
ubus call fwx common '{"api":"add_mac_filter_rule","data":{"name":"儿童设备时长限制","mode":2,"time_mode":2,"user_mac":"14:d1:9e:7b:85:e4","user_name":"我的手机","enabled":1,"time_limit":"1:120,2:120,3:120,4:120,5:120"}}'

{"code":2000}

30. update_mac_filter_rule

更新 MAC 过滤规则。注册顺序：29，类型：POST。

字段类型必填/取值范围示例描述
data.idinteger必填，已存在的 ID1782221547目标规则
data.name / mode / user_mac / user_name / enabled同新增接口可选0传入时更新
data.time_modeinteger可选，1/2/33新的限制模式
data.time_rules / time_list / time_limit / flow_limit同新增接口可选1:1024任一时间载荷存在时，会清除旧限制并按当前 time_mode 重建
ubus call fwx common '{"api":"update_mac_filter_rule","data":{"id":1782221547,"time_mode":3,"flow_limit":"1:1024,2:1024,3:1024,4:1024,5:1024"}}'

{"code":2000}

31. delete_mac_filter_rule

删除 MAC 过滤规则。注册顺序：30，类型：POST。

字段类型必填/取值范围示例描述
data.idinteger必填，已存在的 ID1782221547目标规则
ubus call fwx common '{"api":"delete_mac_filter_rule","data":{"id":1782221547}}'

{"code":2000}

32. get_mac_filter_whitelist

获取 MAC 过滤白名单。注册顺序：31，类型：GET，无业务参数。

字段类型取值范围示例描述
data.list[].macstringMAC14:d1:9e:7b:85:e4白名单 MAC
data.list[].nickname / hostnamestring字符串我的手机终端备注/主机名，未找到时为空
ubus call fwx common '{"api":"get_mac_filter_whitelist","data":{}}'

{"code":2000,"data":{"list":[{"mac":"14:d1:9e:7b:85:e4","nickname":"我的手机","hostname":"phone"}]}}

33. add_mac_filter_whitelist

批量添加 MAC 过滤白名单，已存在项会跳过。注册顺序：32，类型：POST。

字段类型必填/取值范围示例描述
data.mac_listarray<string>必填["14:d1:9e:7b:85:e4"]MAC 列表
ubus call fwx common '{"api":"add_mac_filter_whitelist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

34. del_mac_filter_whitelist

删除 MAC 过滤白名单项。注册顺序：33，类型：POST。

字段类型必填/取值范围示例描述
data.macstring必填，MAC14:d1:9e:7b:85:e4需删除的终端
ubus call fwx common '{"api":"del_mac_filter_whitelist","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000}

35. get_mac_filter_adv

获取 MAC 过滤总开关。注册顺序：34，类型：GET，无业务参数。

字段类型取值范围示例描述
data.enableinteger通常为 0/11MAC 过滤总开关
ubus call fwx common '{"api":"get_mac_filter_adv","data":{}}'

{"code":2000,"data":{"enable":1}}

36. set_mac_filter_adv

设置 MAC 过滤总开关。注册顺序：35，类型：POST。

字段类型必填/取值范围示例描述
data.enableinteger必填，建议 0/11MAC 过滤总开关
ubus call fwx common '{"api":"set_mac_filter_adv","data":{"enable":1}}'

{"code":2000}

37. get_record_base

获取上网审计基础配置和数据占用。注册顺序：36，类型：GET，无业务参数。

字段类型取值范围/单位示例描述
data.enableinteger通常为 0/11上网审计开关
data.record_timeinteger>= 0，天30历史记录保留天数
data.app_valid_timeinteger>= 0，秒5应用访问的最小有效时长
data.history_data_sizestring1-1024，MB，可为空100历史数据最大占用
data.history_data_pathstring目录/tmp/fwx历史数据目录
data.base_data_pathstring目录/tmp/fwx终端基础和实时数据目录
data.status.data_sizeinteger>= 0，KB20480历史根目录总占用
data.status.data_size_unitstring固定 KBKB占用单位
data.status.client_data_sizeinteger>= 0，KB4096client_data 占用
data.status.client_backup_sizeinteger>= 0，KB2048client_backup 占用
data.status.global_sizeinteger>= 0，KB8192global 占用
data.status.visit_db_sizeinteger>= 0，KB6144client.db 占用
ubus call fwx common '{"api":"get_record_base","data":{}}'

{"code":2000,"data":{"enable":1,"record_time":30,"app_valid_time":5,"history_data_size":"100","history_data_path":"/tmp/fwx","base_data_path":"/tmp/fwx","status":{"data_size":20480,"data_size_unit":"KB","client_data_size":4096,"client_backup_size":2048,"global_size":8192,"visit_db_size":6144}}}

38. set_record_base

设置上网审计基础配置。注册顺序：37，类型：POST。目录变更时会尝试迁移原数据。

字段类型必填/取值范围示例描述
data.enableinteger可选，负数按 01审计开关
data.record_timeinteger可选，>= 0，天30保留天数
data.app_valid_timeinteger可选，>= 0，秒5最小有效应用时长
data.history_data_sizestring可选，空或 1-1024100最大历史数据占用，MB
data.history_data_pathstring必填，非 /，长度 1-64/etc/fwx历史数据目录
data.base_data_pathstring必填，非 /，长度 1-64/etc/fwx基础数据目录
data.terminal_data_pathstring可选，兼容旧字段/etc/fwxbase_data_path 为空时作为兼容值
ubus call fwx common '{"api":"set_record_base","data":{"enable":1,"record_time":30,"app_valid_time":5,"history_data_size":"100","history_data_path":"/etc/fwx","base_data_path":"/etc/fwx"}}'

{"code":2000}

39. get_record_whitelist

分页获取上网审计白名单。注册顺序：38，类型：GET。

字段方向类型取值范围示例描述
data.page请求/返回integer>= 1，默认 11页码
data.page_size请求/返回integer1-200，默认 1515每页数
data.total_num / total_page返回integer>= 0 / >= 11总数/总页数
data.list[].mac返回stringMAC14:d1:9e:7b:85:e4白名单 MAC
data.list[].nickname / hostname返回string字符串我的手机当前终端备注/主机名
ubus call fwx common '{"api":"get_record_whitelist","data":{"page":1,"page_size":15}}'

{"code":2000,"data":{"total_num":1,"total_page":1,"page":1,"page_size":15,"list":[{"mac":"14:d1:9e:7b:85:e4","nickname":"我的手机","hostname":"phone"}]}}

40. add_record_whitelist

批量追加上网审计白名单，无效或重复 MAC 会被忽略。注册顺序：39，类型：POST。

字段类型必填/取值范围示例描述
data.mac_listarray<string>必填["14:d1:9e:7b:85:e4"]MAC 列表
ubus call fwx common '{"api":"add_record_whitelist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

41. del_record_whitelist

删除上网审计白名单项。注册顺序：40，类型：POST。

字段类型必填/取值范围示例描述
data.macstring必填，合法 MAC14:d1:9e:7b:85:e4需删除的 MAC
ubus call fwx common '{"api":"del_record_whitelist","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000}

42. set_record_whitelist

全量替换上网审计白名单。注册顺序：41，类型：POST。

字段类型必填/取值范围示例描述
data.mac_listarray<string>必填，可为空数组["14:d1:9e:7b:85:e4"]新的完整白名单
ubus call fwx common '{"api":"set_record_whitelist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

43. update_record_whitelist

set_record_whitelist 的兼容别名，请求和响应字段完全相同。注册顺序：42，类型：POST。

字段类型必填/取值范围示例描述
data.mac_listarray<string>必填["14:d1:9e:7b:85:e4"]新的完整白名单
ubus call fwx common '{"api":"update_record_whitelist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

44. record_action

执行上网审计数据操作。注册顺序：43，类型：POST。

字段类型必填/取值范围示例描述
data.actionstring必填，当前仅 clean_all_dataclean_all_data清空终端数据、备份、全局统计和历史库表
ubus call fwx common '{"api":"record_action","data":{"action":"clean_all_data"}}'

{"code":2000}

54. get_lan_info

获取主 LAN 接口及 DHCP 服务配置。注册顺序：53，类型：GET，无业务参数。

字段类型取值范围/单位示例描述
data.ipaddr / netmaskstringIP/掩码192.168.1.1LAN 地址
data.protostring协议staticLAN 协议
data.gateway / dns1 / dns2stringIP 或空223.5.5.5网关和最多两个 DNS
data.dhcp.enableinteger0/11DHCP 服务开关
data.dhcp.startinteger>= 0100DHCP 起始主机号
data.dhcp.limitinteger>= 0150DHCP 地址数
data.dhcp.leasetimeinteger>= 0，分钟720DHCP 租期
ubus call fwx common '{"api":"get_lan_info","data":{}}'

{"code":2000,"data":{"ipaddr":"192.168.1.1","netmask":"255.255.255.0","proto":"static","gateway":"","dns1":"223.5.5.5","dns2":"","dhcp":{"enable":1,"start":100,"limit":150,"leasetime":720}}}

55. set_lan_info

设置主 LAN 接口及 DHCP，成功后重启 network 和 dnsmasq。注册顺序：54，类型：POST。

字段类型必填/取值范围示例描述
data.ipaddr / netmaskstring可选，IP/掩码192.168.1.1IP 以 CIDR list 形式保存，无效掩码默认 /24
data.protostring可选，不允许 pppoestaticLAN 协议
data.gateway / dns1 / dns2string可选223.5.5.5网关和 DNS
data.dhcp.enableinteger可选，0/11DHCP 开关
data.dhcp.start / limitinteger可选，>= 0100起始主机号/地址数
data.dhcp.leasetimeinteger可选，>= 0，分钟720租期，大于 60 时按整小时写入 UCI
ubus call fwx common '{"api":"set_lan_info","data":{"ipaddr":"192.168.1.1","netmask":"255.255.255.0","proto":"static","dns1":"223.5.5.5","dns2":"","dhcp":{"enable":1,"start":100,"limit":150,"leasetime":720}}}'

{"code":2000}

56. get_wan_info

获取主 WAN 接口配置。注册顺序：55，类型：GET，无业务参数。

字段类型取值范围示例描述
data.protostringdhcp/static/pppoepppoeWAN 协议
data.ipaddr / netmask / gatewaystringIP/掩码或空10.0.0.2静态网络参数
data.dns1 / dns2stringIP 或空223.5.5.5DNS
data.username / passwordstring字符串user@examplePPPoE 账号和密码
ubus call fwx common '{"api":"get_wan_info","data":{}}'

{"code":2000,"data":{"ipaddr":"","netmask":"","proto":"pppoe","gateway":"","dns1":"","dns2":"","username":"user@example","password":"secret"}}

57. set_wan_info

设置主 WAN 接口，成功后 reload network。注册顺序：56，类型：POST。

字段类型必填/取值范围示例描述
data.protostring可选，dhcp/static/pppoepppoe省略时使用现有协议；无现有值则失败
data.ipaddr / netmask / gatewaystringstatic 时可选10.0.0.2静态参数
data.dns1 / dns2stringstatic 时可选223.5.5.5DNS
data.username / passwordstringpppoe 时可选，非空才更新user@examplePPPoE 凭据
ubus call fwx common '{"api":"set_wan_info","data":{"proto":"pppoe","username":"user@example","password":"secret"}}'

{"code":2000}

58. get_wireless_base_setting

获取每个无线 radio 的第一个 Wi-Fi 接口配置。注册顺序：57，类型：GET，无业务参数。

字段类型取值范围示例描述
data.ssid_list[].radiostringradio sectionradio0无线射频 section
data.ssid_list[].sectionstringwifi-iface sectiondefault_radio0Wi-Fi 接口 section
data.ssid_list[].bandstring2.4G/5G/6G 等5G频段标签
data.ssid_list[].ssidstring字符串FanchmWrt-5GSSID
data.ssid_list[].passwordstring密码或空12345678无线密码
data.ssid_list[].encryptionstringUCI 加密值sae-mixed加密方式，未配置为 none
data.ssid_list[].hidden / isolateinteger0/10隐藏 SSID/客户端隔离
ubus call fwx common '{"api":"get_wireless_base_setting","data":{}}'

{"code":2000,"data":{"ssid_list":[{"radio":"radio0","section":"default_radio0","band":"5G","ssid":"FanchmWrt-5G","password":"12345678","encryption":"sae-mixed","hidden":0,"isolate":0}]}}

59. set_wireless_base_setting

批量更新无线 SSID，有变更时执行 wifi reload。注册顺序：58，类型：POST。

字段类型必填/取值范围示例描述
data.ssid_listarray<object>/object必填[]更新列表或键值对象
data.ssid_list[].sectionstring与 radio 至少一个有效default_radio0优先按 section 定位
data.ssid_list[].radiostring可选radio0section 无效时使用 radio 的第一个接口
data.ssid_list[].ssidstring可选FanchmWrt-5G新 SSID
data.ssid_list[].encryptionstring可选sae-mixed加密；空值按 none
data.ssid_list[].passwordstring可选12345678非开放加密时更新；开放网络会删除 key
data.ssid_list[].hidden / isolateboolean/integer/string可选，布尔值0隐藏/隔离开关
ubus call fwx common '{"api":"set_wireless_base_setting","data":{"ssid_list":[{"section":"default_radio0","ssid":"FanchmWrt-5G","encryption":"sae-mixed","password":"12345678","hidden":0,"isolate":0}]}}'

{"code":2000}

60. get_work_mode

获取 FWX 工作模式。注册顺序：59，类型：GET，无业务参数。

字段类型取值范围示例描述
data.work_modeinteger0/100网关模式，1旁路模式；非法配置回退到 0
ubus call fwx common '{"api":"get_work_mode","data":{}}'

{"code":2000,"data":{"work_mode":0}}

61. set_work_mode

设置 FWX 工作模式并同步内核参数。注册顺序：60，类型：POST。

字段类型必填/取值范围示例描述
data.work_modeinteger必填，0/110网关模式，1旁路模式
ubus call fwx common '{"api":"set_work_mode","data":{"work_mode":1}}'

{"code":2000}

62. set_nickname

设置或清除终端备注。注册顺序：61，类型：POST。

字段类型必填/取值范围示例描述
data.macstring必填，MAC14:d1:9e:7b:85:e4终端 MAC
data.nicknamestring必填，可为空我的手机非空时设置，空字符串时删除备注
ubus call fwx common '{"api":"set_nickname","data":{"mac":"14:d1:9e:7b:85:e4","nickname":"我的手机"}}'

{"code":2000}

63. get_mac_blacklist

获取禁止上网的 MAC 黑名单。注册顺序：62，类型：GET，无业务参数。

字段类型取值范围示例描述
data.list[].macstringMAC14:d1:9e:7b:85:e4黑名单 MAC
data.list[].hostname / nicknamestring字符串或 --phone终端信息，未找到时为 --
ubus call fwx common '{"api":"get_mac_blacklist","data":{}}'

{"code":2000,"data":{"list":[{"mac":"14:d1:9e:7b:85:e4","hostname":"phone","nickname":"我的手机"}]}}

64. add_mac_blacklist

添加单个或批量 MAC 黑名单，最多支持 64 个终端。注册顺序：63，类型：POST。

字段类型必填/取值范围示例描述
data.macstring与 mac_list 至少一个有效14:d1:9e:7b:85:e4单个 MAC
data.mac_listarray<string>可选["14:d1:9e:7b:85:e4"]批量 MAC，重复项跳过
ubus call fwx common '{"api":"add_mac_blacklist","data":{"mac_list":["14:d1:9e:7b:85:e4"]}}'

{"code":2000}

65. del_mac_blacklist

删除 MAC 黑名单项。注册顺序：64，类型：POST。

字段类型必填/取值范围示例描述
data.macstring必填，合法 MAC14:d1:9e:7b:85:e4需删除的 MAC
ubus call fwx common '{"api":"del_mac_blacklist","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000}

66. dev_visit_list

分页获取单个终端的内存应用访问记录，当前访问记录排在历史记录之前。注册顺序：65，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求/返回string请求必填，MAC14:d1:9e:7b:85:e4终端 MAC
data.page / page_size请求/返回integer>= 1，默认 1/151分页参数，当前未限制 page_size 上限
data.hostname / ip返回string字符串phone终端主机名/IP
data.ipv6返回string可选``当终端未找到时返回空字符串；当前找到终端的分支未添加该字段
data.total_num / total_page返回integer>= 0 / >= 15总数/总页数
data.list[].name返回string应用名微信应用名称
data.list[].id返回integer> 01002应用 ID
data.list[].act返回integer动作值0最新动作
data.list[].online返回integer0/11访问是否仍在继续
data.list[].ft / lt返回integerUnix 时间戳1782221547首次/最后时间
data.list[].tt返回integer>= 0，秒312持续时长
ubus call fwx common '{"api":"dev_visit_list","data":{"mac":"14:d1:9e:7b:85:e4","page":1,"page_size":15}}'

{"code":2000,"data":{"hostname":"phone","mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","total_num":1,"total_page":1,"page":1,"page_size":15,"list":[{"name":"微信","id":1002,"act":0,"online":1,"ft":1782221235,"lt":1782221547,"tt":312}]}}

67. dev_visit_time

获取单个终端按应用汇总的访问时长。注册顺序：66，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求string必填，MAC14:d1:9e:7b:85:e4终端 MAC
data.total_num返回integer>= 02应用数
data.list[].id / name返回integer/string应用 ID/名称1002应用信息
data.list[].t返回integer>= 0，秒7200累计访问时长
ubus call fwx common '{"api":"dev_visit_time","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"list":[{"id":1002,"name":"微信","t":7200}],"total_num":1}}

68. app_class_visit_time

获取单个终端按应用分类汇总的访问时长。注册顺序：67，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求string必填，MAC14:d1:9e:7b:85:e4终端 MAC
data.class_list[].type返回integer0-152分类索引
data.class_list[].name返回string分类名社交分类名称
data.class_list[].visit_time返回integer>= 0，秒7200分类访问时长
ubus call fwx common '{"api":"app_class_visit_time","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"class_list":[{"type":2,"name":"社交","visit_time":7200}]}}

69. dev_list

获取所有终端及每个终端的前 5 个常用应用。注册顺序：68，类型：GET，无业务参数。

字段类型取值范围/单位示例描述
data.dev_list[].mac / ip / ipv6string字符串14:d1:9e:7b:85:e4终端地址信息
data.dev_list[].hostname / nicknamestring字符串phone主机名/备注
data.dev_list[].onlineinteger0/11在线状态
data.dev_list[].visit_info[]array<object>最多 5 项[]常用应用
data.dev_list[].visit_info[].appid / appnameinteger/string应用 ID/名称1002应用信息
data.dev_list[].visit_info[].latest_timeinteger>= 0，秒7200字段名为历史兼容名，实际值是累计访问时长
ubus call fwx common '{"api":"dev_list","data":{}}'

{"code":2000,"data":{"dev_list":[{"mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","ipv6":"","hostname":"phone","nickname":"我的手机","online":1,"visit_info":[{"appid":1002,"appname":"微信","latest_time":7200}]}]}}

70. class_list

解析 /tmp/feature.cfg 获取应用分类及应用列表。注册顺序：69，类型：GET，无业务参数。

字段类型取值范围示例描述
data.class_list[].namestring分类名社交特征库分类名
data.class_list[].app_list[]array<string>appid,name,with_icon1002,微信,1应用信息字符串，with_icon 为 0/1
ubus call fwx common '{"api":"class_list","data":{}}'

{"code":2000,"data":{"class_list":[{"name":"社交","app_list":["1002,微信,1","1006,钉钉,0"]}]}}

71. get_all_users

获取终端列表，flag 决定返回的详细程度。注册顺序：70，类型：GET。

字段方向类型取值范围/单位示例描述
data.flag请求integer>= 0，默认 03>0增加 IP，>1增加名称，>2增加应用、速率和今日统计
data.page请求/返回integer0 表示不分页，>=1启用分页1页码
data.page_size请求/返回integer>=1，默认 1515每页数；未分页时返回总数
data.total_num / total_page返回integer>=0 / >=11总数/总页数
data.list[].mac返回stringMAC14:d1:9e:7b:85:e4终端 MAC
data.list[].pc_status / pc_status_key返回stringunlimited/app_limited/mac_blockedunlimited行为管理状态
data.list[].in_blacklist / af_whitelist / mf_whitelist返回integer0/10黑名单及两类白名单状态
data.list[].online / active / is_wireless返回integer0/11在线、活跃和无线状态
data.list[].terminal_type返回stringwired/wirelesswireless接入类型
data.list[].session返回integer>=025当前会话数
data.list[].online_time / offline_time返回integerUnix 时间戳或 01782220000最近上线/下线时间
data.list[].ip / ipv6返回stringflag > 0 时存在192.168.1.167IP 地址
data.list[].hostname / nickname返回stringflag > 1 时存在phone主机名/备注
data.list[].applist[]返回array<object>flag > 2，最多 5 项[]常用应用，子字段为 id、name
data.list[].app_id / app / url返回integer/string/stringflag > 21002当前应用 ID、名称和网址
data.list[].up_rate / down_rate返回integerflag > 2，B/s20480当前速率
data.list[].rssi / rx_rate / tx_rate返回integerflag > 2-48Wi-Fi 信号和速率
data.list[].band / wifi_ifname返回stringflag > 25GWi-Fi 频段/接口
data.list[].today_up_bytes / today_down_bytes返回integerflag > 2，字节10485760今日流量
data.list[].today_active_time返回integerflag > 2，秒18000今日活跃时长
data.list[].today_active_minutes返回integerflag > 2，分钟300今日活跃分钟
ubus call fwx common '{"api":"get_all_users","data":{"flag":3,"page":1,"page_size":15}}'

{"code":2000,"data":{"list":[{"mac":"14:d1:9e:7b:85:e4","pc_status":"unlimited","pc_status_key":"unlimited","in_blacklist":0,"af_whitelist":0,"mf_whitelist":0,"online":1,"active":1,"is_wireless":1,"terminal_type":"wireless","session":25,"online_time":1782220000,"offline_time":0,"ip":"192.168.1.167","ipv6":"","hostname":"phone","nickname":"我的手机","applist":[{"id":1002,"name":"微信"}],"url":"weixin.qq.com","app_id":1002,"app":"微信","up_rate":20480,"down_rate":131072,"rssi":-48,"rx_rate":866,"tx_rate":780,"band":"5G","wifi_ifname":"phy0-ap0","today_up_bytes":10485760,"today_down_bytes":104857600,"today_active_time":18000,"today_active_minutes":300}],"total_num":1,"total_page":1,"page":1,"page_size":15}}

72. get_parental_control_detail

获取终端当前实际生效的应用过滤和 MAC 过滤规则详情。注册顺序：71，类型：GET。

字段方向类型取值范围示例描述
data.mac请求string可选，建议必填 MAC14:d1:9e:7b:85:e4目标终端；省略时返回默认空状态
data.pc_status / pc_status_key返回stringunlimited/app_limited/mac_blockedapp_limited当前权限状态
data.af_whitelist / mf_whitelist返回integer0/10应用/MAC 过滤白名单命中状态
data.appfilter_rules[]返回array<object>0 项或多项[]命中应用过滤规则；应用白名单命中时为空
data.appfilter_rules[].rule_id / rule_name返回integer/string规则信息1782221547规则 ID/名称
data.appfilter_rules[].mode / user_mac返回integer/string1/2，MAC2适用模式和指定终端
data.appfilter_rules[].time_rules返回array<object>时间段[]规则时间段
data.appfilter_rules[].category_ids返回array<integer>分类 ID[3]规则包含的应用分类
data.appfilter_rules[].category_stats[]返回array<object>id/count{"id":3,"count":99}每个分类包含的应用 ID 数
data.appfilter_rules[].category_count / app_count返回integer>=01分类数/应用 ID 数
data.macfilter_rules[]返回array<object>0 项或多项[]命中 MAC 规则；MAC 白名单命中时为空
data.macfilter_rules[].rule_id / rule_name返回integer/string规则信息1782221548规则 ID/名称
data.macfilter_rules[].mode / time_mode返回integer1/2，1-32适用模式/限制模式
data.macfilter_rules[].user_mac返回stringMAC14:d1:9e:7b:85:e4指定终端
data.macfilter_rules[].match_type返回stringtime_range/duration/flow/blacklistduration命中类型
data.macfilter_rules[].time_rules / duration_rules / flow_rules返回array<object>按 time_mode 返回其一[]时间段/时长/流量规则
ubus call fwx common '{"api":"get_parental_control_detail","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"pc_status":"app_limited","pc_status_key":"app_limited","af_whitelist":0,"mf_whitelist":0,"appfilter_rules":[{"rule_id":1782221547,"rule_name":"工作时间禁用视频","mode":2,"user_mac":"14:d1:9e:7b:85:e4","time_rules":[{"weekdays":[1,2,3,4,5],"start_time":"09:00","end_time":"18:00"}],"category_ids":[3],"category_stats":[{"id":3,"count":99}],"category_count":1,"app_count":99}],"macfilter_rules":[]}}

73. get_user_parental_control_rules

计算指定终端的所有适用规则、今日使用进度和当前权限。注册顺序：72，类型：GET。

字段方向类型取值范围示例描述
data.mac请求/返回string建议必填，MAC14:d1:9e:7b:85:e4目标终端
data.af_whitelist / mf_whitelist返回integer0/10白名单命中状态
data.list[].module返回stringappfilter/macfilter/blacklistmacfilter规则来源
data.list[].rule_id / rule_name返回integer/string规则信息1782221548规则 ID/名称
data.list[].condition_type返回stringtime_range/duration/flow/blacklistduration条件类型
data.list[].condition返回object按类型包含 time_rules、duration_rules 或 flow_rules{}规则条件
data.list[].today_status.matched返回integer0/1，时间段/黑名单1当前是否命中
data.list[].today_status.used / limit返回integer/double时长模式为分钟，流量模式为 MB120今日已用/限额
data.list[].today_status.progress_percent返回integer0-10080进度百分比
data.list[].today_status.effective_today / exceeded / unlimited返回integer0/10今日有规则/已超额/不限制
data.list[].permission_key / permission_text返回stringunlimited/app_limited/mac_blockedunlimited当前权限
ubus call fwx common '{"api":"get_user_parental_control_rules","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"mac":"14:d1:9e:7b:85:e4","af_whitelist":0,"mf_whitelist":0,"list":[{"module":"macfilter","rule_id":1782221548,"rule_name":"每日两小时","condition_type":"duration","condition":{"duration_rules":[{"weekdays":[1],"duration_minutes":120}]},"today_status":{"used":90,"limit":120,"progress_percent":75,"effective_today":1,"exceeded":0,"unlimited":0},"permission_key":"unlimited","permission_text":"unlimited"}]}}

74. get_user_stat

获取全部终端的今日活跃时长和流量，主要供规则管理脚本使用。注册顺序：73，类型：GET，无业务参数。

字段类型取值范围/单位示例描述
data.ninteger>= 01终端数
data.l[].mstringMAC14:d1:9e:7b:85:e4终端 MAC
data.l[].atinteger>= 0，秒18000今日活跃时长
data.l[].uf / dfinteger>= 0，字节10485760今日上行/下行流量
ubus call fwx common '{"api":"get_user_stat","data":{}}'

{"code":2000,"data":{"l":[{"m":"14:d1:9e:7b:85:e4","at":18000,"uf":10485760,"df":104857600}],"n":1}}

75. get_oaf_status

获取 OAF 识别引擎状态和版本。注册顺序：74，类型：GET，无业务参数。

字段类型取值范围示例描述
data.enableinteger通常为 0/11/proc/sys/oaf/enable 值
data.versionstringFWXD 定义版本1.0.3API/OAF 版本
data.engine_statusinteger0/11OAF proc 节点是否可用
data.engine_versionstring版本或空1.0.3/proc/sys/oaf/version
data.kernel_versionstring内核版本或空6.6.93uname -r
ubus call fwx common '{"api":"get_oaf_status","data":{}}'

{"code":2000,"data":{"enable":1,"version":"1.0.3","engine_status":1,"engine_version":"1.0.3","kernel_version":"6.6.93"}}

76. visit_list

获取一个或所有终端的完整内存应用访问列表。注册顺序：75，类型：GET。

字段方向类型取值范围/单位示例描述
data.mac请求string可选，MAC14:d1:9e:7b:85:e4精确过滤；省略时返回所有终端
data.dev_list[].hostname / mac / ip / ipv6返回string字符串phone终端信息
data.dev_list[].visit_info[].appname / appid返回string/integer应用名/ID微信应用信息
data.dev_list[].visit_info[].latest_action返回integer动作值0最新动作
data.dev_list[].visit_info[].online返回integer0/11访问是否正在继续
data.dev_list[].visit_info[].first_time / latest_time返回integerUnix 时间戳1782221547首次/最后访问时间
data.dev_list[].visit_info[].total_time返回integer>= 0，秒312访问时长
ubus call fwx common '{"api":"visit_list","data":{"mac":"14:d1:9e:7b:85:e4"}}'

{"code":2000,"data":{"dev_list":[{"hostname":"phone","mac":"14:d1:9e:7b:85:e4","ip":"192.168.1.167","ipv6":"","visit_info":[{"appname":"微信","appid":1002,"latest_action":0,"online":1,"first_time":1782221235,"latest_time":1782221547,"total_time":312}]}]}}

77. get_device_list

获取 /proc/net/dev 中除 lo 外的网络设备列表。注册顺序：76，类型：GET，无业务参数。

字段类型取值范围示例描述
data.device_list[]array<string>网口名["eth0","br-lan"]可作为 Dashboard 监控网口的候选列表
ubus call fwx common '{"api":"get_device_list","data":{}}'

{"code":2000,"data":{"device_list":["eth0","br-lan"]}}

78. get_dashboard_param

获取 Dashboard 参数。注册顺序：77，类型：GET，无业务参数。

字段类型取值范围示例描述
data.monitor_devicestring网口名或空eth0Dashboard 流量速率监控网口
ubus call fwx common '{"api":"get_dashboard_param","data":{}}'

{"code":2000,"data":{"monitor_device":"eth0"}}

79. get_init_status

获取 Dashboard 初始化状态。注册顺序：78，类型：GET，无业务参数。

字段类型取值范围示例描述
data.init_statusinteger0/11/etc/fwx_init_status 状态；文件缺失或非 0 时默认 1
ubus call fwx common '{"api":"get_init_status","data":{}}'

{"code":2000,"data":{"init_status":1}}

80. set_init_status

设置 Dashboard 初始化状态。注册顺序：79，类型：POST。

字段方向类型必填/取值范围示例描述
data.init_status请求/返回integer可选，0/1，默认 11写入 /etc/fwx_init_status
ubus call fwx common '{"api":"set_init_status","data":{"init_status":1}}'

{"code":2000,"data":{"init_status":1}}

81. set_dashboard_param

设置 Dashboard 流量速率监控网口。注册顺序：80，类型：POST。

字段类型必填/取值范围示例描述
data.monitor_devicestring必填，非空网口名eth0非空时写入 UCI 并使采样器重新选择网口；空字符串不会更新配置
ubus call fwx common '{"api":"set_dashboard_param","data":{"monitor_device":"eth0"}}'

{"code":2000}