netbox-assurance

NetBox Assurance

你对 NetBox Assurance 的了解可能已过时。 偏差类型、数据源配置和 API 行为会随着版本更新而变化。请优先使用检索，而非依赖预训练知识。

检索来源

来源	URL / 方法	用途
Assurance 文档	https://netboxlabs.com/docs/assurance/	概览、入门指南、UI 工作流
NetBox Platform MCP	如已配置 — 查询偏差、数据源	实时漂移状态

NetBox Assurance 会检测预期网络状态（NetBox 中记录的应有状态）与实际网络状态（网络中的真实状态）之间的漂移。它会将差异显示为偏差，供你通过 NetBox UI 审核和解决。

何时使用此技能

• 配置或排查 Assurance 偏差工作流
• 了解漂移类型及其解决方法
• 设置用于提供实际网络状态的数据源
• 将 Assurance 与 Discovery 和 Diode 集成
• 围绕偏差分流构建运维工作流

快速参考

偏差状态

状态	含义
Queued	已摄取数据，等待分析
Open	已检测到漂移，可供审核
Applied	已接受更改并推送至 NetBox
Ignored	已由操作员忽略
Failed	尝试应用但出错
No Changes	分析未发现差异
Errored	分析过程中发生处理错误

操作

操作	作用	可用于
Apply	接受偏差，并更新 NetBox 以匹配实际状态	Open、Failed
Ignore	永久忽略偏差	Open
Rediff	根据当前 NetBox 状态重新分析	Open、Applied、Failed
Reopen	重新打开已忽略的偏差	Ignored

所有操作均支持对多个偏差执行批量操作。

漂移类型

类型	描述	示例
属性漂移	对象在两处均存在，但属性不同	设备序列号已更改
清单漂移（新增）	在网络中发现对象，但 NetBox 中没有记录	在设备上发现新接口
清单漂移（过期）	NetBox 中有对象，但近期未在网络中观测到	已停用的设备仍在 NetBox 中

拓扑漂移（例如设备关联到错误站点等关系不匹配）和配置漂移（运行配置与预期配置不一致）是未来计划支持的功能。

架构

Assurance 采用三阶段管道：

1. INGESTION          2. ANALYSIS              3. RESOLUTION
   ─────────            ────────                 ──────────
   Actual state    →    Compare actual     →     Review deviations
   collected from       vs intended              and take action
   network              (NetBox) state           (apply/ignore)

数据源将实际网络状态输入系统：

• Discovery Agent — 基于 SNMP/API 的自动网络扫描
• 控制器集成 — VMware vCenter、Cisco Catalyst Center、HPE Mist 等
• Diode SDK — 用于连接任意数据源的自定义 Python/Go 集成

分析引擎会将摄取的数据与 NetBox 中的数据进行比较，并生成偏差，其中包含字段级别的更改详情（每个不同属性的更改前后值）。

数据源

Assurance 至少需要一个提供实际网络状态的数据源。详细设置说明请参阅 references/data-sources.md。

Discovery Agent（推荐入门方式）

NetBox Discovery 的 Orb Agent 会主动扫描网络，并将结果直接馈送至 Assurance。这是最常见的入门方式。

有关 Agent 配置，请参阅 netbox-discovery 技能。

控制器集成

与基础设施控制器（VMware vCenter、Cisco Catalyst Center、HPE Mist 等）的预构建集成可从管理平台拉取状态。

Diode SDK（自定义集成）

对于不受内置支持的数据源，可使用 Diode SDK（Python 或 Go）以编程方式推送实体数据。

有关 SDK 使用模式，请参阅 netbox-diode 技能。

偏差生命周期

完整的状态机请参阅 references/deviation-lifecycle.md。

典型工作流

1. 数据摄取 — 网络数据从数据源传入 → 偏差进入 Queued
2. 运行分析 — 系统与 NetBox 进行比较 → 偏差变为 Open（或 No Changes）
3. 操作员审核 — 在 UI 中检查字段级变更
4. 采取操作：
   • Apply → 更新 NetBox，偏差标记为 Applied
   • Ignore → 忽略偏差，标记为 Ignored
   • Rediff → 根据当前 NetBox 状态重新分析（适用于手动编辑 NetBox 后）

解决模式

场景	建议操作
检测到合理变更（例如，添加了新接口）	Apply — 更新 NetBox
不想跟踪的已知差异	Ignore — 忽略该差异
你已手动更新 NetBox	Rediff — 重新分析以确认
情况已变化，但此前已忽略	Reopen → 然后 Apply 或 Rediff
Apply 因临时错误失败	修复问题，然后 Rediff 或重试 Apply

UI 工作流

导航

Assurance 会在 NetBox 导航中添加 Assurance 部分，其中包含以下视图：

视图	用途
Deviation Types	浏览偏差类别及其计数
Active Deviations	需要关注的未解决偏差
All Deviations	包含已解决偏差的完整列表
Archived Deviations	历史已解决偏差

审核偏差

1. 前往 Assurance → Active Deviations
2. 点击某个偏差以打开详情视图
3. Overview 选项卡 — 来源、对象类型、状态、时间戳
4. Changes 选项卡 — 字段级变更前后对比
5. 采取操作：Apply、Ignore 或 Rediff

批量操作

在任意列表视图中选择多个偏差，即可执行批量操作：

• Bulk Rediff — 根据当前 NetBox 状态重新分析所有选中项
• Bulk Ignore — 忽略所有选中项
• Bulk Apply — 将所有选中项的变更应用到 NetBox

筛选

偏差列表支持以下筛选条件：

• 状态 — Open、Applied、Failed、Ignored 等
• 对象类型 — 例如，设备、接口、IP 地址
• 偏差类型 — 差异的分类
• 数据源 — 生成偏差的集成
• 时间范围 — 数据摄取时间

偏差类型

偏差按类型分类，将所需操作与对象类型相结合：

• Create 类型 — 需要将对象添加到 NetBox（清单差异）
• Update 类型 — 对象已存在，但属性不同（属性差异）

每种偏差类型都会汇总匹配偏差的数量，因此 Deviation Types 视图可用于快速了解差异模式。

比较内容

通过摄取流水线的任何实体类型都可以进行比较。常见类型包括：

• 设备（dcim.device）
• 接口（dcim.interface）
• 站点（dcim.site）
• 设备类型（dcim.devicetype）
• IP 地址（ipam.ipaddress）
• 前缀（ipam.prefix）

系统具有可扩展性 — 可比较数据源提供的任何实体类型。

集成模式

详细的集成指南请参阅 references/integration-patterns.md。

与 NetBox Discovery 集成

Discovery Agent 提供比较所需的“实际状态”一侧：

Network Devices → Orb Agent (Discovery) → Assurance → Deviations → NetBox

Discovery 和 Assurance 紧密协作 — Discovery 负责收集，Assurance 负责比较和修复。

与 Diode SDK 集成

Diode SDK 是自定义集成的编程式摄取途径：

Custom Script → Diode SDK (Python/Go) → Assurance → Deviations → NetBox

与 NetBox Branching 集成

偏差可以限定在 NetBox 分支范围内，让你能够：

• 根据特定分支的状态审核差异
• 将变更应用到分支，而不是主数据库
• 将分支用作解决偏差的暂存区域

Day 1 / Day 1.5 / Day 2 模式

模式	使用场景
Day 1 — 初始填充	对新网络运行 Discovery，批量应用偏差以填充 NetBox
Day 1.5 — 对账	将现有 NetBox 数据与实际网络进行比较，修复差异
Day 2 — 持续保障	持续监控偏移，并在偏差出现时进行分流处理

权限

Assurance 定义了两个权限级别：

权限	授予的能力
查看 Assurance	只读访问偏差视图
添加 Assurance	执行操作的能力（应用、忽略、重新比较、重新打开）

通过 NetBox 的标准用户／组权限系统分配这些权限。

先决条件

• 启用了 Assurance 的 NetBox Cloud 或 NetBox Enterprise。文档规定的要求是：NetBox Enterprise 1.10+ 且具有 Assurance 授权（是否安装 Assurance 服务由许可证文件决定），或为 Starter、Professional 或 Premium 计划添加 NetBox Cloud 附加组件。Assurance 插件版本为 v1.6.x（v1.6.0，2026-09-03），声明支持 NetBox 4.4.10–4.7.x；你获得的 NetBox 版本取决于 Cloud／Enterprise 平台版本中捆绑的版本。
• 至少配置一个数据源
• 数据源与 Assurance 服务之间具备网络连接

Assurance 是 NetBox Cloud 和 NetBox Enterprise 的可选付费附加组件，不属于开源 NetBox Community。

故障排除

未显示任何偏差

1. 确认数据源处于活动状态且正在发送数据
2. 检查 Discovery Agent 是否正在运行并收集数据（参见 netbox-discovery）
3. 确认数据采集正常（数据应流入分析流程）
4. 请耐心等待——分析是异步进行的，可能需要几分钟

误报过多

• 检查哪些对象类型和字段产生了噪声
• 对已知且可接受的差异使用 忽略
• 考虑是否需要调整数据源配置（例如，SNMP 团体字符串、API 凭据）

偏差处理失败

• 在偏差详情视图中查看错误详情
• 常见原因：写入 NetBox 时权限不足、验证错误、依赖项顺序问题
• 修复根本原因后，使用 重新比较 重新分析

大型网络的性能

• 使用筛选缩小偏差视图的范围（按状态、对象类型、时间范围）
• 逐步处理偏差——从一种对象类型或一个站点开始
• 批量操作有助于高效处理大量数据

反模式和限制

1. Assurance 会比较数据源提供的数据——如果数据源未收集某个字段，Assurance 就无法检测该字段的偏移
2. 应用顺序很重要——某些偏差依赖于其他偏差（例如，必须先创建站点，才能将设备分配给该站点）。系统会处理依赖项顺序，但复杂的依赖链可能需要人工干预
3. 过期清单检测能力有限——检测应从 NetBox 中移除的对象（因为它们已不再存在于网络中）取决于观测时间戳，且此能力仍在发展中
4. 并非实时系统——网络变更、发现、分析和偏差可用之间存在固有延迟
5. 分支范围——使用分支时，请确保你针对正确的分支上下文审查偏差

版本说明

NetBox 4.7（2026-09-02）

• 基于 diode-sdk-python 1.14.x / diode-sdk-go 1.12.0 构建的数据源可以生成 4.7 模型（cooling、ModuleBayType）和字段（Interface.channels/channel_id、Service.port_mappings、DeviceType.end_of_life、cooling_method），因此，当你的平台版本包含 NetBox 4.7 后，这些内容便可以进行比较（插件 v1.6.0 声明支持 4.7.x）——请参阅 references/data-sources.md。
• 你在问题排查过程中读取的 REST 响应格式有所变化（选择类型的自定义字段现在是 {"value", "label"} 对象、服务中新增 port_mappings、批量操作错误现在按对象分别返回）——请参阅 references/deviation-lifecycle.md。

NetBox 4.6

• Diode SDK（python 1.12.0 / go 1.9.0）新增了 CableBundle、RackGroup、VirtualMachineType；交换机堆栈发现会生成 VirtualChassis 和成员设备。

参考资料

文档	阅读时机
references/deviation-lifecycle.md	了解状态转换和解决模式
references/data-sources.md	设置要比较的内容
references/integration-patterns.md	将 Assurance 与 Discovery、Diode 和 NetBox Labs 技术栈连接起来

相关技能

• netbox-discovery — 用于网络扫描的 Orb Agent 配置
• netbox-diode — 用于以编程方式摄取数据的 Diode SDK
• netbox-branching — 支持分支的工作流