管理

API 参考

用令牌从脚本、仪表盘或智能家居系统调用烽燧：怎么认证、有哪些接口、返回什么，以及实时事件和 Prometheus 指标。

烽燧的网页控制台用的就是这套 REST API。脚本、仪表盘和智能家居系统可以用令牌调用同样的接口：读取信号和历史、马上刷新、锁频、收发短信，或者订阅实时事件。

AI 智能体请用 MCP：它在这套接口之上多了开关、确认和更严格的限制。

#准备令牌

在控制台「设置 → 令牌与 AI」生成令牌。令牌只显示一次，请马上复制保存；可以设有效期（1 到 365 天或永不过期），随时可以撤销（见安全与隐私）。

每个令牌都能读取路由器的数据，并能让烽燧马上刷新一次。其他事情要在生成时勾选权限，已有的令牌在「设置 → 令牌与 AI」点「权限」修改：

令牌不能修改控制台设置（登录密码、令牌、路由器连接、各种开关），也不能彻底删除「最近删除」里的短信，这些只能在登录后的控制台里做（403 CONSOLE_ONLY）。控制台自己用的接口（/api/auth/*、/api/setup/*、/api/console/*）不对令牌开放，下面不列。

#发请求

把令牌放在 Authorization 头里：

# 读取
curl -H "Authorization: Bearer <令牌>" http://<NAS 的 IP>:18384/api/telemetry

# 改动：POST，请求体是 JSON
curl -X POST \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"auto"}' \
  http://<NAS 的 IP>:18384/api/control/antenna

• 每个 POST 都要带 Content-Type: application/json，没有参数时发 {}。请求体最大 64 KiB（导入通讯录 4 MiB）。
• 读取不会登录路由器。 GET 接口直接返回烽燧内存里的最新数据，可以频繁调用。烽燧默认每 5 秒读一次信号（POLL_INTERVAL_MS），每 60 秒扫描一次附近的基站和已连接设备（NEIGHBOR_SCAN_INTERVAL_MS），见配置参考。
• 刷新和改动会登录路由器。 路由器同一时间只允许一个管理员会话，烽燧把所有请求排队，一次一个。请不要高频调用刷新接口。
• 有人登录路由器自己的管理页时，烽燧会让开：这期间的刷新和改动返回 409 BROWSER_SESSION_YIELDED，什么都不做。
• 用域名访问（例如经过反向代理）时，把域名加进 ALLOWED_HOSTS，否则返回 421 MISDIRECTED_HOST（见安全与隐私）。
• 令牌请求不需要 X-Requested-With。 只有浏览器里用控制台的登录 Cookie 调用时才需要它，那是防跨站请求伪造（CSRF）的检查。
• 默认打码。 用令牌拿到的数据里，IMEI 只留前 6 位，IMSI 只留运营商代码，号码、MAC 和 WAN 地址只留一部分，小区标识和设备名称隐去（REDACT_SENSITIVE_IN_API=true）。登录后的控制台看到原值。

#返回和错误

成功时返回 200，JSON 里 ok 为 true，数据在同一层的字段里。例如锁频段返回（节选）：

{ "ok": true, "lockState": { "mode": "band_lock", "lteBands": [1, 3], "nrBands": [] } }

失败时返回对应的 HTTP 状态码，JSON 里 ok 为 false：

{ "ok": false, "errorCode": "VALIDATION_ERROR", "message": "…" }

脚本请按 errorCode 判断，不要按 message：message 可能是中文或英文，措辞也会改。脚本会遇到的错误码：

#接口

「需要的权限」一栏是令牌除了读取之外还要勾选的权限。每个接口的请求和返回字段见开发者文档的接口契约。

#读取

#刷新

#路由器控制

#设备上网管理

#短信

#其他

改动路由器的接口遵守和控制台一样的规则：在没有验证过的路由器上，烽燧没有实现的写入返回 409 DEVICE_UNVERIFIED_READ_ONLY，你在「设置 → 设备」关掉的返回 409 DEVICE_WRITE_DISABLED，两种情况都不会给路由器发任何请求（见其他型号与品牌）。

#实时事件

GET /api/events 是 Server-Sent Events 流。连上后先收到一条 hello（当前的状态），之后数据一变就推送：

curl -N -H "Authorization: Bearer <令牌>" http://<NAS 的 IP>:18384/api/events

每条消息有 event:（事件名）和 data:（一行 JSON）。另外每 15 秒有一行以 : 开头的心跳（SSE_HEARTBEAT_MS），客户端忽略它即可。断线重连后会重新收到 hello；烽燧不补发断线期间的事件。

• 连接数有上限：总共 SSE_MAX_CLIENTS 条（默认 32），每个地址 6 条，超出返回 429 SSE_LIMIT_REACHED。
• 令牌被撤销或到期时，用它打开的连接立即断开。

#Prometheus 指标

在控制台「设置 → 安全」打开（或在 .env 里设 METRICS_ENABLED=true）后，GET /metrics 返回 Prometheus 文本格式的指标：信号（RSRP、RSRQ、SINR）、载波和带宽、速率、流量、WAN 状态、短信数量、会话和排队情况，以及烽燧自己的内存、CPU 和事件循环延迟。指标里没有任何设备标识。没打开时返回 404。

任何令牌都能读取指标，不需要勾选权限。Prometheus 的抓取配置：

scrape_configs:
  - job_name: fengsui
    metrics_path: /metrics
    authorization:
      credentials: <令牌>
    static_configs:
      - targets: ["<NAS 的 IP>:18384"]

#存活检查

GET /api/health 不需要令牌，返回版本和运行时长，适合存活监控工具。Docker 镜像自带的健康检查用的也是它。

在 GitHub 上编辑此页