这篇文章里的所有内容,都是在我自己桌上的一套 NetBox 4.7.2 上跑出来的,里面装着一整套真实资产:一个站点、一个机柜、十四台设备,接好了线、通好了电、分好了地址,分属三个客户。每张截图都来自这套实例,每条错误信息都是我真遇到过的。

内容按你实际碰到它的顺序展开。这东西是什么,你为什么想要一套,你搜索不出一个星期就会听说的那次分叉,怎样搭起一套,必须按什么顺序录入,然后你能从里面拿回什么。定制和扩展的部分放在最后,因为在你看清要扩展的东西长什么样之前,那些内容都说不通。

NetBox 是什么

NetBox 是一个数据库,它对网络由什么构成有一套非常明确的看法,上面再加一个 Web 应用。它是跑在 PostgreSQL 上的 Django 应用,自 2016年6月 DigitalOcean 发布以来一直以 Apache 2.0 许可开源,如今由 NetBox Labs 和一支志愿维护者团队共同管理。12

往下看,它是分布在十个应用里的 149 个模型,通过 146 个 REST 端点和一个 GraphQL 端点访问。这些数字是从我为这篇文章搭建的实例里数出来的,不是从功能介绍页上抄的:

应用模型数应用模型数
dcim56virtualization7
extras23tenancy6
ipam18wireless3
circuits11users7
vpn10core8

其中五十六个属于 DCIM,也就是物理层:站点、位置、机柜、设备类型、设备,以及设备可能拥有的每一种端口、槽位和线缆端接。十八个属于 IPAM。其余的覆盖线路、隧道和 IKE 策略、虚拟机和集群、无线链路、租户,以及让整个系统可扩展的那套机制。

数量不是重点。重点是它们之间的关联,而看清这一点最快的办法,就是 NetBox 最出名的那个页面。

从机柜开始,因为这个页面最能把它卖出去。

NetBox 中 MCR1-A07 的机柜详情页:左侧显示区域 North West、站点 Manchester DC1、位置 Hall 2、状态 Active、空间利用率 28.6%;右侧是前后立面图,列出 U41 和 U42 的配线架、U38 和 U39 的两台路由器、U35 和 U36 的两台交换机,以及 U15 到 U20 之间的六台虚拟化主机,每台都按角色着色

这张立面图是从数据画出来的,不是上传的图片。每台设备之所以出现在那里,是因为有记录说它占用了那几个 U、朝那个方向,颜色来自你给它分配的角色。空间利用率显示 28.6%,是因为 NetBox 算出来的。没有人去维护这个数字。

由此引出的两件事,比这张图本身更值钱。

你可以问哪些 U 是空的,并得到一个能直接拿来用的答案。你还可以在任何东西装进去之前预留这些 U,这就是“卖你真有的空间”和“卖你以为有的空间”之间的区别。

它刻意不做的事

一个清楚自己不是什么的产品,比一个什么都做却什么都做不好的产品要少见得多,而 NetBox 自己的文档在这一点上说得很直白。它不提供网络监控、DNS 服务、RADIUS、配置管理或设施管理。1

更重要的是,它保存的是你网络的期望状态,而不是运行状态,文档还说自动导入实时网络状态是“strongly discouraged”(强烈不建议的),因为每一条记录都应该先经过人工审核。1

其他一切都建立在这个决定之上,也正是这个决定招来最多争论。争论是这样的:真相来源难道不该就是真相吗?那就去发现网络,把结果导进来。回答是:发现出来的网络告诉你那里有什么,而那里有的东西包括任何人犯过的每一个错误。2021 年留在错误 VLAN 里的一个交换机端口是一个事实。它不是一个意图。

NetBox 保存意图。你的监控系统保存现实。真正有意思的数字是两者之间的差,而你没法只用一个输入算出差值。

另一条原则同样说得很直白:在一个相对简单、能解决百分之八十问题的方案和一个复杂得多的完整方案之间,选简单的那个。1 你第一次想建模某个它不支持的东西时就会体会到这一点,文章快结尾的地方有一整串章节讲碰到这种情况时该怎么办。

NetBox 做的NetBox 不做的
记录应该在那里的东西轮询实际在那里的东西
保存某个端口应有的 VLAN告诉你这个端口挂了
说明某个前缀属于哪个客户向客户收费
用模板渲染设备配置把配置推到设备上
跟踪线路、运营商和承诺带宽监控线路
说明设备在哪个机柜、哪个 U打开机柜门

把右边那一栏当成你仍然需要的工具清单来读。读错了,你就会想把 NetBox 变成所有这些工具,而真相来源就是这样变成又一个没人信任的系统的。

你为什么需要一套

问一家托管服务商(MSP),某个客户网络的权威记录放在哪里,你会得到一个答案。分别去问他们的两个工程师,你会得到两个答案。

一个会指着一张电子表格。一个会指着一张网络图,最后一次保存它的人 2023 年就离职了。还有人会说防火墙配置就是文档,这话至少诚实,因为配置确实描述了一台设备在干什么。只是它没说为什么,没说是谁要求的,也没说那台设备后面的四个客户里,到底是哪一个在为这条规则付钱。

出问题从来不是在你发现记录错了的那天。而是在有人需要它的那天。

时刻你必须拿出来的东西拿不出来的代价
续约谈判一份逐项列明月费到底买了什么的清单竞争对手的报价是逐项列明的,因为他们真的去数过
有工程师递了辞呈他知道的一切,写下来六个月的摸索,一张工单一张工单地发现
有客户要走一份对他们自己资产的描述三周时间去拼凑,外加一个他们会如实给出的评价
审计员问范围问题哪些系统存有个人数据,它们物理上在哪告诉了监管机构一些后来被证明不属实的话
一次迁移需要报价实际在那里的东西的数量你按估算报价,差额自己吞

这些都不稀奇。它们就是平常的某个星期二。

你从中得到的不是文档。文档是你写完之后就不再维护的东西。你得到的是一个拒绝容纳矛盾的数据库,它能回答没人事先想到要问的问题。这篇文章后面有一个机柜,结果发现设备只装了 28.6%,电力却用了 90.7%。没有人专门去找这件事。它只是因为有人在一个设备类型上填过一次功率,就自己冒了出来。

老实的提醒也一并奉上,最后一节讲的就是这个。一份记录的价值,只等于你为保持它正确所付出的成本。但另一种选择是一个连自己都描述不清的企业,而第一个发现这一点的,通常是客户。

另一个:Nautobot

你搜索不出一个星期就会碰到它,所以值得知道当时发生了什么。

2021 年,Network to Code 分叉了 NetBox,把结果叫做 Nautobot。不是软分叉,也不是一个发行版:是一个已经分道扬镳五年的硬分叉。它自己的 v1.0 发布说明把它描述为“a divergent fork of NetBox 2.10”(NetBox 2.10 的一个分歧分叉),代码仓库创建于 2021年2月19日,v1.0.0 于 2021年4月26日发布。3

他们陈述的理由就在他们自己的博客上,值得读他们的原话,而不是我的转述。推动这件事的有三点。他们想卖企业级支持:“We need to offer high-touch support models with Service Level Agreements (SLAs) we can guarantee. We need flexibility to offer Long-term Support (LTS) for customers who can’t upgrade at the pace of a fast moving open source project.”他们想让真相来源处在一个自动化平台的中心,而不是只为文档服务。还有,“there became a growing divergence in our vision about what a Source of Truth for networking should look like and how to get there”。4

第一条理由需要标上日期,因为它已经不成立了。2021年2月,NetBox 背后没有任何公司能卖给你东西。NetBox Labs 直到 2023 年才成立,是在 IBM 收购 NS1 之后从 NS1 分拆出来的,联合创始人之一就是 NetBox 自己的首席维护者。5

而且它不是一个靠别人的项目做起生意的第三方。NetBox Labs 是 NetBox 的管理方:项目自己的文档写着“the open source project is stewarded by NetBox Labs and a team of volunteer maintainers”。1 他们为自行管理的部署销售 NetBox Enterprise,以 NetBox Cloud 的形式替你托管,并提供 7×24 支持。6

所以,“你买不到 NetBox 的支持”这句话,在 Network to Code 分叉的时候说是公道的,现在再说就不公道了。两个项目背后都有一家愿意签合同的商业公司,而在 NetBox 这边,那家公司就是项目的管理方。

大多数人漏掉的是下一句,而正是这一句让这件事不是一个龌龊的故事:“the NetBox project team suggested that we should consider forking.”(是 NetBox 项目团队建议我们考虑分叉。)

一次分叉能做到的文明程度,也就到这儿了。两拨人想要不同的东西,在很长一段时间里把话说开了,然后分开,而不是在同一套代码上打架。两边都还是 Apache 2.0。没有人拿走任何他们无权拿走的东西。

这次分叉到底是为了什么

Nautobot 1.0 的发布说明列出了它相对 NetBox 2.10 增加了什么,这份清单比任何博客文章都更能说明这场争论:3

Nautobot 在 2021 年增加的NetBox 现在的情况
GraphQL 支持NetBox 已经有了
以 Git 集成作为数据源NetBox 已经有了,叫同步数据源
单点登录NetBox 已经有了
密钥管理(Secrets)NetBox 通过插件提供
脚本和报表合并为 JobsNetBox 在 4.7 中正把脚本移到一个插件里
所有模型都支持自定义字段NetBox 有广泛的自定义字段支持
数据校验插件 APINetBox 有自定义校验规则
可定制的状态,作为数据库对象NetBox 的状态仍然是 Python 选项集
用户自定义的模型间关系NetBox 没有对应功能
UUID 主键NetBox 用整数主键
插件 API 增强NetBox 的插件框架此后已经成长了很多

上半部分大多已经趋同。Nautobot 在 2021 年推出的好几样东西,后来都出现在了 NetBox 里,两个项目在公开场合解决同样的问题时,通常就是这样。

下面三项没有趋同,而且它们是架构层面的,不是表面功夫。我今天亲自查了两边的代码,而不是相信 2021 年的发布说明。

Nautobot 的 Status 是一个数据库模型,它自己的源码里描述为“Model for database-backend enum choice objects”,所以一个状态就是一行数据,任何人都能在界面里添加。NetBox 的状态来自 Python 选项集,所以下面 FIELD_CHOICES 那一节加一个状态,要靠编辑 configuration.py 再重启。Nautobot 有 Relationship 和 RelationshipAssociation 模型,所以你可以不写代码就在两个现有对象类型之间定义关系。NetBox 对这个问题的回答是插件,下面还有一串专门讲它的章节。另外,Nautobot 的主键是 UUID,而 NetBox 的是整数。

他们也确实做到了分叉时想做的事。到今天为止,Nautobot 在同一天发布 3.2.x 和 2.4.x,这是一条货真价实、与当前版本并行的长期维护线,而这正是当初陈述的三个理由之一。

选哪个

先看老实的数字。NetBox 有 21,625 个 star 和 3,133 个 fork;Nautobot 有 1,617 和 422。7 两者都在最近两天内有过推送,都是 Apache 2.0,现在背后也都有一家商业公司在卖支持和托管。

这个差距不是对质量的裁决。它反映的是五年的先发优势,以及大多数需要真相来源的人先找到的是 NetBox。但它确实决定了那件通常比功能更要紧的事:你选的那个,能找到多少插件、集成、Ansible 模块、论坛答案和同行。

所以:如果你要的是一份清单,一个供其他系统读取的真相来源,还想要最大的生态和最容易招到人,答案是 NetBox,这篇文章剩下的部分讲的也就是它。如果你想要真相来源的理由,明确就是要用它来驱动自动化,或者你希望状态和关系由你的团队来定义,而不是靠一个配置文件加一次重启,那就在做决定之前好好看看 Nautobot。

别让任何人光凭支持就把其中哪一个卖给你。现在两边都有支持了,而五年后依然存在的差别,就是上面那张表里的那些。

你不该做的,是因为有人告诉你另一个已经死了就选这一个。两个都没死,这个星期两边都还在发布新版本。

把它跑起来

两条路,为了写这篇文章我两条都走了一遍。想二十分钟内跑起来就用容器;如果它要承担关键业务,就在主机上用软件包装。

容器栈

社区维护着 netbox-docker,这是最快的答案:8

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<'EOF'
services:
  netbox:
    ports:
      - 8000:8080
EOF
docker compose pull
docker compose up

这样你就得到应用、PostgreSQL、Redis 和一个后台工作进程,全都连好了。我在 podman 下手工搭了一套一样的,好看清楚各个部件,而这些部件值得了解,因为其中两个会坑人:

容器做什么如果你漏掉它
netbox跑在 gunicorn 后面的 Django 应用什么都不工作
postgres数据库,15 或更高版本什么都不工作
redis / valkey两个数据库:一个放任务,一个做缓存什么都不工作
netbox-workerrqworker,负责消费任务队列webhook 永远不触发,后台任务永远不运行,而且没有任何警告
netbox-housekeeping定期清理变更日志记录永不过期

关键就是第四行。没有工作进程,一切看起来都很健康。事件规则排进队列,然后就停在那儿。

第一次运行时有两件事咬了我,而且两件都不会出现在你会去搜索的错误信息里。

第一次迁移要花很长时间。 不是一分钟。在这台机器上是好几分钟,因为 NetBox 4.7 用 PostgreSQL 的 ltree 替换了 django-mptt,迁移过程中会重建每一张层级表。容器就那么待着应用迁移。别去动它。

没有 API_TOKEN_PEPPERS 就没法创建 v2 API 令牌,唯一的迹象是日志里的一条警告:

UserWarning: API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.

至少设一个,长度至少五十个字符,然后再去查 API 为什么拒绝你。

在主机上,用软件包装

官方文档的路线是在 Ubuntu 24.04 上测试过的。我在一台干净的 24.04 上从头跑到尾,最后得到的是这些:

组件24.04 给我的版本NetBox 4.7 需要的版本
PostgreSQL16.1515 或更高
Redis7.0.156.0 或更高
Python3.12.33.12、3.13 或 3.14
Django6.1.1随 NetBox 一起提供
NetBoxv4.7.2

这些最低要求是 NetBox 自己定的,4.7 同时提高了 PostgreSQL 和 Redis 的下限。9

整个过程就五步。

# 1. the services
sudo apt install -y postgresql redis-server
sudo -u postgres psql -c "CREATE DATABASE netbox;"
sudo -u postgres psql -c "CREATE USER netbox WITH PASSWORD 'something-you-generated';"
sudo -u postgres psql -c "ALTER DATABASE netbox OWNER TO netbox;"
sudo -u postgres psql -d netbox -c "GRANT CREATE ON SCHEMA public TO netbox;"

# 2. the build dependencies
sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential   libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev git

# 3. the application, at a release tag rather than at main
sudo mkdir -p /opt/netbox && cd /opt/netbox
sudo git clone https://github.com/netbox-community/netbox.git .
sudo git checkout v4.7.2
sudo adduser --system --group netbox
sudo chown -R netbox /opt/netbox/netbox/media/ /opt/netbox/netbox/scripts/ /opt/netbox/netbox/reports/

# 4. the configuration: five values, no more
cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py
python3 /opt/netbox/netbox/generate_secret_key.py   # run it twice
sudo $EDITOR configuration.py

# 5. let the upgrade script do the rest
sudo /opt/netbox/upgrade.sh

那五个值是 ALLOWED_HOSTS、DATABASES、REDIS、SECRET_KEY 和 API_TOKEN_PEPPERS。最后两个要分别生成,不要一个当两个用。也就是说,密钥生成器跑两次,把结果粘到不同的行里。

upgrade.sh 会建好虚拟环境,装好所有 Python 依赖,跑迁移,构建离线文档,收集静态文件。在一台新机器上跑完时,它会打印一条看着吓人、其实没事的警告:

WARNING: No existing virtual environment was detected. A new one has
been created. Update your systemd service files to reflect the new
Python and gunicorn executables. (If this is a new installation,
this warning can be ignored.)

然后建一个超级用户,它就跑起来了:

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox && python3 manage.py createsuperuser

凡是正经用途,都应该在前面放 gunicorn,而不是用 runserver。配置文件和 unit 文件已经在仓库里了,这个细节值得知道,因为很多人会自己去写:

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbox netbox-rq

netbox.service 在 127.0.0.1:8001 上跑 gunicorn,netbox-rq.service 跑工作进程,前面再放 nginx 或 Apache 来终结 TLS 并提供 /static。两个服务,第二个就是容器栈里需要的那个工作进程。

必须按什么顺序录入

一套全新的 NetBox 是一个带着主见的空数据库,用它的头一个小时,通常都花在弄清这些主见是什么上。你去添加一台设备,它不让你加。

NetBox 的添加新设备表单:Device 标题下有 Name、标了红色星号的 Device role、Description 和 Tags,然后 Hardware 下是同样标了红色星号的 Device type,接着是 Serial number、Asset tag、Cooling method 和 Airflow

那些红色星号就是全部的教训。NetBox 不会在一样东西所依附的东西存在之前记录它,这不是故意刁难:一台没有类型的设备,是一行回答不了任何设备该回答的问题的数据。

所以我没有去猜,而是问了模型哪些外键真正是必填的,然后通过 API 逐条去破坏这些规则,看看会返回什么。

POST /api/dcim/device-types/   no manufacturer
  {"manufacturer": ["This field is required."]}
POST /api/dcim/devices/        no device type
  {"device_type": ["This field is required."]}
POST /api/dcim/interfaces/     no device
  {"device": ["This field is required."]}
POST /api/ipam/aggregates/     no RIR
  {"rir": ["This field is required."]}
POST /api/circuits/circuits/   no provider, no type
  {"provider": ["This field is required."], "type": ["This field is required."]}
POST /api/virtualization/virtual-machines/   nothing at all
  {"__all__": ["A virtual machine must be assigned to a site, cluster, or device."]}

每一次都被拒绝了,而且准确地说出了缺的是什么。下面是把同样的信息整理成一份前置条件清单:

要创建必须先有可选,但你最好先建
Tenant(租户)无一个 Tenant group
Region、Site group无同类的上级,它们可以嵌套
Site(站点)无一个 Region、一个 Site group、一个 Tenant
Location(位置)一个 Site一个上级 Location、一个 Tenant
Rack type一个 Manufacturer
Rack(机柜)一个 Site一个 Location、Rack group、Rack role、Rack type、Tenant
Device type一个 Manufacturer
Device role无一个上级 Device role,它们可以嵌套
Device(设备)一个 Device role、一个 Device type、一个 Site一个机柜及位置、一个 Platform、一个 Tenant
Interface,以及所有其他组件一台 Device
Cable(线缆)两个可端接的东西一个 Tenant
Aggregate一个 RIR一个 Tenant
VLAN无一个 VLAN group、一个 Role、一个 Tenant
Prefix(前缀)无一个 Site、一个 VLAN、一个 Role、一个 VRF、一个 Tenant
IP address无一个可分配的 Interface、一个 Tenant
Circuit(线路)一个 Provider 和一个 Circuit type一个 Tenant
Circuit termination一条 Circuit一个落地的 Site
Cluster(集群)一个 Cluster type一个 Cluster group、一个 Site、一个 Tenant
Virtual machine一个 Site、一个 Cluster 或一台 Device一个 Platform、一个 Tenant
VM interface一台 Virtual machine

让你付出代价的是第二栏。前缀、IP 地址、VLAN 和租户什么都不需要,所以第一天就可以按任意顺序创建它们,没有任何东西拦着你。它们有没有用是另一个问题,因为一个后面没有接口的地址只是列表里的一行,而一台没有租户的设备,是你以后还得回头再改的设备。

实际干活的顺序

由此得出一个顺序。照着往下做,就永远不会被拒绝。

首先,是其他一切所依附的东西。 这些都不激动人心,而且都很容易弄错,弄错的代价却很低。

  1. 先租户组,再租户。 在其他一切之前做这个。有二十八个模型带租户字段,包括 Site、Location 和 Rack,所以如果客户还不存在,你就没法边建边打上标记,以后只能批量编辑。
  2. 区域和站点组。 两者都可选,都能自我嵌套,而且彼此独立。区域按地理划分,站点组按功能划分,你可以用其中一个、两个都用,或者都不用。
  3. 站点。 几乎一切的根。站点什么都不需要,所以它是你真正能创建的第一样东西。
  4. 位置。 位置需要站点,而且可以嵌套,所以一个机房里有若干排、每排里有若干 pod,就是一个模型套三层。
  5. 机柜角色和机柜组。 两者都可选。机柜组是扁平的,作为第二条轴和位置并列,用来表示排和 pod 很方便。
  6. 先厂商,再机柜类型。 机柜类型需要厂商。如果你不对机柜本身建模,就跳过机柜类型。
  7. 机柜。 机柜需要站点。如果你还给它指定了位置,那个位置必须属于那个站点,NetBox 会检查。

然后是硬件目录,而不是硬件本身。 在你能添加哪怕一台设备之前,你需要厂商、设备类型、设备角色,以及实际上还需要平台。

  1. 厂商。 你可能在第 6 步已经建了一些,因为机柜类型也需要它们。模块类型同样需要。
  2. 设备类型,每个都需要一个厂商。
  3. 设备角色(可嵌套),以及平台。

这是大家会跳过的一步,而正是这一步决定了后面的活要敲多少字。设备类型以模板的形式带着自己的接口、端口和槽位,所以你用它创建的每台设备,一到位就已经带好了正确的组件。类型弄对一次,上架四十台就只是敲四十个名字。

平台是这份清单里的异类,因为设备严格来说并不需要它。还是现在就做。以后承载配置模板和 NAPALM 驱动的就是它,回头再给整套资产补上平台,花掉的会是你本来要花在租户上的同一个晚上。

然后是设备本身。

  1. 设备。 角色、类型和站点都是必填的。机柜和位置可选,如果填了,就必须和站点一致。
  2. 组件,如果设备类型没有自带的话。
  3. 线缆,连接在组件之间。

然后是地址分配,因为地址需要一个接口来落脚,而接口要到第 12 步之后才存在。

  1. RIR,然后是聚合(aggregate)。
  2. 前缀和 VLAN 角色、VRF、VLAN 组,然后是 VLAN。
  3. 前缀,然后是单个的 IP 地址。

然后是商务层。

  1. 运营商、运营商账户和线路类型。
  2. 线路,然后把它们端接到站点上。

还有虚拟资产,它和物理资产是镜像关系。

  1. 集群类型和集群组,然后是集群。
  2. 虚拟机,需要一个站点、一个集群或一台设备,然后是它们的接口。

第 1 到第 10 步是一个下午的活,感觉像行政杂务。里面一点光鲜的东西都没有。但正是这个下午,决定了第 11 步要花一个上午还是两个星期。

以后才会咬人的规则

必填字段是容易的那一半,因为它们立刻失败,并告诉你原因。真正把人绊倒的是一致性规则,只有当你的数据多到足以自相矛盾时,它们才会触发:

device at Leeds, put in a Manchester rack
  {"rack": ["Rack MCR1-A07 (A07) does not belong to site Leeds Edge."]}
device at Leeds, in a Manchester location
  {"location": ["Location Hall 2 does not belong to site Leeds Edge."]}
rack at Leeds, in a Manchester location
  {"__all__": ["Assigned location must belong to parent site (Leeds Edge)."]}
a second device in a unit that is already taken
  {"position": ["U39.0 is already occupied or does not have sufficient
                 space to accommodate this device type: MX204 (1.0U)"]}

如果有人问我何必费这些劲,我会指着最后那一条。NetBox 知道这台设备是 1U,知道机柜里有什么,不会让你在同一个空间里记录两样东西。你的电子表格会让你这么干一整个下午,一声不吭,等你发现的时候,已经有人抱着箱子站在机房里了。

这些规则都不可配置,也都不应该可配置。它们就是“记录”和“愿望”之间的区别。

用起来:每个页面给你什么

资产录进去之后,下面是你实际能从里面拿回的东西。下面所有内容都来自同一套实例:一个机柜、十四台设备,分属三个客户,接好了线、分好了地址。

设备就是它的组件

点进其中一台虚拟化主机,有意思的标签页不是概要,而是接口。

NetBox 中设备 mcr1-hv-01 的接口标签页,显示三个接口:eno1,SFP28 25GE,描述为 to leaf-01,IP 地址 10.20.20.11/24,线缆 MCR1-DAC-0001A 连接到 mcr1-leaf-01 的 Ethernet1;eno2,SFP28 25GE,to leaf-02,线缆 MCR1-DAC-0001B 连接到 mcr1-leaf-02 的 Ethernet1;以及 ipmi,1000BASE-T,描述为 BMC,地址 10.20.10.101/24

横着读一行。接口、速率、你写给它的描述、上面的地址、线缆上的标签,以及对端的端口。这是一次查询,回答的正是每个人实际会问的那个问题:“这个插在哪儿”。

注意地址挂在哪里。它在 eno1 上,而不是在服务器上。这听起来像抠字眼,直到你碰到一台设备,有一个管理接口、两个数据接口和一个环回接口,然后有人问哪个地址代表它。一个把地址挂在设备上的模型回答不了。这个模型能,而且它还能容纳一个接口上有四个地址这种再平常不过的情况。

顺着线缆走

线缆端接在组件上,而不是设备上。一端是一个接口,另一端是一个接口,或者是前端口、后端口、电源插座、线路端接。整个功能就建立在这个细节上,这也是为什么上面的接口列表不用别人告诉,就能在自己的一栏里打印出对端。

如果你把线缆建模成设备连设备,你只是画了一张图。把它端接在端口上,NetBox 就能顺着走。

NetBox 中接口 eno1 的线缆追踪,画成一张纵向图:mcr1-hv-01,一台 Supermicro SYS-1029U-TN10RT,位于 Manchester DC1 / Hall 2 / MCR1-A07 (A07) / Front / U20.0,它的接口 eno1,线缆 MCR1-DAC-0001A 标为 Connected,然后是 mcr1-leaf-01 上的 Ethernet1,一台 Arista DCS-7050SX3-48YC8,位于 Front / U36.0。追踪完成,共 1 段

这里只有一跳,因为这是一根直连线缆。中间加上配线架,它就一块配线架一块配线架地走过去,告诉你一条穿过三个机柜的线路另一端是什么。否则这活就得有人打着手电,再有人在另一头拿着寻线器。

追踪还会打印出每一端的完整位置。站点、机房、机柜、朝向、U 位。如果你曾经在电话里试图告诉远程现场工程师该去看哪台设备,这一行就是全部价值所在。

地址,是一棵树而不是一个标签页

IPAM 是大家冲着来的那一半。

NetBox 前缀列表:10.20.0.0/16 作为 Container,有 5 个子前缀,利用率 1.6%,描述为 Manchester DC1;下面缩进一级是五个活动的子前缀:10.20.10.0/24 在 VLAN mgmt (100) 上,角色为 Management;10.20.20.0/24 租户为 Ravenscroft Legal,在 VLAN ravenscroft-prod (200) 上;10.20.21.0/24 属于 Padgate Foods;10.20.22.0/24 属于 Hartley Components;10.20.30.0/29 在 VLAN transit (110) 上,利用率 16.7%

缩进是根据地址本身计算出来的。你不用告诉 NetBox 10.20.20.0/24 位于 10.20.0.0/16 之内,它自己会算出来,明年有人在中间加一个 /26,它也会继续算对。

每一行都带着你实际会拿来筛选的东西:它映射到的 VLAN、角色,以及它所属的客户。利用率也是算出来的。

打开其中一个,你就能看到里面的地址,以及空隙。

NetBox 中前缀 10.20.20.0/24 的 IP Addresses 标签页:先是一行绿色的“10 IPs available”,然后是 10.20.20.11/24 和 10.20.20.12/24,都处于活动状态,租户为 Ravenscroft Legal,然后是一行绿色的“242 IPs available”

那些绿色的行就是空闲空间,和已用空间排在一起显示。有一个 API 调用能从一个前缀里给你下一个空闲地址,这是 IPAM 自动化里唯一一项立刻就能回本的功能,因为否则大家就是眯着眼盯着电子表格碰运气。

一个接口想挂多少地址就挂多少,两个地址族都行,你再各指定一个作为设备的主地址。

NetBox IP 地址列表,筛选为 mcr1-hv-01 上的接口 eno1,显示四个地址:10.20.20.11/24 标为主地址,10.20.20.201/24 是服务地址,2001:db8:20:20::11/64 是 v6 主地址,2001:db8:20:20::201/64 是服务地址,租户都是 Ravenscroft Legal

一个端口上两个 IPv4、两个 IPv6,这再平常不过,而以设备为中心的模型根本表达不了。

录入地址时,用它所在网络的掩码,而不是 /32。 NetBox 会接受 10.20.20.11/32,并把它归到正确的前缀下,因为包含关系是从主机地址算出来的。它不会做的,是事后替你揣摩:掩码按你输入的原样存储,并原样交给读取它的任何东西,所以一个局域网地址上的 /32,会被渲染成设备配置里的 /32。咬你的地方是三个月后的某个配置模板,而不是今天的表单。

一套安装,三个客户

NetBox 里的大多数对象都可以分配给一个租户。企业用它来区分业务部门。如果你卖托管服务,就每个客户建一个。

NetBox 中 Customers 组里 Ravenscroft Legal 的租户页面,Related Objects 面板列出 Circuits 2、Devices 2、IP Addresses 2、Prefixes 1 和 VLANs 1,顶部有 Custom Objects、Contacts、Journal 和 Changelog 标签页

右边那个面板,就是“这个客户有什么”的答案,而且它是自己组装出来的。不用报表,不用电子表格,不用去问当初搭建它的工程师。

值得仔细想想租户到底意味着什么,因为第一天弄错,以后就是一年的拆解。租户意味着这个对象是专属于那个客户的。只为他们服务的路由器,就挂他们的租户。为四个客户服务的防火墙不属于其中任何一个,所以它不挂租户,这层关系要放到别的地方去。后面会细说,因为大多数人正是在这里发现自己需要添加一些自己的东西。

把数字写在设备类型上

这一步把一份清单和一个能回答问题的东西区分开来,而它每个设备类型大约只花十分钟。

设备类型可以带上它的重量,并通过电源端口模板带上它的功耗。在类型上填一次,你以后用它创建的每台设备都会继承。不填,NetBox 就只会乐呵呵地告诉你某个机柜满了 28.6%,别的什么都不说。

NetBox 中 Supermicro SYS-1029U-TN10RT 的设备类型页面,显示高度 1U、勾选了全深、重量 19.10 kg、散热方式 Air,Power Ports 标签页计数为 2,Related Objects 面板显示 6 台设备

我给这里的五个类型都填了重量,给每个类型配了两个电源端口模板,带最大功耗和分配功耗,给 PDU 类型配了一个输入口和十二个输出口,然后建了一个配电盘和两路进入机柜的馈电,再把所有东西接上线:每台设备的 PSU1 接 PDU A,每个 PSU2 接 PDU B,每个 PDU 的输入口接到它的馈电。

NetBox 电源馈电 MCR1-A07-A,类型 Primary,状态 Active,连接到 mcr1-pdu-a 的 INPUT,利用率显示已分配 5340VA / 5888VA,是一根红色的 90.7% 进度条,电气特性为交流供电、230 伏、32 安、单相、最大利用率 80%

然后,机柜页面就完全变了样。

NetBox 中 MCR1-A07 的机柜页面,现在显示散热能力 Hybrid、散热容量 15.00 kW、绿色的空间利用率 28.6% 和红色的电力利用率 90.7%,旁边是前后立面图

空间利用率 28.6%。电力利用率 90.7%。

那个机柜里的设备只占了三分之一,电力却快用光了,这是关于你资产的一个事实,任何电子表格都不会主动告诉你。下一批订单是装进这个机柜还是别处,也正是由这个事实决定的,而它来自你只在类型上录入过一次的数据。

让它一直显示为零的两件事

一开始我得到的是 0.0%,还得到了两次,两个原因都值得知道,因为哪个都不会报错。

插座必须引用输入口。 PDU 上的电源插座有一个 power_port 字段,指向同一台设备上的上游端口。留空,链条就断了:NetBox 没办法知道那十二个插座是由那个输入口供电的,于是什么都汇总不起来。

把输入口的功耗字段留空。 这条是反直觉的。NetBox 只有在一个电源端口自己的两个功耗字段都为空时,才会根据插在它上面的东西来计算它的功耗:

if self.allocated_draw is None and self.maximum_draw is None:
    ...aggregate the downstream power ports...
# otherwise
return {'allocated': self.allocated_draw or 0, ...}

我很热心地在 PDU 输入口上设了 maximum_draw: 7400,因为 PDU 的额定值就是这么多。于是 NetBox 信了我,把 allocated_draw 当作未设置,报告为零。把两个都清空,它就自己算出来了:

mcr1-pdu-a INPUT -> allocated 5340 VA, maximum 8480 VA, across 12 outlets
mcr1-pdu-b INPUT -> allocated 5340 VA, maximum 8480 VA, across 12 outlets
feed MCR1-A07-A: available 5888 VA   (230 V x 32 A x 80% max utilisation)
RACK power utilisation: 90.7 %
RACK weight: 166.6 kg of 900 kg

所以规则是:在叶子节点上填真实数字,中间的端口留空,让 NetBox 去加总。人为定义的值永远压过计算出来的值,这是正确的行为,而放在 PDU 上恰恰是错误的做法。

散热,这是新加的

4.7 版给 DCIM 加上了散热,而且加的正是越来越贵的那一半。机柜带有散热能力,可以是风冷、混合或液冷,还有以千瓦计的容量;设备类型带有散热方式。再往上是代表冷水机组和精密空调的冷源、代表通往机柜的冷却回路的冷却馈送,以及设备本身上用于冷板和分液歧管的进液和出液组件。

上面那个机柜显示 Hybrid、15.00 kW,因为我是这么告诉机柜的。如果你今年要接收液冷设备,这就是给你目前还记在电子表格里的那个东西准备的模型。

一套安装,多个客户

租户机制是服务商能只跑一套 NetBox、而不是每个客户一套的原因,值得弄明白它做什么,更重要的是,它不做什么。

NetBox 有二十八个模型带租户字段。站点、位置、机柜和机柜预留。设备、线缆和虚拟设备上下文。前缀、IP 地址、地址范围、聚合、VLAN、VLAN 组、VRF、路由目标、ASN。线路和线路组。集群和虚拟机。隧道、L2VPN、无线局域网和无线链路。电源馈电和冷却馈送。

这就是所有能计费的名词。一致地设好它,“这个客户有什么”就不再需要调查。

但租户是一个标签,不是一把锁。它说明这个对象专属于那个客户。它挡不住任何能登录的人把所有东西读个遍,在一家公司内部这没问题,一旦某个客户有了账号,它就毫无用处。

由此引出两件事,第二件是大家会弄错的。

租户意味着专属。只为一个客户服务的路由器,挂他们的租户。为四个客户服务的防火墙不属于其中任何一个,所以什么都不挂,你转而在你实际卖出的那个东西上记录这层关系。把租户硬塞给共享设备,会让每一份基于租户的报表都悄悄出错。

而访问控制完全是另一套机制。

隔离靠的是权限

NetBox 的对象权限接受一个 JSON 约束,这个约束就是一个 Django ORM 过滤器。它在构建任何东西之前先收窄查询集,所以每个视图、导出、API 调用和搜索都会跟着被收窄。

NetBox 中 Ravenscroft read-only 的权限详情页:Enabled 已勾选,Actions 中 View 已勾选,Add、Change、Delete、Render configuration 和 Synchronize data 都打了叉,Object Types 列出 Circuits circuit、DCIM device 和 IPAM prefix,分配了一个用户 ravenscroft-ro,Constraints 面板里是 JSON:tenant__slug 设为 ravenscroft-legal

干活的是三个字段。它适用的对象类型、它授予的操作,以及底部那条约束。其他的都是记账。

这是管理员看到的设备列表。

以 admin 用户查看的 NetBox 设备列表,Results 14,显示 mcr1-core-01 和 02、mcr1-hv-01 到 06、mcr1-leaf-01 和 02、mcr1-pdu-a 和 b,以及 mcr1-pp-01 和 02,各列为状态、租户、站点、位置、机柜、角色、厂商、类型和 IP 地址

这是同一个 URL、同一套安装,以客户身份登录后看到的。

以 ravenscroft-ro 登录后看到的同一个 NetBox 设备列表,Results 2,只显示 mcr1-hv-01 和 mcr1-hv-02,租户都是 Ravenscroft Legal,左侧导航缩减为 Devices、IPAM、Circuits、Plugins 和 Admin

两行而不是十四行,再看看左侧菜单。它缩减到了这个账号被允许碰的四样东西。没有人配置过这个。导航是由同一套权限构建的,所以客户永远不会看到一个点进去会被拒绝的链接。

它说“不”的两种方式

这个细节值得知道,因为两种拒绝含义不同,而且都是有意为之。

客户的令牌请求得到
/api/dcim/devices/200,两行里的一行
/api/dcim/devices/1/,他们自己的200
/api/dcim/devices/2/,别人的404
/api/tenancy/tenants/403
/api/dcim/sites/,从未授权403
完全没有令牌403

404 的意思是:这个类型是你的,但那一行不是。 约束把它从查询集里去掉了,所以就这个请求而言,它不存在。在那里返回 403 等于确认它存在,好奇的客户就能通过遍历 ID 把你的资产数一遍。

403 的意思是:这个类型从来就不是你的。 租户和站点从未授权,所以直接拒绝,客户也就没法枚举平台上还有谁。

然后让他们写

只读是容易的情况。真正的问题是,一个有编辑权限的客户能不能被信任,所以我在同一条约束下授予了 change,然后去找出口。

尝试结果
编辑自己的设备200,已保存
编辑另一个客户的设备404
编辑自己的设备,把它移到另一个客户的租户下403
删除自己的设备403,从未授予删除权限

关键是第三行。把自己的设备重新分配给别人的租户,是最明显的逃逸路线,因为请求到达时这个对象在你的约束之内,之后就在约束之外了。NetBox 是按照对象将被留下的那个状态来评估约束的,所以它拒绝了。我没有相信状态码,而是把设备读了回来,租户确实没动。

这正是大多数自制多租户方案留着的那个洞,而它通常是被客户发现的,而不是被测试发现的。

需要继承的变量

这是大家会弄错的一个区别,弄对了能省下大量编辑工作。

自定义字段是挂在单个对象上的一个值。你逐个对象地设,它就待在那里。适合描述这个东西本身的事实:资产标签、支持合同编号、投运日期。

配置上下文是挂在某个特征上的值,所有符合这个特征的东西都会继承。适合应该层层传递的变量:你的 NTP 服务器、syslog 目标、SNMP community、DNS 域、管理 VLAN、备份窗口。

如果你发现自己在四十台设备上把同一个自定义字段设成同一个值,你要的其实是配置上下文。

NetBox 配置上下文列表:North West base 权重 1000,分配给 North West 区域;Manchester DC1 syslog 权重 2000,分配给 Manchester DC1 站点;两者都处于活动状态

一个上下文就是任意 JSON,可以挂在区域、站点组、站点、位置、设备类型、角色、平台、集群、集群类型、集群组、租户组、租户或标签上。租户也在这份清单里,对服务商来说,这意味着一个对某个客户处处成立的事实,会跟着他们落到你以后为他们添加的每一台设备上。

合并是按键进行的,每个键由权重决定谁胜出。

mcr1-core-01 的 NetBox Config Context 标签页:左侧 Rendered Context 包含 domain、ntp_servers、snmp_community 和 syslog_servers,右侧 Source Contexts 列出权重 1000、包含全部四个键的 North West base,以及权重 2000、只包含 syslog_servers 的 Manchester DC1 syslog

把右边的面板和左边对照着读。区域在权重 1000 上提供了四个键。站点在权重 2000 上提供了一个键。渲染后的上下文原封不动地保留了区域的域名、NTP 服务器和 community,只采用了站点的 syslog 服务器,因为那是唯一有争议的键。

你写的是例外,而不是把所有东西连同例外重新抄一份。这就是全部价值,也是它能扩展、而按设备存放的变量文件不能扩展的原因。

本地上下文压过上面的一切

继承栈有顶层,顶层就是对象本身。设备上的本地上下文数据,压过所有适用于它的源上下文,不管它们的权重是多少。

我在 mcr1-core-01 上设了这个:

{"syslog_servers": ["10.20.10.99"], "note": "this box logs somewhere else"}

它渲染后的上下文变成了:

{
  "note": "this box logs somewhere else",
  "domain": "mcr1.example.net",
  "ntp_servers": ["172.16.10.22", "172.16.10.33"],
  "snmp_community": "n0rthwest",
  "syslog_servers": ["10.20.10.99"]
}

mcr1-core-01 的 NetBox Config Context 标签页,现在 Local Context 已填入 syslog_servers 10.20.10.99 和一条备注,面板上写着本地配置上下文会覆盖所有源上下文,Rendered Context 显示本地的 syslog 服务器,以及继承来的域名、NTP 服务器和 community

本地的 syslog 服务器同时压过了权重 2000 的站点覆盖和权重 1000 的区域。它没提到的东西照样继承,所以域名、NTP 服务器和 community 原封不动地传了下来,新键则直接加了进去。

这是给那一台确实与众不同的设备留的逃生口,面板也明明白白地告诉你它会覆盖所有源上下文。如果你发现自己在很多台设备上用它,而不是一台,那你就是找到了这些设备共有的一个特征,你要的是一个限定到这个特征的上下文。

三个陷阱

没有限定范围的上下文是全局的。 建一个上下文却忘了分配给任何东西,它就会作用于你所有的设备和虚拟机。这是文档里写明的行为,偶尔也正是你想要的。它同样是悄无声息的。

如果你想简单地引用键,键名里就不能有连字符。 上下文数据是 JSON,所以 ntp-servers 完全合法,但 Jinja 的变量名不是 JSON 键。{{ ntp-servers }} 会被解析成一个减法,抛出 UndefinedError: 'ntp' is undefined。对着带连字符的数据写 {{ ntp_servers }},你会得到一个空字符串、HTTP 200,哪儿都没有警告。键名用下划线,最直观的模板就能用。

profile 能拦住拼写错误。 配置上下文 profile 把相关的上下文归成一组,并在保存时对它们的数据强制执行 JSON schema。我给一个 profile 配了一个 schema,要求 syslog_servers 是 IPv4 字符串数组,然后犯了大家真正会犯的那两个错:

{"syslog-server": ["10.1.1.1"]}          singular, by accident
  400  Data does not conform to profile schema:
       'syslog-servers' is a required property

{"syslog_servers": [...], "syslog_port": 99999}
  400  Data does not conform to profile schema:
       99999 is greater than the maximum of 65535

在有人犯错的地方就被拒绝了,而不是四百台设备之后。

渲染配置

上下文数据加上一个 Jinja 模板,就得到一个配置文件。设备以 device 的名义在作用域内,它合并后的上下文以普通变量的形式在作用域内,你还可以遍历它的组件。

mcr1-core-01 的 NetBox Render Config 标签页,显示配置模板 Junos base 以及渲染出来的 Junos 配置:host-name mcr1-core-01、domain-name mcr1.example.net、一行内容为 Manchester DC1 / MCR1-A07 / U39 的位置、两台 NTP 服务器、唯一的 syslog 主机 10.20.10.99、SNMP community n0rthwest,以及每个接口的描述和地址族

那个页面上的每样东西都来自不同的地方,这正是重点:

行来自哪里
host-name mcr1-core-01设备
domain-name mcr1.example.net区域级配置上下文
location "Manchester DC1 / MCR1-A07 / U39"站点、机柜以及在机柜中的位置
server 172.16.10.22区域上下文,权重 1000
host 10.20.10.99 any notice设备自己的本地上下文,同时压过站点和区域
family inet address 10.20.10.11/24那个接口上的地址,掩码按输入原样保留

模板的解析顺序是设备,然后角色,然后平台,三者都没有的话请求就会失败。所以你在平台上分配一次模板,运行那套软件的每台设备都会用它来渲染,除非它的角色或设备本身另有指定。这就是平台的用途:操作系统或厂商软件家族,而不是硬件。

NetBox 负责渲染。它不推送。把输出送上设备,是你的自动化系统的活,等哪天某个模板 bug 本来会把四百台设备重新配置一遍时,你会庆幸这是两个不同的系统。

插件

插件是一个和 NetBox 装在一起的 Django 应用。它可以添加模型、添加页面、扩展两套 API、往现有模板里注入内容、添加导航、添加后台任务队列,以及加载更多 Django 应用。它几乎没有做不到的事,因为底下就是 Django。

安装一个插件只要四条命令加一次重启:

source /opt/netbox/venv/bin/activate
pip install netbox-topology-views netbox-qrcode
# add the package names to PLUGINS in configuration.py, then
python3 manage.py migrate
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

在容器栈上,同样的软件包写进 plugin_requirements.txt,然后重建镜像。不管哪种方式,都要锁定版本,并先查兼容性矩阵,因为一个还没跟上 NetBox 新版本的插件,会让整个应用拒绝启动,而不是把自己禁用掉。

NetBox 已安装插件页面,列出 NetBox Labs 的 Custom Objects 0.7.0 版、Mattijs Vanhaverbeke 的 Topology views 4.7.0 版,以及 Nikolay Yuzefovich 的 qrcode 1.0.0 版

公开的目录里列了 31 个。下面这些值得了解,附上每个插件实际采用的许可证:

插件做什么许可证
DNS把区域、记录和域名服务器作为真相来源MIT
BGP会话、community 和路由策略Apache 2.0
Topology Views根据你的线缆生成图形化拓扑图Apache 2.0
Floorplan图形化的站点和位置平面图LGPL 3.0
QR Code为机柜、设备和线缆生成二维码,用作资产标签Apache 2.0
ACLs访问控制列表和规则Apache 2.0
Prometheus SD直接从 NetBox 给 Prometheus 提供主机列表MIT
Documents挂在线路和设备上的文档Apache 2.0
Lifecycle硬件生命周期终止、许可证和合同Apache 2.0
Contract合同和发票MIT
Reorder Rack拖放调整机柜 U 位Apache 2.0
Branching隔离的、可合并的数据分支NetBox Limited Use
Custom Objects在界面里定义新的对象类型NetBox Limited Use

Prometheus SD 是整个思路最老实的样子。NetBox 知道有什么,那就让 NetBox 去告诉监控系统,别再维护第二份会慢慢跑偏的主机列表。

在最后两行上搭东西之前,有件事要知道。NetBox 本身是 Apache 2.0,自 2016 年 DigitalOcean 发布以来一直如此,如今这个项目由 NetBox Labs 和一支志愿维护者团队共同管理。21 NetBox Branching 和 NetBox Custom Objects 不是:它们采用 NetBox Limited Use License 1.0,只授权“only as part of a NetBox installation obtained from NetBox Labs or a NetBox distributor authorized by NetBox Labs, and only for your own internal use”的使用,并且不授予使用该软件“to provide a managed service or software products that includes, integrates with, or extends NetBox in a way that competes with any product or service of NetBox Labs”的权利。如果你装的是从 GitHub 拿来的 NetBox Community,又是代表客户在运行它,那么在把一套 schema 建在它们上面之前,自己去读一读条款。10 NetBox 自己的安装指南推荐了这两个插件,却只字未提这一点。11

自定义字段

自定义字段给现有模型加一个属性。值以 JSON 形式和每个对象存放在一起,所以不需要迁移,也不需要重启,一共有十三种类型,包括指向其他 NetBox 记录的单对象和多对象引用。

mcr1-core-01 的 NetBox 设备页面,显示一个 Custom Fields 面板,其中 Asset 组包含 Warranty expires 2029-06-30 和 Support contract JNPR-448120,旁边的 Device Type 面板显示 Juniper MX204,Dimensions 面板显示总重 9.5 千克

那里有两个字段,归在我选定的“Asset”标题下。注意它们右边的 Dimensions 面板:9.5 kg,没有人在这台设备上输入过。它来自设备类型。

自定义字段是有校验的,值得知道这一点,因为这和下面那条路线确实不同。我给合同字段配了一个正则表达式,API 就强制执行了它:

PATCH {"custom_fields": {"support_contract": "nonsense"}}
  {"__all__": ["Invalid value for custom field 'support_contract':
                Value must match regex '^[A-Z]{2,4}-[0-9]{6}$'"]}

4.7 里有两处变化,在规模大时很要紧。创建一个带默认值的字段,或者删除一个字段,都必须重写它所适用的每个对象的存储数据,所以在大表上,这项工作会交给一个后台任务,运行期间字段会显示“provisioning”或“deleting”。字段只有处于活动状态时才生效:在这两种操作进行期间,它不会出现在对象上、表单里、筛选器里,也不会出现在任何一套 API 里。这需要工作进程在跑,否则它会无限期地停在那个状态。

要添加的是关于这个东西本身的事实,就用自定义字段。值应该层层传递,就用配置上下文。你需要的东西根本不存在,就看下一节。

自定义下拉菜单,以及覆盖自带的选项

这个标题下面有两种不同的机制,它们解决的是不同的问题。一种用于你自己的字段。另一种改写 NetBox 的字段。

选项集,用于你自己的下拉字段

类型为“selection”的自定义字段从一个选项集里取选项,选项集是一个和其他东西一样在界面里管理的对象。这样“支持级别”就成了一个真正的下拉框,而不是一个会被人拼出三种写法的自由文本。

NetBox 中名为 Support tier 的自定义字段选项集,描述为客户付费购买的服务,列出三个选项:bronze 为下一个工作日,silver 为 8 小时,gold 为 4 小时 7×24

它是强制执行的,通过 API 也一样:

PATCH {"custom_fields": {"support_tier": "platinum"}}
  {"__all__": ["Invalid value for custom field 'support_tier':
                Invalid choice (platinum) for choice set Support tier."]}

选项集是共享的,所以一个选项集可以支撑几个模型上的同一个字段,在一个地方改列表,处处都跟着改。

FIELD_CHOICES,用于 NetBox 自己的字段

这个是大家不知道存在的那个。NetBox 有好几个内置的选项字段可以从 configuration.py 里扩展或替换,包括设备状态、站点状态、机柜状态、线路状态,以及很多别的。12

在名字后面加一个加号,就是在自带的列表上追加。不加,就是整个替换掉。

FIELD_CHOICES = {
    # add to what NetBox ships with
    'dcim.Device.status+': (
        ('burn-in', 'Burn-in', 'cyan'),
        {'value': 'awaiting-rma', 'label': 'Awaiting RMA', 'color': 'orange',
         'description': 'Faulty, with the vendor'},
    ),
    # replace the stock list outright
    'dcim.Site.status': (
        ('surveyed', 'Surveyed', 'purple'),
        ('building', 'Building out', 'orange'),
        ('active', 'Active', 'green'),
        ('closing', 'Closing', 'red'),
    ),
}

我在这套实例上就是这么配的。设备状态返回了七个自带值加上我的两个:

offline, active, planned, staged, failed, inventory, decommissioning,
burn-in, awaiting-rma

而站点状态只返回了我的值,自带列表没了:

surveyed, building, active, closing

一个选项可以是由值、标签和颜色组成的普通元组,也可以是一个字典,字典还能带一段描述,在表单里显示为副标题。它们在哪里都表现得和原生值一样,因为在 NetBox 其余部分看来,它们就是原生值:

NetBox 设备列表:mcr1-hv-06 带着一个青色的 Burn-in 状态徽标,其他设备是自带的 Active 状态,样式和任何内置状态一样

那个徽标就是我的状态,用的是我的颜色,排序和筛选都和其他状态一样。

用它之前,有三件事值得知道。

替换会把自带值从菜单里删掉,而不是从数据库里删掉。 已经持有其中某个值的对象会保留它,但这个值不再出现在选项里,下次有人编辑这个对象时,它也不再是合法的选择。如果你替换了一个列表,检查一下有没有东西还挂在你刚删掉的值上。

它在配置文件里,所以需要重启,也不是界面用户能改的东西。对服务商来说这样才是对的:你的业务认可哪些状态,是一个治理层面的决定,而不是某个星期二下午随手做的决定。

先扩展,再考虑替换。 自带值是每个插件、脚本和集成都预期会看到的。追加不花任何代价。替换是一个你要永远背着的决定。

自定义对象

这里有一个真正的空白。NetBox 能建模集群、虚拟机和虚拟磁盘。它不建模这些磁盘实际所在的数据存储(datastore),而对任何在跑 Proxmox 或 VMware 的人来说,正是这个对象把你买来的存储和使用它的工作负载连起来。

Custom Objects 插件让你在界面里或通过 API 定义一种新的对象类型,不用写任何代码。于是:

NetBox 中 Datastore 的 Custom Object Type 页面,版本 1.0.0,描述为集群存放虚拟机磁盘的共享存储,Fields 标签页显示 7,Fields 面板列出:Name 为 Text,Cluster 为指向 Virtualization > Cluster 的 Object,Provisioned by 为指向 DCIM > Device 的 Multiple objects,Backing 为 Text,Capacity (GB) 为 Integer,Thin provisioned 为 Boolean,Customer 为指向 Tenancy > Tenant 的 Object

七个字段,其中两个是全部意义所在。cluster 是对一个真实 NetBox 集群的单对象引用,设为 protect,这样就没人能把集群从它的存储底下删掉。provisioned_by 是对实际提供这份存储的那些设备的多对象引用。

这样你就得到一个一等对象,有自己的导航入口、列表视图、筛选器、导入和导出:

NetBox Datastores 列表,显示四行:ds-nvme-01,在集群 MCR1-PVE 上,由 mcr1-hv-01、02 和 03 提供,后端是 Ceph RBD NVMe 池,40960 GB,精简置备;ds-nvme-02;ds-archive-01,在一个带 NVMe WAL 的 HDD 池上,196608 GB,非精简置备;以及 ds-ravenscroft-01,8192 GB,租户为 Ravenscroft Legal

而且因为引用是真实的,这层关系从另一端也看得到。打开集群,数据存储就列在它下面。

NetBox 中 MCR1-PVE 的集群页面,这是一个限定在 Manchester DC1 的 Proxmox VE 集群,Custom Objects 标签页显示引用它的数据存储

自定义对象类型继承了让一个 NetBox 对象成为 NetBox 对象的大部分东西:列表和详情视图、导航入口、REST 端点、全文搜索、变更日志、日志记录(journal)、标签、书签、导入导出、事件规则和通知。这些一行都不用写。

它也不是一个假装成表的 JSON 块。插件会执行真正的 DDL,出现在 PostgreSQL 里的是一张真正的表,带着真正的约束:

                    Table "public.custom_objects_2"
     Column      |   Type   | Nullable |     Default
-----------------+----------+----------+------------------
 id              | bigint   | not null | identity
 name            | varchar  |          |
 cluster_id      | bigint   |          |
 backing         | varchar  |          |
 capacity_gb     | bigint   |          |
 thin_provisioned| boolean  |          |
Indexes:
    "custom_objects_2_name_key" UNIQUE CONSTRAINT, btree (name)
Foreign-key constraints:
    ... FOREIGN KEY (cluster_id) REFERENCES virtualization_cluster(id) ON DELETE RESTRICT

我要求的 protect 变成了 ON DELETE RESTRICT,而且确实管用:删除那个集群会返回 409,并说出依赖它的是什么。

依赖它之前要知道的两件事

校验在表单上,不在 API 上。 这条会坑到自动化。我在一个自定义对象类型的字段上声明了 required、一个正则表达式和数值范围,然后通过 REST API 往里写:

我声明的我发送的结果
validation_regex一个什么都匹配不上的值201 Created
required: true完全省略这个字段201 Created
validation_minimum: 1一个负数201 Created
unique: true一个重复值400,被拒绝
on_delete_behavior: protect删除被引用的对象409,被拒绝

守住的那两条,正是变成了数据库约束的那两条。其余的只存在于网页表单上,所以手工输入的人受约束,而每晚的同步任务不受。对比一下前面的核心自定义字段,同样的正则表达式通过 API 也被强制执行了。在这一点改变之前,凡是发票要依赖的东西,都要放在真正的约束后面。

删除一个类型就是删掉一张表。 删除一个字段就是删掉一列。这是从网页表单发出的 DDL,由任何有权限的人执行,文档也是这么说的。13 限制谁能删除这些东西。

什么时候该写一个真正的插件

如果这个对象很重要,如果有自动化往里写,如果你发现里面有垃圾数据会恼火,那就自己写模型。一个最小的 NetBox 插件包括一个 PluginConfig、一个模型、一个序列化器、一个视图集、一个表格、一个表单、几个视图和一张 URL 映射,总共不到两百行,大部分是声明。继承 PrimaryModel 就能免费得到标签、自定义字段、变更日志、日志记录、导出模板和所有权,而你加在模型上的每一条约束处处都会被强制执行,因为跑它的是 NetBox 自己的序列化器机制。

社区维护着一个 cookiecutter 模板和一份完整的插件教程。从它们开始,而不是从一个空目录开始。

而且它的许可证由你自己选,以后谁也改不了。

自定义校验,以及校验器类

上面讲的都是记录那里有什么。这一节讲的是拒绝记录不该有的东西。

NetBox 在写入每个对象之前都会校验它,你还可以在上面加自己的规则。一共有三种机制,都放在 configuration.py 里,合起来几乎能覆盖内部标准需要的一切。

其一:普通规则,不用写代码

校验器可以是一个从字段名到条件的普通映射。不用 Python,而且因为它只是数据,可以在不同安装之间移植。

CUSTOM_VALIDATORS = {
    'dcim.site': (
        {'description': {'required': True}},
    ),
    'dcim.device': (
        {'name': {'regex': r'^[a-z0-9]+-[a-z]+-([0-9]{2}|[a-z])$'}},
    ),
}

可用的条件有 min、max、min_length、max_length、regex、required、prohibited、eq 和 neq。你可以用点分路径伸进关联对象,所以站点上的 region.name 也可以拿来用,还可以按 request.user.username 匹配,不过文档非常正确地告诉你,这种事应该用权限来做。

上面两条规则都立刻生效:

POST a site with no description
  {"__all__": ["Custom validation failed for description:
                ['This field must not be empty.']"]}

POST a device named "Server1"
  {"__all__": ["Custom validation failed for name: ['Enter a valid value.']"]}

第二条就是一个被强制执行的命名规范。不是写在 wiki 页面上,不是存在某人脑子里,也不是新来的人三周后在评审里挨一顿说的那种东西。数据库不收。

其二:校验器类,当规则是一句话时

普通规则是拿一个字段去比一个常量。真正的内部规则通常是有条件的:只有当那个成立时,这个才要紧。对这类规则,你继承 CustomValidator,重写 validate(),然后调用 fail()。

我在 /opt/netbox/netbox/house_rules.py 的一个模块里放了三个:

from extras.validators import CustomValidator


class BillableKitNamesItsCustomer(CustomValidator):
    """Anything in a role we sell has to say whose it is."""
    BILLABLE_ROLES = {'hypervisor'}

    def validate(self, instance, request):
        role = getattr(instance, 'role', None)
        if role and role.slug in self.BILLABLE_ROLES and not instance.tenant:
            self.fail(
                f"A {role} is billable kit, so it must name the customer it belongs to.",
                field='tenant',
            )


class RackedDeviceNeedsAPosition(CustomValidator):
    """A device in a rack with no rack unit is a device nobody can find."""
    def validate(self, instance, request):
        if instance.rack and instance.position is None:
            if instance.device_type and instance.device_type.u_height:
                self.fail(
                    "A device in a rack needs a rack unit. Somebody has to find it.",
                    field='position',
                )


class CustomerPrefixNeedsATenant(CustomValidator):
    """A customer prefix that names no customer cannot be billed."""
    def validate(self, instance, request):
        role = getattr(instance, 'role', None)
        if role and role.slug == 'customer' and not instance.tenant:
            self.fail(
                "A customer prefix must be assigned to a tenant.",
                field='tenant',
            )

然后按点分路径把它们接上:

CUSTOM_VALIDATORS = {
    'dcim.device': (
        {'name': {'regex': r'^[a-z0-9]+-[a-z]+-([0-9]{2}|[a-z])$'}},
        'house_rules.BillableKitNamesItsCustomer',
        'house_rules.RackedDeviceNeedsAPosition',
    ),
    'ipam.prefix': (
        'house_rules.CustomerPrefixNeedsATenant',
    ),
}

注意,一个模型接受的是校验器的元组,普通规则和类可以随意混用,而且全部都会运行。哪怕只有一个校验器,也必须作为可迭代对象传进去,这是很容易白丢五分钟的地方。

然后规则就照它们说的那样执行:

POST a hypervisor with no tenant
  {"tenant": ["A Hypervisor is billable kit, so it must name
              the customer it belongs to."]}

POST a device into a rack with no position
  {"position": ["A device in a rack needs a rack unit.
                Somebody has to find it."]}

POST a prefix with role "customer" and no tenant
  {"tenant": ["A customer prefix must be assigned to a tenant."]}

POST a leaf switch with no tenant
  accepted, because a leaf switch is not in BILLABLE_ROLES

因为 fail() 接受一个 field 参数,错误信息会落在表单里正确的那个输入框上,而不是页面顶部,这就是一条大家学会的规则和一条大家怨恨的规则之间的区别。

这也是对自定义对象那一节里那个空白的回答。那里的校验只存在于网页表单上。CustomValidator 在模型层运行,所以它适用于界面、REST API、GraphQL 变更、批量导入,以及脚本做的任何事。写规则的地方只有一个,而且绕不过去。

其三:保护规则,针对删除

CUSTOM_VALIDATORS 守护写入。PROTECTION_RULES 守护删除,它接受的也正好是同样的两种形式。

PROTECTION_RULES = {
    'dcim.device': (
        {'status': {'eq': 'offline'}},
    ),
}

这表示一台设备只有在 offline 状态时才能被删除。效果是这样的:

DELETE an active device
  {"detail": "Deletion is prevented by a protection rule:
              [\"Custom validation failed for status:
                ['Ensure this value is equal to offline.']\"]"}

set it to offline, then DELETE
  204 No Content

在一个人和一台在线设备之间多加两下按键的阻力,这是整个应用里最便宜的保险。让下线流程成为解锁删除按钮的那个东西。

会坑到你的那一条

已有数据要到你下次碰它时才会被检查。 添加一条规则,并不会回头去校验已经存在的东西。它安静地待着,直到有人保存了一个违反它的对象,然后那个人就会收到一条错误,而错误针对的决定跟他毫无关系。

我亲眼看着它发生。mcr1-hv-06 是在我写下这些规则之前创建的,是一台没有租户的虚拟化主机。它在那儿待得好好的。然后我改了它的描述:

PATCH {"description": "touching it to trigger revalidation"}
  {"tenant": ["A Hypervisor is billable kit, so it must name
              the customer it belongs to."]}

这次编辑跟租户毫无关系。规则照样触发了,因为校验是针对整个对象运行的。

这是正确的行为,也正是一条新规则变成一张支持工单的过程。在启用一条规则之前,先查询会违反它的对象,把它们修好。API 让这件事很容易:规则本身就是一个过滤条件,所以查询带那个角色又没有租户的设备,你就拿到了清单。

然后再启用规则。这样它就只会抓新犯的错,这才是它的用途。

用 Ansible 驱动它

一个没人读取的真相来源会烂掉。netbox.netbox 集合是大多数人防止这件事发生的办法,而且它是双向的:NetBox 告诉 Ansible 有什么,Ansible 告诉 NetBox 它建了什么。

它的版本是 3.23.0,许可证是 GPL-3.0,在 Galaxy 上被拉取了超过 1340 万次。它带有 91 个模块和一个库存插件。14 下面所有内容都是对着同一套实例跑的,用的是一个只装了 ansible-core 2.21.4、pynetbox 7.8.0 和这个集合的容器。

库存清单是一次查询,而不是一个文件

这是第一个下午就能回本的那一半。nb_inventory 直接从 NetBox 构建你的 Ansible 库存清单:

plugin: netbox.netbox.nb_inventory
api_endpoint: http://netbox:8080
token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
config_context: false
group_by:
  - sites
  - device_roles
  - tenants
  - racks
device_query_filters:
  - has_primary_ip: true

它产出的是这个,没有任何人在维护主机列表:

@sites_manchester-dc1:      @device_roles_hypervisor:
  |--mcr1-core-01             |--mcr1-hv-01
  |--mcr1-core-02             |--mcr1-hv-02
  |--mcr1-hv-01               |--mcr1-hv-03
  |--mcr1-hv-02               |--mcr1-hv-04
  ...                         |--mcr1-hv-05
@racks_MCR1-A07:            @tenants_ravenscroft-legal:
  |--mcr1-core-01             |--mcr1-hv-01
  |--mcr1-core-02             |--mcr1-hv-02
  ...                       @tenants_padgate-foods:
@device_roles_core-router:    |--mcr1-hv-03
  |--mcr1-core-01             |--mcr1-hv-04
  |--mcr1-core-02           @tenants_hartley-components:
                              |--mcr1-hv-05

看右边那一栏。因为设备上设了租户,你免费得到了每个客户一个组,所以 --limit tenants_ravenscroft-legal 会让一个 play 恰好只对一个客户的设备运行。在 NetBox 里加一台设备,下次运行时它就在组里了。下线一台,它就没了。没有人需要编辑任何东西。

每台主机到来时都带着 NetBox 对它的了解:

ansible_host     "2001:db8:20:20::11"
primary_ip4      "10.20.20.11"
primary_ip6      "2001:db8:20:20::11"
device_roles     ["hypervisor"]
sites            ["manchester-dc1"]
racks            ["MCR1-A07"]
tenants          ["ravenscroft-legal"]
device_types     ["sys-1029u-tn10rt"]
manufacturers    ["supermicro"]
status           {"label": "Active", "value": "active"}

总共二十二个键,其中一个值得在它让你吃惊之前注意到。ansible_host 是 IPv6 地址,因为那台设备设了 v6 主地址。我拿另外两台只有 v4 的设备核对过,它们返回的是 v4,所以规则是:有 v6 主地址的地方,插件优先用 v6。这是对的,但这种事你也宁可现在发现,而不是在纳闷某个 play 为什么走了一条你压根没想到的路径去连接时才发现。

写回去

模块是另一个方向,其中值得拥有的是 IP 分配,因为 NetBox 知道哪些是空闲的,而你的 playbook 不知道。

- name: Rack the device
  netbox.netbox.netbox_device:
    netbox_url: "{{ nb_url }}"
    netbox_token: "{{ nb_token }}"
    data:
      name: mcr1-hv-07
      device_type: SYS-1029U-TN10RT
      device_role: Hypervisor
      site: Manchester DC1
      rack: MCR1-A07
      position: 14
      face: Front
      tenant: Hartley Components
    state: present

- name: Let NetBox pick the next free address out of the customer prefix
  netbox.netbox.netbox_ip_address:
    netbox_url: "{{ nb_url }}"
    netbox_token: "{{ nb_token }}"
    data:
      prefix: 10.20.22.0/24
      tenant: Hartley Components
      assigned_object:
        device: mcr1-hv-07
        name: eno1
    state: new

注意里面没有什么。没有 IP 地址。你给出前缀,NetBox 就交回下一个空闲地址:

TASK [Let NetBox pick the next free address out of the customer prefix] ****
changed: [localhost]

"device   : mcr1-hv-07  (created)"
"interface: eno1  (created)"
"address  : 10.20.22.1/24  (allocated)"

一秒钟之后它就出现在界面里了,还没接任何线,但已经上架、有了租户、分好了地址:

NetBox 中 mcr1-hv-07 的接口标签页,这是一台由 playbook 创建的设备,显示一个接口 eno1,类型 SFP28 25GE,描述为 to leaf-01,地址为 10.20.22.1/24

那个 playbook 里的陷阱

一行不改地再跑一次,就会发生这个:

"device   : mcr1-hv-07  (already correct)"
"interface: eno1  (already correct)"
"address  : 10.20.22.2/24  (allocated)"

设备和接口是幂等的。地址不是,而且这不是 bug。state: present 的意思是“让它变成这个样子”。state: new 的意思是“给我一个新的”,每一次都是,而它恰恰就是这么做的:跑两次之后,一个接口上有了两个地址。

如果你确实是在置备新东西,这没问题;如果你把它放进一个每晚运行的任务里,它会悄悄吃掉一整个前缀。分配一次并记录结果,或者用 state: present 加上你已经持有的地址。模块做的是你要求它做的事。问题在于,你要求的是不是你真正想要的。

不只是 Ansible

这个集合之所以受关注,是因为大多数网络团队本来就在用 Ansible,但 API 才是产品本身,能和它对话的东西多得很。

东西它是什么许可证
pynetbox这个集合自己用的 Python 客户端Apache 2.0
terraform-provider-netbox把 NetBox 对象作为 Terraform 资源来管理,由 e-breuninger 积极维护MPL 2.0
nornir_netbox把 NetBox 作为 Nornir 库存,给写 Python 而不是 YAML 的人用Apache 2.0
Prometheus SD从 NetBox 给 Prometheus 提供抓取目标MIT
go-netbox一个 Go 客户端,不过从 2025年5月起就没人动过见仓库
DiodeNetBox Labs 自己的数据摄取管道,用来把发现的数据推进去NetBox Limited Use

对已经用 Terraform 管理基础设施的人来说,Terraform 那一项最有意思,因为它让一个 plan 同时创建云资源和记录它的 NetBox 条目,而不是把后一半留给某人的记性。15

Diode 的许可证和 Branching、Custom Objects 一样,所以在它上面搭东西之前,同样的解读也适用。

这一个下午到底买到了什么

上面所有内容花了我一台机器上的一天,而这一天的大部分时间都花在灌数据上,好让页面里有东西可看。两种方式的安装都是二十分钟。真正要紧的是那些决定,而它们都在第一个小时里做出:租户先于一切,设备类型先于设备,数字写在类型上而不是写在设备上。

你因此得到的不是文档。这个区别,没人会去分,直到两样都经历过:文档是你写完之后就不再维护的东西。你得到的是一个拒绝容纳矛盾的数据库:它不让你把两样东西放进同一个 U,不让你把一个机柜放进属于另一个站点的位置,也不让你把一台设备建在一个不存在的类型上。每一次拒绝,都是你六个月后不用再吵的一场架。

而且它会告诉你没人问过它的事。那个机柜设备装了 28.6%,电力却用了 90.7%。没有人专门去找这件事。它只是因为有人在一个设备类型上填过一次功率就自己冒了出来,而这就是“把下一批订单装进那里”和“吃了苦头才发现”之间的区别。

老实的提醒,和每个真相来源都一样。它的价值只等于你为保持它正确所付出的成本,而唯一能熬过一个忙碌季度的版本,是数据一错就会有东西明显坏掉的那种。把你的监控、置备或防火墙规则接上去从它读取,一条错误的记录就不再是某人迟早会处理的文档问题。它会变成某个星期二早上九点半的一次故障,上面写着一个名字。这听起来像是代价。它就是整个机制本身。

也不会有人为此感谢你。一份正确的记录,体现为一次花了两周而不是一个季度的迁移,一次花了一个下午的审计,一个在电话里得到了直截了当回答的客户。这些都不会出现在某份报表上你的名字旁边。

照样去做。另一种选择是一个连自己都描述不清的企业,而一个连自己都描述不清的企业不是在被经营。它是在被记着,而记得的人一年比一年少。


  1. NetBox, Introduction — “Today, the open source project is stewarded by NetBox Labs and a team of volunteer maintainers”,以及它 2015 年起源于 DigitalOcean、2016年6月开源的经过。 ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  2. NetBox, LICENSE.txt — Apache License 2.0,版权归 DigitalOcean, LLC。起源和管理方信息见 the introduction。 ↩︎ ↩︎

  3. Nautobot v1.0.0 release notes — “a divergent fork of NetBox 2.10”,发布于 2021年4月26日,并列出了它相对 NetBox 2.10 增加的内容。 ↩︎ ↩︎

  4. Network to Code, “Why Did Network to Code Fork NetBox?”,2021年2月25日 — 关于 SLA 和长期支持的理由、愿景的分歧,以及“the NetBox project team suggested that we should consider forking”。 ↩︎

  5. NetBox Labs 成立于 2023 年,是 IBM 收购 NS1 之后从 NS1 分拆出来的,联合创始人之一是 NetBox 首席维护者 Jeremy Stretch,并于 2023年4月宣布完成 2000 万美元 A 轮融资:NetBox Labs, “Let’s Go: Announcing NetBox Labs” 以及 the Series A announcement。 ↩︎

  6. NetBox Labs, NetBox Enterprise — 自行管理的商业版,提供“24/7 expert assistance from the NetBox Labs team”;NetBox Cloud 是托管版本。该页面未公布具体的 SLA 条款。 ↩︎

  7. 两个项目的 star 和 fork 数、发布日期和许可证,于 2026年9月30日读自 GitHub API:netbox-community/netbox 和 nautobot/nautobot。Nautobot 并行发布的 3.2.x 和 2.4.x 日期均为 2026年9月28日。 ↩︎

  8. netbox-community/netbox-docker — 社区维护的容器栈,Apache 2.0。 ↩︎

  9. NetBox, Installation — 受支持版本表;PostgreSQL 和 Redis 最低版本的提高见 the v4.7 release notes。版本和发行版信息读自 netbox/release.yaml。 ↩︎

  10. NetBox Limited Use License 1.0 — netbox-custom-objects 采用此许可证,netbox-branching 采用的与之完全相同。文中引用的两段条款均为原文。 ↩︎

  11. NetBox, HTTP Server installation, “What’s Next?” — “Some of the most popular plugins include” NetBox Branching、NetBox Custom Objects、NetBox DNS 和 NetBox BGP,未提及任何许可条款。 ↩︎

  12. NetBox, Data Validation configuration — FIELD_CHOICES,以及表示扩展而非替换的加号后缀:“To replace the available choices, specify the app, model, and field name separated by dots … To extend the available choices, append a plus sign”。 ↩︎

  13. netboxlabs/netbox-custom-objects documentation — “Deleting a Custom Object Type drops an entire database table and should be done with caution.” ↩︎

  14. netbox.netbox on Ansible Galaxy 和 netbox-community/ansible_modules — 版本 3.23.0,GPL-3.0,91 个模块加上 nb_inventory 库存插件。下载次数于 2026年9月30日读自 Galaxy。文中展示的一切都是用 ansible-core 2.21.4 和 pynetbox 7.8.0 跑出来的。 ↩︎

  15. 许可证、活跃度和 star 数于 2026年9月30日读自各项目:pynetbox(Apache 2.0)、terraform-provider-netbox(MPL 2.0,Terraform registry 上为 v6.0.0-rc.1)、nornir_netbox(Apache 2.0)、netbox-plugin-prometheus-sd(MIT)、go-netbox(最后一次推送为 2025年5月9日),以及 Diode,它采用与 Branching 和 Custom Objects 相同的 NetBox Limited Use License 1.0。 ↩︎