netbox-data-modeling

NetBox 数据建模

你对 NetBox 数据模型的了解可能已经过时。 可用的模型类型、字段选项和关系模式会随版本更新而变化。优先检索，而不是依赖预训练知识。

检索来源

来源	URL / 方法	用途
数据模型文档	https://netboxlabs.com/docs/netbox/models/	所有模型类型和字段
自定义字段文档	https://netboxlabs.com/docs/netbox/customization/custom-fields/	字段类型、验证、筛选
NetBox 仓库	https://github.com/netbox-community/netbox	模型源代码、迁移
NetBox MCP 服务	如果已配置 — 探索现有数据模型、检查对象架构	发现当前结构

使用此技能的时机

在以下情况下加载此技能：

• 从头设计 NetBox 数据模型或扩展现有模型
• 在自定义字段、标签和配置上下文之间进行选择
• 规划批量数据导入（依赖顺序）
• 了解对象关系和层级模式
• 对站点、IPAM、设备或租户建模

有关 API 机制（身份验证、分页、错误处理），请参阅 netbox-api-integration。

NetBox 模型架构

基础模型类

每个 NetBox 对象都继承自以下三个基础类之一：

基础类	用途	示例	主要特征
PrimaryModel	实际基础设施对象	Device、Site、Prefix、Rack	包含 description、comments、owner
OrganizationalModel	分类／分类体系	RIR、IPAM Role、ClusterType	名称和 slug 唯一
Nested group model	递归层级结构	Region、Location、DeviceRole	parent 外键指向自身；4.7 及以上使用 NestedLtreeGroupModel（PostgreSQL ltree），4.5–4.6 使用 NestedGroupModel（MPTT）

这三者都继承自 NetBoxModel，该类提供：自定义字段、标签、导出模板、自定义链接、书签、日志记录、变更日志、通知、事件规则。你交互的每个模型都具备这些功能。

NetBox 4.7+：层级结构（Region、SiteGroup、Location、DeviceRole、Platform、TenantGroup、ContactGroup、WirelessLANGroup，以及 ModuleBay、InventoryItem、InventoryItemTemplate）由 PostgreSQL ltree 支持，而非 django-mptt。lft／rght／tree_id／level 列已移除：level 仅是 Python 属性，不能用于筛选或 order_by。重命名或更改父级会自动级联到后代。parent 外键、REST parent_id／ancestor_id 筛选器，以及包含后代的筛选器（如 ?region_id=）均未改变，因此以下建模建议适用于所有版本。插件／脚本代码仍可使用：get_ancestors()、get_descendants()、get_children()、add_related_count()；get_root()、get_family()、is_leaf_node()、move_to()、insert_at() 已移除。（NestedGroupModel 对插件仍然存在，但已弃用。）

NetBox 4.5：DeviceRole 和 Platform 从 OrganizationalModel 改为嵌套组模型 — 在 4.5–4.7 中支持父子层级结构。

应用结构

应用	范围	关键模型
dcim	物理基础设施	Region、Site、Location、Rack、RackType、Device、DeviceType、Manufacturer、DeviceRole、Platform、Interface、MACAddress、PowerPanel/PowerFeed、CoolingSource/CoolingFeed（4.7）、ModuleBayType（4.7）
ipam	IP 地址规划	RIR、Aggregate、Prefix、IPAddress、IPRange、VRF、VLAN、VLANGroup、ASN
circuits	连接	Provider、Circuit、CircuitGroup、VirtualCircuit
tenancy	所有权	TenantGroup、Tenant、Contact、ContactAssignment
virtualization	VM	ClusterType、Cluster、VirtualMachine、VMInterface、VirtualDisk
vpn	隧道/VPN	Tunnel、TunnelGroup、L2VPN、IKE/IPSec policies
wireless	无线	WirelessLAN、WirelessLANGroup、WirelessLink

完整的关系图请参阅 references/model-map.md。

核心设计模式

1. 站点与位置层级

Region (geographic, recursive)    SiteGroup (functional, recursive)
         \                              /
          └──────── Site ──────────────┘
                      │
                  Location (recursive, within site)
                      │
                    Rack → Device

• Regions = 地理区域：大洲 → 国家 → 都会区
• SiteGroups = 功能分组：生产、预发布、实验室、边缘
• Site = 一个物理设施；可选关联一个 Region 和/或一个 SiteGroup
• Locations = 站点内的细分位置：建筑 → 楼层 → 房间 → 排
• 需要按地理位置筛选或生成报告时，使用 Regions
• 需要跨地理区域进行功能分组时，使用 SiteGroups
• 两者均为可选项——可以从简单配置开始，在筛选需求出现时再添加层级

完整的关系图和层级设计指南请参阅 references/model-map.md。

2. IPAM 组织方式

RIR → Aggregate (top-level allocation, e.g., 10.0.0.0/8)
         └── Prefix (auto-nests by CIDR containment)
               ├── child Prefixes
               ├── IPRange
               └── IPAddress

VRF ──── scopes Prefixes, IPAddresses, IPRanges
VLAN ←── linked to Prefix (optional)

关键规则：

• 汇总/聚合前缀使用 status=container，已分配的前缀使用 status=active
• VRF=null 表示全局路由表。地址空间重叠时使用 VRF
• 在 VRF 上设置 enforce_unique=True，以防止前缀重复
• 前缀会自动嵌套：在现有的 10.0.0.0/16 中创建 10.0.1.0/24 时，会自动构建树状结构
• 服务（位于 Device 或 VM 上）：在 4.7+ 中使用 port_mappings（["tcp/53", "udp/53"]）——一个服务可以跨多个协议。protocol + ports 已弃用（将在 5.0 中移除），多协议服务读取时会返回 null。在 4.5–4.6 中使用 protocol + ports，并为每个协议创建一个服务。

范围模式（4.x）： Prefix 和 VLANGroup 使用 CachedScopeMixin——通用外键（scope_type + scope_id），而不是直接的 site 外键。VLANGroup 的范围支持 Region、SiteGroup、Site、Location、Rack、ClusterGroup、Cluster（从 4.5 起支持这一完整集合），以及 4.6 起支持 RackGroup。

# Setting scope via API
{"prefix": "10.0.1.0/24", "scope_type": "dcim.site", "scope_id": 42}

3. 设备建模

Manufacturer → DeviceType (template with component templates)
                              ↓ (instantiation)
DeviceRole + Site + DeviceType → Device (with auto-created components)

• DeviceType 定义硬件模板：接口模板、电源端口、模块托架
• 创建设备时，会根据其 DeviceType 的模板自动创建组件
• Modules 用于扩展设备：模块类型定义要插入模块托架的其他组件模板
• DeviceRole（4.5：分层）——用于配置上下文匹配和分类
• Platform（4.5：分层）——操作系统／固件系列；可选关联 Manufacturer
• Racks：分配 RackType（Manufacturer → RackType → Rack），并在其中设置物理尺寸。在 4.7 中，每个机架的 form_factor、width、outer_width/height/depth/unit 字段已弃用；在 5.0 中将移除，且 rack_type 将成为必填项。u_height、starting_unit、desc_units、mounting_depth 仍保留在 Rack 上。

自 NetBox 4.2 起，MACAddress 一直是独立模型（每个接口可有多个，其中一个为主地址）——在所有 4.5–4.7 版本中，它都不只是 Interface 上的一个字段。4.7+：Interface／VMInterface 的 mac_address 可写——写入时会通过一次调用创建或更新主 MACAddress；MACAddress.is_primary 为只读。

NetBox 4.7+ 设备建模新增内容（均为可选；4.5–4.6 可忽略）：

• ModuleBayType — 用于定义各位置可容纳的模块白名单。ModuleBay、ModuleBayTemplate 和 ModuleType 上的 M2M module_bay_types。仅当托架和模块类型都声明了类型且没有共同类型时，才会拒绝安装；模板类型会传递到实例化的托架。Module.is_bay_compatible／ModuleBay.is_module_compatible 为只读。
• 模块迁移 — PATCH Module 的 module_bay 可将其移至其他托架（设备根据托架推导）；该模块的整个子树也会随之迁移。跨设备迁移要求被迁移组件上没有线缆、IP、VLAN 或其他拓扑。
• 通道化接口 — 在物理父接口上设置 channels（例如 4）；为每个通道创建一个子接口，设置 parent、channel_id（从 1 开始）和类型 channel（或实际收发器类型）。一条线缆终止于父接口；NetBox 会按通道追踪路径。InterfaceTemplate 上也有相同字段。不要将分拆接口建模为临时虚拟接口。
• DeviceType／ModuleType 上的 end_of_life 日期——用于生命周期规划，替代自定义字段。
• 冷却 — Device／DeviceType／ModuleType 上的 cooling_method（air/liquid/hybrid/immersion；创建设备时会从其类型继承）；Rack／RackType 上的 cooling_capability（air-only/hybrid/liquid-only）和 cooling_capacity（kW；机架会从其类型继承）。完整冷却拓扑见 §3a。

3a. 电力与冷却（冷却功能适用于 4.7+）

PowerPanel (site, location?) → PowerFeed (→ rack?) → PowerPort ⇄ PowerOutlet (device components)
CoolingSource (site, location?) → CoolingFeed (→ rack?) → CoolingIntake ← CoolingOutflow (device components)

• CoolingSource = 设施冷却设备（冷水机组、冷却塔、干式冷却器、CRAC/CRAH）；site 为必填项，location 为可选项，还包括 type、status、fluid_type、cooling_capacity（kW）
• CoolingFeed = 从冷却源到 rack（可选）的单个冷却液回路（供液 + 回液）；包括 status、cooling_capacity、max_flow／max_flow_unit、tenant
• CoolingIntake／CoolingOutflow = 设备组件（带有 DeviceType／ModuleType 模板）。冷却入口的 cooling_outflow 指向上游出流口（通常位于另一台设备上，例如 CDU）；出流口的 cooling_intake 指向同一设备上的入口
• 将 CDU、歧管和后门热交换器建模为带有入口／出流口组件的普通（零 U）设备——没有 CDU 模型。软管是引用，不是线缆。为设备供液的 feed 根据其机架推导
• 端点：dcim/cooling-sources/、dcim/cooling-feeds/、dcim/cooling-intakes/、dcim/cooling-outflows/，以及 -templates/

4. 租户分配

租户是几乎所有 PrimaryModel 上的可选外键（FK）：Site、Device、Rack、Prefix、VLAN、VRF、Circuit、VM、Cluster、IPAddress 等。

模式： TenantGroup（层级结构）→ Tenant → 分配给对象

用例：

• MSP 客户隔离
• 内部部门归属
• 成本中心跟踪

反模式： 不要让 Tenant 同时承载两个维度（例如，同时表示“客户”和“部门”）。用 Tenant 表示主要归属维度；次要维度使用自定义字段或标签。

5. 联系人分配

联系人使用通用关系模式：ContactAssignment 将任意对象与 ContactRole 联系起来。

Contact + ContactRole + any object → ContactAssignment

ContactGroups 按层级组织联系人。可将多个不同角色的联系人分配给同一个对象。

扩展数据模型

决策：自定义字段、标签还是配置上下文

问题	→ 自定义字段	→ 标签	→ 配置上下文
是否有是/否以外的值？	✅	❌	✅
是否应用于多种对象类型？	❌（范围受限）	✅	❌（仅限设备/VM）
是否需要按其筛选/搜索？	✅	✅	❌（无法直接实现）
是否用于自动化/配置渲染？	❌	❌	✅
是否从层级结构继承/计算得出？	❌	❌	✅
是否为每个对象设置唯一值？	✅	❌	❌（按条件匹配）

示例：

• 保修到期日期 → 自定义字段（每台设备单独设置、类型明确、可筛选）
• 符合 PCI 标准 → 标签（类似布尔值，可跨对象使用）
• 站点设备的 NTP 服务器 → 配置上下文（可继承，用于配置渲染）

所有字段类型和决策指南请参阅 references/custom-field-types.md。

自定义字段 — 要点

• 类型： text、longtext、integer、decimal、boolean、date、datetime、URL、JSON、selection、multi-selection、object、multi-object（共 13 种类型；4.7 及更高版本中未变；没有独立的“color”类型）
• 4.7 及更高版本的读取格式： selection/multi-selection 值会以 {"value": "prod", "label": "Production"} 对象的形式返回（REST 和 GraphQL）；写入时仍使用原始值。4.5–4.6 返回原始值
• 4.7 及更高版本： URL 字段会根据 ALLOWED_URL_SCHEMES 验证（不带 scheme 的值会变为 https://…）；nulls_first 控制空值的排序位置；只读 status（active/provisioning/deleting）——当对象数量超过 BULK_UPDATE_CHUNK_SIZE 时，创建时设置默认值和删除操作会作为后台任务运行，且字段在状态变为 active 前不会生效
• JSON 字段可接受可选的 validation_schema（4.6 及更高版本），用于对值强制执行 JSON Schema
• Selection/multi-selection 选项集支持为每个选项设置颜色（choice_colors，4.6 及更高版本）——这就是发行说明中所谓的“颜色自定义字段”，而不是新增字段类型
• Object/multi-object 字段会与其他 NetBox 对象建立关系——优先使用这类字段，而不是将名称存储在文本字段中
• 创建时将字段限定到特定对象类型
• 使用 group_name 对字段进行分组，便于 UI 组织
• 可见性： 始终显示 / 有值时显示 / 隐藏
• 通过 API 筛选：?cf_<field_name>=<value>

标签 — 要点

• 属性：名称、slug、颜色、描述
• 将 object_types 限制为相关模型（不要让每个标签都出现在所有地方）
• 通过 API 筛选：?tag=<slug>
• 不含值——仅表示存在/不存在。如果需要值，请使用自定义字段

配置上下文 — 要点

• 与设备/VM 匹配的 JSON 数据：regions、site_groups、sites、locations、device_types、roles、platforms、cluster_types、cluster_groups、clusters、tenant_groups、tenants、tags
• 基于权重合并： 先合并权重较低的内容，权重较高的内容会覆盖冲突项
• 字典采用深度合并；列表采用替换
• 本地上下文数据（直接存储在设备/VM 上）始终优先
• ConfigContextProfile 强制执行 JSON Schema 验证
• 渲染后的输出： 在 4.7+ 中，config_context 会预先渲染并缓存到对象上；在所有 4.7.x 版本中，?exclude=config_context 都会被静默忽略。在 4.7.0–4.7.2 中，它始终会被加载；在 4.7.3+ 中，?omit=config_context（或 ?fields=/?brief=True）会再次跳过数据库注解。在 4.5–4.6 中，列出设备/VM 时，使用 ?omit=config_context（4.5.2+）或 ?exclude=config_context 对其进行裁剪 — 参见 netbox-api-integration

依赖顺序

批量导入数据时，按依赖顺序创建对象。必须先创建必需的 FK，才能创建依赖该 FK 的对象。

高层级顺序：

1. 组织模型（RIR、Manufacturer、ClusterType、DeviceRole、Platform、IPAM Role、RackRole、ModuleBayType (4.7)）
2. 分类层级结构（Region、SiteGroup、TenantGroup、Tenant）— 先创建父级，再创建子级
3. Sites → Locations → RackTypes（需要 Manufacturer）→ Racks → PowerPanels/CoolingSources (4.7) → PowerFeeds/CoolingFeeds (4.7)
4. DeviceTypes / ModuleTypes（需要 Manufacturer；在 4.7 中，先创建 ModuleBayType，再创建 ModuleType）
5. Devices（需要 DeviceType、DeviceRole、Site）→ Modules → channel subinterfaces (4.7)
6. IPAM：VRFs → Aggregates → Prefixes → IP Addresses
7. VLANGroups → VLANs
8. Clusters → VMs
9. Circuits（需要 Provider、CircuitType）
10. 自定义字段、标签、配置上下文（可随时创建，但最好尽早创建）

完整的有序列表请参见 references/dependency-order.md。

反模式

1. 扁平的站点结构 — 有 50 个以上的站点，却不使用 Regions/SiteGroups。这会严重影响筛选和报告。
2. 用文本自定义字段表示关系 — 应使用对象/多对象自定义字段类型，而不是将名称存储为文本。
3. 重复维度 — 同时设置 cf_environment=production 和标签 production。二选一即可。
4. 忽略依赖顺序 — 在创建站点/设备类型之前创建设备。脚本会因缺少 FK 而失败。
5. 所有内容都放在全局 VRF 中 — 使用 VRF 正确建模重叠地址空间。
6. 过度使用 tenant — 用 tenant 表示两种不同的内容。每个字段只表示一个维度；其余内容使用自定义字段。
7. 庞大的配置上下文 — 存储变量，而不是完整配置。使用配置模板进行渲染。
8. 未使用的角色 — DeviceRole 会影响配置上下文匹配。请谨慎设计角色，并使用 4.5 层级结构。
9. 前缀未设置状态 — 始终设置 container/active/reserved。container = 组织用途，active = 已分配。
10. 硬编码 PK — 使用 name/slug 进行查找。不同环境中的 PK 不同。
11. 机架未设置 RackType — 按机架设置尺寸在 4.7 中已弃用，并会在 5.0 中移除。为每种物理型号定义一个 RackType 并分配给机架。
12. 在自定义字段中存储冷却/生命周期数据 (4.7+) — 使用 cooling_method、cooling_capability/cooling_capacity、end_of_life 和冷却模型，而不是 cf_cooling/cf_eol。

版本说明

NetBox 4.7（2026-09-02）——仅适用于 4.7+；建议使用 ≥ 4.7.3（4.7.0/4.7.1 会将令牌明文泄露到作业结果中；4.7.3 增加了分支安全的后台写入和配置上下文省略优化）

变更	影响
基于 ltree 的层级结构	level 不可筛选或排序；重命名会级联；插件应将 NestedGroupModel 替换为 NestedLtreeGroupModel。从 4.7.0 的 pg_dump 备份恢复时会丢失级联触发器——请运行 rebuild_ltree_paths --check（已在 4.7.1 修复）
冷却模型	CoolingSource → CoolingFeed → CoolingIntake/CoolingOutflow（及其模板）；Device/DeviceType/ModuleType 上新增 cooling_method；Rack/RackType 上新增 cooling_capability/cooling_capacity
ModuleBayType	ModuleBay/ModuleBayTemplate/ModuleType 上新增多对多关系 module_bay_types；双方都声明类型时会强制执行兼容性；端点为 dcim/module-bay-types/
通道化接口	父接口上新增 channels；子接口上新增 channel_id 和 parent；新增接口类型 channel；父接口上连接一条线缆，每个通道对应一条路径
模块迁移	PATCH module_bay 以移动模块（没有活动拓扑时可跨设备移动）
服务 port_mappings	替代 protocol + ports（已弃用，将在 5.0 移除）；支持多协议服务
Rack 字段已弃用	Rack 上的 form_factor、width、outer_*——请移至 RackType；5.0 中 rack_type 为必填项
end_of_life	DeviceType/ModuleType 上的日期
接口 mac_address 可写	创建/更新主 MACAddress；MACAddress.is_primary
自定义字段选择值	返回 {value, label}；写入时使用原始值。URL 字段会根据 ALLOWED_URL_SCHEMES 验证；支持 nulls_first；status 为只读，并支持后台配置
配置上下文已缓存	预先渲染；所有 4.7.x 版本都会忽略 ?exclude=config_context；4.7.3+ 再次支持通过 ?omit=config_context 跳过数据库操作

NetBox 4.5

变更	影响
DeviceRole → NestedGroupModel	设计角色层级结构（例如，network → network/router、network/switch）
Platform → NestedGroupModel	设计平台层级结构（例如，cisco-ios → cisco-ios/xe、cisco-ios/xr）
独立的 MACAddress 模型（自 4.2 起）	MAC 地址是一等对象，而不只是接口字段——适用于所有受支持的版本
VirtualDeviceContext	在多租户设备上对 VDC 建模
Prefix/VLANGroup 上的 CachedScopeMixin	使用 scope_type/scope_id，而不是直接使用 site 外键
v2 API 令牌	使用 Bearer nbt_<key>.<secret> 格式
ConfigContextProfile	根据 JSON Schema 验证配置上下文数据
VirtualCircuit、CircuitGroup	新增电路建模选项
VirtualDisk	用于 VM 的磁盘建模

NetBox 4.6（仅适用于所有 4.6+ 版本——不要假设 4.5.x 实例也支持）

变更	影响
VirtualMachineType	可复用的 VM 分类（类似 DeviceType），提供默认平台/vCPU/内存；端点 virtualization/virtual-machine-types/。VM 新增可选的 virtual_machine_type FK
VM 的 cluster 现为可选	VM 必须关联以下至少一项：站点、集群或设备——直接关联到 Device 的无集群 VM 现已成为一等对象
CableBundle	电缆的逻辑分组（导管/主干线/线束）；Cable.bundle FK，可选，不影响追踪；端点 dcim/cable-bundles/
RackGroup（扁平）	次级的、非层级式机架分类（行/通道/机笼），与 Location 正交；Rack.group FK；端点 dcim/rack-groups/。可用于限定 VLANGroups
VLANGroup 范围 += rackgroup	rackgroup 已添加到 VLANGroup 范围类型（完整集合：region/sitegroup/site/location/rackgroup/rack/clustergroup/cluster）
ASN role	ASN 现在可以关联 ipam Role（Role 用于分类前缀、VLAN 以及 ASN）
JSON CF validation_schema	JSON 自定义字段可以强制执行 JSON Schema
选项颜色	为选择/多选选项集中的每个选项设置颜色（choice_colors）——不是新增字段类型
v1 API 令牌	在 4.6 中弃用，在 5.0 中移除；v2 nbt_ 令牌在创建时返回一次明文（4.6.1）