上一篇把 DCIM 的 Site、Location、Rack、Device、Interface、Module、电源和控制台对象梳理清楚。本篇继续处理物理层和运营商线路：设备之间如何连接，配线架如何表达，专线如何从供应商网络进入站点，故障时如何追踪路径，变更前如何判断影响范围。

在 NetBox 中，“连接管理”不是画一张拓扑图然后存档，而是把 Cable、Front Port、Rear Port、Circuit、Circuit Termination、Provider 和 Provider Network 等对象按真实关系建模。图纸可以从数据中派生，审计也可以从数据中执行；如果只把图片当成果，变更发生后图片很快失真。

为什么连接数据容易失真

物理连接最容易出现三类失真。第一类是现场变更没有回写系统：值班人员临时把光纤从一个端口换到另一个端口，业务恢复了，台账没有更新。第二类是文档层级不一致：网络团队维护交换机端口表，数据中心团队维护配线架表，运营商线路在合同或工单里，三个来源互相不能追踪。第三类是模型选错：把运营商 MPLS 云当成一条点到点线，把配线架当普通交换机接口，把电源线和控制台线完全排除在模型外。

NetBox 的优势在于把连接拆成真实对象。Cable 表示直接物理连接；Front Port 和 Rear Port 表示穿通端口和结构化布线路径；Circuit 表示供应商提供的物理链路或电路服务；Circuit Termination 表示电路的 A/Z 端；Provider 和 Provider Network 表示供应商和供应商内部网络边界。每个对象都有状态、标签、描述和关系，路径追踪可以沿着这些关系走完整链路。

连接管理的目标不是“录得越细越好”，而是“录到足以支撑故障、变更、审计和容量规划”。如果某站点只有几台设备，直接 Cable 已经足够；如果是数据中心、园区主干、运营商专线、跨楼宇布线或多租户托管环境，就需要表达配线架、交叉连接、供应商网络和线路状态。

Cable：直接物理连接

官方 Cable 文档说明，NetBox 中设备组件之间的所有连接都由 Cable 表示。Cable 可以连接网络接口、控制台端口、控制台服务器端口、前后穿通端口、电路终端、电源端口、电源插座和电源馈线等端点。这个范围很重要：网络线、电源线、控制台线和电路交接都可以进入同一个物理连接模型。

Cable 的状态包括 active、planned 和 decommissioning。planned 适合提前规划变更窗口中的连接，active 表示当前有效连接，decommissioning 表示准备退役或正在迁移。不要把 planned 连接当成已投产连接消费，监控和自动化应按状态过滤。

Cable 的 type 表示物理介质或分类，label 表示现场标签，color 表示颜色，length 表示长度。label 的价值非常高，因为故障处置时现场工程师往往先看线缆两端标签，再对照 NetBox。标签应与真实标签一致，而不是为了系统美观重新命名。若现场线缆还没有标签，NetBox 中也应标记为待治理，不要伪造看似完整的编号。

NetBox v4.5 引入 Cable Profile，用于表达更复杂的端点映射，例如多位置直通和 MPO shuffle 等场景。普通单根跳线可以不配置 profile；如果涉及多芯光缆、breakout、MPO/MTP 或一根主干承载多个路径，就要评估 profile 是否能提高追踪准确性。不要用一条普通 Cable 粗略代表一束光纤，再在备注里写“其中第 3、4 芯已用”，那样路径追踪和容量统计都无法可靠工作。

端点选择：接口、穿通端口和电源对象

最简单的连接是两个物理接口之间的 Cable，例如 server01:eth0 到 access-sw01:Ethernet1/1。这种直接连接适合短跳线、同机柜设备或模型初期。但在真实机房中，很多连接会经过配线架、ODF、MDF、楼宇弱电间或托管机房交叉连接。如果仍然把服务器直接连到交换机，NetBox 会隐藏中间设施，故障排查时无法回答“这条线经过哪个配线架端口”。

Front Port 和 Rear Port 用于建模穿通路径。官方 Front Port 文档说明，前端口代表较长路径中的物理连接点，例如 UTP 配线架前面板端口；每个 Front Port 都要映射到同一设备上的 Rear Port。官方 Rear Port 文档说明，Rear Port 表示从一条电缆到下一条电缆的延续，一个 Rear Port 可以有多个 position，用于表达多条路径共享一根多芯或多位置线缆的情况。

配线架不应建成交换机。配线架没有转发能力，它只是穿通或跳接设施。把配线架端口建成接口会误导拓扑判断，自动化可能把它当成网络设备端口。正确方式是把配线架作为 Device，设备类型中定义 Front Port Template 和 Rear Port Template，创建设备实例后得到端口，再用 Cable 连接实际路径。

电源路径也值得进入连接模型。服务器 Power Port 到 PDU Power Outlet、PDU 上游到 Power Feed、关键设备双电源是否接入不同电源路径，这些信息在机房故障中非常关键。控制台路径同理，Console Port 到 Console Server Port 可以帮助设备管理口不可达时快速找到带外入口。

结构化布线的建模粒度

结构化布线建模要在精度和维护成本之间取平衡。最小模型是设备接口直接连接设备接口；中等模型加入同机柜配线架；完整模型加入跨机柜、跨房间、跨楼层的 Rear Port、Front Port 和中间 Cable。选择哪一层，取决于变更频率、现场标签成熟度、故障影响和团队维护能力。

如果配线架只是少量静态跳接，且现场从不按端口级追踪，可以先记录设备到交换机的直接连接，并把配线架信息放到 Cable label 或 description。但对于核心网络、主干光纤、托管机房交叉连接和多租户区域，应建到配线架端口级。否则线路迁移、故障定位和容量规划都缺关键节点。

一个典型服务器接入路径可以这样表达：服务器 eth0 用短跳线连接本柜配线架 Front Port；该 Front Port 映射到同设备 Rear Port；Rear Port 通过主干 Cable 连接网络柜配线架 Rear Port；网络柜配线架 Rear Port 映射到 Front Port；最后用短跳线连接交换机接口。NetBox 路径追踪可以沿这个链路显示完整路径。

对光纤主干，要特别注意“物理光缆”和“业务连接”的区别。一根 24 芯光缆可能承载多个链路，每个链路使用不同纤芯组合。若只建一条 Cable 表示整根主干，再把所有业务都写到备注里，后续很难判断哪些芯已占用。更好的方式是按 NetBox 能表达的端点和 profile 建模，至少把可维护的端口、position、标签和业务关系分开。

NetBox 电缆类型配置路径

Cable Type 和标签规范

Cable Type 不需要追求厂商 SKU 级细节，除非采购、库存或审计确实需要。常见分类可以包括 Cat6/Cat6A、OS2 单模、OM4 多模、DAC、AOC、电源线、console 线、运营商交叉连接等。分类太粗会影响容量和兼容性判断，分类太细会让录入人员选择困难。

颜色规范应与现场一致。数据中心常见做法是单模光纤黄色、多模光纤水蓝或橙色、管理网络蓝色或黄色、电源黑色或红蓝区分 A/B 路。NetBox 中的颜色字段应服务现场识别，不应只作为视觉装饰。若现场颜色没有规范，先不要在系统中制造一个虚假的规范，而应把颜色治理列入后续整改。

标签要短、稳定、可贴在两端。过长的标签虽然在系统里清楚，但现场标签机可能打不下。建议把业务描述放到 description，把物理唯一编号放到 label。例如 C-A01-0421 作为电缆编号，description 写明 srv-web01 eth0 to access-sw01 Eth1/5。这样电缆更换、业务迁移和设备改名时，物理编号仍然稳定。

电路标签和 Cable label 要分开。Circuit ID 是供应商合同或服务标识，Cable label 是本地物理线缆标签，Cross-connect ID 是托管机房或运营商交叉连接编号。把三者混成一个字段会导致故障申告和现场操作都不清晰。

标准电缆类型矩阵

Circuit：供应商线路不是普通网线

官方 Provider 文档说明，Provider 是提供连接服务的实体，既可以是运营商，也可以是 IX、对等互联组织或其他提供连接的组织。每条 Circuit 必须关联 Provider，并且 Circuit ID 在该 Provider 下唯一。这意味着 Circuit ID 不应由内部随意编号替代，供应商工单、合同和 NOC 沟通通常都依赖它。

Circuit 表示物理链路或供应商交付的电路服务。常见类型包括互联网专线、MPLS、以太网专线、波分、云专线接入、托管机房交叉连接等。Circuit Type 用于分类，commit rate 用于记录承诺带宽。电路的业务属性、SLA、合同编号、账期和联系人可以根据组织需要放到 Provider Account、自定义字段、联系人或外部合同系统。

Circuit Termination 表示线路端点。官方文档说明，每条 Circuit 最多有两个 termination，分别是 A 和 Z。任一端可以关联站点、设备接口或 Provider Network；NetBox v4.2 中，Circuit Termination 的 termination 字段替代了旧的 site 和 provider_network 字段。写自动化或导入脚本时要按当前模型处理，不能沿用旧字段假设。

Circuit 在 NetBox 的哲学中表示物理链路，不能有超过两个端点。多点网络不能建成一条有多个站点的 Circuit。官方文档建议把多点拓扑的每一条腿作为独立 Circuit，并把一端终止到 Provider Network。Provider Network 用于表示供应商网络边界，例如一个区域 MPLS 网络，内部细节对 NetBox 用户未知或不重要。

A/Z 端与 Provider Network 的选择

点到点专线通常有明确 A/Z 端。例如北京数据中心到上海数据中心的以太网专线，可以把 A 端终止到北京 Site 或具体电路交接口，Z 端终止到上海 Site 或接口。若两端都在自己管理的站点中，并且交接端口清楚，应尽量把 Circuit Termination 通过 Cable 接到真实设备接口或配线架端口。

互联网接入和 MPLS VPN 经常不是简单点到点。总部站点接入运营商云，多个分支也接入同一运营商云，用户只关心每条接入腿和供应商网络之间的关系。这时 Provider Network 比“虚构一个中心站点”更合适。每个站点到 Provider Network 的接入是独立 Circuit，一端在本地 Site，另一端在 Provider Network。

云专线也可以按这个思路建模。例如本地数据中心到云互联节点的物理专线是一条 Circuit，云侧边界可以用 Provider Network 或根据组织掌握程度建成更具体对象。不要把云内 VPC、VNet、TGW 或虚拟连接全部塞到 Circuit 里；NetBox 的 Circuit 更偏物理和供应商交付边界，虚拟网络可以结合 VPN、IPAM、虚拟化或外部云资产系统管理。

A/Z 端命名不必表达主备。A 和 Z 只是线路端点方向，不应把 A 等同主用、Z 等同备用。主备关系可以通过 description、tag、custom field、circuit group 或业务系统表达。若把方向语义和主备语义混在一起，后续线路切换或供应商变更会产生混乱。

运营商资料如何入库

运营商线路入库前，应收集至少五类资料：Provider 名称和 NOC 联系方式；Circuit ID 或服务编号；Circuit Type 和带宽；A/Z 端交付位置、交叉连接编号、机柜和端口；合同或工单链接。没有这些信息，NetBox 只能记录“有一条线”，但故障申告时仍要翻合同和邮件。

Provider Account 适合记录账户级信息，例如客户号、账单账户、门户账号或合同归属。Provider 对象记录供应商本身，Provider Account 记录与组织之间的账户关系。大型组织可能同一运营商有多个区域账户、多个合同主体或多个事业部账单，把这些信息拆开可以减少申告和费用核对错误。

Cross-connect ID 是托管数据中心非常关键的字段。官方 Circuit Termination 文档也提到，在数据中心环境中，电路常通过本地 cross-connect 交付，记录其 ID 很有价值。这个 ID 往往是向机房或运营商报障时最直接的定位信息。

Port speed 和 upstream speed 用于记录 termination 侧带宽，尤其在电路实际连接接口未完全建模时有用。若已把电路端点通过 Cable 接到设备物理接口，接口 speed、duplex、description、VLAN 和 IP 也应与电路信息互相校验。

从线路到接口的路径追踪

NetBox 的 Cable tracing 可以从任意端点追踪路径。官方文档说明，如果 Cable 连接到 pass-through port，并且对端端口还有另一条 Cable，NetBox 会继续追踪，直到遇到非穿通端点或未连接端点。完整路径会展示给用户，也有 REST API 端点可以提供追踪能力。

这意味着结构化布线建模越准确，路径追踪越有价值。从核心交换机接口出发，可以看到跳线、配线架、主干、远端配线架、服务器或电路终端。若只记录设备之间直接连接，追踪路径当然短，但也失去了真实中间节点。

路径追踪不能替代现场验证。NetBox 追踪的是记录中的期望状态，不能自动证明线真的插在那里。对于关键线路，应通过 LLDP、光功率、接口状态、运营商交付测试、现场照片或抽样巡检验证。NetBox 记录与实际不一致时，必须判断是现场接错、台账未更新，还是发现工具识别错误。

故障处理中，路径追踪最适合回答“影响范围”和“下一步找谁”。例如一条业务链路中断，NetBox 可以显示它经过哪些 Cable、配线架和 Circuit，线路归哪个 Provider，A/Z 端在哪里，NOC 联系方式是什么，是否还有同一 Provider Network 下其他 Circuit。排障人员据此决定先查本地光模块、配线架、托管交叉连接，还是直接向运营商报障。

路径追踪的结果还可以用于变更影响分析。假设要替换一台汇聚交换机，先从该设备所有 active 接口出发追踪连接，可以得到下联接入交换机、服务器、配线架端口、运营商电路和电源路径。这个清单比人工查看端口描述可靠，因为端口描述可能长期未更新，而 Cable 关系至少能暴露哪些对象被系统认为相连。

追踪结果需要分类处理。直接连接到服务器或交换机的路径，通常由网络团队负责；经过配线架和机房主干的路径，需要数据中心或设施团队参与；终止到 Circuit Termination 的路径，可能要联系运营商或托管机房。把路径按责任团队拆开，变更计划才不会只覆盖网络配置而漏掉现场施工。

如果追踪中断，也是一种有效信号。中断可能表示端口确实未连接，也可能表示配线架 Front/Rear 映射缺失、Cable 未录入、端点类型选错或 planned 连接未转 active。治理时不要只修当前故障链路，而应统计中断点集中出现在哪类对象上。如果大量路径断在某一批配线架，说明模板或导入规则存在系统性问题。

典型场景一：同机柜服务器接入

同机柜服务器接入是最小模型。服务器网卡通过短跳线连接到接入交换机接口，Cable 两端分别是 dcim.interface。这种模型适合小规模机房、实验环境或尚未建立配线架端口治理的阶段。它的优点是维护简单，缺点是无法表达真实跳线路径和配线架占用。

建模时应先确认服务器和交换机接口是否已经存在。服务器接口来自 Device Type 或手工创建，交换机接口应与设备配置中的接口名称一致。若服务器有多块网卡，应区分管理口、业务口、存储口和带外口，不要把所有端口都命名为 eth0、eth1 而不标明用途。

Cable label 可以使用现场线缆编号，例如 C-A01-0012。description 中写明业务语义，例如 srv-app01 eth0 to acc-sw01 Ethernet1/15。如果业务迁移导致端口变化，只修改 Cable 端点和 description，不改变物理标签编号，除非线缆本身被更换。

验证时至少检查四项：两个端点都是物理接口；接口所在设备状态为 active 或 staged；Cable 状态与实际连接一致；交换机 LLDP 或 MAC 表能证明服务器确实接在该接口附近。若服务器操作系统无法提供 LLDP，可以结合交换机 MAC 地址表、资产序列号和现场抽样验证。

典型场景二：跨机柜结构化布线

跨机柜连接应该避免直接把服务器接口连到远端交换机接口。真实路径通常经过本柜配线架、机柜间主干、网络柜配线架和交换机短跳线。NetBox 中可以用两个配线架 Device、Front/Rear Port 映射和多条 Cable 表达。

建模顺序建议是：先建配线架 Device Type，包含 Front Port Template 和 Rear Port Template；再在对应 Rack 中创建配线架 Device；然后创建服务器到本柜 Front Port 的 Cable；创建本柜 Rear Port 到网络柜 Rear Port 的主干 Cable；最后创建网络柜 Front Port 到交换机接口的 Cable。这个顺序让路径追踪从服务器一路走到交换机。

不要把每个配线架端口手工零散创建。配线架通常端口数量固定，使用模板可以减少命名错误。端口名称应与面板标签一致，例如 01、02、A01、B01，label 可保留现场别名。若端口模板创建错了，先修模板，再评估已创建设备是否需要补齐或重建。

跨机柜主干的容量治理比单条连接更重要。主干 Rear Port 和 position 可以帮助表达多芯或多对线缆的占用情况。若只记录“机柜 A 到机柜 B 有一根主干”，无法知道哪些端口仍可用。对核心区域，应至少能回答：某两个机柜之间剩余多少可用链路、哪些链路 active、哪些 planned、哪些 decommissioning。

现场施工清单可以从 NetBox 导出：源设备、源端口、源配线架端口、目标配线架端口、目标设备端口、电缆标签、颜色、长度、状态和工单号。施工完成后，运维人员按清单逐项确认，再把 planned 对象切为 active。这样 NetBox 从变更前就参与流程，而不是事后补录。

典型场景三：运营商专线接入

运营商专线接入至少涉及 Provider、Circuit、Circuit Termination 和本地交接端口。若供应商交付到托管机房 DDF/ODF，再由本地跳线接到路由器接口，建议把交接点建成配线架或适当的穿通端口，再用 Cable 连接到路由器接口。这样报障时能看到从路由器到交接点再到 Circuit 的完整关系。

电路的 Circuit ID 应使用供应商编号，例如合同、工单或 NOC 识别的服务号。内部业务名可以放到 description、tag 或 custom field。故障申告时，NOC 通常不认识内部名；费用核对时，财务也依赖供应商编号。把内部名覆盖 Circuit ID 会让跨团队沟通变慢。

双运营商或双线路场景要表达冗余关系，但不要强行用一条 Circuit 表示两条线。主备 MPLS、双互联网专线、双云专线都应是独立 Circuit。业务层面的主备、负载分担或 SLA 关系可以通过标签、Circuit Group、描述或外部系统表达。物理上独立的线，就应该是独立对象。

如果电路一端进入 Provider Network，另一端在本地 Site，说明用户只掌握本地接入腿和供应商网络边界。这对 MPLS、运营商云和互联网接入很常见。不要为了让拓扑看起来对称，虚构一个自己并不管理的远端站点。Provider Network 的意义正是表达“供应商内部网络存在，但细节未知或不重要”。

专线验收可以形成固定检查项：Provider 和 NOC 联系方式是否完整；Circuit ID 是否与交付单一致；Circuit Type 和 commit rate 是否正确；A/Z termination 是否符合交付边界；Cross-connect ID、patch panel 和 port 信息是否能定位现场；本地 Cable 是否连接到真实设备接口；接口 IP、VRF 和 BGP 邻居是否与 IPAM/配置一致。

存量线路迁移方法

很多团队开始使用 NetBox 时，已经有大量存量线路。迁移不应先追求一次性完整，而应按风险分批。第一批选择核心网络、互联网出口、数据中心互联、云专线和生产关键服务器上联；第二批覆盖普通接入链路和机柜内连接；第三批再处理历史线路、低风险测试环境和长期离线设备。

存量资料通常来自 Excel、Visio、运营商合同、工单系统、监控端口描述和现场标签。导入前要判断每个来源的可信度。运营商合同对 Circuit ID 和带宽可信，但对本地端口可能过时；交换机 LLDP 对当前邻居可信，但看不到配线架；现场标签对物理线可信，但可能没有业务语义。多来源比对后再入库。

迁移过程中可以保留“不确定”状态。对于知道线路存在但端点不完整的记录，可以先建立 Circuit 或 planned Cable，并用标签标记需现场复核。不要为了达成 100% 完整率而猜端口。错误连接比缺失连接更危险，因为它会在故障时把人带向错误路径。

批量导入连接时，应先导入基础对象：Provider、Provider Account、Circuit Type、Provider Network、配线架 Device Type、配线架实例和端口。基础对象稳定后，再导入 Circuit 和 Cable。若基础对象和连接同时导入，一旦失败，很难判断是端点缺失、命名不一致还是关系错误。

导入后不要立即宣布完成。应选取每个站点、每类线路和每个供应商的样本做现场验证。对关键线路，验证应包括 NetBox 记录、设备接口状态、LLDP 或邻居关系、运营商交付单和现场标签。抽样发现的问题要回写为规则，例如某供应商交付单中的端口编号实际对应本地 ODF 的另一套命名。

故障处置中的连接证据

连接管理的成败经常在故障中显现。链路 Down 时，第一步不是急着改配置，而是确认故障边界：本端设备接口是否 down，远端是否 down，中间配线架是否涉及近期变更，Circuit 是否属于运营商线路，是否有同 Provider Network 的其他线路同时异常。

NetBox 可以提供故障证据链的骨架。Device 告诉你设备位置和角色，Interface 告诉你端口属性和 IP，Cable 告诉你物理连接，Circuit 告诉你供应商和线路编号，Provider 告诉你 NOC 联系方式，Provider Network 告诉你是否可能是供应商侧区域网络。监控、日志和设备命令提供实时状态，NetBox 提供期望关系。

对运营商报障，信息越结构化越好。故障单中应包含 Provider、Circuit ID、A/Z 端、Cross-connect ID、本地接口、端口状态、最近变更、影响业务和联系人。若这些字段都在 NetBox 或关联工单中维护，报障不会依赖值班人员翻历史邮件。

恢复后要做连接复盘。若故障原因是现场跳线错误，说明变更流程没有强制回写；若原因是运营商线路信息过期，说明 Circuit 资料缺少复核；若原因是台账指向错误端口，说明发现对账或现场抽样不足。复盘结论应转化成数据质量规则，而不是只写在故障报告里。

外包和托管场景还要记录责任边界。自有机房通常能直接维护 Rack、配线架和线缆；托管机房可能只能看到客户侧端口和 cross-connect 编号；运营商骨干内部更不应试图细化。NetBox 模型应停在组织能验证和负责的边界上，边界之外用 Provider Network、Circuit ID、工单链接和联系人表达。这样既不会伪造不可验证的内部路径，也能在故障时快速把问题交给正确团队。

关键链路还应保留最近一次现场核验日期。

连接变更流程

连接变更不应从“改 Cable 对象”开始，而应从变更意图开始。新增连接、迁移连接、替换电缆、退役线路和供应商割接，对数据模型的影响不同。变更申请中至少应包含源端点、目标端点、线路标签、期望状态、变更窗口、回滚方式和验证方法。

新增连接可以先创建 planned Cable 或 planned Circuit。这样变更评审能看到未来状态，现场人员也能按标签预布线。变更完成并验证后，再把状态切换为 active。若变更取消，planned 对象应删除或标记取消，不要长期留在系统中干扰容量判断。

迁移连接要保留前后状态。比如服务器从 access-sw01 Eth1/5 迁移到 access-sw02 Eth1/17，应先记录当前 Cable 和目标 Cable，确认新路径可用，再停用或删除旧 Cable。对关键业务，可以保留旧 Cable 为 decommissioning 一段时间，直到监控和业务确认无误。

线路割接要同时处理 Circuit 和 Cable。运营商可能保持 Circuit ID 不变，只更换本地交叉连接；也可能新开一条 Circuit，再迁移业务并退役旧线路。前者主要修改 termination、cross-connect 或 Cable；后者应新建 Circuit，并在业务切换后把旧 Circuit 改为 decommissioning。不要为了省事直接改旧 Circuit ID，否则历史审计和费用核对会断裂。

退役流程要释放关联资源。Circuit 退役后，相关 Cable、配线架端口、设备接口、IP 地址、监控目标和合同费用都可能需要处理。NetBox 只能表达一部分关系，但可以作为退役清单的起点。退役后仍 active 的 Cable、仍占用接口的旧线路、仍保留告警目标的设备，都是质量报表要发现的问题。

自动化和 API 的边界

连接数据适合自动化读取，不适合无审核自动覆盖。API 可以批量创建 Cable、Circuit、Provider、Provider Network，也可以调用追踪接口或读取端点状态。但物理连接来自现场动作，完全自动写入风险很高。更稳妥的模式是：导入计划连接、生成现场施工清单、变更后采集实际邻居、输出差异报告，由负责人确认后再更新 NetBox。

REST API 写入 Cable 时，需要明确两个端点的对象类型和 ID。由于 Cable 支持多种端点，脚本必须先解析端点对象，例如 dcim.interface、dcim.frontport、dcim.rearport、circuits.circuittermination、dcim.powerport 等。不要只用端口名查找，因为不同设备可以有相同端口名。

批量导入应坚持 dry-run。脚本先输出将创建的 Cable、将更新的状态、找不到的端点、重复标签、类型不匹配和冲突对象。只有通过人工复核后才提交。对连接类数据，错误写入比缺失更危险，因为错误连接会误导排障和变更。

GraphQL 适合读取复杂视图，例如一次查询设备、接口、连接、电路和站点字段，用于生成报表或拓扑展示。REST 更适合标准 CRUD 和脚本写入。不要为了“技术统一”强行只用一种接口，按任务选择即可。

质量检查清单

连接数据的第一类检查是完整性：active 设备关键接口是否有 Cable；核心上联是否记录；PDU 电源是否连接；控制台端口是否连接到 console server；Circuit 是否有 A/Z termination；Circuit 是否有关联 Provider 和 Circuit ID；Provider 是否有 NOC 联系方式。

第二类检查是一致性：Cable label 是否唯一；Cable 状态是否与端点设备状态一致；接口 enabled 状态是否与连接状态一致；planned Cable 是否长期未转 active；decommissioning Circuit 是否仍被监控或业务引用；同一 Provider 下 Circuit ID 是否重复。

第三类检查是可追踪性：关键业务接口能否从设备追踪到配线架或远端设备；运营商线路能否从本地接口追踪到 Circuit Termination；配线架 Front Port 是否正确映射 Rear Port；Rear Port position 是否与真实纤芯或端口一致；跨机房主干是否能显示完整路径。

第四类检查是现场抽样。每月选择核心链路、变更频繁链路、新上线线路、近期故障线路和随机普通链路，核对标签、端点、颜色、长度、配线架端口、运营商交叉连接编号和设备接口状态。抽样结果要回到模型修正，而不是只在巡检表中闭环。

第五类检查是生命周期一致性。planned Cable 是否超过变更窗口仍未处理；decommissioning Circuit 是否仍有 active 业务标签；退役设备是否仍连接 active Cable；退役 Provider Account 是否还有未退役 Circuit；停用 Rack 中是否仍有 active 配线架端口。生命周期不一致通常意味着变更只完成了一部分。

第六类检查是权限和审计。谁可以创建 Provider，谁可以修改 Circuit ID，谁可以删除 Cable，谁可以批量把 planned 改为 active，都应有明确边界。连接对象一旦被错误删除，历史追踪会断裂。对高风险对象，建议通过工单和受控脚本变更，而不是让所有维护人员直接自由修改。

常见反模式

第一，把 NetBox 当 Visio 替代品，只追求画出好看的图，不维护底层对象。第二，用备注字段保存整条线路路径，Cable 和 Port 对象却没有关系。第三，把所有配线架端口建成 Interface，导致自动化误以为它是网络设备。第四，运营商 MPLS 网络建成一个虚假的中心站点，导致多点拓扑表达错误。

第五，Circuit ID 使用内部编号，真正供应商编号只写在合同里。第六，planned 连接长期存在，容量报表无法区分真实占用和计划占用。第七，现场标签和 NetBox label 不一致，排障时两边互相找不到。第八，退役线路只在运营商侧取消，NetBox 中仍 active，监控和费用核对继续引用。

第九，自动发现结果直接覆盖 NetBox。LLDP 能证明某一刻设备邻居关系，但不能证明布线模型、配线架路径和业务意图都正确。发现结果应作为证据，经过规则和人工审核后再转成期望状态。第十，只记录网络线，不记录电源和控制台，真正故障时仍要翻现场照片。

小结

NetBox 的电路图与连接管理应从真实对象出发：Cable 表示直接物理连接，Front Port 和 Rear Port 表示穿通路径，Circuit 表示供应商线路，Circuit Termination 表示 A/Z 端，Provider 和 Provider Network 表示供应商与其网络边界。正确建模后，路径追踪、变更评审、故障定位、容量规划和审计才能依赖同一套数据。

本篇完成后，NetBox 已经不只是设备和地址台账，而是具备物理连接和线路治理能力。下一篇会进入 API 使用，把前面建立的 Site、Device、IPAM、Cable 和 Circuit 对象变成自动化系统可以安全读取、校验和有限写入的数据源。

参考资料