iKuai Console

UniFi Network「Site Overview」风格的爱快(iKuai)控制台。仓库分为两个独立工程:

frontend/   Vite + React + TypeScript,轮询爱快 v4.0 REST API
backend/    Node.js ISP 连通性探测服务,数据存 MySQL
openapi/    爱快 v4.0 规范(98 份,字段依据)

前后端各自有独立的 package.json 与 .env,可分别安装、运行、部署。

⚠️ 系统要求:仅支持 iKuai(爱快)4.0 及以上版本的系统 —— 依赖 iKuai v4.0 REST API(/api/v4.0/...),旧版固件(3.x 及更早,仅有 /Action/call 接口)不兼容。

⚠️ 必须部署数据库(MySQL): 后端用 MySQL 持久化 ISP 探测历史以及登录账号,因此 MySQL 是必需依赖,运行后端前请先准备好(见下方「MySQL」)。如只是本地试跑前端,可不连库,但 ISP 历史与登录将不可用。

⚠️ 关于定位:为了防止不必要的问题,当前版本设置为「只读看板」 —— 所有页面只做数据展示(监控、统计、状态总览),不提供任何写入/修改设备配置的操作。后续会逐步加入可写功能,请留意后续更新。

运行截图

截图取自真机(爱快 4.0.222),界面为 UniFi Network 风格,支持浅色 / 深色主题,右上角 LIVE 表示实时轮询中。

总览与拓扑

_{总览 · 全网健康度 / WiFi / 互联网流量 / ISP 延迟 / AP 负载}

_{拓扑 · 网络拓扑图 + 线路实时监控}

设备与客户端

_{设备 · 网关 / 周边设备列表与状态}

_{客户端 · 在线终端、接口、实时上下行}

网络

_{物理网口 · 网口连接 / 速率 / 双工}	_{接口 · WAN / LAN 配置总览}
_{DHCP 策略 · 地址池 / 网关 / DNS / 租期}	_{静态分配 · IP-MAC 绑定}
_{DHCP 租约 · 当前已分配地址}	_{DNS 设置 · 代理 / 缓存 / 防护状态}

路由 · VPN · 认证 · 对象

_{路由 · 负载分流 / 域名分流 / QoS / 静态路由}	_{VPN · WireGuard / IPSec / OpenVPN / L2TP 等}
_{认证 · 在线认证用户 / 账号 / 套餐 / WEB 认证}	_{对象库 · IP / MAC / 域名 / 端口 / 时间对象}

洞察(Insights)

_{流量 · 应用 / 终端流量 TOP 排行}	_{射频 · AP 射频 / 信道在用终端统计}
_{负载 · 性能 / 网络 / 在线终端 / 收发包趋势}	_{审计 · 行为审计、协议占比与终端排行}

服务 · 安全 · 日志 · 系统

_{服务 · FTP / Samba / SNMP / HTTP 服务总览}	_{安全 · MAC / 域名 / URL 访问控制、ACL}
_{安全 · 高级防护(禁 PING / DoS / TCP MSS 等)}	_{系统 · 系统信息、版本、维护与性能}

截图中部分敏感字段(客户端名称、MAC、DNS、公网地址等)已做打码处理。

快速开始

# 1) 安装依赖(两个工程)
npm run install:all        # 等价于在 frontend/ 与 backend/ 各 npm install

# 2) 准备数据库(必需,见下方「MySQL」)并填好 backend/.env

# 3) 启动(两个终端)
npm run backend            # 终端 A:ISP 探测后端 (:5274)
npm run frontend           # 终端 B:前端 (http://localhost:5273)

# 4) 浏览器打开 http://localhost:5273,用首次启动的默认账号 admin / admin 登录,并尽快改密:
#    cd backend && npm run user passwd admin 你的新密码

也可直接进入子目录运行:cd frontend && npm run dev / cd backend && npm start。

登录与 ISP 历史都依赖后端 + MySQL;只跑前端时这两项不可用,其余真实数据照常。

配置

前端 frontend/.env:

变量	说明
`VITE_IKUAI_TOKEN`	API 密钥,作为 `Authorization: Bearer <token>` 发送
`VITE_IKUAI_BASE`	爱快设备地址(Vite 把 `/api` 代理到这里)
`VITE_POLL_MS`	轮询间隔(毫秒),默认 2000
`VITE_ALLOW_MOCK`	`1` 时设备不可达回落模拟数据;`0` 只用真机
`SVC_PORT`	后端端口,Vite 把 `/svc` 代理到这里

后端 backend/.env:

变量	说明
`IKUAI_BASE` / `IKUAI_TOKEN`	爱快设备地址与密钥(用于读取 WAN 网关做 ISP 延迟探测)
`SVC_PORT`	后端监听端口,默认 `5274`
`PROBE_INTERVAL_MS`	探测间隔,默认 `300000`(5 分钟)
`ISP_LOOKUP_URL`	解析当前 ISP 名称的 geo-IP 服务(默认 ip-api.com)
`DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME`	MySQL 连接
`AUTH_ENABLED`	是否开启登录(`1` 开启,`0` 关闭),默认 `1`
`AUTH_SECRET`	会话 Cookie 的 HMAC 签名密钥;留空则每次启动随机生成(重启后登录失效)
`AUTH_USER` / `AUTH_PASSWORD`	首次启动的初始账号(仅在 `users` 表为空时创建);默认 `admin` / `admin`
`AUTH_SESSION_HOURS`	登录会话有效期(小时),默认 `168`(7 天)

secure:false 的 Vite 代理兼容自签名证书;浏览器只与 Vite 同源通信,无 CORS/混合内容。 ISP 名称解析会把路由器公网 IP 发送给第三方(ip-api.com),可通过 ISP_LOOKUP_URL 更换或自建。

MySQL

必需依赖。 后端用 MySQL(mysql2)持久化探测历史(probes 表)与登录账号(users 表),所以运行后端前必须先部署 MySQL(5.7+ / 8.x);已弃用 SQLite。

# 初始化数据库与表(MySQL 5.7+ / 8.x)
mysql -u root -p < backend/sql/init.sql

backend/sql/init.sql 会创建 ikuai_console 库与 probes / users 表(脚本里附带可选的最小权限账号)。若 backend/.env 中的账号具备建库权限,后端启动时也会自动建库建表;连不上时会重试并照常对外服务(但登录需要数据库就绪)。

probes:每个探测周期一行 —— ts(unix 秒,主键)、online、isp、ip、以及到运营商/Cloudflare/Google/GitHub/Microsoft 的延迟(ms)。
users:登录账号 —— username(唯一)、password(scrypt 哈希,绝不明文)、创建/更新时间。

控制台带一个简单的登录门:账号存在 MySQL 的 users 表里,密码用 scrypt 加盐哈希(node:crypto,无第三方依赖,绝不明文存储)。登录态是一枚 HttpOnly、HMAC 签名的会话 Cookie(AUTH_SECRET 签名),后端对 /api(转发到爱快)与 /svc/isp/* 数据接口做鉴权拦截。

首次启动默认 admin / admin(users 表为空时,后端按 AUTH_USER/AUTH_PASSWORD 创建初始账号并在日志告警)。请尽快改密:
```
cd backend && npm run user passwd admin 你的新密码
```

管理账号(在 backend/ 下运行):

npm run user add    <用户名> <密码>     # 新建用户
npm run user passwd <用户名> <新密码>   # 改密码
npm run user list                        # 列出用户

建议设置固定的 AUTH_SECRET(在 backend/.env 里),否则每次重启都要重新登录。生成一个:
```
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
关闭登录:设 AUTH_ENABLED=0(适合内网可信环境)。
修改密码:登录后点右上角头像即可弹窗改密(也可用上面的 npm run user passwd)。

接口:POST /svc/auth/login、POST /svc/auth/logout、GET /svc/auth/me、POST /svc/auth/password(改密,需登录态)。

开发模式(Vite)下 /api 由 Vite 直接代理到设备、不经后端,因此登录拦截只在“单进程/Docker 部署”(后端转发 /api)时对 /api 生效;前端 UI 始终有登录门。

后端接口

GET /svc/isp/summary — 当前 ISP 名称、公网 IP、各目标延迟、24h/7d 在线率
GET /svc/isp/history?buckets=60&hours=24 — 分段在线率(驱动「ISP 性能」长条)

零运行时依赖之外仅 mysql2:node:http + node:net + 系统 ping。

Docker 部署(两容器:host 探测 + 1panel-network 托管)

同一个镜像跑两个角色(ROLE),通过 MySQL 解耦:

服务	网络	职责
`probe`	`network_mode: host`	ISP 检测 + 延迟探测(走宿主网卡,延迟准、能 ICMP、能到 WAN 网关),写 MySQL
`web`	`1panel-network`	托管前端 + 反代 `/api` + 提供 `/svc`,读 MySQL;映射 `60001:5274`

# 复用 backend/.env;1panel-network 必须已存在(external)
docker compose up -d --build
# 浏览器访问 http://<宿主机>:60001

iKuai token 由 web 后端注入(IKUAI_TOKEN),不进前端包。
probe 加了 cap_add: NET_RAW,运营商(网关)延迟才不为空。
MySQL 解析:web 在桥接网里解析不了 Rasp-Mysql 这种主机名 —— 把 backend/.env 的 DB_HOST 改成 MySQL 的 IP(对两个容器都最省事),或在 web 用 extra_hosts 映射。
1panel-network 需先存在(由 1Panel 创建);compose 里声明为 external: true。

单进程模式:不设 ROLE(默认 all)即 probe+web 合一;再设 FRONTEND_DIR=<dist 路径> 就能一个进程托管前端 + 反代 /api + 探测(适合不分网络的简单部署)。

功能(全部真实数据)

总览 UniFi 风格:顶栏 + 左侧设备/ISP 面板 + 主健康区;浅色主题,右上角切换深色。
ISP 卡片 — 真实 ISP 名称 + 到运营商/Cloudflare/Google/GitHub/Microsoft 的真实延迟。
ISP 性能 — 后端 MySQL 历史在线率。
无线 / AC — 先查 GET /network/ac/services 的 ac_status;未开启 AC 显示「未开启 AC 功能」, 开启后按 wireless-score / wireless-statistics / ac/ap-config 真实渲染。

结构

frontend/
  src/lib/        api.ts(iKuai 端点) svc.ts(后端客户端) auth.ts(登录) format.ts usePoll.ts mock.ts
  src/components/  Header Sidebar DevicePanel charts(纯SVG) ui icons
  src/pages/      Dashboard.tsx … Login.tsx(登录页)
  vite.config.ts  tsconfig*.json  index.html  .env
backend/
  src/index.mjs   HTTP 接口 + 探测调度 + 登录鉴权
  src/lib/        env.mjs db.mjs(mysql2) ikuai.mjs probe.mjs auth.mjs(scrypt 哈希 + 会话签名)
  src/cli/user.mjs 账号管理 CLI(npm run user)
  sql/init.sql    建库建表脚本(probes + users)
  .env

Name		Name	Last commit message	Last commit date
.claude		.claude
backend		backend
frontend		frontend
images		images
openapi		openapi
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

iKuai Console

运行截图

总览与拓扑

设备与客户端

网络

路由 · VPN · 认证 · 对象

洞察(Insights)

服务 · 安全 · 日志 · 系统

快速开始

配置

MySQL

登录

后端接口

Docker 部署(两容器:host 探测 + 1panel-network 托管)

功能(全部真实数据)

结构

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

iKuai Console

运行截图

总览与拓扑

设备与客户端

网络

路由 · VPN · 认证 · 对象

洞察(Insights)

服务 · 安全 · 日志 · 系统

快速开始

配置

MySQL

登录

后端接口

Docker 部署(两容器:host 探测 + 1panel-network 托管)

功能(全部真实数据)

结构

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages