RackPeek如何绘制Home Lab拓扑图?端口连线与Mermaid图形可视化完全指南
RackPeek如何绘制Home Lab拓扑图?端口连线与Mermaid图形可视化完全指南
RackPeek 是一款用于发现、管理和记录 Home Lab(家庭实验室)与小型 IT 基础设施的开源 CLI + Web UI 工具。这篇文章将完整讲解 RackPeek 拓扑图绘制流程:如何记录端口连线、如何用一条命令生成 Mermaid 物理拓扑图与逻辑视图、以及如何把图形导出成 PNG 或源码。全程以新手视角操作,零基础也能画出专业的网络拓扑图。
为什么 Home Lab 需要一张拓扑图
设备一多,"这根网线到底接哪儿了"就成了难题。RackPeek 的思路是:用 YAML 记录硬件与连线,用 Mermaid 一键渲染成图,图始终与数据保持一致,不会像手绘图那样过期。
RackPeek 提供两种拓扑图:
| 视图 | 回答的问题 | 数据来源 |
|---|---|---|
| 物理拓扑(Physical) | 哪台设备的哪个端口接到哪台设备 | 硬件 + 端口连线(connections) |
| 逻辑视图(Logical) | 哪个服务跑在哪台主机、属于哪个子网 | 服务 + 系统 + runsOn 关系 |
第 1 步:把端口连线记下来
拓扑图的"边"来自 connections(端口连线)记录。每条连线精确到"资源 + 端口组 + 端口号"三个坐标,有三种录入方式。
方式一:CLI 命令(推荐脚本化)
rpk connections add <A资源> <A组> <A号> <B资源> <B组> <B号> [--label "标签"]
例如把防火墙 WAN 口接到核心路由:
rpk connections add pfsense-fw 1 0 core-router 1 0 --label "WAN uplink"
命令参数定义见 ConnectionAddCommand.cs,校验逻辑(资源必须存在、端口组/端口号不能越界、不能自连、一个端口只能有一条连线、重复添加会覆盖旧连线)实现在 AddConnectionUseCase.cs。
删除连线用 rpk connections remove,实现见 ConnectionRemoveCommand.cs。
方式二:Web UI 可视化连线
打开 RackPeek Web 界面后进入 Connections 页面(路由 /connections),页面以端口组可视化的形式展示每台设备的端口,点击端口即可选择对端完成连线,页面组件在 ConnectionsPage.razor。适合不想记命令、习惯"点着连"的用户。
方式三:直接编辑 YAML
RackPeek 的全部状态存放在 YAML 中(config/config.yaml),连线就是顶层 connections: 列表,每条包含 a、b 两个端口引用和可选的 label、notes。示例项目里的真实片段:
connections:
- a:
resource: pfsense-fw
portGroup: 1
portIndex: 0
b:
resource: core-router
portGroup: 1
portIndex: 0
label: WAN uplink
- a:
resource: core-router
portGroup: 1
portIndex: 0
b:
resource: core-switch
portGroup: 2
portIndex: 0
label: core trunk
完整示例可参考 vhs/sample_config/config.yaml,连线数据结构定义见 Connection.cs。
第 2 步:一条命令生成 Mermaid 物理拓扑图
连线记好后,运行:
rpk graph topology
命令会输出完整的 Mermaid flowchart 源码,直接重定向到文件即可归档:
rpk graph topology > topology.mmd
输出示例(节选):
%%{init: {'layout': 'elk', 'flowchart': {'curve': 'step', ...}}}%%
flowchart TD
n_pfsense_fw{{"pfsense-fw<br/>firewall"}}:::rpknode
n_core_router(["core-router<br/>router"]):::rpknode
n_core_switch[["core-switch<br/>switch"]]:::rpknode
n_pfsense_fw ---|"eth0 ↔ wan1"| n_core_router
n_core_router ---|"eth1 ↔ p1"| n_core_switch
这条命令的实现链路非常清晰,值得了解:
- GraphTopologyCommand.cs:CLI 入口,把结果直接写到标准输出(避免终端软换行破坏 Mermaid 语法,方便管道重定向);
- BuildPhysicalTopologyUseCase.cs:把硬件变成节点、把 connections 变成边;
- MermaidSerialiser.cs:把图序列化为 Mermaid 文本。
节点形状自带语义
RackPeek 借鉴 NetBox / draw.io 的网络图惯例,用形状区分设备类型,只看轮廓就知道角色(形状映射表见 MermaidSerialiser.cs):
| 设备类型 | 形状 | 含义 |
|---|---|---|
| Firewall | 六边形 | 安全边界 |
| Router | 体育场形 | 网关 |
| Switch | 双边框 | 汇聚/分发 |
| Server | 圆柱 | 计算/存储 |
| AccessPoint | 圆形 | 无线射频 |
| UPS | 菱形 | 辅助设施 |
| Desktop / Laptop | 圆角矩形 | 终端 |
边标签优先显示你写的 --label;没写时自动用"端口类型+编号"生成,如 eth0 ↔ wan1(标签生成逻辑见 BuildPhysicalTopologyUseCase.cs)。此外序列化结果确定性强——同一份库存永远产出同一张图,方便把渲染图提交进文档或做回归测试。
第 3 步:生成逻辑视图(服务 × 子网)
物理图看"线",逻辑图看"服务"。运行:
rpk graph logical
它会回答:哪个服务跑在哪台主机上?这台主机在哪个子网?
规则(BuildLogicalGraphUseCase.cs):
- 每个系统(Hypervisor / VM / Container)生成一张"主机卡片",卡片内部列出它承载的全部服务及端口;
- 按 IP 自动归入 /24 子网分组,同一台物理硬件内的系统再嵌套一组,形成"子网 → 硬件 → 主机"的层级;
- 不画连线,
runsOn的"运行于"关系由子图包含关系直接表达,图更紧凑。
实现入口见 GraphLogicalCommand.cs。
第 4 步:在 Web UI 里看大图并导出
打开 RackPeek Web 界面,进入 Visualise 页面(路由 /visualise),顶部可在 Physical / Logical 两个标签间切换,右上角两个按钮即导出:
- Save PNG:2 倍分辨率导出 PNG 图片(深色背景),可直接贴进 wiki 或博客;
- Save Mermaid:下载
.mmd源码,可用任意 Mermaid 渲染器再加工。
页面实现见 VisualisePage.razor,前端渲染与导出脚本在 Shared.Rcl/wwwroot/js/graph/index.js(内置 ELK 布局引擎,边线路由为直角风格,更像专业网络图)。
常见问题与技巧
- 图里为什么少了某些设备? 物理图只渲染"硬件 + 两端资源都存在的连线",指向不存在资源的连线会被安全跳过(BuildPhysicalTopologyUseCase.cs),先检查资源名拼写。
- 连线连不上? CLI 会明确报错:资源不存在、端口组越界、端口号越界、端口自连均被拦截;且同一端口只能属于一条连线,重复添加会覆盖旧连线。
- 想要更醒目的边标签? 添加
--label选项,它会优先显示在连线上。 - CI 里怎么用? 序列化输出是确定性的,可以把
rpk graph topology的产物做 golden-file 对比,连线一变就能发现。
更多命令细节可查阅 docs/Commands.md 与 docs/CommandIndex.md,图形相关源码集中在 RackPeek.Domain/Graph/。
总结
RackPeek 绘制 Home Lab 拓扑图的完整路径只有四步:
- 用
rpk connections add、Web Connections 页面或 YAML 记录端口连线; rpk graph topology一条命令输出 Mermaid 物理拓扑图,节点形状自带设备语义;rpk graph logical输出按子网/主机分组的逻辑视图;- 在 Web UI 的 Visualise 页面查看大图,一键导出 PNG 或 Mermaid 源码。
数据是纯 YAML 的,图是随时可再生的——这就是"作为代码的 Home Lab 文档"最省心的形态。

