RackPeek如何绘制Home Lab拓扑图?端口连线与Mermaid图形可视化完全指南

原创2026-10-10 13:50:371,993 阅读

RackPeek如何绘制Home Lab拓扑图?端口连线与Mermaid图形可视化完全指南

RackPeek 是一款用于发现、管理和记录 Home Lab(家庭实验室)与小型 IT 基础设施的开源 CLI + Web UI 工具。这篇文章将完整讲解 RackPeek 拓扑图绘制流程:如何记录端口连线、如何用一条命令生成 Mermaid 物理拓扑图与逻辑视图、以及如何把图形导出成 PNG 或源码。全程以新手视角操作,零基础也能画出专业的网络拓扑图。

RackPeek Home Lab 拓扑图绘制演示

为什么 Home Lab 需要一张拓扑图

设备一多,"这根网线到底接哪儿了"就成了难题。RackPeek 的思路是:用 YAML 记录硬件与连线,用 Mermaid 一键渲染成图,图始终与数据保持一致,不会像手绘图那样过期。

RackPeek CLI 命令行界面截图

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

这条命令的实现链路非常清晰,值得了解:

节点形状自带语义

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 拓扑图的完整路径只有四步:

  1. 用 rpk connections add、Web Connections 页面或 YAML 记录端口连线;
  2. rpk graph topology 一条命令输出 Mermaid 物理拓扑图,节点形状自带设备语义;
  3. rpk graph logical 输出按子网/主机分组的逻辑视图;
  4. 在 Web UI 的 Visualise 页面查看大图,一键导出 PNG 或 Mermaid 源码。

数据是纯 YAML 的,图是随时可再生的——这就是"作为代码的 Home Lab 文档"最省心的形态。

登录后查看全文
RackPeek