A modern and elegant dashboard for network traffic visualization and analysis.
Neko Master 代码库综合研究报告(中文)
执行摘要
Neko Master 是一个面向边缘网关的现代网络流量分析平台,提供实时监控、流量审计与多网关管理能力。系统从 Clash/Mihomo 与 Surge 采集流量,聚合到 SQLite,并通过 Next.js 前端可视化。
1. 项目总览
1.1 目标与边界
Neko Master 是“流量可观测层”,它不提供代理接入或路由能力,而是聚焦:
- 从网关采集并聚合流量统计
- 向客户端推送实时 WebSocket 更新
- 提供历史流量分析与可视化
- 同时管理多个后端网关
1.2 技术栈
| 层 | 技术 |
|---|---|
| 前端 | Next.js 16、React 19、TypeScript、Tailwind CSS v4 |
| UI | shadcn/ui(new-york)、lucide-react |
| 图表 | Recharts、D3.js、react-simple-maps |
| 状态管理 | TanStack React Query、WebSocket hooks |
| 后端 | Fastify 5、ws、better-sqlite3 |
| GeoIP | maxmind(本地 MMDB)+ 在线回退 |
| i18n | next-intl(zh/en) |
| 工程化 | Turbo monorepo、pnpm workspaces |
| 部署 | Docker、Next.js standalone |
1.3 仓库结构
neko-master/
├── apps/
│ ├── collector/ # 后端采集服务
│ │ └── src/
│ │ ├── index.ts # 入口,编排全部服务
│ │ ├── app.ts # Fastify API
│ │ ├── websocket.ts # WebSocket 广播
│ │ ├── collector.ts # Clash WS 采集
│ │ ├── surge-collector.ts # Surge 轮询采集
│ │ ├── realtime.ts # 内存实时聚合
│ │ ├── batch-buffer.ts # 批量写入优化
│ │ ├── geo-service.ts # GeoIP 服务
│ │ ├── db.ts # 数据库门面
│ │ └── database/ # schema + repositories
│ └── web/ # Next.js 前端
├── packages/
│ └── shared/ # 共享类型与工具
└── docs/
2. 核心架构
2.1 高层数据流
Clash/Mihomo --WebSocket--> Collector
Surge --HTTP Poll--> Collector
Collector -> SQLite (持久化)
Collector -> RealtimeStore (低延迟)
Collector -> WS Server (实时推送)
Web UI 通过 HTTP + WebSocket 消费数据
2.2 三层模型
- 前端层(Next.js):HTTP 拉取 + WS 实时更新。
- 采集层(Fastify + ws):API、广播、网关采集。
- 存储层(SQLite + 内存):持久化 + 低延迟查询。
3. 后端深度分析
3.1 入口编排(index.ts)
启动流程包含:
- 初始化数据库
- 初始化 GeoIP
- 启动 WS 服务(3002)
- 启动 API(3001)
- 每 5 秒执行后端管理循环
- 每 6 小时执行自动清理
3.2 Clash 采集器(collector.ts)
- 连接
ws://.../connections - 支持 Bearer 认证
- 断线后 5 秒重连
- 对每条连接计算流量增量并写入 batch + realtime
- 清理超时未出现连接(默认 5 分钟)
3.3 Surge 采集器(surge-collector.ts)
- 轮询
GET /v1/requests/recent - 默认 2 秒,错误时指数退避
- 解析
notes中策略路径并转换为统一链路格式 - 用
recentlyCompleted(5 分钟 TTL)防止重复计数
3.4 RealtimeStore(realtime.ts)
维护多个按 backendId 分片的实时 map:summary、minute、domain、ip、proxy、device、rule、country。
核心能力:
recordTraffic()写入实时增量merge*()与数据库结果合并clearTraffic()在 flush 后清空对应增量- 超限时按流量淘汰低价值条目(底部 25%)
3.5 BatchBuffer(batch-buffer.ts)
- 复合键聚合:
backendId + minute + domain + ip + chain + rule + sourceIP... - flush 条件:30 秒或 5000 条
- 分两阶段写入:流量统计 + 国家统计
3.6 WebSocket 服务(websocket.ts)
连接与订阅流程:
- 客户端连接(可通过 query token/cookie)
- 服务端鉴权
- 客户端发送
subscribe(后端、时间范围、最小推送间隔等) - 服务端按订阅推送
stats
机制细节:
- 全局广播节流(最小 1 秒)
- 客户端级最小推送间隔
- 摘要缓存:实时范围短 TTL,历史范围长 TTL
3.7 数据库层
核心表
| 表 | 作用 |
|---|---|
domain_stats |
域名聚合 |
ip_stats |
IP 聚合 |
proxy_stats |
代理链路聚合 |
rule_stats |
规则聚合 |
country_stats |
国家聚合 |
device_stats |
设备(源 IP)聚合 |
事实表(范围查询)
| 表 | 粒度 | 场景 |
|---|---|---|
minute_dim_stats |
分钟 | 短时间范围(<6h) |
hourly_dim_stats |
小时 | 长时间范围(>6h) |
设计模式
StatsDatabase门面 + 多仓库分域实现BaseRepository提供通用解析和聚合工具- DB 范围查询缓存:实时约 8 秒、历史约 5 分钟
3.8 GeoIP 服务(geo-service.ts)
双提供者:
- 在线 API(默认)
- 本地 MMDB(可选)
查找流程:私网短路 -> DB 缓存 -> 失败冷却 -> 并发去重 -> 队列限流查询 -> 回写缓存。
容错策略:
- 失败 IP 30 分钟冷却
- 队列溢出丢弃新请求
- 周期清理失败记录
4. 前端深度分析
4.1 Next 配置(next.config.ts)
/api/*rewrite 到 collector- PWA 仅生产启用
- 注入版本号与 WS 端口等环境变量
4.2 Dashboard 结构
DashboardPage 由 Sidebar、Header、Content 组成,Content 按 tab 切换:Overview、Domains、IPs、Proxies、Rules、Devices、Regions。
4.3 数据获取模式
- HTTP:React Query 拉取历史和分页数据
- WS:自定义 hook 订阅实时数据并更新本地状态/缓存
4.4 国际化
next-intl- 语言:
zh(默认)、en - 文案:
apps/web/messages/{zh,en}.json
5. 多后端架构
5.1 后端隔离
- 数据库:主键包含
backend_id - RealtimeStore:按后端分片
- WebSocket:客户端订阅特定后端
5.2 后端管理循环
每 5 秒执行:读取配置 -> 判断是否变更 -> 重启/启停采集器 -> 清理已删除后端实例。
5.3 后端类型
| 类型 | 协议 | 数据源 |
|---|---|---|
clash |
WebSocket | /connections |
surge |
HTTP 轮询 | /v1/requests/recent |
6. 认证与安全
6.1 Cookie 鉴权
- 用户在设置中配置 token
- 服务端 hash 后存入
auth_config - 登录后签发
HttpOnlycookieneko-session - 后续请求自动携带 cookie
6.2 鉴权中间件
- 公共路由跳过
- 当开启鉴权时,验证 cookie 或 Bearer token
- 校验失败返回 401
6.3 紧急访问模式
FORCE_ACCESS_CONTROL_OFF=true可临时关闭鉴权- 仅用于恢复场景,不建议生产启用
7. 性能优化
7.1 DB 级
- WAL 模式
synchronous=NORMAL- 增大 cache
- 内存临时表
- busy timeout
7.2 应用级
- 批量写入(30 秒或 5000 条)
- 查询缓存(实时短 TTL / 历史长 TTL)
- 内存 RealtimeStore 增量聚合
- WS 广播节流
- GeoIP 查询限速
7.3 内存治理
- domain/ip 上限 50K
- 超限淘汰低流量项
- 连接陈旧清理
8. 数据保留
配置存储于 app_config:
retention.connection_logs_daysretention.hourly_stats_daysretention.auto_cleanup
自动清理每 6 小时执行一次,按阈值删除过期 minute/hourly 数据。
9. 环境变量
9.1 核心变量
| 变量 | 默认值 | 说明 |
|---|---|---|
DB_PATH |
./stats.db |
SQLite 路径 |
COOKIE_SECRET |
自动生成 | Cookie 签名密钥 |
API_PORT |
3001 | API 端口 |
COLLECTOR_WS_PORT |
3002 | WS 端口 |
WEB_PORT |
3000 | Web 端口 |
9.2 调优变量
| 变量 | 默认值 | 说明 |
|---|---|---|
FLUSH_INTERVAL_MS |
30000 | flush 间隔 |
FLUSH_MAX_BUFFER_SIZE |
5000 | 缓冲上限 |
REALTIME_MAX_MINUTES |
180 | 实时窗口 |
DB_RANGE_QUERY_CACHE_TTL_MS |
8000 | 实时查询缓存 TTL |
DB_HISTORICAL_QUERY_CACHE_TTL_MS |
300000 | 历史查询缓存 TTL |
10. 测试
- 框架:Vitest
- 位置:
apps/collector/src/**/*.test.ts - 以仓库与服务层测试为主,前端自动化测试仍偏少
常用命令:
pnpm --filter @neko-master/collector test
pnpm --filter @neko-master/collector test -- src/modules/auth/auth.service.test.ts
pnpm --filter @neko-master/collector test:watch
11. Docker 部署
- 单容器运行:Web(3000)+ API(3001)+ WS(3002)
- 推荐使用
docker-compose挂载data与可选geoip目录 - 反向代理需正确转发
/_cm_ws并设置 Upgrade 头
12. 关键设计模式
- Repository Pattern:分离数据访问与业务逻辑
- Facade Pattern:
StatsDatabase统一入口 - Observer Pattern:WS 广播订阅更新
- Strategy Pattern:GeoIP 在线/本地策略切换
- Batch Aggregation Pattern:批量聚合写入,显著降低 I/O
13. 可改进方向
- 类型安全:GeoIP 返回类型可再收紧
- 错误体系:可引入更统一的结构化错误模型
- 性能:RealtimeStore 可探索 LRU 替代当前淘汰策略
- 测试:补齐前端与端到端覆盖
- 文档:可生成 OpenAPI/Swagger 文档
14. 结论
Neko Master 在架构上实现了采集、存储、展示的清晰分层,并通过批量聚合、实时缓存和多后端隔离获得了较好的性能与可维护性。整体已具备生产可用形态,后续可在测试深度、契约治理和观测性上进一步加强。