前两篇完成了 NetBox 的部署路线，本篇开始把 NetBox 真正用起来。IPAM 不是“把 IP 地址录进系统”，而是把地址空间、路由隔离、二层域、用途、状态、归属、分配和审计组织成一套可被团队和自动化共同使用的模型。只有先把模型设计清楚，后续 DCIM、连接、API 和自动化才不会建立在一堆散乱地址记录之上。

本文以 NetBox 当前官方数据模型为依据。需要特别注意：NetBox v4.2 起，Prefix 的旧 site 字段被 scope 字段替代；scope 可指向 region、site、site group 或 location。很多旧教程仍按“Prefix 直接挂 Site”讲解，实际部署时要以当前版本字段为准。本文不假设当前机器已有可操作 NetBox，只提供可迁移的建模方法、API 示例和验收清单。

先定义 IPAM 的治理目标

IPAM 的第一目标是让地址分配可预测。任何人申请一个管理网地址、服务器网地址、VIP 或 loopback 时，都应能知道从哪个地址池分配、是否需要 VRF、是否绑定 VLAN、由谁批准、如何回收、下游系统如何消费。若仍靠人工在多个表里搜索“看起来没用”的地址，NetBox 只是换了一个界面。

第二目标是让地址状态可审计。一个地址从规划、预留、启用、弃用到释放，应该有 owner、原因和时间线。删除记录不是最好的回收方式，因为它会抹掉历史。更稳妥的做法是先切换状态、完成冷却期和发现对账，再决定是否释放或保留审计。

第三目标是让地址与现实对象建立关系。IP address 可以分配给设备接口、虚拟机接口和 FHRP group；设备或虚拟机可以指定 primary IPv4 和 primary IPv6。地址不应只写在描述字段里。关系建好后，API 才能回答“这个 IP 属于哪个接口、哪台设备、哪个站点、哪个租户、哪个自动化范围”。

第四目标是让自动化不猜测。DHCP、DNS、监控、配置生成和审计脚本都应该从明确对象读取数据。Prefix 的角色、scope、tenant、VLAN、status 和自定义规则共同构成自动化契约。缺少这些字段时，自动化就会回到字符串匹配和人工例外。

地址空间的层次

NetBox IPAM 的核心对象包括 RIR、Aggregate、VRF、Route Target、Prefix、IP Range、IP Address、VLAN、VLAN Group、ASN、Role 和 FHRP Group。它们不是同一层级的“字段集合”，而是分别描述地址来源、路由表、网络前缀、具体地址、二层域和共享网关。

RIR 表示地址资源来源，例如 APNIC、ARIN、RIPE NCC 或内部定义的私有地址来源。Aggregate 表示从某个来源获得或规划的大地址块。企业内部私有地址也可以建 Aggregate，但应在描述中说明它是内部规划，不要伪装成外部注册资源。

VRF 表示独立路由表。官方文档说明，每个 Prefix、IP Range 和 IP Address 最多属于一个 VRF；未分配 VRF 的对象属于 global table。若相同地址段在两个 VRF 中存在，必须在 NetBox 中创建两个独立对象。这个规则非常关键，否则重叠地址会被错误地视为冲突或同一资源。

Prefix 表示 IPv4 或 IPv6 网络与掩码，必须是网络部分，不能是单个主机地址。Prefix 会按父 Aggregate 和 VRF 自动组织。Prefix 的状态不影响其成员 IP 地址状态；container 状态只表示它用于组织子 Prefix，而不直接分配地址。

IP Address 表示一个主机地址和掩码，代表配置在网络接口上的地址。它可以分配给设备接口、虚拟机接口或 FHRP group。官方文档还说明，设备和虚拟机可以为每个地址族指定 primary IP；若同时存在 IPv4 和 IPv6，默认偏好 IPv6，可通过配置调整。

VLAN 是二层域，Prefix 是三层地址空间。二者可以关联，但不应混为一个对象。官方文档说明，一个 VLAN 可以分配多个 Prefix。现实中双栈、多个网段共享二层或一个网段不绑定 VLAN 都很常见。

设计 VRF 与唯一性

很多企业只有一个默认路由表，也应该明确是否使用 global table。global table 简单，但一旦出现租户网络、云专线、VRF-Lite、MPLS VPN、OT 隔离域或重复私网地址，后续迁移会困难。建议在建模前梳理哪些地址空间允许重叠，哪些必须全局唯一。

VRF 可以分配给 tenant，帮助按客户或内部用户组织地址。Route Distinguisher 和 Route Target 则用于记录 MPLS/VPN 场景中的路由区分与导入导出关系。它们不是所有环境都需要，若网络没有这些概念，不要为了字段完整而随意填。

NetBox 的 VRF 有 “enforce unique” 选项，可以控制该 VRF 内是否强制唯一地址空间；global table 的唯一性可通过 ENFORCE_GLOBAL_UNIQUE 配置控制。是否开启取决于治理策略。强制唯一可以减少误录，允许重复则适合特殊设计，但需要更严格的 owner 和描述。

一个常见原则是：生产路由域尽量强制唯一；实验、客户、隔离或安全域按 VRF 建模；所有自动化必须把 VRF 作为查询条件之一。不要只用 IP 字符串查找对象，否则在重叠地址环境中必然返回错误结果。

命名上，VRF 不建议只叫 prod、test。更好的名称包含范围和用途，例如 corp-prod-global、plant-a-ot、customer-a-vrf。若网络设备中已有正式 VRF 名称，NetBox 应尽量一致，以减少自动化映射。

Aggregate、Prefix 和 Scope

Aggregate 适合记录大地址块来源和整体规划，例如 10.0.0.0/8 私有企业地址、172.16.0.0/12 实验地址、某段公网地址或 IPv6 /32。它不直接替代 Prefix。Prefix 才是后续划分、利用率和地址分配的主要对象。

Prefix 的 scope 是当前版本需要关注的字段。官方文档指出，Prefix 的 scope 可以是 region、site、site group 或 location，并替代了 NetBox v4.2 之前的 site 字段。这意味着“地址属于哪里”不再只能指向站点，而可以根据组织粒度表达更宽或更窄的范围。

scope 的选择应来自真实管理边界。总部园区统一规划的地址池可以挂 site group；某个数据中心机房专用地址可以挂 site；某个楼层或机房区域专用地址可挂 location；跨区域的公网地址池可能暂不挂具体站点。不要把所有 Prefix 都强行挂到一个默认 Site，否则区域利用率和自动化范围都会失真。

Prefix 状态的含义也要规范。container 用于组织子前缀，不直接分配地址；active 表示正在使用；reserved 表示已保留但未投入；deprecated 表示不再推荐或待回收。状态本身不会阻止所有操作，团队需要用流程、权限或自定义验证加强约束。

is_pool 表示把 Prefix 当作池处理，首尾地址也被认为可用，适合 NAT pool 等场景。不要在普通二层网段上随意启用，否则自动分配可能把网络地址或广播地址当作可用地址。mark_utilized 可让 Prefix 报告 100% 利用率，适合外部系统或特殊用途，但会影响容量视图，应有明确说明。

IPv4 与 IPv6 的不同心智模型

IPv4 管理经常围绕“节省地址”和“避免冲突”，IPv6 更强调层级规划和一致分配。不要把 IPv4 中常见的 /30、/29、零碎回收思路照搬到 IPv6。IPv6 的地址空间大，重要的是前缀层级、站点分配、路由汇总、DNS 和安全策略。

IPv6 Prefix 规划通常先确定企业级前缀，再按区域、站点、业务、VLAN 或安全域划分。终端网络常见 /64，但实际取值取决于企业规范和设备能力。NetBox 可以记录巨大 IPv6 空间，但可视化和利用率解释要避免按 IPv4 直觉判断“浪费”。

双栈网络中，IPv4 和 IPv6 不是两个孤立表。设备、接口、VLAN、租户和服务往往相同，只是地址族不同。自动化应同时处理 primary IPv4 和 primary IPv6，并理解 NetBox 默认偏好 IPv6 的行为。若组织仍以 IPv4 为主，配置和脚本要明确选择。

DNS 名称也要区分。IP Address 的 dns_name 是与地址相关的 A/AAAA 记录值，不等同于完整 DNS 管理。若需要区域、CNAME、PTR、委派和记录生命周期，仍应由 DNS 平台或插件处理。NetBox 可以提供权威输入，但不是完整 DNS 服务。

VLAN、Prefix 与二三层边界

VLAN Group 用于组织 VLAN，常见范围包括站点、区域、租户或网络域。VLAN ID 在不同组或站点中可能重复，因此自动化查询 VLAN 时不应只查 vid=100，还要加 group、scope、site 或其他唯一条件。

VLAN 的状态、角色和租户用于表达二层域的生命周期与用途。Prefix 关联 VLAN 后，可以从二层域找到三层地址空间，也可以从地址空间找到网络接入域。但并非所有 Prefix 都有 VLAN，例如 loopback、点到点、隧道、VIP 或公网池。

一个 VLAN 多个 Prefix 的场景很常见：IPv4 与 IPv6 双栈、迁移期间临时双网段、同一二层承载多个逻辑地址池。一个 Prefix 只能关联一个 VLAN，因此不要把“多个 VLAN 共用一个 Prefix”作为正式模型，它通常说明网络设计或记录粒度需要复核。

VLAN 命名建议包含用途而不是只重复 ID，例如 users-office-a、srv-prod-web、mgmt-oob。若设备配置中已有标准 VLAN 名称，NetBox 尽量一致。描述字段记录网关、DHCP、ACL 或责任人，但不要把完整配置粘贴进去。

建模顺序

NetBox IPAM 落地操作路径

落地时先建立字典，再建立地址。推荐顺序如下：

  1. 定义 Region、Site group、Site、Location、Tenant 和必要角色。
  2. 定义 RIR、Aggregate、VRF、Route Target 和 ASN。
  3. 定义 VLAN Group、VLAN role、VLAN。
  4. 创建 container Prefix，表达企业、区域和站点地址规划。
  5. 创建可分配 Prefix，补充 scope、VRF、VLAN、role、tenant 和状态。
  6. 创建或导入 IP Address，关联接口、FHRP group 或保留用途。
  7. 设置设备或虚拟机 primary IP。
  8. 建立审计、导入、回收和自动化消费流程。

这个顺序能减少后期返工。若一开始就导入几万条 IP address，却没有 Prefix、VRF、tenant 和接口关系，后续整理会比重新规划更痛苦。

一个企业地址规划示例

假设企业有北京数据中心、上海办公室和苏州工厂。北京数据中心承载生产服务器和管理网络；上海办公室有办公网、访客网和无线网；苏州工厂有 IT 网络和 OT 网络，OT 网络需要与普通企业网络隔离。

可以先建立两个 VRF：corp-global 和 plant-sz-ot。普通企业地址进入 corp-global，苏州 OT 地址进入独立 VRF。若 OT 与 IT 使用重叠私网地址，独立 VRF 能避免冲突；若不重叠，也能清晰表达路由隔离和权限边界。

Aggregate 层记录 10.0.0.0/8 为企业私有地址，fd00:10::/32 为企业 IPv6 ULA 示例。Prefix 层按区域划分：10.10.0.0/16 给北京，10.20.0.0/16 给上海，10.30.0.0/16 给苏州 IT，10.130.0.0/16 给苏州 OT。每个 /16 使用 container 状态，并设置 scope 到对应 Site 或 Site group。

在北京下创建 10.10.10.0/24 作为服务器 VLAN，10.10.99.0/24 作为管理 VLAN，10.10.254.0/24 作为 loopback 或基础设施地址。服务器 VLAN 关联 VLAN 110，管理 VLAN 关联 VLAN 199。loopback Prefix 不关联 VLAN，但角色标记为 loopback。

VIP 地址以 IP role 标记为 VIP，若属于 VRRP、HSRP、GLBP 或 CARP 等共享网关，当前官方建议虚拟 IP 分配给 FHRP group，而不是某一台真实设备接口。这样模型能表达共享性质，避免自动化误认为 VIP 独占于单设备。

地址分配流程规定：服务器普通地址由对应 Prefix 分配下一个可用地址，状态为 active 并关联服务器接口；未来预留地址状态为 reserved，填写到期和负责人；迁移下线地址先改为 deprecated，经过三十天发现无使用后释放。这个流程比直接删除地址更适合审计。

API 操作原则

NetBox REST API 位于 /api/ 下，IPAM 资源路径包括 /api/ipam/prefixes/、/api/ipam/ip-addresses/、/api/ipam/vrfs/、/api/ipam/vlans/ 等。官方 REST 文档说明，列表和详情视图分别用于检索、创建、更新和删除对象；所有对象都有数字主键 ID，相关对象在写入时可以用 ID 或足够唯一的一组属性指定。

API 示例只作为结构参考。真实调用前，先在当前 NetBox 实例的 /api/schema/swagger-ui/ 查看字段、过滤器和请求格式。不要从旧文章复制 site 字段写入 Prefix；当前应按 scope_type、scope_id 或 API 支持的嵌套形式处理。

创建 Prefix 的示意：

bash
curl -X POST "${NETBOX_URL}/api/ipam/prefixes/" \
  -H "Authorization: Token ${NETBOX_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{
    "prefix": "10.10.10.0/24",
    "status": "active",
    "vrf": {"name": "corp-global"},
    "scope_type": "dcim.site",
    "scope_id": 12,
    "description": "北京数据中心生产服务器网段"
  }'

这个示例中的 scope_id 必须来自真实站点 ID。更稳妥的自动化会先根据 slug 查询 Site，并检查唯一返回，再创建 Prefix。把 ID 写死在脚本中容易在测试和生产环境错配。

分配 IP 到接口的示意：

bash
curl -X POST "${NETBOX_URL}/api/ipam/ip-addresses/" \
  -H "Authorization: Token ${NETBOX_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{
    "address": "10.10.10.21/24",
    "status": "active",
    "role": "secondary",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 69023,
    "dns_name": "app01.example.com"
  }'

官方 REST 文档明确 generic relation 需要 assigned_object_type 和 assigned_object_id。设备接口使用 dcim.interface，虚拟机接口使用 virtualization.vminterface。脚本必须按对象类型选择，不要假设所有地址都归属设备接口。

读取大量对象时使用分页、过滤和字段裁剪。官方文档说明，API 支持 fields、omit 和 brief=true，可以降低响应复杂度。不要用 limit=0 在生产频繁拉取全量对象，尤其是地址和接口数量很大时。需要全量同步时做增量、分页、缓存和速率控制。

自动分配与并发风险

NetBox 支持从 Prefix 查找可用 IP 或可用子 Prefix 的操作，UI 和 API 都可以使用。自动分配适合标准流程，但必须处理并发。两个自动化任务同时申请同一个 Prefix 的地址时，不能只在客户端读取“第一个可用地址”后假设成功。应让服务端创建动作承担冲突检查，并在冲突时重试。

地址申请流程建议包含申请对象、用途、Prefix 选择规则、是否需要 DNS、是否绑定接口、是否需要网关或防火墙策略、回收时间。自动化只执行规则明确的请求；无法判断的请求进入人工审批。

可用地址并不等于网络中未被使用。NetBox 只能说明数据库中未占用。首次纳管和长期运行都需要与 ARP、ND、DHCP、DNS、监控或设备配置做对账。发现某地址在网络中活跃但 NetBox 未记录，应先创建待审核差异，而不是直接把它标记 active。

DHCP 地址池可以用 IP Range、Prefix 状态或约定字段表达，具体取决于 DHCP 平台和团队流程。不要把每个动态租约都长期写入 NetBox，除非有明确用途和清理机制。更常见做法是记录 DHCP 池范围，租约由 DHCP 系统管理，NetBox 用于规划和审计。

多站点地址规划

多站点环境最容易出现的问题，是每个站点用自己的表格和自己的命名方式。总部看到 10.20.0.0/16，工厂叫“二期生产网”，云团队叫 prod-vpc-east，实际可能指向相同或重叠地址。NetBox 上线前要把多站点地址规划统一成可查询层级。

一种稳妥结构是用 Aggregate 记录企业总地址块，用 container Prefix 划分区域，再用 scope 指向 site group、site 或 location。比如 10.0.0.0/8 作为总私网 Aggregate，10.10.0.0/16 给北京数据中心，10.20.0.0/16 给上海办公，10.30.0.0/16 给苏州工厂。每个 /16 下再拆管理、服务器、办公、无线、访客和安全域。

如果站点很多，不建议每个站点都手工决定地址段。可以建立地址分配矩阵：区域占高位，站点占中间位，业务用途占低位。这样新站点申请时，自动化可以根据站点编号和用途分配候选 Prefix，人工只审批例外。矩阵本身写入文档，NetBox 记录结果。

站点合并和搬迁需要单独建模。不要把旧站点 Prefix 直接改名成新站点，否则历史审计会丢失。更好的方式是新建目标 Prefix 或调整 scope，旧 Prefix 进入迁移状态，保留描述和工单。迁移期间同一 VLAN 或业务可能同时存在旧新地址，自动化要能识别状态。

跨站点共用地址池要谨慎。例如企业公网地址池可能跨多个站点使用，可以让 Prefix scope 为空或挂在更高层级；具体 IP 再通过分配对象体现使用位置。若强行把整个公网池挂到某个站点，会误导容量和责任归属。

对于云 VPC、Direct Connect、ExpressRoute 或云上虚拟网络，是否建为 Site、Site group、Cloud 区域或单独标签，取决于团队模型。关键是 Prefix 的 scope、tenant 和 VRF 能让自动化明确它属于哪个网络域，而不是只靠描述写“云上”。

IPv6 推进中的 IPAM 设计

IPv6 项目失败常常不是技术不支持，而是规划仍按 IPv4 零散方式进行。NetBox 中应先定义 IPv6 地址来源、区域前缀、站点前缀、VLAN 前缀和接口地址规则，再让网络、DNS、安全和监控系统跟随。

IPv6 的 Prefix 数量可能很大，但单个 Prefix 下不应枚举所有可能地址。只记录真实使用、保留、网关、VIP、loopback、接口或有审计意义的地址。利用率指标在 IPv6 下更多用于子 Prefix 分配，而不是主机地址占比。

双栈上线时，建议把 IPv4 和 IPv6 Prefix 通过相同 scope、tenant、role 和 VLAN 关联起来。这样业务团队查询某个 VLAN 时能同时看到两个地址族。若 IPv6 另建一套命名和角色，后续自动化会出现两套逻辑。

网关地址、FHRP 和 Anycast 在 IPv6 中也需要清晰角色。VRRP、HSRP、GLBP、CARP 等虚拟地址按官方建议分配给 FHRP group；Anycast 地址要标记角色并说明发布范围。不要把共享地址绑定到某一台设备接口。

IPv6 地址的 DNS 和反向解析更依赖自动化。NetBox 可提供 dns_name 和对象关系，但正式 DNS 更新仍应经过 DNS 平台。上线前要验证新增、修改、回收和回滚，不要只验证正向解析成功。

安全团队也需要参与 IPv6 IPAM。很多防火墙和监控规则最初只覆盖 IPv4，NetBox 中的 IPv6 Prefix 可以驱动策略生成或审计。若 NetBox 记录了 IPv6 但下游系统忽略它，就会形成可见性盲区。

权限和职责分工

IPAM 权限不能只分“管理员”和“查看者”。地址规划、地址分配、地址回收、VRF 管理、VLAN 管理和自动化 token 应分别授权。错误的 Prefix 或 VRF 变更影响范围远大于单个 IP 地址。

建议设定三类角色。架构或网络规划人员可以创建 Aggregate、VRF、container Prefix 和全局角色；区域网络工程师可以在授权 scope 内创建可分配 Prefix、VLAN 和 IP；自动化身份只在指定 Prefix 中分配或更新地址，不能修改 VRF、Aggregate 和全局状态选择。

对象权限应结合 scope、tenant、tag 或自定义字段设计。比如工厂团队只能维护苏州工厂 site 下的 Prefix 和 VLAN，不能修改总部数据中心地址。多租户场景中，tenant 字段有助于归属，但不自动等于权限隔离，需要显式权限规则。

审批流程中，Prefix 创建和地址分配可以使用不同强度。新建 /24 生产网段可能需要架构审批、防火墙评审和容量检查；分配一个已批准 Prefix 中的服务器 IP 可以由自动化完成。把所有操作都要求人工审批会降低使用率，把所有操作都自动化又会放大错误。

变更日志记录谁改了对象，但不说明为什么。IPAM 关键对象建议在 comments、custom field 或工单系统中关联申请单。自动化写入时也应带上变更来源，方便追踪某个地址为什么被分配。

定期权限复审要覆盖人和 token。离职人员、临时迁移 token、旧脚本 token 和长期管理员都要清理。自动化 token 到期前要轮换，避免突然失败；权限扩大必须有审批和记录。

API 事务边界和幂等

NetBox API 是对象级 CRUD，不会替你实现完整业务事务。一个地址申请可能需要创建 IP、设置 DNS 名称、关联接口、设置 primary IP、创建变更记录和通知下游。中间任何一步失败，都可能留下半完成状态。自动化必须设计幂等和补偿。

幂等的基本原则是：先查询目标状态，若已存在且符合预期则跳过；若存在但冲突则报错；若不存在才创建。不要每次执行都 blindly POST，否则重试会产生重复对象或失败噪音。创建前要用唯一键查询，创建后保存目标 ID。

对于 IP 地址，唯一键通常不是 address 字符串，而是 VRF 加 address。对于 VLAN，通常是 group 或 scope 加 vid。对于 Prefix，通常是 VRF 加 prefix，也可能加 scope 作为治理条件。脚本中的唯一键必须与团队模型一致。

批量操作应分批执行并记录结果。一次导入一万条地址，若第六千条失败，脚本要能从结果文件恢复，而不是重头开始制造重复。每批变更应有 dry-run、确认和执行模式。

删除操作默认高风险。自动化删除前应输出将删除对象和依赖关系，确认状态、冷却期和 owner。很多场景中修改状态比删除更合适。真正删除后，恢复要依赖数据库备份或审计重建。

错误处理要区分认证失败、权限不足、校验失败、对象不存在、返回多个对象、并发冲突和服务器错误。不同错误的重试策略不同。权限或校验失败不应无限重试；并发冲突可短暂重试；服务器错误要告警。

质量报表和运营指标

IPAM 进入日常运行后，需要看质量指标，而不是只看地址利用率。利用率只能说明空间是否紧张，不能说明数据是否可信。一个 20% 利用率的地址池也可能充满错误关系和过期记录。

基础质量报表包括：没有 VRF 但应在 VRF 内的 Prefix；没有 scope 的生产 Prefix；没有 role 的 Prefix；active IP 没有关联对象；设备接口上的地址与设备 site 不一致；VLAN 与 Prefix scope 不一致；deprecated 地址超过冷却期；reserved 地址缺少负责人或到期时间。

容量指标包括：Prefix 利用率、子 Prefix 消耗率、即将耗尽的地址池、IPv4/IPv6 双栈覆盖率、VLAN 到 Prefix 关联率、地址回收周期。容量指标要按 scope、tenant、role 和 VRF 分组，否则全局平均值会掩盖局部耗尽。

流程指标包括：地址申请平均时间、自动分配成功率、人工审批积压、发现差异关闭时间、回收超期数量、API 错误率和 token 过期数量。它们能反映 IPAM 是否真正融入运维，而不是只作为静态数据库。

报表输出后必须有人处理。每条质量规则指定 owner 和修复 SLA。无法自动判断的异常进入待审核列表，已确认合理的例外使用标签或自定义字段标记，并定期复审。否则报表会变成没人看的噪音。

事故复盘：一次地址冲突如何暴露流程问题

一个常见事故是新服务器上线时使用了“看起来空闲”的地址，结果与旧系统冲突。排查发现 NetBox 中该地址不存在，但交换机 ARP 表显示它已长期使用。旧系统由某个项目组直接配置，未走 IPAM 申请；监控发现未知地址后也没有反馈流程。

这个事故不能只归咎于执行人没查清。流程上至少有四个缺口：地址分配入口不唯一；NetBox 未作为变更前置条件；发现系统没有与 NetBox 对账；未知地址没有 owner 和处置流程。修复也不能只是补录一个 IP。

更完整的修复包括：所有新地址申请必须通过 NetBox 或接入 NetBox 的工单；自动化分配只从批准 Prefix 中取地址；监控或扫描每周输出未知活跃地址；未知地址先标记为待确认，不纳入可用池；项目组补充 owner 和生命周期；高风险 Prefix 暂停自动分配直到差异关闭。

复盘后还要更新 NetBox 模型。可能需要给 Prefix 增加 owner、自定义字段或标签；增加 reserved 地址策略；为特定网段开启更严格的人工审批；调整发现脚本只读报告而不覆盖期望。事故价值在于修补系统，而不是写一份“加强沟通”的结论。

类似事故也会发生在 VRF 中。脚本只按地址查找，误把客户 A 的 10.1.1.5 当成客户 B 的地址；或者 VLAN 100 在两个站点重复，自动化只按 VID 查找。复盘结论应推动脚本使用完整唯一键，而不是要求操作员“注意环境”。

导入旧数据

从 Excel 或旧 IPAM 导入时，先清洗再导入。清洗顺序包括：统一 VRF、站点和 VLAN 名称；补全 CIDR；识别重复地址；区分 Prefix 与 IP Address；修复描述中的多字段混合；判断哪些记录已经失效。

导入先做 dry-run。脚本读取源文件后，按唯一键查询 NetBox，输出将创建、更新、跳过和冲突的清单。人工确认后再执行写入。每条写入记录源行号和目标 ID，便于回滚和复查。

CSV 导入适合相对简单、字段稳定的数据；API 脚本适合需要查询依赖、创建关联和处理错误的复杂迁移。无论哪种方式，都先在测试实例执行。导入后用计数、抽样和关系检查验证，不要仅看页面没有报错。

旧表中的“备注”往往包含网关、DHCP、DNS、负责人、变更日期和特殊说明。迁移时应拆成标准字段、自定义字段、租户、标签或工单链接。把整段备注搬入 description，只是把不可计算的数据换了位置。

导入不应绕过权限和审计直接写数据库。NetBox API 和导入功能会执行模型校验和变更记录。直接 SQL 写入可能破坏关系和升级兼容性。

地址回收流程

回收比分配更容易出错。释放一个仍在使用的 IP，可能造成业务冲突；永久保留所有弃用地址，又会让地址空间看起来耗尽。建议采用状态驱动的回收流程。

第一阶段是提出回收。变更系统或自动化把地址从 active 切换为 deprecated，记录来源工单、负责人和计划释放日期。接口关联可以按流程保留或解除，但必须能追溯原对象。

第二阶段是观察冷却。对 deprecated 地址进行网络发现、DNS 查询、DHCP 租约和监控检查。如果仍被观察到使用，流程回到人工复核。若无使用且冷却期结束，才进入释放。

第三阶段是释放或保留审计。可重新分配的地址删除或改回可用状态；需要审计的地址保留 deprecated 记录并标记不可分配。关键系统地址、历史 VIP、公网地址和合规范围通常不应快速删除。

自动分配程序必须排除 deprecated 和 reserved 地址，除非有明确审批。Prefix 利用率报告应说明是否把 deprecated 算作占用，不同统计口径用于不同目的。

与 DNS、DHCP 和监控集成

NetBox 可以成为 DNS 和 DHCP 自动化的输入，但它不是 DNS 或 DHCP 服务。IP Address 的 dns_name 可作为记录生成来源，Prefix 或 IP Range 可作为地址池规划来源。真正的区域文件、动态更新、租约、反向解析和冲突处理仍由 DNS/DHCP 平台承担。

与 DNS 集成时，先定义哪些地址会生成记录、记录类型、命名规则、TTL、反向解析和删除策略。VIP、Anycast、NAT 和多地址主机可能需要额外规则。不要简单把所有 dns_name 非空的地址推送到生产 DNS。

与 DHCP 集成时，NetBox 记录可分配池和保留地址，DHCP 系统记录动态租约。保留地址可以从 NetBox 下发到 DHCP，但租约回写要谨慎，避免临时终端制造大量短生命周期对象。

与监控集成时，NetBox 可以输出 active 设备、primary IP、接口地址或管理 Prefix。监控系统应理解 VRF 和 scope，否则可能扫描不该访问的网络。监控发现的未知地址进入差异报告，而不是自动写入权威记录。

验证与冲突排查

NetBox IPAM 验证与冲突排查

IPAM 验收先看结构。检查 Aggregate 下是否存在孤立 Prefix；Prefix 的 VRF、scope、role、tenant 和 VLAN 是否符合规划；container Prefix 是否没有直接分配地址；可分配 Prefix 是否没有错误的 is_pool 或 mark_utilized。

然后看唯一性。按 VRF 统计重复 Prefix 和 IP Address，确认允许重复的场景都有说明。global table 是否允许重复取决于配置和策略，不能默认。VLAN ID 也要结合 group 或 scope 判断唯一。

再看关系。active IP 是否分配给正确接口或 FHRP group；设备 primary IP 是否存在并属于 active 地址；VLAN 是否关联正确 Prefix；已退役设备是否仍占用 active 地址；DHCP 池和保留地址是否重叠。

最后看实际网络。抽样比较设备配置、ARP/ND、路由表、DHCP 租约和 DNS。差异分为四类：NetBox 漏记、现场私改、发现误报、模型不适配。每类处理方式不同。直接让扫描结果覆盖 NetBox 会破坏 Source of Truth。

常见问题之一是 Prefix 重叠。NetBox 支持父子 Prefix，但同级重叠可能说明规划错误。先判断是否应是父子关系、不同 VRF 还是重复录入。若是不同 VRF，必须设置 VRF；若是父子关系，父 Prefix 状态可能应为 container。

另一个常见问题是 IP 看起来可用但无法分配。原因可能是处于不同 VRF、地址属于 IP Range、首尾地址因 is_pool 未启用不可用、权限不足或并发冲突。排查时不要只看地址字符串，要查看 Prefix、VRF 和状态。

IPAM 上线检查表

IPAM 模块正式开放前，应完成一次范围清晰的上线检查。首先确认对象字典已经冻结：VRF、scope、tenant、role、status、VLAN group 和命名规范都有 owner。其次确认首批 Prefix 不只是能创建，还能被查询、分配、回收和审计。第三确认自动化 token 只能访问授权范围，普通用户不能修改全局地址规划。第四确认发现差异有处理入口，不会直接覆盖 NetBox。第五确认备份恢复后，Prefix、IP、VLAN、接口关联和变更记录仍可查询。

上线不是一次性动作。首月应每周复查未知地址、重复地址、无 owner Prefix 和自动化失败；稳定后进入月度质量报表。只要 IPAM 仍在被申请、分配和回收，就需要持续治理。

备份与治理

NetBox IPAM 备份恢复与治理闭环

IPAM 数据位于 NetBox PostgreSQL 数据库中，因此数据库备份是基础。仅导出 CSV 或 API JSON 不能完整恢复关系、权限、变更历史和自定义字段。CSV 更适合审计和离线分析，不是灾备替代品。

同时要备份配置和密钥，因为自定义字段、状态选择、验证规则和插件可能影响 IPAM 行为。恢复时若缺少这些配置，同一数据库也可能无法正确启动或显示。

治理上建议每月生成 IPAM 质量报告：无 scope 的生产 Prefix、无 owner 的 Prefix、重复地址、active 但未分配对象的地址、deprecated 超过冷却期、VLAN 无 Prefix、Prefix 无角色、自动化 token 即将过期、最近三十天未验证的地址池。

每季度复审地址规划。业务增长、云连接、IPv6 推进、工厂网络隔离和安全分区变化都会影响 Prefix 结构。NetBox 中的层级应反映当前网络策略，而不是永远保留最初导入时的 Excel 结构。

小结

NetBox IPAM 的核心是把地址空间建模为可治理对象：RIR 和 Aggregate 描述来源，VRF 描述路由隔离，Prefix 描述可分配网络，IP Address 描述具体接口地址，VLAN 描述二层域，scope、role、tenant 和状态描述管理边界。当前版本中 Prefix 使用 scope 替代旧 site 字段，这是旧文和旧脚本最容易出错的地方。

落地时先做地址规划和对象字典，再导入数据；自动化必须把 VRF、scope 和对象关系作为查询条件；地址回收要用状态和冷却期；发现结果用于对账，不应无审核覆盖期望状态。下一篇进入 DCIM 设备管理，把站点、机架、设备、设备类型、接口和物理资产关系建立起来，再与本篇的 IPAM 对象连接。

参考资料