NetBox v3.1 发布解读无线网络、FHRP 组、联系人体系与动态配置新特性全解析【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox本篇技术指南以仓库内 docs/release-notes/version-3.1.md 为骨架系统梳理 NetBox v3.12021-12-06 发布 v3.1.0其后迭代至 v3.1.11的核心新特性、破坏性变更与 REST API 变更并结合当前仓库源码逐一印证其底层实现。读完本文你将掌握联系人Contact、无线网络Wireless LAN/Link、FHRP 组、条件 Webhook、接口桥接、多 ASN、动态配置与 SSO 登录等能力的建模思路、字段含义与落地方式同时了解 v3.1 版本要求 PostgreSQL 10 这一硬性前提。一、版本总览与升级前提NetBox v3.1 是一次功能密集的重大版本主线新特性多达八项联系人对象、无线网络、动态配置更新、FHRP 组、条件 Webhook、接口桥接、站点多 ASN 以及 SSO 单点登录。v3.1.0 发布于 2021-12-06此后通过 v3.1.1 ~ v3.1.11 共 11 个补丁版本持续修复缺陷、打磨体验最后一次发布为 2022-04-05。1.1 硬性升级前提PostgreSQL 10 及以上原文档在 v3.1.0 开头即以警告形式强调见 version-3.1.mdPostgreSQL 10 Required— NetBox v3.1 requires PostgreSQL 10 or later.这一要求对应原文档 Other Changes 中的 #7318 与 base_requirements.txt 中对 PostgreSQL 相关依赖psycopg、django 等的约束。升级部署前务必确认数据库版本满足要求。1.2 破坏性变更Breaking Changesv3.1.0 一次性引入了四项需要迁移注意的破坏性变更变更项说明影响Cable 的租户过滤语义变化tenant/tenant_id过滤器改为按电缆自身直接分配的租户过滤而非按两端终结对象所属父对象的租户依赖旧语义的过滤查询结果可能变化属性重命名电缆终结模型的cable_peer、cable_peer_type重命名为link_peer、link_peer_type涉及 REST API 字段与外部脚本需同步更新导出内容类型表示变化Webhook 与自定义字段导出时关联的内容类型改为原始字符串值如dcim.site而非人类可读名称影响依赖导出数据的自动化流程接口类型标识修正128GFC 接口类型由128gfc-sfp28更正为128gfc-qsfp28影响使用该类型标识的导入数据与筛选器link_peer/link_peer_type的改名并非简单措辞调整其背后是为了容纳无线链路——v3.1 让接口之间除了物理电缆连接之外还存在无线链路连接因此用中性的 link链路统一描述两类连接。从 device_components.py 中接口的has_link判断逻辑可以看到这种统一self.cable_id is not None or getattr(self, wireless_link_id, None) is not None即是否存在连接同时考虑电缆与无线链路两种形态。二、联系人对象Contact Objectsv3.1 在 tenancy 应用中引入了一套用于跟踪联系人信息的全新模型对应 issue #1344用户可以创建独立的联系人对象含姓名、头衔、邮箱等并挂接到 NetBox 内的各类模型上。2.1 数据模型Contact / ContactGroup / ContactRole / ContactAssignment从 contacts.py 的源码可以完整还原这套模型的设计Contact核心联系人实体字段包括name自然排序、title、phone、emailEmailField、address、linkURL并通过多对多groups关联 ContactGroup。ContactGroup继承NestedLtreeGroupModel即基于 ltree 的层级分组模型支持无限层级嵌套并利用 GiST 索引与sort_path做高效树查询其ContactGroupManager.annotate_contacts()用path 操作符统计本组及所有后代组内的联系人数量。ContactRole联系人角色如 billing、technical属于组织型模型。ContactAssignment联系人与目标对象的多对多挂接关系通过 GenericForeignKeyobject_typeobject_id实现可关联任意启用了contacts特性的模型。挂接时必须指定角色role并可选择性指定priority优先级同时以UniqueConstraint(fields(object_type,object_id,contact,role))保证同一对象上同一联系人同一角色不重复。2.2 分配规则与约束原文档明确一个对象可关联的联系人数量无上限一个联系人可被分配到任意多个对象。这与ContactAssignment中不设数量限制的建模一致。分配时priority字段使用ContactPriorityChoices如 primary/secondary/tertiary 等用于表达相对优先级。此外ContactAssignment.clean()会校验目标对象类型是否具备contacts特性不支持的对象类型会抛出ValidationError。2.3 REST APIv3.1 新增了四个联系人相关端点详见下文REST API 变更小节/api/tenancy/contact-assignments//api/tenancy/contact-groups//api/tenancy/contact-roles//api/tenancy/contacts/三、无线网络模型Wireless LAN / Wireless Linkv3.1 引入两个新模型issue #3979来建模无线网络同时大幅扩展了接口Interface的无线属性。3.1 两种连接形态从 models.py 源码可见WirelessLAN多接入无线网段任意数量的无线接口可接入。核心字段ssid必填最大长度由SSID_MAX_LENGTH定义、group可挂到 WirelessLANGroup 层级分组、status默认 active、vlan可关联 VLAN、tenant。继承WirelessAuthenticationBase获得认证属性。WirelessLink恰好两个无线接口之间的点对点连接。字段包括interface_a/interface_b均指向dcim.Interfaceon_deletePROTECT、ssid、status默认 connected、tenant并以UniqueConstraint(fields(interface_a,interface_b))保证唯一性。其clean()会校验两端接口的类型必须属于WIRELESS_IFACE_TYPES无线接口类型集合否则报错save()时会缓存两端接口所属的设备到_interface_a_device/_interface_b_device从而支持按设备过滤无线链路。3.2 共享的认证属性WirelessAuthenticationBase抽象基类为 WirelessLAN 与 WirelessLink 提供了统一认证三件套字段类型说明auth_typeCharField(50)认证类型open / WEP / WPA / WPA2 等见WirelessAuthTypeChoices可空auth_cipherCharField(50)认证加密算法如 TKIP / AES可空auth_pskCharField预共享密钥Pre-Shared Key长度受PSK_MAX_LENGTH约束3.3 接口无线属性扩展原文档指出接口模型新增了如下无线相关属性对应的字段定义在 device_components.pyrf_role无线角色——Access Point接入点或 Station站点rf_channel预定义信道位于某个标准化频段内rf_channel_frequency与rf_channel_width自定义信道频率与带宽例如用于授权频段场景tx_power接口的发射功率建模enhancement #7606wireless_link关联的 WirelessLinkwwn接口的 World Wide Name 字段enhancement #1337。值得注意的验证逻辑源码中clean()规定rf_channel/rf_channel_frequency/rf_channel_width只能设置在无线接口上且当已选定预定义信道时自定义频率必须与信道默认频率一致Cannot specify custom frequency with channel selected.。这保证了预定义信道与自定义频率两种表达方式互不冲突。四、FHRP 组First Hop Redundancy Protocol Groups为帮助建模 HSRP、VRRP、GLBP 等第一跳冗余协议配置v3.1 引入了 FHRP 组模型issue #6235。4.1 FHRPGroupFHRPGroup(PrimaryModel)字段字段说明group_id组 IDPositiveSmallIntegerField必填name组名可空protocol协议HSRP / VRRP / GLBP / 其他见FHRPGroupProtocolChoicesauth_type认证类型可空auth_key认证密钥最长 255 字符可空ip_addresses通过 GenericRelation 关联的一个或多个虚拟 IP 地址ipam.IPAddressservices通过 GenericRelation 关联的服务其__str__会生成类似HSRP: 10 (192.0.2.1)的展示形式协议 组 ID 首个虚拟 IP。排序默认按protocol, group_id。v3.1.x 中该模型持续演进v3.1.3 为协议增加 other其他选项#8100v3.1.11 又新增 Checkpoint ClusterXL 协议#8830。4.2 FHRPGroupAssignmentFHRPGroupAssignment(ChangeLoggedModel)用于把设备/虚拟机的接口挂接到 FHRP 组interface_typeinterface_idinterface通过 GenericForeignKey 指向任意设备接口或 VM 接口group所属 FHRP 组priority数字优先级受FHRPGROUPASSIGNMENT_PRIORITY_MIN/FHRPGROUPASSIGNMENT_PRIORITY_MAX约束PositiveSmallIntegerField Min/Max 校验并按-priority降序排列。约束上UniqueConstraint(fields(interface_type,interface_id,group))保证同一接口在同一个 FHRP 组中只允许出现一次。相关修复还包括v3.1.1 校验创建 FHRP 组时虚拟 IP 的唯一性#8009v3.1.5 修复以 IP 地址与 other 协议创建 FHRP 组时的 KeyError#8224v3.1.9 修正 FHRP 组列表的成员计数#8808与 assignment 的 REST API URL#8807。4.3 REST API/api/ipam/fhrp-groups//api/ipam/fhrp-group-assignments/接口序列化器serializer中为设备/VM 接口新增了只读字段count_fhrp_groups便于列表页直接展示成员组数量。五、条件 WebhookConditional Webhooksv3.1 为 Webhook 增加了conditions字段issue #6238使 Webhook 只有在满足指定条件时才触发。例如只希望设备状态为 active 或 staged 时发出请求{ attr: status.value, op: in, value: [active, staged] }多条条件可以通过 AND/OR 逻辑嵌套组合完整语法见原文档指向的 条件逻辑参考文档。从当前仓库 conditions.py 的源码可以确认该机制由Condition单条条件含attr/op/value与ConditionSet条件集合负责 AND/OR 递归求值组成ConditionSet.eval(data)会调用func(d.eval(data) for d in self.conditions)即把各子条件的求值结果按集合逻辑AND/OR聚合从而支持任意深度的嵌套布尔表达式。REST API 层面extras.Webhook序列化器events.py新增了conditions字段与模型字段一一对应。六、接口桥接Interface Bridgingv3.1 在设备与虚拟机的接口模型上新增bridge字段issue #6346用于表示同一父设备/虚拟机内部接口间的二层桥接邻接关系bridge字段见 device_components.py 第 827 行附近的 ForeignKey指向同一设备/VM 上的另一个接口bridge 同时被加入为一种接口类型不过任何类型的接口都可以被指定为桥接接口。由此可以组合出两种典型拓扑桥接组bridge group多个物理接口桥接到同一个虚拟接口类型为 bridge模拟二层交换组内部交叉互联internal cross-connect两个物理接口互相桥接。桥接能力还延伸到电缆追踪v3.1.0 的 enhancement #7761 让电缆追踪可以跨越桥接接口v3.1.1 修复了无电缆的桥接接口间电缆追踪问题#8003v3.1.11 则在接口视图展示桥接成员#8163。七、站点多 ASNMultiple ASNs per Sitev3.1 引入独立的 ASN 模型issue #6732使一个站点可以分配多个 ASN。7.1 ASN 模型从 asns.py 源码可见当前仓库中该模型已加入ContactsMixin即后续版本支持联系人挂接字段说明rir负责该 AS 号段的区域互联网注册机构必填PROTECT 删除保护asnAS 号使用ASNField全局唯一支持 16 位或 32 位role该 ASN 的主要功能角色可空tenant租户可空原文档强调每个 ASN 实例必须有一个 32 位 AS 号即最大支持到 4294967295覆盖 4 字节 ASN。站点模型dcim.Site通过新增的asns关系与ipam.ASN建立多对多关联同时保留旧的asn整数字段以维持向后兼容直到后续版本移除。7.2 4 字节 ASN 与 ASDOT 展示结合 v3.1.x 的增强点v3.1.6 起在表中以 ASDOT 记号展示 4 字节 ASN#8293v3.1.7 引入独立的 ASDOT 列#8275并将 ASN 纳入全局搜索#8367、把 ASN Web UI 提升到与其他对象一致的标准#8476。源码中asn_asdot与asn_with_asdot两个属性ASNField.to_asdot即负责对大于 65535 的 AS 号输出x.y格式的 ASDOT 记法。7.3 REST API/api/ipam/asn/八、动态配置更新Dynamic Configuration Updatesv3.1 实现动态配置能力issue #5883部分 NetBox 配置参数现在可以通过Admin 管理界面直接修改保存后立即生效无需重启 NetBox且每次动态配置的迭代版本都会保存在数据库中管理员可随时回滚到任意历史版本。8.1 优先级与持久化机制原文档明确了两点关键规则configuration.py中定义的参数优先于管理界面中的设置——即静态配置文件仍是最高优先级管理界面配置只在静态文件未定义对应参数时生效动态配置的每一次变更都会被持久化并保留历史版本支持随时恢复。从当前仓库源码看这一机制由 core/models 中的ConfigRevision模型与 config/init.py 的缓存逻辑协同实现配置读取层会从最新的active 的ConfigRevision填充缓存当不存在任何 ConfigRevision 时保持空配置并缓存空状态避免重复查询创建新 ConfigRevision 时会通过 post_save 信号激活并刷新缓存。相关测试见 test_config.py其中覆盖了无 ConfigRevision 时的空缓存、ConfigRevision.data 为 NULL、version 字段等边界场景。8.2 管理与验证管理界面中的动态配置表单ConfigRevisionForm相关验证逻辑位于 test_forms.py用于确保管理员在界面提交的参数组合合法。另有一个细节值得注意v3.1.11 的 enhancement #8974 为配置修订表单中的文本域启用了等宽字体方便管理员阅读 JSON 形态的配置数据。九、SSO 单点登录Single Sign-On Authenticationv3.1 通过 python-social-auth 库引入 SSO 认证支持issue #7649。管理员可以选用该库支持的任意认证后端如 Google OAuth2、Microsoft Entra ID/Azure AD、Okta 等来启用单点登录。仓库中与 SSO 相关的文档资料位于 docs/administration/authentication/ 目录其中 google.md、microsoft-entra-id.md、okta.md 分别给出了 Google、Microsoft Entra ID、Okta 三种后端的配置示例含 App Registration、Client Secret 等步骤overview.md 提供总体介绍配置层面的参数说明可进一步参阅 remote-authentication.md。配置示例文件 netbox.env 中亦有与认证相关的环境变量可参考。v3.1.3 中还标准化了RemoteUserBackend的日志记录器名称#7972便于运维排查认证日志。十、v3.1.x 补丁版本重点回顾v3.1 系列共 11 个版本除 v3.1.0 外均为缺陷修复与体验增强。下表提炼各版本的高价值变更完整列表见 version-3.1.md版本日期代表性增强代表性修复v3.1.112022-04-05桥接接口成员展示、按父设备 ID 过滤子设备、IP DNS 名支持通配符、Checkpoint ClusterXL 协议、站点联系人批量编辑设备编辑视图机架位置搜索异常、全局搜索结果机架设备计数v3.1.102022-03-25100% 利用率条配色区分、站点/位置视图添加非机架设备、按联系人与联系人角色过滤对象深色模式导航栏背景、VLAN 组按站点过滤、接口rf_role置空错误v3.1.92022-03-07全部适用模型支持 description 精确匹配过滤、LC/SC/LSH 端口类型新增 PC/UPC 光纤端面、服务协议列表新增 SCTP批量导入限制 bridge/parent/LAG 为设备接口、权限中多 tag 去重、FHRP 组 assignment 的 API URLv3.1.82022-02-15nbshell支持 Tab 补全、机架正面设备超链接化、changelog 表显示完整用户名CSV 导出时空日期返回空字符串、表配置键available_columns错误、自定义字段/Webhook 批量编辑v3.1.72022-02-03ASN 加入全局搜索、自定义脚本表单field_order控制字段顺序、联系人加入全局搜索、布尔自定义字段图标化分数单位电缆长度计算、内容类型 API 免除模型权限、housekeeping 脚本执行权限v3.1.62022-01-17ASDOT 记号展示 4 字节 ASN、Stackwise-n 接口类型、按创建/更新时间排序对象表虚拟 chassis 成员机架展示、cluster_count序列化修复、自定义字段默认值误显示为已应用过滤器v3.1.52022-01-06页内对话框确认删除、电缆过滤表单增加长度字段前缀 IP 视图 ValueError、ChoiceVar 可选字段强制选择、无线 LAN/Link 认证参数批量编辑v3.1.42022-01-03聚合子前缀视图添加前缀按钮、admin UI 批量分配用户到组、确立netbox/local/本地资源目录标签列渲染、大 IPv6 前缀 IndexError、自定义整数字段负值边界v3.1.32021-12-29表格内嵌自定义链接、前缀视图可用 IP 计数、CSV 导入指定自定义字段验证器、FHRP 组协议 otherNAPALM 响应不再 URL 解码、自定义脚本转发HTTP_X_FORWARDED_FOR、无线序列化器缺失字段v3.1.22021-12-20基于 HTMX 的动态对象表、6/60 GHz 无线信道、设备/VM 主 IP 的 NAT 链接、导航菜单直接创建服务设备类型上下文误用于 VM、长对象字符串变更日志 DataError、IP 分配给多对象的校验v3.1.12021-12-13表列头排序指示符可用前缀/IP 端点权限评估、不可满足请求返回 409、电缆按站点 slug 或机架名过滤其中 v3.1.2 的HTMX 动态对象表#8057 目录与 htmx.py 即承载了这套动态表格机制。v3.1.8 的nbshellTab 补全#8620 的交互效率。十一、REST API 变更汇总v3.1.0 的 REST API 变更量较大除上文各节已列出的新增端点外还有大量字段级变更整理如下11.1 新增端点IPAM/api/ipam/asn/、/api/ipam/fhrp-groups/、/api/ipam/fhrp-group-assignments/Tenancy/api/tenancy/contact-assignments/、/api/tenancy/contact-groups/、/api/tenancy/contact-roles/、/api/tenancy/contacts/Wireless/api/wireless/wireless-lans/、/api/wireless/wireless-lan-groups/、/api/wireless/wireless-links/11.2 字段级变更节选新增tags字段的模型组织型模型全面支持标签circuits.CircuitType、dcim.DeviceRole、dcim.Location、dcim.Manufacturer、dcim.Platform、dcim.RackRole、dcim.Region、dcim.SiteGroup、ipam.RIR、ipam.Role、ipam.VLANGroup、tenancy.ContactGroup、tenancy.ContactRole、tenancy.TenantGroup、virtualization.ClusterGroup、virtualization.ClusterType对应 enhancement #6497。电缆终结类模型CircuitTermination、ConsolePort、ConsoleServerPort、FrontPort、PowerFeed、PowerOutlet、PowerPort、RearPort、Interfacecable_peer→link_peer、cable_peer_type→link_peer_type。dcim.Interface新增bridge、rf_channel、rf_channel_frequency、rf_channel_width、rf_role、tx_power、wireless_link、wwn以及只读的count_fhrp_groups。virtualization.VMInterface新增bridge与只读的count_fhrp_groups。dcim.Cable新增tenant字段enhancement #6715。dcim.Location新增tenant字段enhancement #6874。dcim.Devicedisplay字段现在包含资产标签asset tag若有并新增airflow字段enhancement #3839。dcim.DeviceType新增airflow字段。dcim.Site新增指向 ipam.ASN 的asns关系。extras.Webhook新增conditions字段。extras.ImageAttachment新增last_updated字段配合 enhancement #7812 的图片附件变更日志。11.3 值得留意的接口细节修复v3.1.1 修复了可用前缀/IP 端点available prefixes/IPs的权限评估问题#5869并将不可满足的可用前缀/IP 请求从错误状态改为返回409#7519v3.1.6 恢复了多个序列化器缺失的created与last_updated字段#8342。这些细节对依赖 REST API 做集成的读者具有实际参考价值。十二、v3.1 其余值得关注的增强除上述大特性外v3.1.0 还包含若干重要的模型与能力扩展多数在当前仓库中仍可找到对应实现自定义字段类型扩充新增longtext支持 Markdown#6711与json#7452两种类型并为自定义字段新增过滤查找filter lookups#6615。自定义校验规则允许以纯数据或指向类的点分路径dotted path形式定义自定义校验规则#7619。接口 WWN 与发射功率接口新增 WWN 字段与tx_power建模#1337、#7606。命名唯一性放宽cluster 名称、region/site group/location 名称的唯一性约束被放宽#1943、#7354以适应多租户/大规模部署的命名习惯。设备类型组件视图拆分设备类型的组件列表迁移到独立视图#7530。内容类型表示标准化导入与导出功能统一了内容类型的表示方式#7858。十三、总结NetBox v3.1 是一份信息量巨大的版本它用八项新特性奠定了后续版本的能力底座——联系人体系与 FHRP 组丰富了物理/逻辑资源的建模维度无线网络与接口桥接补齐了接入层与二层拓扑的表达能力条件 Webhook 让自动化触发更加精准动态配置与 SSO 则分别提升了运维效率与认证体验同时以 PostgreSQL 10 为硬性门槛、以link_peer重命名为代表的破坏性变更也提醒升级者提前规划迁移。本文所有字段与约束说明均可回溯到仓库源码contacts.py、fhrp.py、asns.py、models.py、device_components.py、conditions.py 等如需进一步了解后续版本演进可继续阅读 release-notes 目录下的其他版本说明。【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考