2. NetBox数据模型总览

NetBox 不是一张“设备清单表”，而是一套围绕网络基础设施建立的关系型数据模型。理解它的关键，不是记住有多少种对象，而是理解对象之间的从属、引用与聚合关系：谁定义“型号”，谁代表“实物”，谁把实物放进“位置”，谁又把位置归入“层级”。只有把这条关系链理清，后续的 IPAM、VLAN、接口、线缆、电源、集群等模块才能挂接到正确的锚点上。

本节先建立一张全局地图。NetBox 的核心对象可以按“定义层—实例层—位置层—逻辑层”四类来理解：厂商（Manufacturer）与设备类型（Device Type）属于定义层，决定设备长什么样；设备（Device）属于实例层，是真实存在的资产；站点（Site）、区域（Region）、位置（Location）、机架（Rack）属于位置层，回答“在哪里”；租户（Tenant）与集群（Cluster）属于逻辑层，回答“归谁用、跑什么”。

从“厂商”到“设备类型”：先定义，再实例化

厂商（Manufacturer）是最顶层的定义对象，代表设备的生产者，例如 Cisco、华为、H3C、Juniper。它本身不描述任何具体设备，只作为设备类型的归属方。设备类型（Device Type）则描述“某一款具体型号”，例如 Cisco Catalyst 9300-48P、华为 CE6865-48S8CQ。设备类型上通常记录：厂商、型号名称、U 高（1U/2U）、端口模板、电源端口模板、设备类型图片等。

这里有一个容易混淆的点：设备类型不是“某台设备”，而是“某款设备的规格模板”。一台真实设备在 NetBox 中创建时，必须选择一个设备类型，从而自动继承其 U 高、端口布局等属性。因此，厂商与设备类型是 1:N 关系，设备类型与设备也是 1:N 关系。如果型号录错，后续所有同型号设备都会继承错误规格，所以定义层的数据质量直接决定实例层的准确性。

站点、区域、位置与机架：回答“在哪里”

位置层是 NetBox 中最容易被低估、却最影响查询效率的部分。区域（Region）是最高层级的地理或行政划分，例如“华东”“华南”“华北”；站点（Site）是具体的物理场所，例如“上海张江机房”“深圳福田数据中心”；位置（Location）是站点内部的进一步细分，例如“3 楼 A 区”“B 栋 2 层”；机架（Rack）则是设备实际安装的物理框架，通常位于某个位置之下。

这四者的关系是逐级从属：区域 1:N 站点，站点 1:N 位置，位置 1:N 机架。机架有明确的 U 高（如 42U），设备安装到机架时会占用具体的 U 位区间。NetBox 会校验 U 位是否冲突，避免两台设备被放到同一位置。这个校验是自动的，但前提是机架 U 高和设备 U 高都录入正确。

设备：所有关系的汇聚点

设备（Device）是 NetBox 数据模型的核心实例对象，也是关系最密集的节点。一台设备通常同时引用以下对象：设备类型（型号）、设备角色（用途，如接入交换机、核心交换机、防火墙、负载均衡）、站点（所在场所）、机架（安装位置）、租户（归属方）、集群（若为集群成员）。此外，设备还可以关联平台（操作系统）、序列号、资产标签、管理 IP 等。

设备角色（Device Role）是一个独立对象，用于表达设备的逻辑用途，而不是物理型号。例如同一款 Catalyst 9300，既可能作为“接入交换机”，也可能作为“汇聚交换机”。角色与设备类型正交，二者组合才能完整描述一台设备。这也是 NetBox 建模灵活性的体现：型号回答“是什么”，角色回答“干什么”。

租户与集群：逻辑归属与资源池

租户（Tenant）用于表达资源的归属方，可以是部门、客户、业务线或项目。租户不是“用户”，而是资源分组维度。例如“电商业务部”“视频业务部”“外部客户 A”都可以作为租户。租户可以关联站点、机架、设备、集群、IP 前缀、VLAN 等，从而实现按归属方统计资源。

集群（Cluster）用于表达一组协同工作的设备，典型场景是虚拟化集群、Kubernetes 集群、数据库集群。集群有集群类型（Cluster Type），例如 VMware vSphere、Kubernetes、MySQL Galera。集群可以包含多台成员设备，也可以关联站点和租户。集群与设备的关系是 N:M 的变体：一台设备可以属于一个集群，也可以独立存在；一个集群可以包含多台设备。

关系链的实际查询价值

理解这些对象的关系，最终是为了查询和自动化。例如，要查“上海张江机房 3 楼 A 区所有 Cisco 接入交换机的管理 IP”，查询路径是：区域→站点→位置→机架→设备→设备类型（厂商=Cisco）→设备角色（接入）→管理 IP。如果位置层缺失或设备类型未关联厂商，这条查询就会断链。

再比如，要统计“某租户在所有站点的设备数量”，需要租户与设备、租户与站点同时建立关联。NetBox 的过滤器（Filter）和 API 正是基于这些外键关系工作的。因此，建模时不要只填“必填字段”，而要考虑未来要按什么维度查询、统计和自动化，再决定哪些关系必须建立。

一个可参考的录入顺序

由于对象之间存在外键依赖，录入顺序不能随意。推荐顺序如下：

1. 厂商 → 设备类型（先定义型号模板）
2. 区域 → 站点 → 位置 → 机架（先建立空间层级）
3. 设备角色、平台、集群类型（先建立分类字典）
4. 租户（先建立归属维度）
5. 集群（关联站点、租户、集群类型）
6. 设备（引用设备类型、角色、站点、机架、租户、集群）

这个顺序的本质是“被引用者先建，引用者后建”。如果顺序颠倒，创建设备时会发现下拉框为空，无法选择设备类型或机架。批量导入时同样要按此顺序准备 CSV 文件，否则外键解析会失败。

把这张表当作建模检查表：每创建一个对象，确认它的上游依赖是否已经存在。这样能避免大量返工，也能让后续的 IPAM、VLAN、线缆、电源等模块顺利挂接。NetBox 的数据模型并不复杂，复杂的是关系是否完整、命名是否一致、层级是否清晰。先把这八个核心对象的关系理顺，后面的章节就有了稳固的锚点。