蓝波湾无线网桥 REST API 配置说明

1. 概述

REST API 是通过 HTTP 协议在预定义的一组面向资源的 URL 上访问的接口。WIS 无线网桥的 REST API 以 JSON 包装器形式实现，支持对设备资源的创建、读取、更新和删除（CRUD）操作，可满足自动化开局、批量配置、状态监控与远程运维等需求。

本文所有主流程示例均采用 HTTP Basic 认证，每条命令直接携带用户名和密码。默认设备地址为 192.168.1.2，账号密码为 root/admin。

2. 使用准备

以下命令均在 Windows cmd.exe 中执行。设备使用自签名 HTTPS 证书，curl 需加 -k 参数跳过证书校验；如出现中文乱码，可先执行 chcp 65001 切换控制台编码。

API 基础地址与设备管理页面的访问方式保持一致，设备默认使用 HTTPS 连接：

• HTTPS 登录管理页面时，使用 https:///cgi-bin/api/v1；
• HTTP 登录管理页面时，使用 http:///cgi-bin/api/v1。

curl 常用参数说明如下：

3. 认证方式

HTTP Basic 认证直接使用设备 Web 登录账号和密码，每次请求携带 -u root:admin，无需先登录获取 token，便于脚本化调用。

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/system/info

认证成功时返回 ok=true 并在 data 中携带设备信息；密码错误或未携带认证信息时返回认证失败（401）。

4. 响应格式与状态码

接口成功时返回 ok=true；失败时返回 ok=false 和 error 对象：

{ "ok": true, "data": { } }
{ "ok": false, "error": { "code": 401, "message": "authentication required" } }

5. 查询接口

5.1 查看设备信息

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/system/info

成功时返回 ok=true，包含主机名、型号、固件版本、序列号、MAC 地址、IP 地址等设备信息。返回示例：

{ "ok": true, "data": { "hostname": "Wireless-Bridge", "serial_number": "W0B32250200113", "manufacturer": "WIS", "model": "X619", "model_number": "IPQ5018/AP-MP03.5-C1", "hardware_version": "v0", "software_version": "develop_version", "board_name": "qcom,ipq5018-ap-mp03.5-c1", "system_type": "ARMv7 Processor rev 4 (v7l)", "kernel": "5.4.213", "firmware": "OpenWrt 23.05-SNAPSHOT r0-3c83419af", "firmware_version": "23.05-SNAPSHOT", "firmware_revision": "r0-3c83419af", "target": "ipq50xx/ipq50xx_32", "rootfs_type": "squashfs", "uptime_seconds": 3491, "local_time": 1788960711, "mac_addresses": { "ath1": "de:36:43:32:7c:57", "bond0": "92:ac:2c:74:7e:6c", "br-lan": "dc:36:43:32:7c:54", "eth0": "dc:36:43:32:7c:54", "gre0": "00:00:00:00", "ip6gre0": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00", "ip6tnl0": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00", "sit0": "00:00:00:00", "wifi0": "00:03:7f:12:31:31", "wifi1": "dc:36:43:32:7c:57" }, "ip_addresses": [ { "device": "br-lan", "address": "192.168.1.2/24" } ], "status": "online" } }

5.2 查看运行状态

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/system/status

成功时返回 ok=true，包含 uptime、CPU、内存、网络接口、无线状态和客户端信息。

5.3 查看配置文件列表

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/config

成功时返回 ok=true，列出设备当前支持读取的配置文件名称。

5.4 读取无线配置

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/config/wireless

成功时返回 ok=true，包含 wireless 配置文件下的全部配置段。返回示例：

{ "ok": true, "data": { "file": "wireless", "sections": [ { ".type": "wifi-device", ".name": "wifi0", ".anonymous": false, "type": "qcawificfg80211", "channel": "auto", "macaddr": "dc:36:43:32:7c:56", "hwmode": "11axg", "disabled": "1" }, { ".type": "wifi-iface", ".name": "cfg023579", ".anonymous": true, "device": "wifi0", "network": "lan", "mode": "ap", "ssid": "wireless-bridge", "encryption": "none" }, { ".type": "wifi-device", ".name": "wifi1", ".anonymous": false, "type": "qcawificfg80211", "channel": "45", "macaddr": "dc:36:43:32:7c:57", "hwmode": "11axa", "band": "3", "country": "00", "txpower": "26", "htmode": "HT160", "superos_antgain": "19" }, { ".type": "wifi-iface", ".name": "wifinet1", ".anonymous": false, "device": "wifi1", "network": "lan", "mode": "ap", "ssid": "wireless-bridge", "encryption": "ccmp", "key": "12345678", "en_6g_sec_comp": "0", "sae": "1", "wds": "1", "vlan_tag": "1", "ieee80211w": "1", "add_sha256": "1" } ] } }

5.5 读取指定配置段

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/config/wireless/wifi1

成功时返回 ok=true 及对应配置段。section 可使用名称或类型索引。

5.6 查看在线规范

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/openapi.json

成功时返回 OpenAPI JSON，可用于核对设备端当前暴露的全部接口。

6. 配置修改流程

配置修改采用三段式流程：先暂存修改 → 查看暂存内容 → 确认后应用；如不提交，可随时回退暂存修改。

6.1 准备无线配置请求文件

> put.json echo {"set":{"wifinet1":{"ssid":"wireless-bridge-X6-Test123","key":"12345678a12"},"wifi1":{"txpower":"1"}}}

作用：生成 put.json。复杂 JSON 建议先写入文件，再用 -d @put.json 提交，避免 cmd 引号转义出错。

type put.json | python -m json.tool

作用：格式化检查 put.json，能正常缩进输出即表示 JSON 格式正确。

6.2 暂存无线配置修改

curl -k -u root:admin -X PUT https://192.168.1.2/cgi-bin/api/v1/config/wireless -H "Content-Type: application/json" -d @put.json

成功时返回 ok=true 并提示 changes staged，此时配置已暂存、尚未生效。

6.3 查看暂存修改

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/config/pending

成功时返回 ok=true，显示当前待提交的配置修改。

6.4 应用暂存修改

curl -k -u root:admin -X POST https://192.168.1.2/cgi-bin/api/v1/config/apply -H "Content-Type: application/json" -d "{}"

成功时返回 ok=true，设备提交配置并按配置类型重载服务。注意：无线或网络配置变更可能导致短暂断连。

6.5 回退暂存修改

curl -k -u root:admin -X POST https://192.168.1.2/cgi-bin/api/v1/config/revert -H "Content-Type: application/json" -d "{}"

成功时返回 ok=true，未提交的暂存修改被丢弃；配置一旦应用则无法回退。

7. 配置导出与导入

7.1 导出配置

（1）导出配置到 JSON

curl -k -u root:admin -X GET https://192.168.1.2/cgi-bin/api/v1/system/config/export -o config-export.json

作用：把配置导出接口返回保存为 config-export.json，该文件包含 base64 编码的备份包内容。

（2）生成备份包 backup.tar.gz

python -c "import json,base64; d=json.load(open('config-export.json',encoding='utf-8'))['data']; open('backup.tar.gz','wb').write(base64.b64decode(d['content']))"

作用：从 config-export.json 的 data.content 解码，生成真正的配置备份包 backup.tar.gz。

（3）导出 UCI JSON

curl -k -u root:admin -X GET "https://192.168.1.2/cgi-bin/api/v1/system/config/export?format=json" -o config-export-uci.json

作用：导出可读的 UCI JSON 配置，便于查看配置内容；不等同于 sysupgrade 备份包。

（4）导出 cfg.tar.gz

curl -k -u root:admin https://192.168.1.2/cgi-bin/api/v1/system/config/export -o cfg.tar.gz

作用：一条命令把配置备份下载到本地 .tar.gz（标准 sysupgrade备份包，与 LuCI 备份/恢复兼容。

7.2 导入配置

（1）生成导入请求文件

python -c "import base64,json; json.dump({'content':base64.b64encode(open('backup.tar.gz','rb').read()).decode()}, open('import.json','w',encoding='utf-8'))"

作用：把 backup.tar.gz 编码为接口可接收的 import.json。

（2）导入恢复配置

curl -k -u root:admin -X POST https://192.168.1.2/cgi-bin/api/v1/system/config/import -H "Content-Type: application/json" -d @import.json

成功时返回 ok=true 并提示配置已恢复，需重启设备使配置完全生效。

（3）恢复配置

curl -k -u root:admin https://192.168.1.2/cgi-bin/api/v1/system/config/import \ -H "Content-Type: application/octet-stream" --data-binary @cfg.tar.gz

下载到的文件直接上传回设备；成功时返回 ok=true 并提示配置已恢复，需重启设备使配置完全生效。

7.3 固件升级

（1）保留配置升级

curl -k -u root:admin "https://192.168.1.2/cgi-bin/api/v1/system/upgrade?confirm=true" \ -H "Content-Type: application/octet-stream" --data-binary @firmware.bin

固件版本直接上传到设备上并执行升级动作；成功时返回 ok=true 并提示刷写期间设备不可达, 可能需要较长时间才会重新上线。

（2）不保留配置升级

curl -k -u root:admin "https://192.168.1.2/cgi-bin/api/v1/system/upgrade?confirm=true&keep=0" \  -H "Content-Type: application/octet-stream" \  --data-binary @firmware.bin

加 &keep=0表示不保留配置

固件版本直接上传到设备上并执行升级动作；成功时返回 ok=true 并提示刷写期间设备不可达, 可能需要较长时间才会重新上线。

8. 设备维护

8.1 重启设备

curl -k -u root:admin -X POST https://192.168.1.2/cgi-bin/api/v1/system/reboot

作用：让设备重启。执行后设备会短时间无法访问，通常等待 2~5 分钟后再连接。

8.2 恢复出厂设置

curl -k -u root:admin -X POST https://192.168.1.2/cgi-bin/api/v1/system/factory-reset -H "Content-Type: application/json" -d "{\"confirm\":true}"

作用：让设备恢复出厂设置并重启。该操作会清空当前配置，执行前建议先导出备份。

9. 常见异常测试

以下为常见异常场景的测试命令与预期返回，可用于验证接口的鉴权与容错行为：

10. 字段说明

本节列出常用配置项和返回字段，包含字段名称、用途说明和可填写范围。标注为"只读"的字段仅用于查看设备状态，不能通过配置接口修改；可配置字段请按现场网络规划和设备支持能力填写。

10.1 系统信息（GET /system/info）

系统信息接口的返回字段全部为只读，可用于资产登记与状态巡检：

10.2 系统设置（system @system[0]）

10.3 网络设置 WAN（network）

WAN 端口仅路由模式下进行配置：

10.4 网络 LAN（network lan）

10.5 DHCP 服务器（dhcp lan）

仅路由模式下配置 DHCP 服务器：

10.6 无线射频（wireless wifi1）

10.7 无线接口（wireless wifinet1）

10.8 端口转发（firewall redirect）

11. 注意事项

• HTTP Basic 会在每次请求中携带用户名和密码，测试环境应使用 HTTPS；
• 配置修改只会先暂存，必须执行 apply 后才会写入配置并生效；
• 修改 LAN/WAN IP 后设备地址可能变化，需要使用新地址重新访问。