本说明书基于系统主界面所承载的全部功能模块编写,涵盖设备接入、无线运维、拓扑可视化、预警通知、运维闭环与系统管理等全部能力,图文并茂,适合网络运维人员与系统管理员阅读。

系统版本：3.5

作者微信：javacoo

目录

1. 系统概述

2. 运行环境与安装

3. 登录系统

4. 主界面布局

5. 数据看板

6. 设备扫描

7. 设备列表与设备详情

8. 无线终端

9. 射频分析

10. 设备拓扑与地图

11. 可视化(指标趋势 / 统计报表 / 监控大屏 / 流量分析)

12. 运维闭环(告警工单 / 配置基线 / 自动备份 / 批量运维 / 接入向导 / 队列监控 / Ping监测)

13. 设备预警

14. 系统管理

15. 系统工具

16. 退出登录

17. 典型业务流程

18. 授权与试用

19. 数据文件与安全说明

20. 常见问题(FAQ)

21. 附录:术语表

1. 系统概述

1.1 系统简介

RouterOS 无线设备管理系统是一套面向 Mikrotik RouterOS 无线网络设备(基站 AP、无线控制器 AC、微波 CPE、路由器、交换机等)的一体化运维管理平台。系统将"设备接入 → 状态监控 → 无线健康分析 → 拓扑可视化 → 流量分析 → 预警通知 → 运维闭环 → 开放集成"整合在统一的 Web 界面中,帮助运维人员:

• 快速盘点网内设备:网段扫描自动发现可登录的 RouterOS 设备并一键入库;

• 实时掌握设备状态:在线/离线、电压、温度、CPU、内存等指标持续上报;

• 深度运维无线网络:AP 健康评分、接入终端(RSSI/SNR/速率/CCQ)明细、终端漫游轨迹、信道干扰分析与推荐信道一键下发;

• 可视化呈现:站点分层拓扑图(聚合/聚焦/总览钻取/变更留痕/影响分析)、设备 GIS 地图、指标趋势曲线、统计报表与全屏监控大屏;

• 闭环处置故障:越限/离线自动生成告警工单,支持"未处理 → 处理中 → 已解决 → 已关闭"流转;

• 主动风险防控:多通道(邮件/短信/电话语音/企业微信/钉钉/飞书/自定义 HTTP)预警通知体系;

• 规范配置管理:配置抓取、快照基线、行级 Diff 比对与一键回滚,批量脚本下发与固件升级登记,并可按计划自动备份、下载设备侧原生备份;

• 自助接入向导:将设备令牌 / 服务器地址 / 初始化脚本封装为三步向导,新设备一键植入并确认纳管状态;

• 持续运维监测:队列限流状态采样(含字节趋势与计数重置)与持续 Ping 链路质量监测(延迟/丢包曲线),周期任务默认关闭、按需开启。

• 接口级流量分析:逐接口实时收发速率与累计字节趋势、按时间窗聚合的收发面积图、全网带宽 TOP 榜与突增接口标红,把"设备是否健康"进一步延伸到"链路带宽被谁用满";

• 开放与智能集成:提供 API Key(按 read/write/mcp 分级授权) 与 MCP(Model Context Protocol)服务,可被第三方运维平台、自动化工具乃至 AI 助手以标准协议查询设备/告警/拓扑/流量并下发脚本,能力可编排、可审计;

• 企业统一身份:支持钉钉 / 飞书第三方登录与账号绑定,降低批量开通与日常登录摩擦;

• 舒适值守体验:全站深色/浅色主题一键切换(图表随之自动换色),配合全屏监控大屏,适合长时间值班与电视投放。

1.2 系统优势与特色

一句话定位:面向 Mikrotik RouterOS 无线网络的一体化运维平台——单机即可部署、不依赖任何第三方云平台(仅高德地图底图与经纬度选点需外网,其余功能可全程内网运行),数据完全自主、无按年订阅的隐性成本,对无线指标深度建模,并把"看见问题"延伸到"处置留痕"、再延伸到"可被集成与自动化"。相比"通用网管软件 + 一堆手工脚本"与"厂商云管平台(SaaS)"这两条常见路线,本系统在私有化、无线深度、闭环留痕、开放集成四个维度同时占优,差异点集中在下表:

五点最值得关注的优势

1. 对无线网络本身建模,而不是只监控"设备活着" 健康评分、干扰评分、CCQ、SNR、漫游轨迹、推荐信道这些指标是按 802.11 运维语义组织的:射频分析页给出按频率轴的占用热力柱状图与"换过去预计干扰评分能降到多少",并可一键下发;无线终端页可按 AP 展开每个接入终端并回溯其漫游过程。这类能力在通用 NMS 里通常是缺失的,而它恰是无线集成商每天都要用的那部分。

2. 不要求被管设备做任何改造 采集与下发走 RouterOS 原生 API(默认 8728)与 SSH,设备侧不安装任何代理;需要持续上报时,也是用 RouterOS 自带的 scheduler + script 实现,由接入向导一次性植入,并可一键停用/卸载——随时能回到"设备上不存在本系统任何残留对象"的状态。

3. 同一套能力,两种交付形态 普通版便于自用;安全版(topology-secure.exe + 加密 jar + 解密 agent)面向对外交付,配合授权证书可按签发时指定的期限做试用或正式授权,并有全局鉴权与操作审计兜住越权。两者共用同一套数据库与配置结构,切换重装不影响已纳管数据(授权机制详见第 18 章)。

4. 能力开放、可被集成与自动化,而不是封闭黑盒 这是与厂商云管平台拉开差距的关键一环:API Key 按 read/write/mcp 分级授权,让外部系统只能拿到应有的权限;MCP 服务把设备、告警、拓扑、无线终端、射频扫描、流量等做成标准工具,可被自动化工具乃至 AI 助手直接调用(只读工具走 read/mcp,下发脚本这类写工具强制 write)。所有调用均纳入统一鉴权与审计,开放而不失控(详见 §14.5、§14.6)。

5. 数据主权与零云依赖 全系统以单文件嵌入式数据库 + 单机 jar 形态交付,设备凭据、拓扑、告警、历史指标都留在自己机房里,不上传任何第三方云;除高德底图外可全程内网运行,也没有按年订阅、按设备数计费的隐性成本——对数据敏感、网络隔离的行业客户尤其关键。

适用与不适用(便于选型)

1.3 功能架构

RouterOS 无线设备管理系统
├── 设备接入
│   ├── 数据看板(总览统计 / 报警分布 / 无线健康)
│   ├── 设备扫描(网段发现 / 一键入库)
│   └── 设备列表 / 设备详情(软硬件资源 / 无线 / 用户 / 日志)
├── 无线运维
│   ├── 无线终端(AP 健康 / 接入终端 / 漫游时间线)
│   └── 射频分析(干扰评分 / 推荐信道 / 一键下发)
├── 可视化
│   ├── 设备拓扑(站点分层/总览钻取/自动绘制/变更留痕/影响分析/资产对账/导入导出)
│   ├── 设备地图(GIS 定位 / 状态展示)
│   ├── 指标趋势 · 统计报表 · 监控大屏 · 流量分析
│   └── 系统工具(Ping / Traceroute / 无线扫描 / 网络信息 / 配置备份)
├── 运维闭环
│   ├── 告警工单(自动生成 / 状态流转)
│   ├── 配置基线(快照 / Diff / 回滚)
│   ├── 自动备份(备份计划 / 设备侧原生备份 / 快照下载)
│   ├── 批量运维(脚本下发 / 固件升级登记)
│   ├── 接入向导(令牌 / bootstrap.rsc / 一键植入 / 纳管确认)
│   ├── 队列监控(限流采样 / 字节趋势 / 计数重置)
│   └── Ping 监测(多目标周期探测 / 延迟丢包曲线)
├── 设备预警
│   ├── 邮箱配置 / 通知渠道 / 指标字典 / 预警设备(阈值条目) / 预警配置 / 预警规则 / 预警任务 / 预警日志
│   └── 活动告警面板(firing 实时视图)
└── 系统管理(RBAC 与集成)
    ├── 用户管理 / 角色管理 / 菜单管理 / 操作审计 / API Key / MCP 接入 / 第三方登录
    └── 顶部栏:深色主题切换 / 账号绑定(第三方登录)

2. 运行环境与安装

2.1 前置条件

• 网络互通:运行管理系统的服务器需与被管 RouterOS 设备网络可达;如需跨网段扫描,服务器本机需配置对应网段的 IP 地址;

• 设备凭据:具备 RouterOS 登录账号(默认 admin)及密码,设备需开启 API 服务(默认端口 8728);

• JVM 环境:JDK 1.8 及以上。

2.2 启动方式

部署形态:当前仅支持单机客户端版(env=client,内嵌 SQLite,数据全在本地)。云/中心版形态(env=cloud,MySQL + 设备公网回连)为历史遗留、尚未发布:启动器对 env=cloud 会直接拒启并输出引导提示,application-cloud.yaml 仅保留占位。如需集中纳管,现阶段请以单站点客户端形态交付。

方式一：安装程序(推荐,面向最终用户)

运行 routeros-topology-setup.exe 安装后,程序目录下会自带精简的 JRE 与启动器,双击 topology.exe 即可,无需预先安装 Java。安装目录结构如下:

系统托盘:托盘图标右键弹出菜单(“打开管理页面”/“退出”),左键双击直接打开管理页。选“退出”会优雅停服(撤销 HTTP 服务、停定时器、关数据库连接池与邮件资源)后再结束进程;Linux 或无桌面环境(headless)下托盘自动跳过,不影响服务运行。

方式二：脚本启动(面向开发/运维)

Windows 环境可使用 run/ 目录下的脚本:

Linux 环境推荐后台启动(示例命令已给出建议的 JVM 参数:G1GC、1G 堆):

nohup java -server -ms1024m -mx1024m -XX:+UseG1GC -XX:G1HeapRegionSize=2m \
  -Dfile.encoding=UTF-8 -jar topology-1.0-jar-with-dependencies.jar &

启动后浏览器访问系统地址(默认 HTTP 端口参见 application.yaml 配置),将自动跳转至登录页。

提示:需在 RouterOS 的"云服务配置"工具中将服务地址与端口指向本系统服务器,设备才能持续上报数据(用于数据看板、无线终端、射频分析等"上报驱动"功能)。

2.3 内存参数与日志落点

Windows 启动器(topology.exe / topology-secure.exe)已内嵌一组经实测校准的 JVM 参数,常规使用无需改动:

两条注意事项

1. 不要把 MetaspaceSize 与 MaxMetaspaceSize 设成同一个值。本系统运行期常驻约 8400 个类、元空间实际占用约 48MB;若两者同为 50MB,进程会在"涨到顶→Full GC 却卸不掉类→再 Full GC"中空转并于数分钟内退出,而 GUI 启动器不会弹任何提示。

2. 这组参数内嵌在 exe 内部,修改 setup\*.exe4j 的 vmParameters 后必须重新生成启动器才生效;临时调参可改用 run\start.bat / run\start-secure.bat 启动(它们从 JVM_OPTIONS 读取)。

日志与取证文件(排障时按此顺序取现场):

3. 登录系统

系统访问入口为登录页(路由 /Login,/ 地址自动重定向)。

操作步骤:

1. 输入账号与密码。全新安装时系统已内置初始管理员:admin,初始口令 Admin@123(首启自建,无需人工创建);首次登录后请立即在“系统管理 → 用户管理”修改该口令;其余账号由管理员在该处创建;

2. 点击登录按钮;

3. 登录成功后系统自动获取当前用户的角色与权限集合(permissions),并加载该用户可见的动态菜单树与页面令牌(Token);

4. 若拥有"记住密码"选项,勾选后账号密码将保存在本地浏览器中,下次自动填充。

异常说明:

第三方登录(钉钉 / 飞书):

除账号口令登录外,系统支持企业统一身份登录(钉钉/飞书),降低批量开通摩擦。该能力属企业版门控功能(见 §18.10),由管理员在「系统管理 → 第三方登录」页面(/oauthSettings)自行配置 App 凭据并即时生效,无需修改服务器 yaml(见 §14.7):

1. 登录页点击对应平台的第三方登录入口,前端向 GET /api/oauth/url/:provider 取回授权跳转地址;

2. 在钉钉/飞书完成扫码或授权后回调 GET /api/oauth/callback/:provider,系统校验 state 并签发本系统 JWT;

3. 若该第三方身份尚未绑定本地账号,则提示先登录后在顶部栏“账号绑定”处完成首次绑定(见 §4 与 §14.7);已绑定则直接进入系统。

未启用时点击第三方入口会返回“第三方登录未启用”提示,不影响账号口令登录。

4. 主界面布局

登录成功后进入系统主界面(路由 /home),所有功能页面均承载于该布局之内。

界面分为四个区域:

内置默认菜单结构如下:

• 数据看板

• 设备扫描

• 设备列表

• 无线终端

• 射频分析

• 设备拓扑与地图:设备拓扑、设备地图

• 可视化:指标趋势、统计报表、监控大屏、流量分析

• 运维闭环:告警工单、配置基线、自动备份、批量运维、接入向导、队列监控、Ping监测

• 设备预警:邮箱配置、通知渠道、设备配置、指标字典、通知预设、通知策略、预警任务、活动告警、预警日志

• 系统管理(仅管理员可见):用户管理、角色管理、菜单管理、操作审计、API Key、MCP 接入

• 系统工具

监控大屏为独立全屏路由(/screen),不套用它导航布局,适合投放到电视/大屏设备。

深色主题:点击标题栏的主题切换按钮可在全站浅色/深色之间切换,选择保存在浏览器 localStorage(键 app-theme)并在下次登录时自动恢复;趋势/报表/大屏中的图表会随之自动切换为深色配色,适合值班大屏与长时间值守。

5. 数据看板

入口:左侧菜单「数据看板」;专业/企业版登录后首页即内嵌看板内容。

版本限定:数据看板为专业版及以上能力。社区/标准版证书下该菜单置灰锁定,接口返回 403("当前授权版本不含该功能"),首页改为起始引导页(见 §18.10)。

数据看板是运维人员的"第一屏",汇总全网运行态势。

5.1 界面构成

健康评分分级标准:

5.2 使用要点

• 数据均来自设备上报,若"在线终端"或"无线健康"无数据,请先确认设备已完成扫描入库并开启了云服务上报;

• 长时间挂机监控建议保持 1~5 分钟自动刷新;需要定格画面时选择"关闭"。

6. 设备扫描

入口:左侧菜单「设备扫描」。

设备扫描用于主动发现网段内可登录的 RouterOS 设备,是设备接入系统的第一步。

6.1 扫描步骤

1. 填写扫描地址段:输入设备网段内任一 IP 与 子网掩码(如 192.168.1.10 / 255.255.255.0);如需扫描多个网段,点击添加网段逐条录入(至少保留一条);

2. 填写登录凭据:输入 RouterOS 登录账号(默认 admin)与登录密码;

3. 点击扫描按钮,系统逐个网段探测可登录(API 可达)的设备,扫描期间显示"正在扫描网段,请稍候...";

4. 扫描完成后表格列出所有发现的设备,顶部提示"共发现 N 台设备,已保存 M 台"。

6.2 扫描结果表

6.3 注意事项

• 只有点击"保存"的设备才会入库,未保存的记录刷新页面后丢失;

• 保存时系统自动以 API 端口 8728 登记凭据,并在后台自动开启该设备的云服务配置(持续上报);

• 缺少 MAC 地址的设备无法保存;

• 跨网段扫描要求服务器本机已配置对应网段的 IP,否则该网段探测不到设备;

• 如需批量清空上次扫描结果重新探测,可在设备扫描相关操作中使用"刷新"能力(对已入库设备重新登录探测,详见 7.1)。

7. 设备列表与设备详情

入口:左侧菜单「设备列表」。

7.1 设备列表

展示所有已入库设备的清单,并提供批量状态刷新与设备维护操作。

列表中的"安装位置"在设备详情页的自定义配置中编辑;"设备类型"在扫描保存时确定。

7.2 设备详情

入口:设备列表 → 行内「详情」按钮。

设备详情页是单台设备的深度运维视图,包含以下子页签:

设备详情页摘要界面参考:

网络信息(IP 地址/路由/ARP/DHCP)实际位于「系统工具 → 网络信息」页签,选定在线设备后一键查询,实测参考:

无线接口详情参考:

使用要点:

• 在详情页录入的经纬度将直接决定"设备地图"页面中该设备标记的位置;

• "网内设备 / 用户 / 日志"页签要求设备在线且凭据有效;

• 修改设备账号密码属于高危操作,请牢记新密码并同步更新系统中保存的凭据(重新扫描保存即可)。

8. 无线终端

入口:左侧菜单「无线终端」。

无线终端是上报驱动的无线运维工作台,用于回答"每台 AP 上挂了哪些终端、信号质量如何、终端在哪里漫游"。

8.1 左栏:无线设备(AP)列表

• 展示所有在线上报的无线设备,每项显示:设备名称、健康评分标签(含"优秀/良好/一般/差"分级)、MAC、接入终端数、平均信号(dBm)、信道/频段/频宽;

• 点击某台 AP,右侧联动刷新为该 AP 的明细;

• 顶部刷新按钮重新拉取健康总览。

8.2 右上:接入终端明细

选中 AP 后展示其接入终端表,核心指标:

8.3 终端事件时间线(漫游/上下线轨迹)

点击终端行,弹出该终端的事件时间线对话框:

• 按时间倒序展示近 7 天的"接入(绿点)/ 离开(红点)"事件,包含所接入的 AP MAC 与当时信号;

• 用于排查"终端频繁掉线""跨 AP 漫游异常"等问题。

8.4 右下:AP 健康趋势

• 选中 AP 后展示其时序曲线:健康评分、接入终端数、信号随时间的变化;

• 支持切换时间窗 6h / 24h / 72h;

• 结合趋势可判断 AP 性能劣化的起始时间点,与配置变更/环境干扰事件对照定位根因。

9. 射频分析

入口:左侧菜单「射频分析」。

射频分析页面提供信道干扰扫描、干扰评分、推荐信道与一键下发能力,数据来自 rf_scan / rf_neighbor / rf_channel_audit 三张表。

9.1 基本流程

1. 左栏选择一台在线 AP(列表显示健康/干扰标签、频段、信道、频宽);

2. 页面加载时冷读该 AP 最近一次落库的扫描结果(不会自动发起实时扫描);

3. 顶部工具条设置无线接口(如 wlan1)与扫描时长(2~15 秒),点击开始扫描——系统弹出二次确认后,才会实时连接设备执行 wireless-scan(扫描期间该接口可能短暂中断业务,请选择合适窗口操作);

4. 扫描完成后页面展示分析结果(见下)。

9.2 分析结果解读

9.3 一键下发推荐信道

当"推荐信道 ≠ 当前信道"时,一键下发到推荐信道按钮可用:

1. 点击按钮,系统给出强警示(下发将中断该接口无线服务数秒,请确认现场允许);

2. 确认后后端直接修改该 AP 的频宽/信道参数,并写入下发审计(旧值/新值/操作人/结果);

3. 点击工具条下发审计按钮,在抽屉中查看历史下发记录:时间、接口、旧值(频率/信道/频宽)、新值、操作人、执行结果。

注意:内置"无需下发"表示当前已是最优;下发前请确认该 AP 下挂终端可容忍短暂断线。

10. 设备拓扑与地图

10.1 设备拓扑

入口:菜单「设备拓扑与地图 → 设备拓扑」(路由 /monitor)。

拓扑页面基于自研 cc-topology 组件渲染全网设备连接关系,支持预览与编辑两种模式。本版(3.5)对拓扑做了一次系统性增强,新增:站点分层视图(设备按站点分组聚合/聚焦)、站点总览钻取(每站点抽象为一个汇总节点,双击钻入)、资产对账(台账与网络实况全量比对)、拓扑变更记录(保存自动留痕+结构化对比)、影响分析(某设备故障会拖死哪些下游)、立即发现(按需触发上报,新链路分钟级成图)与 SNMP 轮询开关/单台立即探测,并把工具条重排为"筛选 / 三簇动作按钮"两行布局。以下按操作顺序逐节说明。

10.1.1 界面与工具条

页面顶部固定两行工具条。第一行为搜索与筛选:

第二行为动作按钮,按"视图 → 发现同步 → 告警"三簇排布,簇间竖线分隔(预览态):

画布左下角常驻线型图例:虚线=无线回传/接入,实线=有线直连,SNMP 徽标=异构设备主动轮询兜底链路;在线/离线/告警状态以节点颜色标识。

10.1.2 预览基础:节点详情卡与异常设备侧栏

点击任意设备节点,画布左上弹出固定详情卡(区别于悬停提示,卡片可交互):在线设备实时展示 IP地址、Mac地址、CPU占用、上线时长、接收/发送速率、关联终端(AP/AC 且有终端时)、信号、速率来源、刷新时间,底部提供 地图定位 / 查看详情 / 该设备告警 / 影响分析 四个操作按钮;离线设备显示"离线状态,没有实时数据"。

异常设备侧栏(右上):汇总全部离线/告警设备,按站点分组("未分配"恒排最后),组头(站点名+计数)点击可折叠该组,每条提供"定位""详情"快捷跳转;侧栏可收起为"异常 N"小按钮,不遮挡画布。编辑态自动隐藏。

主题联动:顶部栏切换深色后,拓扑画布、节点配色与图表整体切换,适合值守大屏。

10.1.3 站点分层视图(新)

站点是设备的台账属性(如"园区总部/车间覆盖"),也是拓扑的第二层视图维度:同站点设备被圈进同一个椭圆分组(combo),大规模网络可按站点逐层收敛地看。

站点分配(工具条,需 top:edit):弹窗列出全部设备,支持按名称前缀分组与按 IP 网段分组两种自动预填(仅预填、可逐行修改;离线无 IP 设备跳过网段分组;清空站点=取消分配),确认后即时生效并刷新分组。

站点视图下拉四种模式:

视图偏好会记住(刷新后保持),站点被清空分配时自动回退"全部展开"。

注意:徽标在线数与分组以实时上报为准;设备离线且无报告数据时按"未分配"归组。

10.1.4 拓扑变更记录(新)

每次保存拓扑自动留痕快照;"变更记录"打开抽屉:快照时间线(时间/操作人/备注)、快照当前(割接/变更前主动留痕,备注可选)、任选两条结构化对比——新增/移除/移动的节点与新增/移除的连线逐条列出,支持删除快照。

10.1.5 资产对账(新)

"对账检查"弹窗将台账与网络实况全量比对:新发现未入库、已入库但失联、登录信息失效等差异逐条列出,可一键应用处置动作;对账事件保留历史记录,可回溯"什么时候、对哪台设备做过什么"。

10.1.6 发现机制:自动绘制与立即发现

编辑模式工具条按"保存链 | 生成工具 | 导入导出"三簇排布:返回 / 保存;自动绘制(按发现策略全量重建连线)、自动布局、发现策略下拉——全量(含ARP/桥表) / 含LLDP邻居 / 含ARP/桥表 / 仅无线;导入(.json 覆盖当前图)/ 导出。手动编辑支持拖拽节点、连线、添加/删除自定义节点(素材来自 cc-elements 图标库)。

立即发现(预览态,需 top:edit):按需触发全部设备马上上报一轮状态,不必等最长 3 分钟的调度周期——新开通的无线链路、刚改的回传关系可以在几十秒内成图;配合周期调度形成"平时自动、急时手动"的发现节奏。

10.1.7 站点总览与钻取(新)

站点视图选"站点总览"后,画布做展示层变换:每个站点抽象为一个虚拟汇总节点(站点名+在线数/总数),站与站之间的多条链路聚合为一条站间链路(悬停可看链路条数),右上提示"站点总览:双击站点钻入"。双击站点节点即钻入该站点的设备拓扑,从下拉切回其他视图即退出。总览是纯展示层变换,不会写入已保存拓扑。

已知限制:总览态下站间聚合连线当前存在渲染缺陷(连线与×N角标不可见,悬停链路仍可见聚合说明),已登记待后续版本修复。

10.1.8 影响分析(新)

节点详情卡点"影响分析":基于已保存拓扑的链路方向推算该设备故障的波及面——下游设备(精确依赖)沿无线语义逐跳展开并给出跳数,相邻设备(有线/手工边)列出一跳邻居(方向未知)。割接前评估"断了这台 AC,哪些 AP 的终端会掉",一目了然。

注意:列表基于已保存拓扑推算,拓扑未保存或与实时链路不符时以保存拓扑为准;当前对手绘/历史拓扑中非标准编号的节点,精确依赖可能为空(口径限制,已登记)。

10.1.9 SNMP 兜底链路(设备详情页)

对无被动上报的第三方交换机/AP,系统提供 SNMP 主动轮询补全有线链路(入口在设备详情页 SNMP 配置区,拓扑画布中以 SNMP 徽标连线呈现):

• LLDP/FDB 轮询开关:对该设备后台低频轮询 LLDP 邻居与转发表,补全有线链路;

• 全局轮询(新):SNMP 轮询总开关(需专业/企业版授权),落库持久、跨重启保持,关闭后不再产生轮询负载;

• 立即探测(新):对单台设备立即采集一轮并回报邻居数,不等 5 分钟周期、不受全局开关约束(同设备 10 秒冷却),用于配置完 SNMP 参数后马上验证连通性。

10.2 设备地图

入口:菜单「设备拓扑与地图 → 设备地图」(路由 /map)。

• 基于高德地图渲染,一次性拉取全部设备,使用设备详情页录入的经纬度定位(高德 GCJ-02 坐标,无需转换);

• 仅渲染经纬度有效的设备,因此新设备入库后请先到设备详情页"地图选点"补录坐标;

• 按 deviceType 选择不同图标(基站/AC/CPE/路由器等),并以视觉区分在线/离线;

• 顶部图例可折叠,按设备类型展示色条与中文名称(路由/交换/AP/AC/CPE/移动),名称与颜色可在“色系配置”中自定义(存于 type_color_config 表,内置种子已修正为中文显示;早期历史库中曾以字面转义串写入 label,升级到当前版本后启动时会自动修复为中文,无需手工改库);

• 点击标记弹出设备静态摘要(名称/类型/状态等),可一键跳转设备详情;

• 与拓扑页"异常设备"面板联动:异常设备可快速定位到地图位置。

11. 可视化

11.1 指标趋势

入口:菜单「可视化 → 指标趋势」(路由 /metricTrend)。

• 选择单台设备与时间窗(6 / 24 / 72 / 168 小时),读取时序库 device_metric_ts;

• 双轴折线图:左轴百分比指标 —— CPU、内存、CCQ、健康评分;右轴 —— 收发速率、信号 dBm;

• 数据受保留期限制(默认最长回溯 7 天),更早的历史请查阅统计报表。

11.2 统计报表

入口:菜单「可视化 → 统计报表」(路由 /report)。

• 条件:聚合周期(日/周/月)+ 日期区间 + 范围(全网或单设备);

• 表格展示每台设备在各周期的均值/极值指标,配合折线图直观对比;

• 支持导出 CSV(含 BOM,Excel 直接打开不乱码)与图表图片导出;

• 说明:周/月报表由日数据二次聚合;受时序保留期(默认 7 天)限制,月度报表按可用天数展示。

11.3 监控大屏

入口:菜单「可视化 → 监控大屏」(路由 /screen)。

• 独立全屏页面(不含系统导航),深色主题,按 1920×1080 设计并随窗口自适应缩放,适合投放值班大屏;

• 聚合展示:总览统计、无线健康、实时告警滚动、设备分布地图等;

• 15 秒自动刷新;地图组件加载不就绪时自动退化为设备分布统计,不影响其余模块;

• 参考整屏效果:

11.4 流量分析

入口:菜单「可视化 → 流量分析」(路由 /traffic)。

面向接口级带宽利用的分析页,数据来自每次采集周期自动写入的时序表 device_interface_traffic_ts(与指标趋势共用采集链路,保留期默认 7 天):

• 设备选择 + 时间窗:选择单台设备与时间窗(1 / 6 / 24 / 168 小时);

• 接口实时快照表:列出各接口最新的实时收发速率(rx/tx bps)与累计字节流量,当某接口峰值超过窗口均值 3 倍时以红色标记,便于快速定位带宽热点;

• 收发趋势面积图:按分钟/小时/日粒度聚合的 rx/tx 速率曲线(tx 轴镜像向下),直观展示链路忙时;

• 全网 TOP 榜:按接口峰值速率排序的横向堆叠柱,定位全网最繁忙的接口。

接口速率与累计字节均直接取自设备上报的 interfacerates 与 interfacestats 报告段,无需人工配置;无流量上报的接口速率为 0。

12. 运维闭环

运维闭环将"告警发现 → 工单处置 → 配置修复 → 批量执行"串成完整链路,并提供设备自助接入向导与队列限流、持续 Ping 两项运维监测能力。

12.1 告警工单

入口:菜单「运维闭环 → 告警工单」(路由 /alarmTicket)。

• 工单自动生成:设备上报越限(runtime)或离线(offline)时,后端自动 upsert 工单;重复触发只递增"发生次数",不产生重复工单;

• 恢复自动解决:数据驱动预警的设备当所有指标从 firing 恢复(resolved)且无剩余告警时,系统自动把该设备 runtime 工单置为"已解决"(状态 3),操作人记为 system,无需人工关单;离线工单仍需人工流转;

• KPI 卡片:未结 / 未处理 / 处理中 / 已解决 / 已关闭 各状态计数;

• 过滤条:按状态、级别、类型、设备 MAC 查询;

• 状态流转:未处理 → 确认 → 处理中 → 已解决 → 已关闭,每次流转可填写备注;操作人由服务端从 JWT 注入,前端不可伪造,全程可审计。

12.2 配置基线

入口:菜单「运维闭环 → 配置基线」(路由 /configBaseline)。

12.3 批量运维

入口:菜单「运维闭环 → 批量运维」(路由 /batchOps)。

• 设备选择:多选表格,支持按名称/MAC 过滤,表头显示"已选 N 台 / 共 M 台";

• 批量配置下发:对已选设备逐台写入 device_script(落库后待设备端拉取执行,非实时,请给予执行时间);

• 固件升级登记:为已选设备登记目标版本,状态置"待执行";设备完成升级后通过 /data/gather/firmware 回执自动更新当前版本与状态,无需人工回填。

12.4 自动备份

入口:菜单「运维闭环 → 自动备份」(路由 /backup)。

自动备份在"配置基线"的快照能力之上,提供周期化、自动化的配置留存,含三块:

备份计划为 opt-in:未新建并启用计划前不会自动抓取;抓取内容仍走"配置基线"同一快照存储,可在配置基线页做 Diff 与回滚。

12.5 接入向导(对接码自助接入)

入口:菜单「运维闭环 → 接入向导」(路由 /onboard)。

对接码自助接入向导把设备接入所需的"令牌 + 服务器地址 + 初始化脚本"封装为三步流程,便于新设备快速纳管:

1. 接入信息:展示本系统对设备可达的服务器地址/端口、设备令牌(启用时显示、可复制)与按当前配置渲染好的 bootstrap.rsc 初始化脚本(可下载,或直接复制到 Winbox 的 New Terminal 执行);若服务器地址未显式配置,页面提示"设备侧将按自身网关自动探测";

2. 一键植入:选择一台已入库的在线设备,由服务端向该设备下发 cloud_* 脚本与计划(幂等,可重复执行),使其开始持续上报;

3. 状态确认:实时探测设备侧云服务配置是否齐全并回连,支持"立即检测"与自动轮询(5s),以标签给出纳管结论(如已启用/已是最新/已被他机纳管/失败/未配置等),并列出缺失项与陈旧项。

未启用云服务(cloudConfig)时页面顶部给出警示,向导不可用,需联系管理员完成服务器配置。向导仅读取接入信息并复用既有植入/探测通道,不新增设备命令接口。

12.6 队列监控

入口:菜单「运维闭环 → 队列监控」(路由 /queueMonitor)。

针对 RouterOS /queue simple 的限流与流量计数做采样 — 展示 — 重置闭环:

采样结果与时序落 device_probe_metric(probe_type=queue)。手动采样随时可用;周期自动采样默认关闭(opt-in),需服务端在 application-client.yaml 将 probeConfig.queueMonitorEnabled 置 true 并重启,系统才按分钟周期对在线设备批量采集。

12.7 Ping 监测

入口:菜单「运维闭环 → Ping监测」(路由 /pingMonitor)。

以"源设备 + 目标地址"为对象做持续 Ping 探测,量化链路时延与丢包:

探测结果落 device_probe_metric(probe_type=ping)并回写对象最近状态。"立即探测"随时可用;周期自动探测默认关闭(opt-in),需服务端 probeConfig.pingMonitorEnabled=true。

13. 设备预警

预警子系统由 9 个页面组成,采用数据驱动的评估引擎(指标字典 + 阈值条目 + 状态机防抖 + 恢复联动),取代早期"固定几项硬编码阈值"的判定方式:每次设备上报时,系统按设备所配置的阈值条目逐项评估,越限且达到"持续次数"才升级为告警(firing),回落即自动恢复(resolved)并发送"已恢复"通知、自动解决工单。

推荐按以下顺序配置:

指标字典(可监控指标与单位)  →  预警设备(为设备挂载阈值条目:指标/算子/上下限/持续次数/级别)
        →  邮箱配置 / 通知渠道(发送通道)  →  预警配置(发给谁/走什么通道/什么模板/什么级别)
        →  预警规则(静默/时段/重试/升级链)  →  预警任务(把"配置+规则"绑定为可执行任务,须为"运行"类型才接收指标告警)
        →  活动告警面板(实时查看 firing)  →  预警日志(执行结果追溯)

灰度说明:是否走新引擎由设备的"评估引擎"标识决定——在"预警设备"里为某设备保存过阈值条目后,该设备即切换到新版(数据驱动);尚未配置条目、仅有旧固定阈值的设备仍走旧版(固定列)判定,二者互斥不会重复告警。

13.1 邮箱配置

入口:菜单「设备预警 → 邮箱配置」。

维护全局 SMTP 邮件服务(邮件通道使用此处配置,无需单独选择渠道):

支持新增、修改、删除。

参数说明与示例:

13.2 通知渠道

入口:菜单「设备预警 → 通知渠道」。

配置短信/语音/企业微信/钉钉/飞书/自定义 HTTP 等通道参数,一个渠道类型可配置多条(如多个钉钉群机器人):

参数说明与示例:

钉钉 / 飞书加签(群机器人安全设置):

当企业为群机器人开启了"加签"安全设置时,需在 AccessSecret(加签密钥) 填入机器人 Webhook 页面给出的 secret(通常以 SEC 开头):

• 钉钉:系统按当前 timestamp 计算 sign = Base64(HmacSHA256(timestamp+"\n"+secret, key=secret)) 并拼到 Webhook 的 URL 上;

• 飞书:系统将 timestamp 与 sign(空密钥的 HmacSHA256)写入请求体;

• 企业微信及未填加签密钥的场景保持直连发送,向后兼容,不受影响。

若机器人采用"自定义关键词"或"IP 白名单"模式,则无需填写加签密钥,留空即可。加签仅影响 IM 群机器人通道,短信/语音/邮件通道无关。

渠道建好后建议先点行内发送测试验证连通性,再投入预警使用。

13.3 指标字典

入口:菜单「设备预警 → 指标字典」(路由 /warningMetric)。

集中维护可被监控的指标(编码、名称、分类、单位、取数方式、支持算子、默认上下限)。系统内置一批常用指标(如 CPU 负载、内存使用率、收发速率、接入终端数、信号强度 dBm、SNR、CCQ、电压、温度、干扰评分、健康分等),内置指标只读(修改/删除按钮禁用,后端 SQL 层亦以 built_in='0' 护栏兜底);运维可添加自定义指标扩展监控维度。

指标取数由后端在收到设备上报时自动解析,无需填写采集脚本;普通运维仅需了解各指标含义并在"预警设备"中挂载阈值即可。

13.4 预警设备(阈值条目)

入口:菜单「设备预警 → 设备配置」(路由 /warningDevice)。

定义被监控设备集合,并为每台(组)设备挂载阈值条目——每个指标一条规则,取代旧的固定电压/温度/信号输入框。

• 新增只需填写集合名称与设备 IP(多台以英文逗号分隔);

• 修改弹窗上半部仍是名称/IP,下半部是阈值条目子表格,可"添加条目/删行"逐条维护。

每条阈值条目字段:

列表"评估引擎"列显示该设备走新版(数据驱动)还是旧版(固定列);保存过条目即切新版。

参数说明与示例:

阈值先宽后紧逐步收紧,避免上线初期告警风暴。删除设备会联动删除其全部阈值条目并即时刷新预警缓存,改配置无需重启。

13.5 预警配置

入口:菜单「设备预警 → 预警配置」。

定义"发生什么级别的告警、走什么通道、发给谁、发什么内容":

参数说明与示例:

13.6 预警规则

入口:菜单「设备预警 → 预警规则」。

定义告警发送策略,防止告警风暴:

参数说明与示例:

13.7 预警任务

入口:菜单「设备预警 → 预警任务」(路由 /warningTask)。

将"预警配置 + 预警规则"绑定为可执行的任务。任务类型已与后端枚举对齐:

列表展示任务名称、类型、关联配置/规则名称、状态与执行次数,支持修改/删除。

任务类型说明(关键):

⚠️ 要让"预警设备"里配置的阈值条目真正发出通知,必须至少启用一个"设备运行状态预警任务"并关联期望的预警配置与规则;否则指标越限只会更新活动告警面板与工单,不会推送通知。

13.8 活动告警面板

入口:菜单「设备预警 → 活动告警」(路由 /warningActiveAlert)。

实时展示当前处于 firing(告警中) 的所有指标告警(来自数据驱动评估引擎),是"现在到底哪些设备哪些指标在报"的统一视图。

工具栏可刷新,或勾选自动刷新(10s)做值守监控。指标回落后该行从此面板消失,并按预警任务联动发送"已恢复"通知、自动解决 runtime 工单。

13.9 预警日志

入口:菜单「设备预警 → 预警日志」。

追溯每次告警派发的执行结果:

• 字段:预警任务、预警状态、通道、接收人、预警内容、Provider 响应、耗时(ms)、预警时间等;

• 支持刷新与批量删除;

• 排查"没收到告警"时:先确认任务启用 → 查看日志中该次派发状态与 Provider 响应 → 结合通道配置中的"成功标识"判断网关侧是否真的发送成功。

关键字段解读:

14. 系统管理

入口:菜单「系统管理」(仅拥有 sys:* 权限的管理员可见,普通用户菜单自动隐藏,直接输入 URL 也会被路由守卫拦回首页)。

14.1 用户管理

• 用户列表(不回显密码)+ 新增/编辑;重置密码、删除;

• 分配角色:多选下拉绑定角色;

• 用户密码由后端 BCrypt 加密入库,任何接口不回传明文;

• 后端防止"自锁"保护:不允许当前管理员删除/停用自身。

字段说明与示例:

14.2 角色管理

• 角色新增/编辑/删除(内置 admin 角色不允许删除);

• 分配菜单:树形勾选该角色可见的菜单(按 parentId 组装,勾选项与 role_menu 存储精确对应);

• 角色决定用户登录后左侧动态菜单的可见范围与接口权限。

分配菜单树勾选示例:

树节点采用独立勾选(check-strictly):勾选"设备预警"目录不会自动全选子项,需逐个确认子菜单,避免误授权。

14.3 菜单管理

• 树表维护菜单项:名称、路由 path、权限标识(permission)、图标 icon、排序 sort、上级 parent;

• 存在子菜单时禁止删除,防止孤儿节点;

• 修改后用户重新登录(或刷新菜单)即生效。

字段填写规则:

14.4 操作审计

• 系统对所有非 GET 的 /api/** 写操作全局落审计日志(密码类字段已掩码);

• 过滤条:用户名、动作关键字、日期区间;

• 行展开可查看请求 params 快照,用于事后追溯"谁在什么时候改了什么";

• 射频信道下发、告警工单流转等操作人均取自 JWT,不可伪造。

方法列彩色标签与展开行说明:

示例排查:发现某日 09:47 一条 POST /api/rf/apply(信道下发)记录,展开可见旧值/新值频率参数与操作人,即可定位到变更源头。

14.5 API Key 管理

入口:菜单「系统管理 → API Key」(仅管理员可见)。

面向对外开放与自动化集成的长期凭证,与登录 JWT(短期会话令牌)互补。支持生成 / 列表 / 吊销:

• 生成POST /api/config/api-key/generate:指定名称与 scope,创建时明文密钥仅展示一次,请当场复制保存;后端仅存其 SHA-256 哈希,之后任何接口不再回传明文;

• 列表GET /api/config/api-key/list:展示名称/scope/创建时间/最后使用,不回显密钥;

• 吊销POST /api/config/api-key/revoke/:id:立即失效,不可恢复。

scope 分级(决定这把 Key 能做什么):

使用方式:请求头 X-Api-Key: <明文密钥> 作用于任意 /api/** 接口;权限门禁按方法分级——GET 需 read,非 GET 需 write。用仅含 read 的 Key 调写接口会返回 403(本轮验证矩阵已实测)。

14.6 MCP 接入

入口:菜单「系统管理 → MCP 接入」(可查看工具清单与接入示例)。

MCP(Model Context Protocol)服务供 AI 助手/自动化平台以标准协议查询与操作本系统。服务端为 JSON-RPC 2.0:

• 端点:POST /mcp(可选 GET /mcp 返回服务信息);该路径不在 /api/ 前缀下,鉴权在 Handler 内部自行校验;

• 鉴权:请求头 Authorization: Bearer <含 mcp scope 的 API Key>;无 Key 或未含 mcp scope 时返回 JSON-RPC error(-32001 / -32003)而非 HTTP 401,属协议约定;

• 方法:initialize、tools/list(返回工具清单)、tools/call(调用具体工具)。

内置工具清单:

示例:curl -X POST http://<host>:<port>/mcp -H "Authorization: Bearer <key>" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{"status":"online"}}}'

14.7 第三方登录

入口:「系统管理 → 第三方登录」管理页面(路由 /oauthSettings,需 sys:oauth 权限、企业版授权),管理员在页面填写参数并保存即生效,无需修改 yaml、无需重启;账号绑定为用户侧操作,位于顶部标题栏右侧「账号绑定」按钮(路由 /oauthBind,登录用户均可见)。

• 启用:在 /oauthSettings 页面配置。页面含总开关与钉钉/飞书各自的独立开关及凭据(钉钉需 AppKey/AppSecret,飞书需 AppID/AppSecret;任一对凭据未填齐时该入口返回“第三方登录未启用或配置不完整”),系统始终可正常口令登录。

• 存储与生效:配置保存于 oauth_config 表,库内值优先覆盖 application-client.yaml 的 oauthConfig 兜底值(yaml 仅在库中无记录时生效);登录页可见的供应商列表读取公共端点 GET /api/oauth/config,库内保存后即时生效免重启。

• 密钥安全:AppSecret 落库前以 AES-GCM 加密存储;页面回显仅给脱敏信息(AppKey 首尾各 2 字符 + ****,密钥只显示“已设置/未设置”),密钥永不回显;编辑时密钥留空 = 不改动存量值。

• 版本限定:第三方登录配置页、登录与账号绑定均属企业版门控功能(OAUTH 键);非企业版证书下菜单 /oauthSettings 置灰锁定、/oauthBind 入口锁定、/api/oauth/** 返回 403(见 §18.10)。

• 回调地址:redirectUri 必须填写为前端 hash 路由形式 http://<系统地址:端口>/#/oauth/callback/<provider>,并在钉钉/飞书开放平台登记完全一致的回调地址;留空时的相对兜底路径无法被平台正确回跳。

• 账号绑定页 /oauthBind(顶部栏进入):GET /api/oauth/config 展示启用状态与供应商;GET /api/oauth/bindings 列出当前用户已绑定身份;POST /api/oauth/bind 完成首次绑定、POST /api/oauth/unbind 解绑(均用登录 JWT,绑定关系存于 oauth_binding 表)。

• 授权链路 GET /api/oauth/url/:provider 与回调 GET /api/oauth/callback/:provider 属公开白名单,由登录页第三方入口触发。

15. 系统工具

入口:左侧菜单「系统工具」。

面向选定在线设备运行只读诊断/运维工具,全部经后端 RouterOS API 实时执行(要求设备在线且已保存登录凭据;选择离线设备时页面会给出黄色警示)。

工具条选择目标设备(下拉含名称/MAC/在线标签),页签提供 5 种工具:

链路连通性与带宽问题排查可参考系统工具实测:

日志联动分析:

16. 退出登录

点击顶部标题栏右侧退出按钮:

1. 弹出确认框"确定注销并退出系统吗?";

2. 确认后系统清除本地令牌与用户状态,并跳转回登录页;

3. 超时未操作重新访问系统时同样会要求重新登录。

17. 典型业务流程

17.1 新网络接入(从零到监控)

① 登录系统 → ② 设备扫描(填网段+凭据,逐台选类型并保存)
   → ③ 设备列表(刷新状态确认在线)→ ④ 设备详情(编辑名称/位置/经纬度/照片)
   → ⑤ 设备拓扑(自动绘制→保存布局)→ ⑥ 数据看板/监控大屏验收

17.2 无线质量优化

数据看板发现"差"级 AP → 无线终端定位高负载/弱信号 AP
   → 查看健康趋势确定劣化时间窗 → 射频分析"开始扫描"
   → 查看推荐信道与干扰评分 → 确认业务低峰期"一键下发"
   → 下发审计留痕 → 观察评分是否回升

17.3 终端投诉处理(掉线/漫游异常)

无线终端 → 选择 AP → 定位投诉终端 MAC 行 → 点击查看事件时间线
   → 分析 7 天内接入/离开与信号变化 → 结合 CCQ/SNR 判断覆盖或干扰问题
   → 转射频分析或调整点位

17.4 告警体系落地

指标字典(确认待监控指标)→ 邮箱配置/通知渠道 → 预警设备(圈定设备 + 挂载阈值条目)
   → 预警配置(级别/通道/接收人/模板)→ 预警规则(静默期/时段/重试/升级链)
   → 预警任务(绑定并启用；指标告警需一个"运行状态"类型任务才能派发)
   → 活动告警面板实时观察 firing → 预警日志验证派发 → 告警工单处置(恢复自动关单)

17.5 配置合规与灾备

配置基线:抓取配置 → 保存快照 → 设为基线
   日常:定期抓取与基线 Diff → 发现漂移 → 一键回滚(待设备端执行)
   批量:批量运维下发脚本 / 登记固件升级 → 回执自动更新状态
   灾备:自动备份启用计划(仅配置变更才存快照)→ 快照下载留存

17.6 新设备自助接入(对接码向导)

接入向导:① 查看服务器地址/设备令牌、下载 bootstrap.rsc
   → ② 选择在线设备"一键植入"云服务配置(幂等)
   → ③ "立即检测 / 自动轮询"确认纳管状态(缺失项/陈旧项一目了然)

17.7 链路质量与限流监测

队列监控:选设备 → 采样 → 查看各队列限速/已用字节 → 打开趋势曲线 → 需要时"重置计数"
Ping 监测:新增"源设备 + 目标"对象 → "立即探测一轮" → 查看最近状态 → 打开延迟/丢包曲线
   (周期自动采样/探测默认关闭,需服务端开启 probeConfig 后按分钟周期运行)

18. 授权与试用

本系统采用授权证书(License)强校验机制。试用用户与正式客户在此关注同一套规则:证书放在哪里、到期前会怎样提醒、到期后会造成什么后果。

18.1 证书文件位置

证书均位于与 topology.exe 同级的 license\ 目录(即运行目录下,不是 jar 内部):

18.2 校验如何生效

授权校验共三层,逐层收紧:

1. 启动门:程序启动时校验一次;

2. 周期复检:默认每 30 分钟复检一次(对应配置 licenseRecheckMinutes),因此到期时间已过但程序未重启也会被识别;

3. 每次请求:所有业务接口逐个判定,授权失效时统一返回 403。

18.3 到期前提醒

进入“到期前 N 天”窗口后(默认 N=7,可调),会在两处提示续期:

提醒只在尚未过期时有效。已过期后写操作已被拦截,登录也进不去,因此“没看到提醒”不等于“不会过期”,请以 license\license.lic 的有效期或界面状态接口为准。

18.4 到期后的表现

重要:到期后连登录都会被拦(不只是“不能保存”),因此请务必在到期前完成续期,避免在无人值守时彻底失去系统入口。

18.5 试用证书的两个认知点

• 有效期从“签发时刻”起算,不是从“安装时刻”起算。例:厂商 10 月 2 日签发的 15 天证书,你在 10 月 10 日才安装,可用天数只剩 7 天。请拿到安装包后尽快部署。

• 试用包与正式包功能完全一致,未开通时长限制以外的功能裁剪。

18.6 按机器绑定交付

部分证书会绑定指定机器的网卡 MAC 以阻止拷到第二台机器运行:

• 普通(不绑定)证书:直接放 license\ 即可,默认配置就能跑;

• 绑定证书:除放证书外,服务端需将 application.yaml 的 securityConfig.licenseHardwareCheck 置为 true 才会强制生效(默认 false,以保证旧的非绑定证书升级后不被误拦);

• 绑定生效后,更换网卡/更换主机将导致校验失败,需联系厂商重新签发。

18.7 续期(更换证书)步骤

1. 从厂商取得新的 license.lic(如需换公钥库,会一并下发 publicCerts.keystore);

2. 停止服务(托盘右键“退出”或 stop.bat);

3. 覆盖 license\license.lic;若为新公钥体系,同时覆盖 license\publicCerts.keystore;

4. 删除 license\license.installed(避免命中旧的校验缓存);

5. 重新启动,确认启动日志出现“授权校验通过”且首页不再弹续期提醒。

证书与公钥库必须同批成对:用新公钥库配旧证书、或用旧公钥库配新证书,均会报“证书无效”。

18.8 相关配置项速查

以下项位于 application.yaml 的 securityConfig 下,修改后需重启生效:

18.9 查看当前授权状态

已登录用户可访问状态接口 GET /api/license/status(仅需登录,不需额外权限),返回字段:

18.10 版本档位与功能门控

证书除有效期外还携带授权版本(Edition)信息,决定“能用哪些功能、能管多少设备”。版本判定与登录权限(RBAC)正交:权限管“谁能操作”,版本管“这份授权买没买这个功能”。

• 判定来源:版本取自证书内的 edition 字段;证书未携带版本信息(历史“通用证书”)或无法识别时,按企业版全功能不限兜底,保证存量部署零影响;证书可在基线之上显式追加 allowedFeatures(取并集)。

• 未授权时的表现:对应功能菜单置灰并显示锁标记;接口在鉴权前被版本门控拦截,返回 403(文案“当前授权版本[xx]不含该功能,如需使用请升级授权”);社区/标准版首页改为起始引导页(见 §4)。

• 设备配额:超出当前版本设备上限时,新增纳管会被拒绝并给出升级引导(计数按 device 表全量,离线设备不释放名额)。

• 查看当前档位:GET /api/license/features(仅需登录)返回 editionName、maxDevices/unlimitedDevices、backupLimitPerDevice、当前已纳管台数与生效功能集等。

• 升级方式:由厂商签发更高档位证书,更换步骤同 18.7;各版本定价与能力明细见《收费模式及标准》。

19. 数据文件与安全说明

本章面向部署人员,说明数据落在哪里、哪些内容受保护、哪些不受保护。

19.1 数据文件清单

19.2 数据库本身没有访问口令

本系统使用 SQLite 单文件数据库(data\routeros.s3db)。需要明确告知使用方:

• 该文件不需要任何用户名/口令即可被打开,任何标准 SQLite 工具(如 DB Browser for SQLite)都能直接读取全部表;文件扩展名不是保护手段;

• 这是嵌入式单机库的行业常规做法,代价是文件级权限就是唯一的访问控制。

因此请务必:

19.3 哪些字段已加密

加密算法说明:上表四类密文的新写入一律采用 AES/GCM(随机 IV、完整性校验,前缀 ENCG:);历史 ENC:(AES/ECB)密文仍可直接解密读取(双读兼容),且服务启动时会自动把存量 ENC: 记录一次性升级为 ENCG:(幂等,升级失败保留原值不影响启动)。无前缀=历史明文,启动期加密迁移与取用前加密兜底不变。

两条重要提醒:

1. 设备口令密文与本机密钥绑定——只把 data\ 拷到另一台机器而不同时迁移 config\aes.key,原存凭据将无法解密,需重新录入。

2. 拿到整机目录的人同时拿得到 config\aes.key,因此“列加密”防的是“只拷走库文件”的场景,不能防整机拷贝。

19.4 数据导出与留存建议

• 需要对外提供数据时,优先使用界面报表/导出功能,只给业务字段,不要直接给 .s3db 文件;

• 报废/重装前若库中存有真实设备凭据,建议先停用服务并安全删除 data\ 与 backup\;

• 审计需求:“系统管理 → 操作审计”保留了写操作痕迹,但该表同样无口令保护,请按保密级处置。

20. 常见问题(FAQ)