NetBox Module Type Profiles 完全指南用 JSON Schema 为模块类型扩展自定义属性【免费下载链接】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/netboxModule Type Profiles模块类型配置文件是 NetBox 中用于对 模块类型Module Type 进行分类并扩展自定义属性的核心机制每个模块类型可选地挂接一个配置文件而配置文件的属性通过一段 JSON Schema 定义。读完本文你将掌握配置文件的四个字段、JSON Schema 的编写规则与支持的数据类型、配置文件与模块类型的赋值关系以及它在数据校验、REST API、GraphQL、搜索与过滤中的底层实现可以直接在你的 NetBox 实例中落地使用。什么是模块类型配置文件在 NetBox 的设备建模体系中模块Module 是安装在设备模块槽位中的可替换硬件例如机箱交换机中的线卡而 模块类型 则定义了这类硬件的模板厂商、型号、端口模板等。同一个模块类型下面可能还会存在一批规格接近但细节不同的型号——例如同为服务器电源系列却有不同电压、功率、热插拔能力的多个型号。模块类型配置文件ModuleTypeProfile正是为此设计的它按分类维度把模块类型归组并允许通过一段 JSON Schema 为挂接在该配置下的模块类型补充用户自定义属性比如电源的输入电流与电压处理器的时钟频率与核心数硬盘的磁盘类型、容量与转速。配置文件的两个关键特性从设计上就保持了可选模块类型可以不受任何配置文件约束profile字段为空配置文件的schema字段也可以留空。也就是说配置文件可以纯粹作为一个分类机制使用完全不需要引入自定义属性只有当你确实需要为模块类型补充规格参数时才需要定义 schema。配置文件包含哪些字段配置文件是一个标准的 NetBox 组织模型继承PrimaryModel参见 模块模型源码包含以下字段字段必填说明Name是配置文件的唯一名称例如Power Supply或Disk。模型中通过uniqueTrue保证全局唯一长度上限 100 字符Description否对配置文件的简要描述长度上限 200 字符Schema否定义挂接该配置的模块类型可设置或必须设置属性的 JSON Schema必须是合法的 JSON Schema否则为nullComments否关于配置文件的自由格式备注支持 Markdown 渲染Owner归属否与 NetBox 的资源所有权功能集成可选Tags标签否标准的 NetBox 标签支持说明Name与Schema定义在ModuleTypeProfile模型自身netbox/dcim/models/modules.py#L95-L105而Description、Comments、Owner、Tags 等来自PrimaryModel基类。此外clone_fields (schema,)表明新建配置文件时可以直接克隆现有配置的 schema。用 JSON Schema 定义模块类型属性配置文件的核心价值在于Schema字段。下面这段官方示例为模块类型定义了三个属性其中type与capacity被标记为必填{ properties: { type: { type: string, title: Disk type, enum: [HD, SSD, NVME], default: HD }, capacity: { type: integer, title: Capacity (GB), description: Gross disk size }, speed: { type: integer, title: Speed (RPM) } }, required: [ type, capacity ] }写入 Schema 字段时NetBox 会通过validate_schema校验器netbox/utilities/jsonschema.py#L165-L180做基础合法性检查schema 必须是 dict 类型并调用jsonschema.validator_for(schema).check_schema(schema)验证其本身符合 JSON Schema 规范空值None或空字符串被直接放行。支持的数据类型与约束从JSONSchemaProperty的实现netbox/utilities/jsonschema.py#L64-L162可以看出配置文件 schema 中的每个属性会被动态映射成对应的 Django 表单字段实际支持以下能力JSON Schema 关键字支持的取值映射到的表单行为typestring/integer/number/boolean/array/object分别映射为文本、整数、浮点、布尔、数组、JSON 字段title任意字符串作为表单字段的 label缺省时由属性名自动标题化description任意字符串作为表单字段的 help text经 Markdown 渲染default任意合法值作为表单初始值enum值列表渲染为下拉选择框ChoiceField数组属性的items.enum渲染为多选formatemail/uri/iri/uuid/date/time/datetime映射到对应语义的 Django 表单字段minLength/maxLength/pattern数字 / 正则字符串长度校验与正则校验minimum/maximum/multipleOf数字数值范围与倍数校验required属性名列表对应字段在表单中必填也就是说你写的每一段 schema 都会在 NetBox 的模块类型编辑表单中被翻译成真实的输入控件——enum变成下拉框、boolean变成勾选框、description变成帮助文案属性定义与表单输入体验一一对应。内置配置文件开箱即用的 8 类硬件规格NetBox 在数据库迁移阶段就预置了 8 个面向常见硬件的配置文件迁移 0206_load_module_type_profiles.py对应的 schema 存放在 netbox/dcim/migrations/initial_data/module_type_profiles/配置文件内置属性节选CPUarchitecture架构、speed时钟频率GHz、cores核心数Fan风扇转速等规格GPU显卡规格Hard disktypeHD/SSD/NVME默认 SSD、size容量 GB必填、speed转速 RPMMemory内存规格Power supplyinput_currentAC/DC默认 AC、input_voltage电压默认 120、wattage输出功率、hot_swappable热插拔默认 falseExpansion card扩展卡规格Transceiver光模块/收发器规格以 hard_disk.json 和 power_supply.json 为例可见默认值与必填项的编写方式与前面官方示例完全一致。这些内置配置文件可以让常见硬件分类开箱即用也为你编写自定义 schema 提供了贴近实战的参考模板。配置文件如何与模块类型联动配置文件的挂接关系定义在ModuleType模型上netbox/dcim/models/modules.py#L125-L171profile外键指向ModuleTypeProfileon_deletePROTECT——被模块类型引用中的配置文件不可直接删除attribute_dataJSON 字段用于存储该模块类型实际填写的属性值ModuleType.Meta.ordering (profile, manufacturer, model)模块类型列表默认按配置文件分组排序。赋值之后属性的校验发生在模型清理阶段。ModuleType.clean()netbox/dcim/models/modules.py#L292-L302的逻辑是if self.profile and self.profile.schema: try: jsonschema.validate(self.attribute_data, schemaself.profile.schema) except JSONValidationError as e: raise ValidationError(_(Invalid schema: {error}).format(errore)) else: self.attribute_data None即只要模块类型挂接了带 schema 的配置文件其attribute_data就必须通过jsonschema.validate()的校验必填项缺失、类型不符、枚举越界等都会报错若配置文件或 schema 为空attribute_data会被强制置空。相关测试见 netbox/dcim/tests/test_models.py 与 netbox/dcim/tests/test_forms.py后者还验证了属性描述经safe过滤器渲染为帮助文案时的 HTML 净化。展示层面ModuleType.attributes属性netbox/dcim/models/modules.py#L252-L266会把attribute_data按 schema 的properties顺序整理成人类可读的键值对键优先取title数组/列表值会被拼接成以逗号分隔的字符串最终按键排序返回——模块类型详情页和列表页的Attributes列ModuleTypeProfileTable.attributes见 netbox/dcim/tables/modules.py展示的就是这份数据。实际操作路径在 NetBox 中完整使用配置文件的工作流如下创建配置文件在 DCIM 模块类型配置文件中新建记录填写唯一名称可选填写描述在 Schema 字段粘贴一段合法 JSON Schema也可留空仅作分类使用编辑模块类型在模块类型表单中从下拉框选择该配置文件表单会自动渲染出 schema 定义的属性输入控件按需填写属性值保存校验提交时clean()触发 JSON Schema 校验必填项缺失或格式不符会直接阻止保存查看与维护在模块类型列表/详情页查看属性列配置文件支持克隆、批量导入ModuleTypeProfileImportForm、批量编辑与批量重命名对应视图见 netbox/dcim/views.py#L1813-L1902。通过 REST API 管理配置文件暴露了完整的 REST APIModuleTypeProfileViewSet见 netbox/dcim/api/views.py#L294-L297序列化字段包括id、url、display、name、description、schema、owner、comments、tags及创建/更新时间netbox/dcim/api/serializers_/devicetypes.py#L87-L93。REST API 也支持按profile、profile_id以及动态属性attr_*过滤模块类型例如查询attr_speed2.4。通过 GraphQL 查询配置文件在 GraphQL 中同样可查ModuleTypeProfileTypenetbox/dcim/graphql/types.py#L774-L780暴露fields__all__并关联反向的module_types列表配合 ModuleTypeProfileFilter 支持按名称及 lookup 条件过滤。搜索与过滤全局搜索ModuleTypeProfileIndexnetbox/dcim/search.py#L270-L276索引name、description、comments三个字段加权依次为 100 / 500 / 5000列表过滤ModuleTypeProfileFilterSetnetbox/dcim/filtersets.py#L862-L867支持id、name、description等标准过滤过滤表单还提供标签与归属过滤netbox/dcim/forms/filtersets.py#L754-L759对应测试见 netbox/dcim/tests/test_filtersets.py#L1845-L1901。深入阅读模块类型模型本身Module Type 文档模块实例化后的硬件单元Module 文档相关硬件建模模型Device Type 文档、Module Bay Type 文档模型源码netbox/dcim/models/modules.pyJSON Schema 校验与表单映射实现netbox/utilities/jsonschema.py内置配置文件的初始数据netbox/dcim/migrations/initial_data/module_type_profiles/小结模块类型配置文件把硬件分类与规格扩展两个诉求统一到一处分类用名称即可规格扩展则交给标准 JSON Schema。借助 NetBox 对 schema 的表单化渲染、模型层jsonschema.validate强校验以及 REST API / GraphQL / 搜索过滤的全面覆盖你可以在不写代码的前提下为电源、CPU、硬盘、光模块等各类硬件维护结构化的规格数据为后续的网络自动化与配置编排提供准确、可信的数据源。【免费下载链接】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），仅供参考