Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

18.0 KB
Raw Blame
#!/usr/bin/env node
// Generates docs/architecture.excalidraw from the architecture in docs/architecture.md

const fs = require('fs');

let _seed = 1000;
const now = Date.now();

function s() { return _seed++; }

function rect(id, x, y, w, h, bg, strokeColor = "#495057", strokeWidth = 2) {
  return {
    id, type: "rectangle",
    x, y, width: w, height: h,
    angle: 0, strokeColor, backgroundColor: bg,
    fillStyle: "solid", strokeWidth, strokeStyle: "solid",
    roughness: 0, opacity: 100, groupIds: [], frameId: null,
    roundness: { type: 3 }, seed: s(), version: 1, versionNonce: s(),
    isDeleted: false, boundElements: [], updated: now, link: null, locked: false
  };
}

function text(id, x, y, content, fontSize = 13, color = "#212529", align = "left") {
  const lines = content.split('\n');
  const w = Math.max(...lines.map(l => l.length)) * fontSize * 0.56 + 16;
  const h = lines.length * fontSize * 1.55 + 8;
  return {
    id, type: "text",
    x, y, width: w, height: h,
    angle: 0, strokeColor: color, backgroundColor: "transparent",
    fillStyle: "solid", strokeWidth: 1, strokeStyle: "solid",
    roughness: 0, opacity: 100, groupIds: [], frameId: null,
    roundness: null, seed: s(), version: 1, versionNonce: s(),
    isDeleted: false, boundElements: [], updated: now, link: null, locked: false,
    text: content, fontSize, fontFamily: 1,
    textAlign: align, verticalAlign: "top",
    containerId: null, originalText: content,
    lineHeight: 1.55, baseline: fontSize
  };
}

function arrow(id, x1, y1, x2, y2, color = "#868e96", dashed = false) {
  const dx = x2 - x1, dy = y2 - y1;
  return {
    id, type: "arrow",
    x: x1, y: y1, width: Math.abs(dx), height: Math.abs(dy),
    angle: 0, strokeColor: color, backgroundColor: "transparent",
    fillStyle: "solid", strokeWidth: 2,
    strokeStyle: dashed ? "dashed" : "solid",
    roughness: 0, opacity: 100, groupIds: [], frameId: null,
    roundness: { type: 2 }, seed: s(), version: 1, versionNonce: s(),
    isDeleted: false, boundElements: [], updated: now, link: null, locked: false,
    points: [[0, 0], [dx, dy]],
    lastCommittedPoint: null, startBinding: null, endBinding: null,
    startArrowhead: null, endArrowhead: "arrow"
  };
}

function label(id, x, y, content, fontSize = 12, color = "#495057") {
  return text(id, x, y, content, fontSize, color);
}

const elements = [];
const e = (...args) => elements.push(...args);

// ─────────────────────────────────────────────────────────────────
// TITLE
// ─────────────────────────────────────────────────────────────────
e(text("title", 40, -50, "Neko Master 系统架构图", 28, "#212529"));

// ─────────────────────────────────────────────────────────────────
// LAYER 1: FRONTEND  y: 0 → 440
// ─────────────────────────────────────────────────────────────────
const FE_Y = 0, FE_H = 440;
e(rect("fe-layer", 40, FE_Y, 1760, FE_H, "#e7f5ff", "#1971c2", 3));
e(text("fe-title", 60, FE_Y + 8, "🖥  前端展示层 (Frontend)  ·  Next.js 16 App Router", 17, "#1864ab"));

// Next.js inner container
e(rect("fe-nextjs", 70, FE_Y + 38, 1700, 185, "#d0ebff", "#339af0", 2));
e(text("fe-nextjs-t", 90, FE_Y + 46, "Next.js 16 (App Router)", 14, "#1864ab"));

// 4 page cards
const CARDS = [
  ["fe-dash",    90,  FE_Y+72, 390, 138, "Dashboard\n仪表板\n\n主数据看板"],
  ["fe-over",   500,  FE_Y+72, 390, 138, "Overview\n概览\n\n汇总统计"],
  ["fe-charts", 910,  FE_Y+72, 390, 138, "Charts\n图表\n\n趋势可视化"],
  ["fe-tables",1320,  FE_Y+72, 440, 138, "Interactive Tables\n交互式表格\n\n域名/IP/代理/规则"],
];
CARDS.forEach(([id, x, y, w, h, txt]) => {
  e(rect(id + "-r", x, y, w, h, "#ffffff", "#74c0fc", 1));
  e(text(id + "-t", x + 12, y + 10, txt, 12, "#1864ab"));
});

// React Query & WS Hook
e(rect("fe-rq-r",   70, FE_Y+235, 835, 185, "#e7f5ff", "#339af0", 2));
e(text("fe-rq-t",   90, FE_Y+245,
  "React Query (TanStack)\n\n· API 数据获取与缓存\n· 乐观更新与状态管理\n· 自动重试与错误处理",
  13, "#1864ab"));

e(rect("fe-wsh-r", 925, FE_Y+235, 845, 185, "#e7f5ff", "#339af0", 2));
e(text("fe-wsh-t", 945, FE_Y+245,
  "useStatsWebSocket Hook\n\n· WebSocket 连接管理\n· 实时数据订阅\n· 自动重连与心跳",
  13, "#1864ab"));

// ─────────────────────────────────────────────────────────────────
// Arrow  FE → SVC
// ─────────────────────────────────────────────────────────────────
const SVC_Y = 510;
e(arrow("arr-fe-svc", 950, FE_Y + FE_H, 950, SVC_Y, "#1971c2"));
e(label("arr-fe-svc-lbl", 960, FE_Y + FE_H + 8, "HTTP / WebSocket  (Cookie 认证)", 12, "#1971c2"));

// ─────────────────────────────────────────────────────────────────
// LAYER 2: SERVICE  y: 510 → 1700
// ─────────────────────────────────────────────────────────────────
const SVC_H = 1190;
e(rect("svc-layer", 40, SVC_Y, 1760, SVC_H, "#ebfbee", "#2f9e44", 3));
e(text("svc-title", 60, SVC_Y + 8, "⚙️  服务层 (Collector Service)", 17, "#2b8a3e"));

// API Server
e(rect("svc-api-r", 70, SVC_Y + 40, 840, 300, "#d3f9d8", "#51cf66", 2));
e(text("svc-api-t", 90, SVC_Y + 50,
  "API Server (Fastify)\n\nREST API Endpoints:\n  /api/backends     - 后端管理\n  /api/stats        - 统计数据\n  /api/auth         - 认证管理\n  /api/domains      - 域名统计\n  /api/ips          - IP 统计\n  /api/proxies      - 代理统计\n  /api/rules        - 规则统计\n  /api/devices      - 设备统计\n  /api/gateway/*    - 网关代理\n  /api/retention    - 数据保留",
  12, "#1b5e20"));

// WebSocket Server
e(rect("svc-ws-r", 930, SVC_Y + 40, 835, 300, "#d3f9d8", "#51cf66", 2));
e(text("svc-ws-t", 950, SVC_Y + 50,
  "WebSocket Server (ws)\n\n· 连接管理 (Client Connections)\n· 订阅管理 (Range / Backend / Interval)\n· 广播推送 (Broadcast Stats)\n· 摘要缓存 (Summary Cache, 2s TTL)\n· 策略缓存同步 (Surge Policy Sync)\n\n数据包类型:\n  stats  trend  domains  ips  pong",
  12, "#1b5e20"));

// Gateway Collectors container
const GC_Y = SVC_Y + 360;
e(rect("svc-gc-outer", 70, GC_Y, 1700, 310, "#c3fae8", "#20c997", 2));
e(text("svc-gc-title", 90, GC_Y + 8, "Gateway Collectors  (数据采集器)", 14, "#087f5b"));

// Clash Collector ×2  +  Surge Collector
const COL_Y = GC_Y + 38;
const COLS = [
  ["svc-clash1", 90,  COL_Y, 520, 255,
   "Clash Collector (Mihomo)\n\n协议: WebSocket\n  WS /connections  实时推送\n\n功能:\n· 流量追踪 + 增量计算 (delta)\n· 代理链提取 (chains)\n· 批量缓冲 (30s flush / 5000条)\n· GeoIP 查询集成\n· 指数退避重连"],
  ["svc-clash2", 630, COL_Y, 520, 255,
   "Clash Collector (Mihomo)\n\n协议: WebSocket\n  WS /connections  实时推送\n\n功能:\n· 流量追踪 + 增量计算 (delta)\n· 代理链提取 (chains)\n· 批量缓冲 (30s flush / 5000条)\n· GeoIP 查询集成\n· 指数退避重连"],
  ["svc-surge1",1170, COL_Y, 580, 255,
   "Surge Collector\n\n协议: HTTP REST Polling (2s)\n  GET /v1/requests/recent\n\n功能:\n· 防重复计算 (recentlyCompleted Map)\n· 策略缓存同步 (10min 定时)\n· 增量计算 + 批量缓冲 (30s)\n· GeoIP 查询集成\n· 指数退避重试 (≤5次)"],
];
COLS.forEach(([id, x, y, w, h, txt]) => {
  e(rect(id + "-r", x, y, w, h, "#ffffff", "#63e6be", 1));
  e(text(id + "-t", x + 12, y + 10, txt, 11, "#087f5b"));
});

// Policy Sync + RealtimeStore
const PS_Y = SVC_Y + 700;
e(rect("svc-ps-r",  70, PS_Y, 840, 170, "#d3f9d8", "#51cf66", 2));
e(text("svc-ps-t",  90, PS_Y + 10,
  "Policy Sync Service  (背景任务)\n\n· 定时同步 Surge 策略: /v1/policies\n            /v1/policy_groups/select\n· 存储: surge_policy_cache 表\n· 缓存过期: 10 分钟 | 回退: 直接 API",
  12, "#1b5e20"));

e(rect("svc-rt-r", 930, PS_Y, 835, 170, "#d3f9d8", "#51cf66", 2));
e(text("svc-rt-t", 950, PS_Y + 10,
  "RealtimeStore  (内存实时数据, 按 backendId 隔离)\n\n· summaryByBackend  · minuteByBackend\n· domainByBackend   · ipByBackend\n· proxyByBackend    · ruleByBackend\n· countryByBackend  · deviceByBackend\n\nmerge*() 合并 DB 数据与实时增量",
  12, "#1b5e20"));

// GeoIP Service
const GEO_Y = SVC_Y + 900;
e(rect("svc-geo-r", 70, GEO_Y, 1700, 160, "#d3f9d8", "#51cf66", 2));
e(text("svc-geo-t", 90, GEO_Y + 10,
  "GeoIP Service\n\nProviders: IP-API.com (默认)  |  IPInfo.io (备选)\n功能:    本地 LRU 缓存  ·  批量查询优化  ·  失败冷却机制  ·  IPv4/IPv6 双栈  ·  ASN 查询",
  12, "#1b5e20"));

// BatchBuffer (triple write hint)
const BB_Y = SVC_Y + 1095;
e(rect("svc-bb-r", 70, BB_Y, 1700, 80, "#d3f9d8", "#51cf66", 2));
e(text("svc-bb-t", 90, BB_Y + 12,
  "BatchBuffer.flush()  ·  三写模式 (Triple Write):\n    ① SQLite  (始终写入)     ② ClickHouse Buffer 表  (CH_WRITE_ENABLED=1)     ③ RealtimeStore  (内存实时)",
  12, "#1b5e20"));

// ─────────────────────────────────────────────────────────────────
// Arrows  SVC → Storage
// ─────────────────────────────────────────────────────────────────
const ST_Y = SVC_Y + SVC_H + 20;
e(arrow("arr-svc-sq",  480, SVC_Y + SVC_H,  480, ST_Y, "#f08c00"));
e(arrow("arr-svc-ch", 1400, SVC_Y + SVC_H, 1400, ST_Y, "#f08c00", true));
e(label("arr-svc-sq-lbl",  490, SVC_Y + SVC_H + 4, "SQLite (始终写入)", 11, "#e67700"));
e(label("arr-svc-ch-lbl", 1220, SVC_Y + SVC_H + 4, "ClickHouse (CH_WRITE_ENABLED=1, 可选)", 11, "#e67700"));

// ─────────────────────────────────────────────────────────────────
// LAYER 3: STORAGE  y: ST_Y → ST_Y+500
// ─────────────────────────────────────────────────────────────────
const ST_H = 480;
e(rect("st-layer", 40, ST_Y, 1760, ST_H, "#fff9db", "#f59f00", 3));
e(text("st-title", 60, ST_Y + 8, "💾  数据存储层 (Storage)", 17, "#e67700"));

// SQLite
e(rect("st-sq-r", 70, ST_Y + 42, 840, 415, "#fff3bf", "#fcc419", 2));
e(text("st-sq-t", 90, ST_Y + 52,
  "SQLite Database  (WAL Mode)  [始终启用]\n\n统计表  (按 backend_id 分区):\n  domain_stats    ip_stats         proxy_stats\n  rule_stats      country_stats    device_stats\n  minute_stats    hourly_stats     daily_stats\n\n配置 / 缓存表:\n  backend_configs   geoip_cache   asn_cache\n  auth_config       retention_config\n  surge_policy_cache\n\nRepository 模式 (12 个 Repo 类):\n  domain · ip · rule · proxy · device\n  country · timeseries · config · backend\n  auth · surge · trafficWriter",
  12, "#7d5807"));

// ClickHouse
e(rect("st-ch-r", 930, ST_Y + 42, 835, 415, "#fff3bf", "#fcc419", 2));
e(text("st-ch-t", 950, ST_Y + 52,
  "ClickHouse  [可选, CH_ENABLED=1]\n\nBuffer 表 (异步接收, ~5min 合并):\n  traffic_detail_buffer\n  traffic_agg_buffer\n  country_buffer\n         ↓  merge  (SummingMergeTree)\n主数据表:\n  traffic_detail   (连接详情)\n  traffic_agg      (聚合统计)\n  country_stats    (国家统计)\n\n读取路由 (STATS_QUERY_SOURCE):\n  sqlite     → 全部读 SQLite  (默认)\n  clickhouse → 全部读 ClickHouse\n  auto       → 智能路由",
  12, "#7d5807"));

// ─────────────────────────────────────────────────────────────────
// Arrow  DS → SVC  (upward, left side)
// ─────────────────────────────────────────────────────────────────
const DS_Y = ST_Y + ST_H + 20;
e(arrow("arr-ds-svc", 100, DS_Y, 100, SVC_Y + SVC_H, "#9c36b5"));
e(label("arr-ds-lbl", 112, DS_Y - 120, "数据采集\nWebSocket\n/ HTTP Poll", 11, "#9c36b5"));

// ─────────────────────────────────────────────────────────────────
// LAYER 4: DATA SOURCES  y: DS_Y → DS_Y+360
// ─────────────────────────────────────────────────────────────────
const DS_H = 360;
e(rect("ds-layer", 40, DS_Y, 1760, DS_H, "#f3d9fa", "#9c36b5", 3));
e(text("ds-title", 60, DS_Y + 8, "📡  数据源层 (Data Sources / Gateways)", 17, "#862e9c"));

// Clash/Mihomo
e(rect("ds-clash-r", 70, DS_Y + 42, 840, 295, "#eedefa", "#cc5de8", 2));
e(text("ds-clash-t", 90, DS_Y + 52,
  "Clash / Mihomo Gateway\n\nWebSocket 端点:\n  WS /connections  (实时推送, 每连接更新)\n  WS /traffic\n  HTTP /rules  /proxies\n\n连接数据格式:\n  { connections: [{\n    id: \"uuid\",\n    metadata: {\n      host, destinationIP, sourceIP,\n      chains: [...],  rule, rulePayload,\n      upload, download  }}]}",
  12, "#862e9c"));

// Surge
e(rect("ds-surge-r", 930, DS_Y + 42, 835, 295, "#eedefa", "#cc5de8", 2));
e(text("ds-surge-t", 950, DS_Y + 52,
  "Surge Gateway (v5+)\n\nHTTP REST API 端点:\n  GET /v1/requests/recent  (最近连接, 2s 轮询)\n  GET /v1/policies         (策略列表)\n  GET /v1/policy_groups/select  (策略组)\n\n开启方式:\n  http-api = 127.0.0.1:9091\n  http-api-tls = false\n\n注意: DNS 在代理服务器解析\n      无法获取真实落地 IP",
  12, "#862e9c"));

// ─────────────────────────────────────────────────────────────────
// AGENT MODE SECTION  (below main arch)
// ─────────────────────────────────────────────────────────────────
const AG_Y = DS_Y + DS_H + 80;

e(text("ag-section-title", 40, AG_Y - 38, "── Agent 模式架构 (远程数据采集) ──────────────────────────────────────────────────────────────────", 16, "#495057"));

// Central Panel
e(rect("ag-panel-r", 600, AG_Y, 700, 380, "#e7f5ff", "#1971c2", 2));
e(text("ag-panel-t", 620, AG_Y + 10,
  "中心面板 (Neko Master)\n\nFastify API Server:\n  POST /api/agent/report\n       接收批量流量增量\n  POST /api/agent/heartbeat\n       接收心跳 (在线状态)\n  POST /api/agent/config-sync\n       规则/代理/Provider 配置\n  POST /api/agent/policy-state\n       当前策略状态\n\nBackend 类型: agent://\n系统生成 token, 绑定 agentId",
  12, "#1864ab"));

// Arrow: Agent → Panel
const AG_HOST_Y = AG_Y + 450;
e(arrow("ag-arr-up", 950, AG_HOST_Y, 950, AG_Y + 380, "#868e96"));
e(label("ag-arr-lbl", 960, AG_HOST_Y - 50, "HTTP  (token 鉴权)", 11, "#868e96"));

// Remote Host
e(rect("ag-host-r", 300, AG_HOST_Y, 1300, 500, "#ebfbee", "#2f9e44", 2));
e(text("ag-host-t", 320, AG_HOST_Y + 10,
  "网关旁边的主机 (Remote Host)\n\nnekoagent  (CLI 管理器, Shell 脚本)\n  /etc/neko-agent/<instance>.env     配置文件\n  /var/run/neko-agent/<instance>.pid  PID 文件\n\nneko-agent  (守护进程, Go)\n  1. 拉取网关数据\n       Clash/Mihomo: WS /connections (实时推送)\n       Surge:        HTTP GET /v1/requests/recent (2s 轮询)\n  2. 增量计算 (Delta)\n       识别新/更新连接 → 计算 upload/download 增量 → 聚合\n  3. 批量上报 (每 2s)  POST /api/agent/report\n       最多 1000 条/批, 积压上限 50000 条\n  4. 心跳 (每 30s)  POST /api/agent/heartbeat\n  5. 配置同步 (每 2min, MD5 去重)  POST /api/agent/config-sync\n  6. 策略同步 (每 30s, 变化时)  POST /api/agent/policy-state\n\nPID 锁: 同一 backendId 同时只允许一个进程运行",
  12, "#1b5e20"));

// Gateway below agent host
const AG_GW_Y = AG_HOST_Y + 570;
e(arrow("ag-arr-gw", 950, AG_GW_Y, 950, AG_HOST_Y + 500, "#868e96"));
e(label("ag-gw-lbl", 960, AG_HOST_Y + 510, "本地网络 (LAN)", 11, "#868e96"));

e(rect("ag-gw-r", 600, AG_GW_Y, 700, 100, "#f3d9fa", "#9c36b5", 2));
e(text("ag-gw-t", 620, AG_GW_Y + 20, "Clash/Mihomo  或  Surge  Gateway API", 14, "#862e9c"));

// ─────────────────────────────────────────────────────────────────
// OUTPUT
// ─────────────────────────────────────────────────────────────────
const diagram = {
  type: "excalidraw",
  version: 2,
  source: "https://excalidraw.com",
  elements,
  appState: {
    gridSize: null,
    viewBackgroundColor: "#f8f9fa"
  },
  files: {}
};

const outPath = 'docs/architecture.excalidraw';
fs.writeFileSync(outPath, JSON.stringify(diagram, null, 2), 'utf-8');
console.log(`✅  Generated ${outPath}  (${elements.length} elements)`);