🧭 用 Three.js 给家庭网络做一个 3D 服务拓扑(含公网访问码门户)

💡 「服务部署在哪台主机的哪个端口」这件事,表格记不住、2D 图看不清、力导向图会乱。所以花了一个版本迭代出一个自定义 Three.js 场景:固定的网络层级 + 会转风扇的硬件模型 + 实时指标驱动,再配一套有时效的访问码门户放到公网。

0. 为什么不用现成方案

动手前先排除了四个候选:

方案	结论
3d-force-graph / react-force-graph-3d	生态成熟,但力导向布局会打乱固定网络层级
Grafana Node Graph	适合调用链,端口和主机卡交互展示不自由
Cytoscape.js	2D 图能力强,不是真 3D
NetBox Topology	适配 NetBox 资产模型,部署重,与现有 NetAlertX/8789 栈冲突

我的需求核心是清楚表达层级 + 端口归属,还要保留拖拽旋转、缩放、搜索、点击详情——所以最终用 Three.js 自定义场景,不用通用力导向图。

拓扑按真实网络层级组织,而不是随机布局:

1	互联网 → 公网网关 → 主路由 → 主机 → 服务:端口

12 个拓扑节点、56 条服务/端口映射、25 台 LAN 设备。点击节点打开右侧详情,列出全部服务、端口和访问链接;选中主机还会展开 3D 服务轨道,按 Web/API、监控、存储/媒体、自动化/通知分组。

拓扑总览

服务轨道展开

端口锁定与详情

快捷键:/ 搜索、O 服务轨道、E 硬件剖视、D 故障演练、Esc 逐级退出。桌面端斜视 3D 布局,移动端自动切两列纵向布局。

架构上最重要的一条约束:浏览器只访问同源接口,不接触 Beszel 凭据或数据库文件。

数据链路与公网访问

metrics_bridge.py 以只读方式访问 Beszel 的 SQLite,合并 NetAlertX 在线状态和可选的 Kuma 状态页,每 15 秒原子更新 metrics.json
server.py 负责静态文件和 8789 同源代理(/api/status、/api/devices),带缓存和后台预热,避免跨域和浏览器私网限制
指标超过 90 秒未更新自动标记 STALE,接口不可用时回退到静态拓扑状态;/api/metrics/health 暴露指标年龄供告警判断

实时感的映射规则:CPU 驱动设备光晕和风扇转速,磁盘 I/O 驱动硬盘灯频率,网络流量驱动连线光粒子密度与速度;NetAlertX 离线的设备熄灯、外壳降透明、连线变灰。

路由器、NAS、1U 服务器、塔式 PC、Mac mini、SBC 六类硬件模型,程序化生成,不依赖第三方素材授权:

GLB 硬件细节

硬件爆炸视图

npm run assets:verify 会校验 12 个 GLB、文件头和体积预算——三个 CI workflow 都先跑它,防止资产回归。

公网入口用独立 Cloudflare Tunnel(主域名 topology.shallowrecall.top,备用 net3d),两层权限:

访客入口 /access:输入管理员生成的访问码——支持生效/过期时间、最大兑换次数、会话时长、禁用/延期/删除;达到上限后新登录拒绝、已登录会话自然存续
管理入口 /admin:HTTP Basic Auth,支持快捷有效期、搜索、状态筛选、使用进度和移动端卡片布局

访问码门户

管理后台

移动端管理后台

安全要点:

三个 GitHub Actions workflow,全部先跑 assets:verify 和 metrics:verify:

CI:用 VITE_MOCK_API=true 的 Mock 数据构建,并用 Playwright 生成版本截图
Deploy:main 更新后由 .55 上的 self-hosted runner(debian-network-topology)构建,只更新 /opt/network-topology-3d/dist——不会覆盖 server.py、Basic Auth 环境文件或访问门户
Release:推送 v* tag 时用 Mock 数据生成带截图描述的 GitHub Release