NetBox Custom Fields 深度指南：用自定义字段扩展内置数据模型-北京尧图网络

后端网络数据建模【免费下载链接】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 的自定义字段Custom Fields允许管理员在无需改动核心数据库表结构的前提下为绝大多数对象类型Site、Device、IP Address、Prefix 等追加任意业务属性是 NetBox 中应用最广泛的扩展机制之一。本文以 customfield.md 为核心骨架结合netbox/extras/models/customfields.py模型实现与 custom-fields.md 使用手册逐项讲解自定义字段的全部配置属性、字段类型、生命周期状态、校验规则与底层存储原理帮助读者完整掌握自定义字段的创建、配置与 API/模板消费方式。为什么需要自定义字段向既有模型补充任意属性NetBox 中每个模型在数据库里都是一张独立的表模型的每个属性对应表中的一列。例如 Site 存储在dcim_site表中包含name、facility、physical_address等列。然而现实中的运维数据往往千差万别你可能需要为每台设备关联一个内部工单号、为每个前缀标注所属业务线、为每个租户记录合同到期日……这些需求合法但不通用不适合写进每一个 NetBox 安装都会携带的核心表结构。自定义字段正是为此而生管理员可以在Customization → Custom Fields页面创建自定义字段将其绑定到一个或多个对象类型之后该字段会自动出现在这些对象类型的 Web UI、REST API、GraphQL API、表单、过滤器与导出结果中。从源码角度CustomField 模型定义了全部配置属性是理解本文所有内容的实现基石。自定义字段的底层存储对象旁的 JSON 数据自定义字段的值并非写入各对象表的新列而是以 JSON 形式直接存储在每个对象自身的custom_field_data字段中。这一点在 custom-fields.md 中有明确说明这种设计避免了为扩展属性做复杂的跨表查询读取对象时自定义数据随对象一并返回。模型的serialize()与deserialize()方法customfields.py负责值在存储与 Python 对象之间的转换Decimal 值转为浮点数、日期序列化为 ISO 8601 字符串、对象类型字段存储目标对象的主键多对象字段存主键列表。底层数据操作则通过 PostgreSQL 的jsonb_set/jsonb_extract_path等函数完成见 populate_initial_data 与 rename_object_data。自定义字段的全部配置属性详解以下按 customfield.md 的字段条目逐一展开每个配置项都对应CustomField模型中的一个模型字段括号内给出源码中的实际定义。Model(s)绑定对象类型选择该自定义字段适用的一个或多个 NetBox 对象类型ContentType。模型定义为object_types多对多关系customfields.py。一个字段可以同时绑定多个对象类型绑定后即对所有这些模型生效。注意并非所有模型都支持自定义字段。Name字段内部名称字段的原始名称name用于数据库与 API只能包含字母数字与下划线且不允许出现双下划线__。该名称全局唯一uniqueTrue。如果需要在界面上显示更友好的名称请使用下面的label。Status字段生命周期状态字段的生命周期状态取值为active、provisioning或deletingCustomFieldStatusChoices。该状态由 NetBox 自动维护、不可手工设置仅当字段处于active时才能被使用。状态机制的完整说明见后文字段生命周期一节。Label显示标签可选的人类友好名称label展示在 Web 表单与对象详情页上若未定义则回退使用name。Group Name分组名称为字段指定分组group_name同一对象类型下具有相同分组名的字段会在对象视图的自定义字段面板中归入同一分组标题下。分组名必须完全一致否则会各自成为独立标题。未分组的字段仅按 weight 与 name 排序模型Meta.ordering [group_name, weight, name]见 customfields.py。分组只影响 UI 展示不影响 API 中的自定义数据表示。Type字段类型字段保存的数据类型这是自定义字段最核心的属性必须在以下类型中选择对应 CustomFieldTypeChoices类型描述Text自由文本用于单行Long text任意长度自由文本支持 Markdown 渲染Integer整数可为正或负Decimal固定精度小数4 位小数Boolean真或假DateISO 8601 格式日期YYYY-MM-DDDate timeISO 8601 格式日期时间YYYY-MM-DD HH:MM:SSURL在 Web UI 中显示为链接值受ALLOWED_URL_SCHEMES限制无 scheme 的值如example.com按https处理并存储为绝对 URLJSON以 JSON 格式存储的任意数据Selection从若干预定义候选中选取一个值Multiple selection支持多选的候选字段Object引用object_type指定的单个 NetBox 对象Multiple object引用object_type指定的一个或多个 NetBox 对象其中选择类字段必须绑定一个包含至少两个选项的 choice set对象类字段必须指定 related object type见 clean() 的校验逻辑。Related Object Type关联对象类型仅用于 Object 与 Multiple object 类型字段related_object_type指定该字段所引用的 NetBox 对象类型。该外键使用on_deletePROTECT被引用的对象类型存在关联时不可被删除。Related Object Filter关联对象过滤器同样仅用于对象类字段related_object_filter以 JSON 形式的query_params字典限制可选对象例如{status: active}只允许选择状态为 active 的对象。在表单生成时该字典会作为query_params传入动态选择控件to_form_field。警告此设置仅为便捷性而设不应依赖它来强制数据完整性——它只影响 UI 中可选的候选项并不阻止通过 API 写入非限定值。Weight排序权重数值型权重weight默认值 100用于覆盖按名称的字母序排列。权重较低的字段排在较高字段之前若定义了分组权重在分组上下文内生效。Required必填启用后该字段必须填写有效值对象才能通过校验required。在表单生成时作为required参数传入对应控件。Unique唯一性启用后每个对象类型下每个对象必须为该字段设置唯一值unique。注意布尔型字段无法强制唯一clean() 会拒绝这种组合。Description描述字段用途的简要说明description可选用。设置后会以 Markdown 渲染后显示在表单字段的帮助文本中to_form_field。Filter Logic过滤逻辑定义按自定义字段过滤对象时值的匹配方式filter_logic默认值为 Loose选项描述Disabled禁用对该字段的过滤Loose匹配值的任意出现不区分大小写的子串匹配Exact仅匹配完整字段值举例以red精确过滤只会命中值恰为red的对象而宽松过滤会同时命中red、red-orange、bored等包含该子串的值。在底层过滤器实现to_filter中Loose 对应icontains查找表达式。UI Visible界面可见性控制字段在对象查看页是否显示ui_visible默认 Always选项描述Always查看对象时始终显示默认If set仅当已定义值时才显示Hidden查看对象时不显示适合仅供程序消费、不面向人工用户的字段UI Editable界面可编辑性控制字段在对象编辑页是否可编辑ui_editable默认 Yes选项描述Yes编辑对象时可修改字段值默认No编辑时显示该字段但不可修改只读Hidden编辑对象时不显示该字段注意这两个设置只影响 Web UI对 REST API 与 GraphQL API 没有任何影响——自定义数据总是可以通过两种 API 读写。当ui_editable ! YES时表单字段会被标记为disabledto_form_field。Default默认值新建对象时预填的默认值default可选用必须用 JSON 表达字符串需加双引号如Foo。布尔字段用true/false选择类字段必须取候选项之一。创建带默认值的字段时该默认值会写入所有现存对象但对已存在字段追加默认值不会回填历史对象见 custom-fields.md。默认值需通过字段自身的类型校验clean()。Choice Set候选集仅用于 Selection 与 Multiple selection 字段choice_set指定该字段合法取值所依据的候选集CustomFieldChoiceSet。候选集可以包含 IATA、ISO 3166、UN/LOCODE 等内置基础选项也可自定义 extra choices并支持按字母排序order_alphabetically。候选集可为单个选项定义颜色带颜色的选项在对象详情页上以徽章badge形式渲染见 customfield.md 与 CustomFieldChoiceSet.colors。若选择字段未指定候选集或非选择字段却指定了候选集校验都会失败clean()。Cloneable可克隆启用后克隆现有对象时自动预填该字段的值is_cloneable默认关闭。Nulls First空值排序按该字段排序对象时控制无值null对象排在有值对象之前还是之后nulls_first默认启用null 排前。Minimum / Maximum Value数值上下限仅用于数值型Integer、Decimal字段validation_minimum / validation_maximum可选用分别限定最小/最大合法值Decimal 精度为 4 位小数、max_digits16。非数值字段设置这些值会触发校验错误clean()。Validation Regex校验正则仅用于字符串类字段Text、Long text、URL见 clean()可选用validation_regex。正则定义在保存前会先经过validate_regex校验。建议使用^与$强制整串匹配例如^[A-Z]{3}$将值限制为恰好三个大写字母。校验通过 Pythonre.match执行validate()并同步注入到表单字段的 validators 中。Validation SchemaJSON 校验模式仅用于 JSON 类型字段validation_schema可选定义一份 JSON Schema。非 JSON 字段定义 schema 会被拒绝clean()。字段生命周期Active / Provisioning / Deleting从 NetBox 4.7 起见 custom-fields.md创建带默认值的字段与删除字段都可能涉及重写大量对象的历史数据。当影响的对象数超过BULK_UPDATE_CHUNK_SIZE配置阈值时该工作无法在单个请求内完成NetBox 会将其交给后台任务执行字段状态随之变化状态含义Active字段已生效、可供使用Provisioning默认值正在写入现存对象Deleting字段数据正在从现存对象中移除判断是否需要后台任务的依据是字段所绑定对象类型的对象总数而非实际持有该字段值的对象数因为 NetBox 无法在不全表扫描的情况下统计持有值的对象——这正是该阈值存在的意义custom-fields.md。底层通过_exceeds_inline_limit()以探针计数方式判定customfields.py只查询比阈值多一个主键即可判断避免全表COUNT(*)。关键行为均有源码佐证字段仅在 active 状态存活。provisioning / deleting 期间字段不出现在对象、表单、过滤器与两种 API 中其存储数据只由负责它的任务读写CustomFieldManager.get_for_model 默认只返回 active 字段。provisioning 中的字段仍会向新建对象提供默认值deleting 中的字段数据不参与对象保存与默认值生成DATA_STATUSES (STATUS_ACTIVE, STATUS_PROVISIONING)见 choices.py。非 active 字段在任务运行期间禁止修改配置包括增删绑定的对象类型否则报错provision_data、remove_data、clean()。待删除字段会继续占用其名称直到数据被清除防止新字段继承遗留数据delete()。上述操作依赖运行中的后台 workerrqworker参见后台任务说明。中途失败而滞留在 pending 状态的字段可始终直接删除遗留的 provisioning 字段没有应用内重试入口需要从后台任务队列Admin → System → Background Tasks需 staff 账户重新入队或删除后重建。从字段上解绑对象类型时数据会被立即移除不经过任务在超大表上仍受请求超时限制重命名字段同理。值校验体系类型感知的 validate()无论是通过表单、REST API 还是 GraphQL 写入字段值最终都经过 validate() 的统一校验Text / Long text必须为字符串若定义了校验正则则执行re.match。URL必须为字符串且 scheme 必须被ALLOWED_URL_SCHEMES允许防御javascript:等危险 scheme同样支持正则。Integer必须是整数且在 min/max 范围内。Decimal必须是可解析的小数且满足 min/max。Boolean只能是True/False/1/0。Date / Date time必须是 ISO 8601 格式。Selection必须精确命中候选集之一validate()。Multiple selection必须是全部由合法字符串组成的列表。Object / Multiple object值必须是对象主键或主键列表。JSON若定义了 validation_schema则用 jsonschema 校验。必填字段为空None或时抛出Required field cannot be empty。从表单到过滤器to_form_field() 与 to_filter()to_form_field() 将自定义字段翻译成 Django 表单字段供 Web 表单、批量编辑、CSV 导入、过滤器表单等场景复用Integer →IntegerField带上 min/maxDecimal →DecimalField(max_digits16, decimal_places4)Boolean →NullBooleanField下拉Date/DateTime → 带日期选择控件的字段。Selection/Multiple selection → 基于候选集动态生成选择字段Web 端通过/api/extras/custom-field-choice-sets/{pk}/choices/异步加载选项CSV 导入时切换为 CSV 选择字段。URL →LaxURLField(assume_schemehttps)无 scheme 输入按 https 补齐。Object/Multiple object → 动态模型选择控件把related_object_filter作为query_params传给选择器。to_filter() 则把字段映射为 django_filters 过滤器Text/URL 用MultiValueCharFilterLoose 时加icontains、Integer/Decimal/Object 用数值过滤器、Multiselect 用数组过滤器、Object 用主键过滤器Multi-object 加contains查找。字段过滤目标为custom_field_data__{name}且通过MissingKeyAwareFilterMixin保证否定查询能正确匹配到完全未携带该字段键的对象。消费自定义字段模板与 API在 Jinja2 模板中使用 cf 属性导出模板、Webhook 等特性使用 Jinja2 模板。支持自定义字段的对象通过cf属性暴露自定义数据比直接访问custom_field_data更简洁。例如 Site 模型上名为foo123的自定义字段可写为{{ site.cf.foo123 }}custom-fields.md。通过 REST API 读写通过 REST API 获取对象时所有自定义数据包含在custom_fields属性中。例如一个站点带两个自定义字段{ id: 123, name: Raleigh 42, custom_fields: { deployed: 2018-06-19, site_code: US-NC-RAL42 } }Selection 与 Multiple selection 字段返回{value, label}结构与 NetBox 内置选项字段约定一致该转换由 resolve_selection_value 统一实现REST 与 GraphQL 共享custom_fields: { site_type: { value: datacenter, label: Data Center }, regions: [ {value: us-east, label: US East}, {value: us-west, label: US West} ] }写入时直接传嵌套 JSON且选择字段传原始值而非{value, label}对象{ name: New Site, custom_fields: { deployed: 2019-03-24, site_type: datacenter } }GraphQL API 的custom_fields字段对选择类值同样解析为{value, label}表示。实战要点与注意事项字段名一经确定应保持稳定重命名会触发对现存对象数据的 JSON 键迁移rename_object_data在超大表上可能超时。不要依赖 Related Object Filter 做数据完整性约束——它只过滤 UI 候选。URL 类型字段的 scheme 白名单由ALLOWED_URL_SCHEMES配置控制如需开放自定义协议请参考安全配置。大规模表上的字段创建/删除务必确保rqworker正常运行否则字段会滞留在 provisioning/deleting 状态。自定义字段虽可绑定任意对象类型但并非所有模型都支持创建前请确认目标模型具备自定义字段能力。若需为候选集规划统一的值与颜色映射可参考候选集模型文档与CustomFieldChoiceSet实现customfields.py其支持基于内置基础选项IATA/ISO 3166/UN/LOCODE叠加自定义选项并会阻止删除仍被对象引用的选项。通过合理组合上述属性自定义字段几乎可以承载任意结构化的运维元数据而无需触碰 NetBox 核心表结构——这正是 NetBox 作为网络自动化事实来源source of truth可灵活适配各类组织数据模型的根基所在。赞分享后端网络数据建模【免费下载链接】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 自定义字段Custom Fields完全指南从建模、配置到 REST/GraphQL API 与生命周期管理NetBox 自定义字段Custom Fields完全指南从建模、配置到 REST/GraphQL API 与生命周期管理 NetBox 中的自定义字段后端网络数据建模Revanced-patches完全指南轻松打造个性化YouTube体验的终极补丁集Revanced patches完全指南轻松打造个性化YouTube体验的终极补丁集 Revanced patches 是一套功能强大的补丁集专为打造个性化如何安装Krita Vision Tools从零开始配置AI绘画插件的完整指南如何安装Krita Vision Tools从零开始配置AI绘画插件的完整指南 Krita Vision Tools是一款强大的Krita插件它通过AI技术人工智能AI 应用计算机视觉本地部署图像处理桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

NetBox Custom Fields 深度指南：用自定义字段扩展内置数据模型

相关推荐

iCloud 云同步 Provider 深入解析：Readest 第五大云同步后端的架构、签名与落地实践

PixiEditor 跨平台渲染实战拆解：Skia + Avalonia + Drawie

Spark Connect 开发者指南：连接字符串协议、Proto 消息演进与客户端代码生成

更多资讯

Switch游戏格式转换全攻略：NSCB实现XCI、NSP与NSZ互转

LTspice EMC滤波器仿真：从建模到实测的完整设计流程

Sanic 核心 API 完全指南：cookies、handlers、headers、request、response 与 views 模块源码级解析

Microsoft.Extensions.DependencyModel 完全指南：解析 .deps.json 依赖清单与动态编译实践

STM32CubeIDE安装配置与HAL开发全链路解析

YOLOv11+ByteTrack+单目测距：自动驾驶感知融合实战与踩坑指南

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？