netbox-migration

NetBox 迁移

你对 NetBox 导入机制的了解可能已经过时。 可用的导入方法、批量操作限制和 Diode 实体类型会随版本演进。请优先检索信息，而不是依赖预训练知识。

检索来源

来源	URL / 方法	用途
NetBox REST API 文档	https://netboxlabs.com/docs/netbox/integrations/rest-api/	批量创建/更新端点
Diode 文档	https://netboxlabs.com/docs/diode/	高容量数据导入
pynetbox 仓库	https://github.com/netbox-community/pynetbox	用于编写导入脚本的 Python SDK
NetBox MCP 服务	如果已配置 — 验证导入的数据是否正确写入	迁移后验证

此技能将指导你如何思考并执行向 NetBox 迁移数据。它涵盖完整生命周期：分析杂乱的源数据、清理数据、选择导入策略、按正确顺序加载数据，并验证所有数据是否正确写入。

这与 NetBox 版本升级无关。 本技能讲解如何首次将电子表格、旧版工具或其他 CMDB 中的数据导入 NetBox（或重新导入）。

何时使用此技能

• 需要导入电子表格、CSV 或数据转储到 NetBox
• 从其他 CMDB/IPAM（phpIPAM、Device42、RackTables、ServiceNow、InfoBlox）迁移
• 规划 NetBox 部署，需要填充初始数据
• 将多个来源的数据整合到 NetBox，并将其设为可信数据源

快速入门决策树

数据量有多少？

• 少于 100 个对象 → 使用 NetBox CSV 导入 UI
• 100–10K 个对象 → 使用 pynetbox 脚本
• 10K 个以上对象或持续同步 → 使用 Diode SDK

数据来源是什么？

• 电子表格 → 先清理，再使用 pynetbox 或 CSV 导入
• 旧版 IPAM 工具 → 检查是否有现成的迁移工具，否则导出→转换→导入
• 网络发现数据 → 导入基础数据，然后使用 Discovery 补充信息
• 多个来源 → 为每种数据类型确定主要来源，并协调冲突

一次性操作还是持续同步？

• 一次性操作 → 使用带有获取或创建模式的 pynetbox 脚本
• 持续同步 → 使用 Diode SDK 定期运行
• 混合方式 → 使用 Diode 批量导入，使用 pynetbox 修正关系

五个阶段

每次迁移都遵循这一流程。不要跳过任何阶段——最常见的失败原因是在未进行评估和清理的情况下直接开始导入。

阶段 1：评估

目标： 了解现有数据、NetBox 的需求，以及两者之间的差距。

1. 盘点数据来源 — 列出所有保存基础设施数据的电子表格、数据库、工具、Wiki 页面和人员。确定每种数据类型的权威来源。

2. 将字段映射到 NetBox 模型 — 对于每个来源字段，找出对应的 NetBox 模型和字段。常见来源系统的映射方式请参阅 references/source-mapping.md。

3. 确定保留与舍弃的内容 — 并非所有数据都需要迁移。NetBox 有特定的模型；不适用的数据可放入自定义字段、备注，或直接舍弃。原则是：从 NetBox 的需求出发，而不是从电子表格中的内容出发。

4. 确定范围 — 分阶段迁移。先迁移物理层级（站点、机架、设备），然后是 IPAM，再然后是连接关系，最后进行数据补充。不要试图一次完成所有工作。

5. 检查现有工具 — phpIPAM 有 ipam-migrator，RackTables 有 racktables2netbox。编写自定义脚本之前，先在 GitHub 上搜索。

需要留意的棘手映射：

• 来源中的“Location”在 NetBox 中可能指站点、站点内的位置或区域
• 来源中的“Device type”通常指角色，而不是 NetBox 的 DeviceType（后者指硬件型号）
• 来源中每台设备只有一个 IP → 需要创建一个 Interface，为其分配 IP，然后将其设为 primary_ip
• “Cisco Catalyst 9300-48P” → 拆分为 Manufacturer("Cisco") + DeviceType(model="Catalyst 9300-48P")
• 位置层级“Building A, Floor 3, Room 301” → 嵌套的 Location 对象

关于 NetBox 的数据模型和关系，请参阅 netbox-data-modeling。

阶段 2：数据清理

原则： 垃圾进，垃圾出。导入前先清理数据——导入后在 NetBox 中修复数据，比在电子表格中修复更困难。

10 项主要清理任务：

1. 统一名称格式 — 选择一种命名规范（建议使用小写字母和连字符），并在所有数据中统一应用。“NYC-DC1”、“New York DC 1”、“nyc dc1” → nyc-dc1。

2. 统一制造商名称 — “Cisco”、“cisco”、“Cisco Systems”、“CISCO” → 统一为一个规范名称。大小写敏感很重要，尤其是使用 Diode 的 reconciler 时。

3. 统一设备类型 — “C9300-48P”、“Catalyst 9300 48P”、“WS-C9300-48P” → 每种硬件型号统一使用一个型号字符串。

4. 去重 — 同一设备在不同来源中使用了不同名称。多条记录使用了同一个 IP。选择权威记录。

5. 删除过时数据 — 已停用多年的设备仍在电子表格中。将其标记为 decommissioning 或删除。

6. 验证 IP — 必须使用正确的 CIDR 表示法。主机地址需添加 /32。10.0.0.1/24 表示 /24 上的 IP 地址，而不是前缀——要了解其中的区别。

7. 补齐必填字段 — 每台 Device 都需要：name、device_type、role、site。每个 IP 的 address 都必须使用 CIDR 表示法。检查 NetBox 各模型的必填字段。

8. 映射状态值 — 来源中的“production”/“live”/“up” → NetBox 的 active。来源中的“down”/“retired” → NetBox 的 offline 或 decommissioning。有效选项：active、planned、staged、offline、decommissioning、inventory。

9. 处理多值单元格 — 一个单元格中的“10.0.1.1, 10.0.1.2” → 拆分为多条记录。

10. 清除格式残留 — Excel 去掉的前导零、尾随空格、BOM 字符、合并单元格产生的空白、“N/A”和“unknown”值 → 决定跳过或使用占位值。

社区经验： “先在 NetBox 中手动填写几条记录并导出，然后按照该格式构建 CSV。”NetBox 的 CSV 导出表头与导入表头并不一致——务必先用少量样本进行测试。

阶段 3：导入

根据 references/import-patterns.md 中的决策框架选择策略。

策略	适用场景	依赖项排序
CSV 导入（UI）	少于 1K 个对象，类型简单	手动 — 每次导入一种类型
pynetbox	1K–100K 个对象，逻辑复杂	手动 — 由你控制顺序
Diode SDK	10K 个以上对象，需要持续同步	自动 — 协调器处理依赖项
自定义脚本	模式化数据、NetBox 内转换	手动 — Django ORM

无论采用哪种策略，都要遵循依赖项顺序。 对象必须先存在，其他对象才能引用它们。完整的 11 层顺序见 references/dependency-order.md。

依赖层级摘要：

1. 租户、标签、制造商、RIR、设备角色、机架角色
2. 区域、站点组
3. 站点
4. 位置（位于站点内）
5. 机架（位于位置内）— (4.7) 然后是冷却源/馈电
6. 设备类型 + 组件模板（需要制造商）— (4.7) 如果使用模块槽类型，先创建它们
7. 设备（需要类型、角色、站点）— 根据模板自动创建组件
8. 接口（模板之外的自定义接口）— (4.7) 父接口之后创建通道子接口
9. VRF、VLAN、前缀、IP 地址 → 分配给接口；服务
10. 线缆、电路、服务提供商
11. 虚拟机、集群、配置上下文、自定义字段值

循环依赖问题： 设备的 primary_ip 需要：创建设备 → 创建接口（根据模板自动创建）→ 创建 IP → 将 IP 分配给接口 → 更新设备的 primary_ip。这需要分两轮处理——先创建所有对象，再设置主 IP。

Diode 可消除大部分排序问题。 它会自动创建缺失的依赖项。如果你导入的 Device 引用了不存在的 Site，Diode 会先创建 Site。对于大型迁移，这是一个显著优势。参见 netbox-diode。

主要导入规则：

• 始终使用获取或创建模式 — 使脚本具备幂等性并可重复运行
• 先在暂存环境中测试 — 使用单独的 NetBox 实例进行试运行
• 分阶段导入 — 先导入站点/机架并验证，再导入设备并验证，最后导入 IPAM
• 在 CSV 中通过名称/slug 引用对象，而不是数据库 ID
• DeviceType/ModuleType 使用 YAML 格式，而不是 CSV（它们包含组件模板）
• 使用 pynetbox 批量创建：nb.dcim.devices.create([{...}, {...}]) — 分成约 100 个对象一批（这是兼顾吞吐量与内存的推荐大小，不是 NetBox 强制规定的上限）。批量写入要么全部成功，要么全部失败。(4.7) 批量写入失败时，会针对每个有问题的对象返回一条错误，并提供它在提交列表中的 index — 将它映射回源数据行，只重新提交这些对象；超大批次可以通过 ?background=true 作为后台任务运行。参见 references/import-patterns.md。
• 读取设备/VM 时裁剪 config_context，使用 ?omit=config_context（4.5.2+）：在 4.5–4.6 中，它会跳过开销巨大的逐对象渲染；在 4.7.0–4.7.2 中，配置上下文会被缓存，因此它只会裁剪负载；在 4.7.3+ 中，它会像 ?fields=/?brief=True 一样再次跳过数据库注释。?exclude=config_context 在 4.5–4.6 中效果相同，但在所有 4.7.x 版本中都会被静默忽略
• **为验证而读取大型数据集：**在 NetBox 4.6+ 中，优先使用游标分页（?start=<id>&limit=N），而不是深度 ?offset= 扫描 — offset 越大，速度越慢。参见 netbox-api-integration。

API 模式参见 netbox-api-integration。

阶段 4：验证

完整迁移需要全部三层验证。

第 1 层：结构（NetBox 已接受数据）

• 对象数量与源数据一致：设备、IP、前缀、站点、VLAN
• 没有导入错误或跳过的记录
• 所有对象均已填写必填字段
• 自定义字段值已写入 — （4.7） 选择/多选值读回时会成为 {"value", "label"} 对象；比较 ["value"]，写入原始值

第 2 层：关系（连接正确）

• 每台设备的站点、设备类型、制造商和角色均正确
• 每个 IP 都已分配到正确设备上的正确接口
• 应设置主 IP 的设备均已设置
• 机架位置与源布局一致
• VLAN 与前缀的关联正确
• VRF 分配与路由设计一致
• 前缀层级合理（容器包含子前缀）

第 3 层：运行状态（与实际网络一致）

• NetBox 中的设备可通过网络访问
• NetBox 中的 IP 与设备的实际配置一致
• 网络中没有未录入 NetBox 的设备
• 接口状态与实际情况一致
• 此层使用 Discovery 和 Assurance — 参见第 5 阶段

完整清单请参见 references/validation-checklist.md。

验证脚本模式：

import pynetbox
nb = pynetbox.api("https://netbox.example.com", token="...")

# Count verification
source_device_count = 500  # from your source data
assert nb.dcim.devices.count() >= source_device_count

# Spot-check critical devices
for name in ["core-rtr-01", "fw-01", "dns-01"]:
    d = nb.dcim.devices.get(name=name)
    assert d, f"Missing: {name}"
    assert d.primary_ip, f"No primary IP: {name}"
    assert d.site, f"No site: {name}"

# Find orphaned IPs
for ip in nb.ipam.ip_addresses.all():
    if not ip.assigned_object:
        print(f"Unassigned: {ip.address}")

第 5 阶段：迁移后

数据加载完成并不代表迁移结束。 只有当 NetBox 与实际情况一致，并确立为权威数据源时，迁移才算完成。

运行 Discovery 以补全缺漏

电子表格永远无法涵盖所有信息。使用 Orb Agent 发现缺失内容：

• 网络扫描（NMAP） — 找出 NetBox 中没有的 IP，识别未经授权的设备
• 设备发现（NAPALM/SNMP） — 获取真实的接口配置、VLAN、MAC 地址和 OS 版本
• LLDP/CDP 邻居数据 — 自动发现线缆连接

Discovery 可补全源数据中总会缺失的信息：接口、实际 IP 分配、MAC 地址、真实平台版本和线缆拓扑。请参见 netbox-discovery。

运行 Assurance 以验证正确性

定义“正确”的标准，然后检查是否符合要求：

• 每台活动设备都有主 IP
• 每台活动设备至少有一个接口
• 每个机架都关联站点和位置
• 每个前缀都有 VRF（适用于多 VRF 环境）
• 同一 VRF 中没有重复 IP

请参见 netbox-assurance。

建立持续流程

• 定期安排 Discovery 运行，以检测偏差
• 每周审查 Assurance 报告
• 建立变更流程：先在 NetBox 中记录变更，再在网络上实施
• 与自动化集成（Ansible/Terraform 将 NetBox 作为权威数据源）

完整性标准

满足以下条件时，迁移才算完成：

1. ✅ 所有源数据均已录入 NetBox（每台设备、每个 IP、每个前缀、每个 VLAN）
2. ✅ 关系正确（IP → 接口 → 设备 → 机架 → 站点）
3. ✅ 层级结构合理（区域 → 站点 → 位置 → 机架）
4. ✅ IPAM 组织有序（前缀层级、VRF 范围、聚合覆盖所有地址空间）
5. ✅ 命名一致（采用统一规范，没有重复或歧义）
6. ✅ Discovery 确认与实际情况一致（没有虚构设备或遗漏设备）
7. ✅ Assurance 规则通过（合规性检查全部为绿色）
8. ✅ 可停用源系统（NetBox 现已成为权威数据源）

反模式

1. 导出格式 ≠ 导入格式 — NetBox CSV 导出的表头与导入表头不同。务必使用样例进行测试。
2. 区分大小写 — “Site A”和“site a”会创建重复项，尤其是通过 Diode 操作时。
3. 接口会自动创建 — 创建设备时，DeviceType 模板会创建接口。不要重复创建。
4. 循环依赖（主 IP） — 需要分两步操作：创建设备 → 创建 IP → 再分配给设备。
5. CSV 编码 — 使用不带 BOM 的 UTF-8 编码，并采用 LF 换行符。
6. Slug 冲突 — 自动生成的 Slug 可能冲突。名称相似时，请提供明确的 Slug。
7. 设备名称唯一性 — 唯一性按站点和租户确定，而非全局确定。不同站点使用相同名称没有问题。
8. 大型 CSV 导入速度较慢 — 对于超过 1K 个对象的导入，请改用 API 或 Diode。
9. 不要一次迁移所有内容 — 分阶段进行：站点 → 设备 → IPAM → 连接。
10. “感到不知所措” — 这很正常。专注于 NetBox 有对应模型的数据，忽略无法映射的数据。

版本说明

NetBox 4.7 (2026-09-02)

• 批量创建/更新失败时返回 {"detail", "errors": [{"index": N, "errors": {...}}]}（仍是全有或全无）；批量写入时使用 ?background=true，会返回 202 和一个可供轮询的作业。参见 references/import-patterns.md。
• 在所有 4.7.x 版本中，?exclude=config_context 会被静默忽略（配置上下文已缓存）——请改用 ?omit=config_context 或 ?fields= 投影：在 4.7.0–4.7.2 中仅影响负载；在 4.7.3+ 中会再次跳过数据库注解。
• Selection 自定义字段读取时为 {"value", "label"}；写入时仍接受原始值。
• Services：port_mappings（["tcp/443"]）取代 protocol + ports（旧的字段组合仍可写入，但会在 5.0 中移除）。
• 新增可导入模型：ModuleBayType、冷却源/供给管线/进液口/出液口、通道子接口；DeviceType/ModuleType 上新增 end_of_life 和 cooling_method。参见 references/dependency-order.md 和 references/source-mapping.md。
• 层级结构迁移到 ltree：REST _depth 保持不变，但 NetBox 内的脚本不再能按 level 过滤或排序。
• 核心自定义脚本已弃用（将在 5.0 中移除）——新建导入工具时优先使用 pynetbox/Diode。

NetBox 4.6 (2026-06-04)

• 游标分页（?start=）、仅写入的 add_tags/remove_tags、RackGroup、CableBundle、VirtualMachineType。

参考资料

• references/source-mapping.md — 按源系统划分的字段映射
• references/dependency-order.md — 完整的 11 层导入顺序
• references/validation-checklist.md — 导入后验证清单
• references/import-patterns.md — 各种导入策略的代码示例