切换深色模式
管理 REST / WebSocket API
本章用于程序访问网关管理功能，与 Edge 的 HTTP 数据推送是两套接口。基地址是实际网关管理地址；下文省略主机部分。当前管理界面使用同源会话 Cookie，不用 LoRaWAN 密钥或 MQTT 密码作为网页认证。
认证与适用范围
登录和退出不要求已有会话，info 信息查询公开；其余本章常规管理接口需要登录会话。终端和组播路由只在 Edge 启动时注册，Std 不应通过猜路径寻找这些功能。可选维护终端还要求额外授权。
| 登录请求字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | 字符串 | 是 | 交付的网页管理用户名 |
| password | 字符串 | 是 | 对应网页管理密码，不是 Wi-Fi/MQTT/终端密钥 |
登录 body 形如 {"username":"YOUR_ACCOUNT","password":"YOUR_PASSWORD"}，替换占位符；后续携带服务端设置的 Cookie，不用前端显示菜单用的 token=1 Cookie 代替真正会话。
登录与响应
POST /api/user/login 发送用户名和密码，成功返回 data.mode（server / proxy）和 gwType，并设置 HttpOnly 会话 Cookie。后续请求携带此 Cookie；同一源地址访问 WebSocket 也携带它。当前会话有效期约 8 小时，网关重启或会话失效后重新登录。
受保护接口未登录返回 HTTP 401。普通业务错误除了 HTTP 状态还需检查 JSON code，不能只判断 200：
json
{
"code": 0,
"msg": {
"label": "ok",
"err": ""
},
"data": {}
}data 按接口返回，成功写操作也可能没有 data。错误码：0 成功，−1 请求错误，1000 创建失败、2000 更新失败、3000 删除失败、4000 查询失败、5000 参数错误；详细信息在 msg.err，语言提示在 msg.label。某些版本的查单条记录实现可能产生尾随响应，若收到非单个 JSON 应保留原始响应和版本反馈，不能把解析失败当作“记录不存在”。
GET 也可能改变设备
保存、Wi-Fi 连接、下发、模式切换、重启、恢复和升级均有实际影响。尤其 mode/reboot/factory/language 使用 GET 仍会执行操作，不由链接预览、扫描器或自动健康检查访问。本次 G4 Edge 实测已执行模式切换、测试终端登记和业务配置保存；升级、恢复出厂、删除全部终端及无线下行没有执行。
接口清单
下表按当前路由核对；终端与组播仅 Edge 注册。字段为查询参数时进行 URL 编码；JSON 使用标准双引号、UTF-8、Content-Type: application/json。
| 方法 | 路径 | 模式 | 请求 / 返回与行为 |
|---|---|---|---|
| POST | /api/user/login | 两种模式 | JSON：username、password；成功返回 mode、gwType，并设置会话 Cookie |
| POST | /api/user/logout | 两种模式 | 无 JSON 必需字段；清除会话 |
| PUT | /api/user/modify/password | 两种模式 | JSON：username、password，各 1～32 字节；更改账户凭据 |
| GET | /mode/server | 两种模式 | 旧路径，行为同 /api/gateway/mode/server |
| GET | /mode/proxy | 两种模式 | 旧路径，行为同 /api/gateway/mode/proxy |
| GET | /api/gateway/mode/server | 两种模式 | 切到 Edge，成功后重启；已有同模式时返回当前模式信息 |
| GET | /api/gateway/mode/proxy | 两种模式 | 切到 Std，成功后重启；不是普通 GET 查询 |
| GET | /api/gateway/language | 两种模式 | lang（默认 zh-CN）；data 为语言字符串；会保存设置，不能当作无副作用查询 |
| GET | /api/gateway/info | 两种模式 | 返回模式、版本、MAC、统计时间/计数/流量，可选经纬度；不含配置页的网关 EUI |
| GET | /api/gateway/factory | 两种模式 | 恢复出厂并重启；可能改变网络/热点 |
| POST | /api/gateway/upgrade | 两种模式 | multipart/form-data 的 file 字段，正式 ZIP 升级包；保持原文件名，匹配型号架构；成功重启 |
| POST | /api/gateway/codec/update | Edge | 无 JSON 必需字段；仅 Edge，返回目录更新结果 |
| GET | /api/gateway/config/get | 两种模式 | 返回 data.chnum（8 通道组数）、data.gc、data.regionTemplates；界面接收通道数为 chnum×8 |
| PUT | /api/gateway/config/set | 两种模式 | 完整 GatewayConfig JSON，见下表；成功后重启 |
| GET | /api/gateway/reboot | 两种模式 | 立即请求重启，无 JSON |
| POST | /api/gateway/test/mqtt | 两种模式 | MQTTConfig JSON：url、username/password、clientId、可选 TLS 材料；真实连接 |
| POST | /api/gateway/test/http | 两种模式 | HTTPConfig JSON：dataUpURL、headers；真实 POST 空对象 |
| POST | /api/gateway/test/udp | 两种模式 | JSON：addr，格式 host:port；真实 UDP 交互 |
| GET | /api/gateway/test/ping | 两种模式 | param=目标 空格 接口；空格做 URL 编码，接口 default / eth0.1 / apcli0 / ppp0；返回 ok、out |
| GET | /api/gateway/net_eth/status | 两种模式 | 返回 status；会检查指定链路的连通性 |
| GET | /api/gateway/net_4g/status | 两种模式 | 返回 status；取决于设备 4G 支持与连通性 |
| GET | /api/gateway/wifi/info | 两种模式 | 返回 connect_info，包含当前连接信息；按敏感配置处理 |
| GET | /api/gateway/wifi/scan | 两种模式 | 无线扫描；返回 data.list 扫描结果数组，不是修改已保存热点 |
| POST | /api/gateway/wifi/connect | 两种模式 | JSON：ssid、password；空 SSID 用于断开；会改变当前连接 |
| WebSocket | /api/gateway/stream | 两种模式 | WebSocket 文本消息，为网关实时数据 JSON；同源 Cookie 认证 |
| POST | /api/mote/add/batch | Edge | Mote JSON 数组；当前批次在同一事务内登记，任一项失败会回滚本批次，先检查重复和字段 |
| POST | /api/mote/add | Edge | 单个 Mote JSON，见终端字段表 |
| GET | /api/mote/get | Edge | id=16 位 HEX DevEUI；不是数字序号 |
| GET | /api/mote/list | Edge | search、alive、limit（默认10）、offset（默认0）、class、group、filterGroup；返回 total、result |
| PUT | /api/mote/update | Edge | Mote JSON；读取原记录后保留完整配置和计数再提交 |
| DELETE | /api/mote/delete | Edge | id=DevEUI；删除终端 |
| DELETE | /api/mote/delete/all | Edge | 删除全部终端；不作为分页清空 |
| POST | /api/mote/send | Edge | 原生下行 JSON，见 MQTT 章；code=0 不保证终端收到 |
| GET | /api/mote/down/queue/len | Edge | id=8 位 HEX DevAddr；返回 len，注意不同于 mote/get 的 id |
| WebSocket | /api/mote/stream | Edge | WebSocket；id=DevEUI 或 *（默认），推送终端实时记录 |
| GET | /api/mote/rx2 | Edge | 返回 bw（0/1/2）、freq（MHz）、sf（索引 0～5 对应 SF12～SF7）；不是原生下行 freq/sf 的单位 |
| POST | /api/group/add | Edge | MoteGroup JSON，见组播表 |
| GET | /api/group/get | Edge | addr=8 位 HEX 组地址 |
| GET | /api/group/list | Edge | search、limit（默认10）、offset（默认0）；返回 total、result |
| GET | /api/group/freqband | Edge | 返回 freqbaud（此键保留原拼写），为当前频段 |
| PUT | /api/group/update | Edge | 完整 MoteGroup JSON |
| DELETE | /api/group/delete | Edge | addr=组地址；删除组 |
| POST | /api/group/send | Edge | 原生下行 JSON，仅 groupAddr，不能同时提供 moteeui |
| POST | /api/group/add/mote | Edge | 查询 addr、search、alive、allCheck、filterGroup；JSON 体为 DevEUI 字符串数组 |
| DELETE | /api/group/remove/mote | Edge | eui=DevEUI；解除分组关系，不修改终端内部组参数 |
| DELETE | /api/group/remove/all/mote | Edge | addr=组地址；移除该组成员 |
首页信息返回字段
GET /api/gateway/info 的 data 使用以下名称；它没有登录响应的 mode 字段，也没有配置页的 gatewayId。
| 字段 | 含义 |
|---|---|
| gatewayType | 页面模式名称 Edge / Std；登录响应另用 server / proxy |
| gatewayVersion | 网关程序版本 |
| gatewaySerial | 首页显示的 MAC / 序列标识，不直接作为 16 位网关 EUI |
| startTime、endTime | 本次管理程序启动时间与当前网关时间；程序重启后重新统计 |
| recvPacket、sendPacket | 接收和发送统计 |
| crcOk、crcError | 接收 CRC 统计 |
| recvFlow、sendFlow、totalFlow | 带单位的字符串（如 0B）；4G 启用时取 ppp0，否则取配置的有线接口，并非所有链路总流量或终端应用字节统计 |
程序判断身份时按实际字段取值，不能因读取 data.mode / data.version 得到空值就判断设备未启动。
读取与保存 GatewayConfig
读取响应的 data.gc 才是可编辑网关对象，保存时不要把外层 code/msg/chnum/regionTemplates 整包当作配置。
| 分组 | 字段 | 格式与用途 |
|---|---|---|
| sys | gatewayId | 16 位 HEX 网关 EUI |
| sys | addrType、ip、router、mask | dhcp / static 及当前 IPv4 网络参数 |
| sys | ntpIp | 时间服务器纯域名或 IP |
| sys | wifiEnable、wifiHidden、wifiSsid、wifiPassword | 热点开关、隐藏、名称和密码；仅硬件支持时存在 |
| sys | enable4G、operator、enableGps | 对应硬件能力及运营商设置；缺失字段不强行加入 |
| sys | networkPriority | 接口名按优先级用空格分隔的字符串，例如 eth0.1 apcli0 ppp0；保留实际接口名 |
| comm | freqBand、freqStart、freqEnd | 区域及 Hz 频率边界 |
| comm | freqMode、regionTemplateId | 模板/旧兼容选择及模板 ID，按读取的 regionTemplates 选择 |
| comm | enableMqtt | 依模式决定 Std 数据 MQTT 或 Edge 远程管理连接使能，不替代 Edge 输出选择 |
| output | bridgeAddr | Std UDP 目标（多目标部署按当前配置） |
| output | mqttData、mqttConf | 数据与远程管理各自的 MQTTConfig |
| output | http | dataUpURL、headers（字符串映射），仅 Edge 输出 |
| output | rs485 | protocol、slaveId、moteRegisterNum、baudRate、checkCrc，可选 timeout/dataBits/parity/stopBits |
| output | basicStation | semtechUdpBind、gatewayId、lns、cups、classB/classC 等适配配置；按读取对象与服务器要求处理 |
| extend | restart | isRestart 布尔、times 为 HH:mm |
| extend | gwType、bridgeMode | 设备能力标识与 v3 / v4 / basicstation-udp / none |
| server | autoRegisterABP | Edge 自动登记开关 enabled；回读可能含 appSKey/nwkSKey，但当前 config/set 只保存 enabled，不通过此接口修改该密钥对 |
MQTTConfig 为 url（包含 tcp:// 或 TLS 方案和端口）、username、password、clientId，可带 caContent、certContent、certKeyContent；路径类 caCert/tlsCert/tlsKey 按部署使用，不把其他机器路径当作上传内容。Basic Station 的 lns/cups 使用 enabled、uri、trustContent、certContent、keyContent、authKeyContent 等分别配置，不与普通 MQTT 字段互换。
RS485Config 中 protocol 为 modbus / private，timeout 单位 ms，dataBits 为 5～8，stopBits 为 1/2。parity 使用数字字节：78=N（无）、79=O（奇）、69=E（偶），不是直接把字符串 N/O/E 写入该 JSON 数值字段。当前界面波特率选择为 2400、4800、9600、19200、38400、57600、115200；slaveId 与主站匹配，moteRegisterNum 为每终端寄存器数，必须为正数。
保存使用完整、已核对的对象；当前协议不是通用 JSON Merge Patch。省略不准备修改的现有分组可能导致清除、默认化或错误。成功后重启，必须重连回读并验收业务。
Mote 终端对象
| 字段 | 类型 | 写入规则 |
|---|---|---|
| name | 字符串 | 可读名称，避免重复 |
| devEUI | HEX 字符串 | 16 位，必需 |
| isOtaa | 布尔 | true OTAA，false ABP |
| devAddr | HEX 字符串 | ABP 8 位地址，OTAA 不填写旧会话 |
| appKey | HEX 字符串 | OTAA 32 位密钥 |
| appSKey、nwkSKey | HEX 字符串 | ABP 两个 32 位会话密钥 |
| class | 字符串 | A / C，匹配终端实际接收方式 |
| interval | 整数，秒 | 在线判定窗口，默认 7200；不是向终端配置发包周期 |
| rx1DelayMs、rx2DelayMs | 可选整数，ms | 默认 1000/2000，200～60000，RX2 更晚 |
| joinRx1DelayMs、joinRx2DelayMs | 可选整数，ms | 默认 5000/6000，200～60000，Join RX2 更晚 |
| id、deviceType | 整数 | 序号与类型；更新时保留原值，修改序号会影响 RS485 映射 |
| fCntUp、fCntDown、lastSeen | 整数 | 会话计数和最近上报时间；普通更新保留服务器原值，提交这些字段不会重置计数；lastSeen 为 Unix 毫秒 |
| groupAddr、alive、lastData、lastCodecData | 可选读回数据 | 分组/在线/最近数据；lastData 为 Base64 应用字节，lastCodecData 为解析对象；最近数据来自运行缓存，重启后需等待新上报 |
MoteGroup 组播对象
主要字段为 groupName、groupAddr（8 位 HEX）、groupAppSKey / groupNwkSKey（各32位 HEX）；groupId、fCntDown、createAt 为读回记录。完整更新时保留 groupId 和 createAt；当前更新接口保留服务器原有 fCntDown，不接受通过此接口回退组下行计数。分组成员管理不等于向终端配置组密钥，实际组播准备见终端与组播。
只读调用示例
以下使用占位地址与环境变量，不内置真实密码。Cookie 文件含登录凭据，妥善保管；示例未向实机执行写操作。
sh
curl -c gateway.cookies -H 'Content-Type: application/json' \
--data "$GATEWAY_LOGIN_JSON" http://GATEWAY_IP/api/user/login
curl -b gateway.cookies http://GATEWAY_IP/api/gateway/info
curl -b gateway.cookies http://GATEWAY_IP/api/gateway/config/getWebSocket 数据与可选维护终端
/api/gateway/stream 与 /api/mote/stream?id=* 均推送 JSON 文本，但消息结构不同：
| 实时入口 | 消息结构 | 载荷怎样读取 |
|---|---|---|
网关 /api/gateway/stream | moteTx、gwRx、phyPayloadJson | phyPayloadJson 本身是 JSON 字符串，需要再次解析；这是无线帧记录 |
Edge 终端 /api/mote/stream | 与 MQTT 原生上行相同的 app 对象 | app.userdata.payload 为 Base64 应用字节；FPort 取 app.userdata.port，计数取 app.userdata.seqno，可选解析取 app.userdata.decodedData |
终端流可用 id=16位HEX的DevEUI 筛选，默认 id=* 查看全部。两种流都不是 REST 的 code/msg/data 包装，不能互换解析结构；终端流无需先启用业务 MQTT 输出。重连后实时流不承诺补齐断开期间记录。
以下可选维护终端使用独立的 SSH 授权 Cookie，与前面的普通管理会话分开。只有带相应维护终端构建能力的版本才注册 /api/gateway/ssh/unlock（POST，password）、/api/gateway/ssh/access（GET，返回 active/expiresAt）及 /api/gateway/ssh/terminal（WebSocket）。它们使用额外维护授权，不是普通网页账户自动获得；没有该能力返回不可用时不向旧 /ssh/connect 猜测发送。终端消息有 connect/input/resize 等交互字段，仅由配套维护界面使用，不作为设备业务 API。本册不演示执行系统命令。
RX2 查询与原生下行：单位不能直接复制
GET /api/mote/rx2 和远程 mote:rx2 返回的是网页下发表单格式。以某个 CN470 配置为例，构造响应片段：
json
{"bw": 0, "freq": 505.3, "sf": 0}| 字段 | RX2 查询格式 | 原生 app 下行格式 |
|---|---|---|
| 频率 | freq=505.3，MHz | freq=505300000，Hz |
| 扩频因子 | sf=0，索引，0～5 对应 SF12～SF7 | sf=12，实际 SF，7～12 |
| 带宽 | bw=0，125kHz | bandwidth=0，同样的枚举 |
此查询返回网关当前区域对应的 RX2 预设，并没有向终端发起参数读取；终端若使用不同 RX2，需按其实际设置核对。因此不能把查询返回对象直接嵌进 app。转换公式是 freqHz=round(freqMHz×1000000)、sfValue=12-sfIndex，键 bw 改为 bandwidth；仍须与终端实际接收参数一致。Class A 由上行后的接收窗口调度，这组值不能代替它的窗口参数。
分页、筛选和标识
| 参数 | 类型 / 默认 | 用法 |
|---|---|---|
| search | 字符串，默认空 | 终端/组列表的搜索条件，URL 编码 |
| limit | 非负整数，默认 10 | 本次希望取得的条数；调用方使用合理的小批量 |
| offset | 非负整数，默认 0 | 已跳过条数，下一页用 offset+limit，不是页码 |
| alive | 布尔字符串，默认 false | true 只取在线终端，false 不作在线筛选 |
| class | 字符串，默认空 | 按实际终端 A/C 筛选 |
| group | 字符串，默认空 | mote/list 使用的组地址；与 filterGroup=exclude 配合时排除此组。group/add/mote 的目标组改用 addr，不要混用 |
| filterGroup | 字符串 | all / ungrouped / exclude 等分组选择条件 |
| allCheck | 布尔字符串，默认 false | 仅组成员添加。false 时 JSON 数组是待添加的 DevEUI；true 时数组是全选范围中要排除的 DevEUI。仅添加 Class C，全选范围不局限当前页 |
当前 group/add/mote 的全选添加使用 search、alive、Class C 和 ungrouped 筛选；查看列表时的 group + filterGroup=exclude 边界不会原样用于全选添加。需要精确控制成员时，使用 allCheck=false 并明确列出待添加 EUI，提交后重新查询成员。
列表响应 data.total 是匹配总数，data.result 为本页数组；没有结果时某些版本为 null，接收端可按空数组处理。读取终端或配置会返回会话密钥/认证材料，日志与导出必须按凭据保管。
请求体示例与返回核对
可运行的登录、读取和分页示例见接入示例。ABP 添加使用 JSON 布尔 false，不是字符串 "false"；Excel 的 isOtaa=0/1 由网页转换，不能直接套到 REST 布尔字段。
json
{
"name": "example-only",
"devEUI": "0011223344556677",
"isOtaa": false,
"devAddr": "12345678",
"appSKey": "00000000000000000000000000000000",
"nwkSKey": "00000000000000000000000000000000",
"class": "A",
"interval": 7200,
"rx1DelayMs": 1000,
"rx2DelayMs": 2000,
"joinRx1DelayMs": 5000,
"joinRx2DelayMs": 6000
}这是字段构造示例，全零密钥是占位，不能作为现场建档参数。POST add 成功通常只有 code=0 与 msg，之后通过列表和真实上报复核。重复 EUI/名称/地址可能得到创建失败，不能将 1000 当成功码。
配置保存的特殊行为
config/set 接收 data.gc 对应的完整对象。Std 开启数据 MQTT 时，程序按桥接方案设置本地转发地址，不能用 bridgeAddr 强行覆盖内部适配路径；没有启用 TLS 的 MQTT URL 会清除 TLS 材料。需要证书时先确认 URL 为配套的 SSL/TLS 方案，再确认页面证书内容。
网络查询返回
联网状态与 Wi-Fi 查询使用普通 HTTP GET，只有 stream 是这里的实时 WebSocket。wifi/scan 返回 data.list，wifi/info 返回 data.connect_info（可能含密码），net_eth/status 与 net_4g/status 返回 data.status。链路状态的 Ping 探测可能耗时，不能高频请求或将浏览器短超时直接当物理断线。