nix-topology：实践指南

实际评估nix-topology时，我先确认它解决的具体问题： 直接从 NixOS 配置生成基础设施和网络图。这类日常自动化工具真正难在输入边界、依赖和失败处理如果不清楚就很难稳定复用，仓库说明只能作为第一层证据。我的评估方法是用一项范围明确的真实任务完成最小试跑，然后检查配置时间、输出质量、异常信息和维护痕迹是否与文档一致。我会把它列入愿意先做小范围验证并复查原始文档的团队的候选清单，而不是仅凭项目介绍直接纳入生产。

文档 | 安装与使用

nix 拓扑

使用 nix-topology，您可以自动生成基础设施和网络 直接从 NixOS 配置中将图表绘制为 SVGs，并获得与上图类似的内容。 它定义了一个新的全局模块系统，您可以在其中指定您拥有的节点和网络。 大部分工作由随附的 NixOS 模块完成，该模块自动从主机收集所有信息。

• 从您的 NixOS 配置中自动提取大量信息：
• systemd-networkd 的接口
• 已知配置的服务
• 来自microvm.nix的客人
• 来自 nixos 货柜的客人
• 来自kea的网络信息
• 渲染主图（物理连接）和以网络为中心的图
• ➡ 通过您的连接自动传播分配的网络
• 允许您添加外部设备，如交换机、路由器、打印机......

查看 示例 目录中的一些独立示例 或者在 文档 中查看渲染结果。

为什么？

我开始有点羡慕 r/homelab 上所有手工制作的基础设施图。 但谁有时间这么做呢？我宁愿花更多的时间 创建一个我一生中会使用一两次的发电机。 也许对其他人也有用。

安装与使用

安装应该像将 nix-topology 添加到 flake.nix 一样简单， 定义全局模块并将 NixOS 模块添加到您的系统中。 还提供 片状部件 模块（请参阅本节末尾的示例）。

1. 将 nix-topology 添加为 flake 的输入

   inputs.nix-topology.url = "github:oddlama/nix-topology";
   

2. 将公开的覆盖层添加到全局 pkgs 定义中，以便可以使用必要的工具进行渲染

   pkgs = import nixpkgs {
     inherit system;
     overlays = [nix-topology.overlays.default];
   };
   

3. 在主机配置中导入暴露的 NixOS 模块 nix-topology.nixosModules.default

   nixosConfigurations.host1 = lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./host1/configuration.nix
        nix-topology.nixosModules.default
      ];
   };
   

4. 使用topology = import nix-topology { pkgs = /*...*/; };创建全局拓扑。 将其公开为薄片中的输出，以便您可以访问它。

   # Repeat this for each system where you want to build your topology.
   # You can do this manually or use flake-utils.
   topology.x86_64-linux = import nix-topology {
     inherit pkgs; # Only this package set must include nix-topology.overlays.default
     modules = [
       # Your own file to define global topology. Works in principle like a nixos module but uses different options.
       ./topology.nix
       # Inline module to inform topology of your existing NixOS hosts.
       { nixosConfigurations = self.nixosConfigurations; }
     ];
   };
   

5. 通过 nix build .#topology.x86_64-linux.config.output 渲染您的拓扑，生成的目录将包含您完成的 svgs。 请注意，这可能需要一分钟时间，具体取决于您定义的主机数量。评估许多 nixos 配置只需要一些时间， 并且渲染器有时很难及时处理更大的 PNGs。

Example flake.nix

{
  inputs = {
    flake-utils.url = "github:numtide/flake-utils";
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nix-topology.url = "github:oddlama/nix-topology";
    nix-topology.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, flake-utils, nixpkgs, nix-topology, ... }: {
    # Example. Use your own hosts and add the module to them
    nixosConfigurations.host1 = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./host1/configuration.nix
        nix-topology.nixosModules.default
      ];
    };
  }
  // flake-utils.lib.eachDefaultSystem (system: rec {
    pkgs = import nixpkgs {
      inherit system;
      overlays = [ nix-topology.overlays.default ];
    };

    topology = import nix-topology {
      inherit pkgs;
      modules = [
        # Your own file to define global topology. Works in principle like a nixos module but uses different options.
        ./topology.nix
        # Inline module to inform topology of your existing NixOS hosts.
        { nixosConfigurations = self.nixosConfigurations; }
      ];
    };
  });
}

Example flake.nix 带片-parts

{
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
  inputs.nix-topology.url = "github:oddlama/nix-topology";
  # ...
  outputs = inputs:
    inputs.flake-parts.lib.mkFlake {inherit inputs;} {
      imports = [
        inputs.nix-topology.flakeModule
      ];
      perSystem = {...}: {
        topology.modules = [
          {
            # Your global topology definitions
          }
        ];
      };
    };
}

添加连接、网络和其他设备

第一次渲染后，初始图表可能看起来有点无结构。 这只是因为 nix-topology 会丢失一些重要的连接，而这些连接是无法做到的 源自一堆 NixOS 配置，例如物理连接。 您可能还想添加一些常见的设备，例如互联网图像， 交换机、路由器之类的东西。但不用担心，所有这一切都很简单。 文档 中有一个完整的 [章节将指导您完成它。

TL;DR：您可以通过指定此信息来添加连接和网络 在全局拓扑模块中，或在本地 NixOS 配置之一中：

# This is a topology module, so use it in your global topology, or under `topology = {};` in any participating NixOS node
{
  # Connect node1.lan -> node2.wan
  nodes.node1.interfaces.lan.physicalConnections = [{ node = "node2"; interface = "wan"; }];
  # Add home network
  networks.home = {
    name = "Home Network";
    cidrv4 = "192.168.1.1/24";
  };
  # Tell nix-topology that myhost.lan1 is part of this network.
  # The network will automatically propagate via the interface's connections.
  nodes.myhost.interfaces.lan1.network = "home";
}

或者本地（e.g.host1/configuration.nix）：

{
  topology.networks.home = {
    name = "Network Made by Host1";
    cidrv4 = "192.168.178.1/24";
  };
  topology.self.interfaces.lan1.network = "home";
}

TODO

是的，还有很多可以添加或改进的地方。

信息收集（提取器）

• Podman/docker 收获
• networking.interfaces 提取器
• 磁盘（来自disco）+渲染
• 无常渲染？
• Nixos nftables 防火墙渲染？

一般

• NAT指示
• Macvtap/vlan/bridge 接口类型 svg，带小链接
• 可配置的字体
• 使颜色可配置