NetBox 虚拟电路（Virtual Circuit）建模指南：在多条物理链路上抽象虚拟连接

后端网络数据建模【免费下载链接】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点击查看免费下载虚拟电路Virtual Circuit是 NetBox 电路管理Circuits模块中的核心模型之一用于在底层一组解耦的物理连接之上把两个或多个接口抽象为一个逻辑上的连接关系。本文以 docs/models/circuits/virtualcircuit.md 为骨架结合 虚拟电路模型源码、选项定义、序列化器 与 过滤器集 等实现证据系统讲解虚拟电路的字段语义、状态机、终止点Termination拓扑角色、底层校验规则、REST API 使用方式以及如何通过FIELD_CHOICES自定义状态帮助你在 NetBox 中准确建模运营商级虚拟连接如 EVPL、VPLS、点对点 L2 服务等。一、什么是虚拟电路理解其与物理电路的分工物理电路Physical Circuit建模的是实实在在的物理链路如光纤、租用专线而虚拟电路则是在这些物理连接之上叠加的逻辑抽象。官方文档给出的典型场景是两台设备各自有一个虚拟接口virtual interface每个虚拟接口绑定到本设备的一个物理接口这些物理接口分别通过独立的物理电路连接到同一个提供商网络于是两个虚拟接口之间就构成了一条虚拟电路。在源码中模型文档字符串也明确了这一语义class VirtualCircuit(ContactsMixin, PrimaryModel): A virtual connection between two or more endpoints, delivered across one or more physical circuits. 关键点在于解耦物理与逻辑虚拟电路不关心底层走的是哪几条物理电路只要两端都挂在同一个提供商网络上即可多端点能力不同于物理电路只有 A/Z 两个端子虚拟电路通过终止点Termination可以连接两个或多个端点见 virtualcircuittermination.md依赖模型虚拟电路依赖于 提供商网络 与 虚拟电路类型源码中通过prerequisite_models声明了这一前置条件virtual_circuits.pyprerequisite_models ( circuits.ProviderNetwork, circuits.VirtualCircuitType, )也就是说在 NetBox UI 中创建虚拟电路之前必须先存在对应的 Provider Network 和 Virtual Circuit Type 对象。二、虚拟电路字段详解官方文档列出了五个核心字段Provider Network提供商网络、Provider Account提供商账户可选、Circuit ID电路编号、Type类型、Status状态。下面结合模型源码逐一展开并补充字段约束与默认值。2.1 Provider Network提供商网络必填虚拟电路所跨越的提供商网络即在哪张运营商网络上建立这条虚拟连接。这是一个必填的外键指向circuits.ProviderNetwork且采用PROTECT删除保护——只要仍有虚拟电路引用该网络就不能直接删除它virtual_circuits.py。2.2 Provider Account提供商账户可选与虚拟电路关联的提供商账户如账单账户、业务账户。该字段可为空blankTrue, nullTrue同样是PROTECT保护的外键virtual_circuits.py。需要注意一个隐含约束如果填写了 Provider Account它必须与 Provider Network 属于同一个 Provider。这一校验在模型的clean()方法中强制实现virtual_circuits.pydef clean(self): super().clean() if self.provider_account and self.provider_network.provider ! self.provider_account.provider: raise ValidationError({ provider_account: The assigned account must belong to the provider of the assigned network. })同时模型提供provider只读属性直接返回provider_network.provider方便在模板与 API 中统一取用。2.3 Circuit IDcid必填唯一由提供商分配给虚拟电路的唯一标识符对应模型字段cidcid models.CharField( max_length100, verbose_name_(circuit ID), help_text_(Unique circuit ID) )其唯一性由数据库约束保证。模型 Meta 中定义了两条UniqueConstraintvirtual_circuits.py(provider_network, cid)同一提供商网络内 cid 唯一(provider_account, cid)同一提供商账户内 cid 唯一。也就是说电路编号并不是全局唯一的而是在某个网络/账户的上下文内唯一这与现实运营商的业务习惯一致不同运营商可能使用相同的内部编号。2.4 Type虚拟电路类型必填指向circuits.VirtualCircuitType用于按功能或技术对虚拟电路分类例如区分 EVPL、VPLS、专线穿透等业务类型。类型本身是组织级Organizational可完全自定义的模型只有 Name 与 Slug 两个业务字段virtualcircuittype.md由VirtualCircuitType(BaseCircuitType)定义virtual_circuits.py。2.5 Status状态虚拟电路的运行状态默认取值为CircuitStatusChoices这是一个ChoiceSetchoices.py。默认状态与颜色、语义说明如下表状态数据库值显示名称颜色语义plannedPlanned青色cyan规划中预留未来使用但尚未部署provisioningProvisioning蓝色blue正在配置、准备投入服务activeActive绿色green完全可用正在服役默认值offlineOffline红色red已安装但当前不在服务deprovisioningDeprovisioning黄色yellow正在从服务中移除decommissionedDecommissioned灰色gray已退役不再服役模型中status字段的默认值是STATUS_ACTIVEvirtual_circuits.py也就是说新建虚拟电路默认即为 Active。状态颜色由get_status_color()从CircuitStatusChoices.colors映射中取得用于 UI 徽章着色。注意该状态集合与物理电路circuits.Circuit共用同一个CircuitStatusChoices因此下文介绍的FIELD_CHOICES自定义方式对两者同时生效配置键均为circuits.Circuit.status。三、自定义虚拟电路状态FIELD_CHOICES 实战官方文档在 Custom circuit statuses 提示中明确指出可以通过配置参数FIELD_CHOICES下的Circuit.status键定义额外的电路状态。该配置的完整说明见># 替换默认状态以下示例将电路状态替换为 Foo/Bar/Baz 三个选项 FIELD_CHOICES { circuits.Circuit.status: ( (foo, Foo, red), (bar, Bar, green), (baz, Baz, blue), ) }若只想追加自定义状态而保留默认六项则在键末尾加FIELD_CHOICES { circuits.Circuit.status: ( (custom, Custom Status, purple), ) }NetBox v4.7 起还支持字典格式可附带description在 UI 中作为选项副标题展示FIELD_CHOICES { circuits.Circuit.status: ( {value: provisioned, label: Provisioned, color: green, description: Provisioned and ready}, ) }从源码层面看这一机制由 utilities/choices.py 中的ChoiceSetMeta元类实现每个声明了key的ChoiceSet在类创建时会读取settings.FIELD_CHOICES中对应键的配置——存在普通键则整体替换CHOICES否则查找键名进行追加字段标识大小写不敏感。CircuitStatusChoices恰好声明了key Circuit.statuschoices.py因此该配置会同时作用于物理电路与虚拟电路。四、虚拟电路终止点Virtual Circuit Termination拓扑角色建模要真正接通一条虚拟电路需要为其添加终止点。官方文档在 virtualcircuittermination.md 中说明终止点代表一个虚拟接口dcim.Interface且必须是虚拟接口到虚拟电路的连接并定义了三种功能角色取决于虚拟电路的拓扑形态点对点或 Hub-and-Spoke 多点角色数据库值显示名称颜色语义源码注释peerPeer绿色作为对等端点与其他 peer 连接点对点hubHub蓝色中心端点spoke 连接到此spokeSpoke橙色远端端点连接到 hub角色定义见 choices.py默认角色为peer。终止点模型本身virtual_circuits.py包含以下字段与规则virtual_circuit所属虚拟电路CASCADE级联删除删除虚拟电路会一并删除其终止点role上述三种角色之一interface指向dcim.Interface的一对一外键即一个接口最多属于一条虚拟电路description可选描述。两个关键实现细节值得注意只允许虚拟接口。clean()中强制校验interface.is_virtual非虚拟接口会抛出 Virtual circuits may be terminated only to virtual interfaces. 错误virtual_circuits.py对端自动推导。peer_terminations属性按角色返回对端终止点Peer 角色返回同电路中其他所有 PeerHub 返回其全部 SpokeSpoke 返回其 Hubvirtual_circuits.py这为 UI 展示与拓扑计算提供了便利。此外变更日志ObjectChange会将该终止点的变更关联到其所属虚拟电路对象上to_objectchange中设置related_object。五、在 NetBox 中使用虚拟电路5.1 UI 操作虚拟电路的 UI 视图位于 Circuits 应用下views.py提供标准的对象列表、详情、编辑、删除以及批量导入/编辑/重命名/删除等操作。对象详情页的属性面板ui/panels.py展示 provider、provider network、provider account、Circuit ID等宽字体并带复制按钮、type带颜色、status、tenant 与 description终止点面板则展示虚拟电路、角色以及所绑定接口所属的设备与接口信息ui/panels.py。5.2 REST API虚拟电路对外暴露为/api/circuits/virtual-circuits/资源序列化器见 serializers_/circuits.py创建一条虚拟电路的请求体示例{ cid: VC-1001, provider_network: 1, provider_account: 2, type: 3, status: planned, tenant: null, description: Point-to-point EVPL to branch office }字段说明provider_network、type为必填主键provider_account、status、tenant可选status为 ChoiceField取值必须是上文状态表或FIELD_CHOICES自定义后中的数据库值响应中的brief_fields仅含cid、description、provider_network等精简字段可用于列表场景serializers_/circuits.py。终止点则通过/api/circuits/virtual-circuit-terminations/管理序列化器包含virtual_circuit、role与interfaceserializers_/circuits.py。REST API 测试用例tests/test_api.py展示了完整的创建数据形态例如在同一个 Provider Network 与 Provider Account 下用不同 cid 批量创建多条虚拟电路。5.3 过滤与检索过滤VirtualCircuitFilterSetfiltersets.py支持按 providerID/slug、provider_accountID/account、provider_network、typeID/slug、status、tenant 等过滤全文搜索q会匹配cid、description与comments字段。注意VirtualCircuitTerminationFilterSet还支持通过终止点的interface_id反向定位虚拟电路filtersets.py。全局搜索VirtualCircuitIndexsearch.py将cid权重 100、description权重 500与comments权重 5000纳入 NetBox 全局搜索索引结果展示 provider_network、provider_account、status 等属性。GraphQL虚拟电路同样暴露于 GraphQL API类型定义见 graphql/types.py支持与 REST 一致的字段查询。5.4 批量操作与租户/联系人作为PrimaryModel且混入ContactsMixin虚拟电路支持租户Tenant通过tenant外键归属租户并在表格中按租户分组显示联系人Contacts可关联联系人/联系人组便于跟踪业务责任人批量导入VirtualCircuitImportFormforms/bulk_import.py支持 CSV 批量创建字段与 API 创建保持一致克隆clone_fields包含 provider_network、provider_account、status、tenant、descriptionvirtual_circuits.pyUI 中可从已有对象一键克隆创建。六、完整建模示例两条分支站点间的 EVPL综合以上内容一个完整的建模流程如下创建Provider运营商如 ISP Alpha创建该运营商的Provider Network如 Alpha Metro Ethernet创建Provider Account如 Enterprise Billing Account创建Virtual Circuit Type如 EVPL为两台设备各创建一个虚拟接口Interface类型为 virtual创建Virtual Circuit填写cid如VC-1001、选择网络/账户/类型/状态/租户为虚拟电路添加两个Termination两端接口均选择角色Peer点对点场景若为多点Hub-and-Spoke拓扑则中心端接口角色选Hub分支端选Spoke。完成后即可在 UI 中查看电路详情与两端接口、在 API 中检索该电路并通过FIELD_CHOICES按需扩展自定义状态以贴合实际业务。七、相关模型与进一步阅读电路类型Circuit Type、物理电路Circuit、电路终止点Circuit Termination提供商Provider、提供商账户Provider Account、提供商网络Provider Network虚拟电路终止点Virtual Circuit Termination、虚拟电路类型Virtual Circuit Type配置参数 FIELD_CHOICESREST API 使用指南、GraphQL API 使用指南核心实现文件索引虚拟电路模型、状态与角色选项、REST 序列化器、过滤器集、API 测试用例、视图与 UI 面板、netbox/circuits/ui/panels.py。赞分享后端网络数据建模【免费下载链接】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点击查看免费下载相关推荐NetBox 虚拟电路终结Virtual Circuit Termination模型完全指南NetBox 虚拟电路终结Virtual Circuit Termination模型完全指南 虚拟电路终结Virtual Circuit Terminat后端网络数据建模NetBox Virtual Circuit Types虚拟电路类型完全指南字段、定制与数据建模NetBox Virtual Circuit Types虚拟电路类型完全指南字段、定制与数据建模 NetBox 使用虚拟电路Virtual Circui后端网络数据建模NetBox 虚拟化建模指南用集群、虚拟机类型与虚拟机构建虚实一体的网络资产台账NetBox 虚拟化建模指南用集群、虚拟机类型与虚拟机构建虚实一体的网络资产台账 NetBox 的虚拟化模块 virtualization 允许你在一套数后端网络数据建模上一篇高性能金融数据处理架构设计基于mootdx的通达信数据读取解决方案下一篇如何将Qwen2-0.5B部署到生产环境性能优化与资源管理指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考