netbox-administration

NetBox 管理

你对 NetBox 管理的了解可能已经过时。 配置设置、身份验证后端和权限模型会随着版本更新而变化。优先检索信息，而非依赖预训练知识。

检索来源

来源	URL / 方法	用途
安装文档	https://netboxlabs.com/docs/netbox/installation/	设置、依赖项、升级
配置文档	https://netboxlabs.com/docs/netbox/configuration/	所有配置设置
身份验证文档	https://netboxlabs.com/docs/netbox/administration/authentication/overview/	LDAP、SAML、OIDC、SSO
NetBox 仓库	https://github.com/netbox-community/netbox	源代码、发行说明
NetBox MCP 服务	如果已配置 — 检查实例状态、用户权限	验证当前配置状态

需要配置、保护、维护或排查 NetBox 服务安装问题时，请使用此技能。如需了解 API 使用模式，请参阅 netbox-api-integration。

快速参考

服务管理

sudo systemctl restart netbox netbox-rq   # After config changes
sudo systemctl status netbox netbox-rq     # Check health

基本管理命令

命令	用途
python manage.py nbshell	交互式 NetBox shell
python manage.py reindex	重建搜索索引
python manage.py trace_paths	重建线缆路径追踪
python manage.py rebuild_prefixes	重建前缀层级
python manage.py runscript	执行自定义脚本（核心脚本已在 4.7 中弃用，并将在 5.0 中移除 — 请参阅 netbox-custom-scripts）
python manage.py rebuild_config_context_cache [--force]	(4.7) 填充预渲染的配置上下文缓存；对于绕过信号的写入操作，--force 会重新渲染已填充的条目
python manage.py rebuild_ltree_paths [--check] [app.Model ...]	(4.7) 检测（--check，不加锁）或修复过时的层级 path/sort_path 列

例行维护：从 4.4 起，例行维护会通过内置系统任务自动运行 — 请移除所有 housekeeping cron 任务。手动执行 python manage.py housekeeping 命令的功能已在 4.7 中移除；在 4.6 中仍可运行，但会发出 FutureWarning。

关键文件位置

文件	用途
netbox/netbox/configuration.py	主配置（Python 模块）
netbox/netbox/ldap_config.py	LDAP 设置（如使用）
local_requirements.txt	额外的 Python 包
gunicorn.py	WSGI 服务配置

配置

配置位于 configuration.py 中，这是一个 Python 模块。可通过 NETBOX_CONFIGURATION 环境变量覆盖其路径。更改后，重启：sudo systemctl restart netbox。

必需参数

参数	用途
ALLOWED_HOSTS	用于 Host 请求头验证的 FQDN/IP
DATABASES	PostgreSQL 连接
REDIS	Redis 配置 — tasks 和 caching 必须使用不同的数据库 ID
SECRET_KEY	Django 密钥（≥50 个字符，绝不可泄露）
API_TOKEN_PEPPERS	用于 v2 令牌哈希的 Pepper 字典（4.5+）

动态参数与静态参数

部分参数是动态参数，可在“管理 > 系统 > 配置”中编辑，无需重启。configuration.py 中硬编码的值始终优先于通过界面设置的值。

动态参数包括：CHANGELOG_RETENTION、CHANGELOG_RETAIN_CREATE_LAST_UPDATE（4.6 — 清理记录时保留每个对象最初的创建记录和最新的更新记录）、JOB_RETENTION、MAINTENANCE_MODE、MAX_PAGE_SIZE、BANNER_*、GRAPHQL_ENABLED、CUSTOM_VALIDATORS、PROTECTION_RULES 等。

NetBox 4.7 配置变更 — 升级前请在 configuration.py 中修复以下配置：

• SENTRY_DSN、SENTRY_SAMPLE_RATE、SENTRY_SEND_DEFAULT_PII、SENTRY_TRACES_SAMPLE_RATE 已移除 — 请将其设为 SENTRY_CONFIG 的键（dsn、sample_rate 等）。若 SENTRY_ENABLED = True，但 SENTRY_CONFIG 中没有 dsn，服务将拒绝启动。
• JINJA2_FILTERS 更名为 JINJA_FILTERS（旧名称在 5.0 之前仍可使用，但会产生 DeprecationWarning）。
• 发送邮件必须配置 EMAIL['SERVER'] — 若省略，发送邮件时（而非启动时）会引发 InvalidMailer。
• 新增的 WEBHOOK_DEFAULT_TIMEOUT（默认 60 s）必须小于 RQ_DEFAULT_TIMEOUT，否则 NetBox 将拒绝启动 — 若你将 RQ_DEFAULT_TIMEOUT 降至 ≤ 60，请显式设置此参数。
• 新增的 BULK_UPDATE_CHUNK_SIZE（默认 5000）用于限制每次批量 UPDATE 的行数；对超过此对象数量的对象批量创建带默认值的自定义字段或删除自定义字段时，将转为后台任务。

完整的参数目录请参阅 references/configuration-guide.md。

身份验证

NetBox 支持多个身份验证后端，并按顺序尝试。通过 REMOTE_AUTH_BACKEND（字符串或列表）进行配置。

后端选项

后端	适用场景	配置位置
本地（默认）	小型团队，没有集中式 IdP	configuration.py（AUTH_PASSWORD_VALIDATORS）
LDAP	Active Directory / OpenLDAP 环境	ldap_config.py（单独文件）
远程用户	反向代理身份验证（nginx/Apache）	configuration.py（REMOTE_AUTH_*）
社交身份验证	SAML、OIDC、OAuth2（Azure AD、Okta、Keycloak 等）	configuration.py（SOCIAL_AUTH_*）

常见身份验证注意事项

1. Gunicorn 会剥除请求头 — gunicorn v22.0+ 会静默丢弃名称中带下划线的 HTTP 请求头。请在 gunicorn 配置中添加 header_map = dangerous，以处理远程身份验证请求头。
2. LOGIN_FORM_HIDDEN 可能导致无法登录 — 如果 SSO 出现故障且登录表单被隐藏，将无法登录。必须编辑配置并重启。
3. 后端顺序很重要 — 后端会按顺序依次尝试；第一个成功的后端生效。组合使用 LDAP 和本地身份验证时，请确保顺序符合预期。
4. 客户端位于代理之后时的 IP 地址（NetBox 4.6.1+）— HTTP_CLIENT_IP_HEADERS 控制用于确定客户端 IP 的请求头（默认 ('HTTP_X_REAL_IP', 'HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR')）。请根据反向代理进行设置，以便基于 IP 的令牌限制（allowed_ips）和日志记录获取真实的客户端地址，而非代理地址。
5. LOGIN_REQUIRED 已弃用（4.6，v5.0 移除）。新部署中请勿推荐使用；匿名访问由 DEFAULT_PERMISSIONS / EXEMPT_VIEW_PERMISSIONS 控制。
6. 4.7 中 SSO 库的主版本升级 — social-auth-app-django 6.0 / social-auth-core 5.1。升级前，请在非生产环境的 4.7 实例上测试所有 SAML/OIDC 后端；在验证完成前，请保留使用本地凭据的管理员账号（并设置 LOGIN_FORM_HIDDEN = False）。

设置详情请参阅 references/authentication-backends.md。

权限

NetBox 使用基于对象的权限，而非 Django 内置的模型级权限。

对象权限模型

每个 ObjectPermission 包含：

• 对象类型 — 指定适用的模型
• 操作 — view、add、change、delete（以及 run 等自定义操作）
• 约束条件 — 基于 JSON 的 ORM 筛选条件，用于限制可访问的对象

约束语法

# AND — single dict
{"status": "active", "region__name": "US"}

# OR — list of dicts
[{"vid__gte": 100}, {"status": "reserved"}]

# Current user reference
{"created_by": "$user"}

# Django lookups supported: __in, __gte, __lt, __startswith, __isnull, etc.

约束针对数据库记录进行评估，而非内存中的实例。对于创建或更改操作，NetBox 会在原子事务中保存，然后重新查询——如果约束不匹配，就会回滚。

令牌管理

NetBox 4.5+：v2 令牌采用 Bearer nbt_<key>.<token> 格式。系统绝不会存储明文（仅存储 HMAC-SHA256 摘要）。需要在配置中设置 API_TOKEN_PEPPERS。在 4.6.1+ 中，v2 明文令牌只会在创建响应中返回一次——请在此时保存。 v1 令牌（Token <plaintext> 格式）：在 4.6 中正式弃用，并将在 v5.0 中移除。升级到 5.0 前，请将所有集成迁移到 v2 令牌。

NetBox 4.7+：REST 创建时，token 字段为只读——客户端无法再指定明文（任何提供的值都会被忽略）。通过 REST 执行自定义脚本需要令牌具有 write_enabled = true。4.7.0/4.7.1 会将通过 ?background=true 批量请求创建的令牌明文记录在作业结果中（任何能查看作业的人都能读取）——请运行 ≥4.7.3（4.7.3 还增加了支持分支的后台写入和配置上下文省略优化），并更换以这种方式创建的任何令牌。

令牌功能：write_enabled（只读开关；(4.7) 还用于控制 REST 脚本执行）、allowed_ips（IP 限制）、expires（到期时间）、enabled（软禁用）。

重要：DEFAULT_PERMISSIONS

DEFAULT_PERMISSIONS 适用于所有经过身份验证的用户。默认设置允许令牌自我管理。设置自定义 DEFAULT_PERMISSIONS 会清除这些默认权限——如有需要，必须重新配置令牌权限。

完整详情请参阅 references/permissions-guide.md。

运维

备份清单

1. 数据库：pg_dump --username netbox netbox > netbox.sql
   • 为缩小备份体积，可排除变更日志：--exclude-table-data=core_objectchange
2. 媒体文件：tar -czf netbox_media.tar.gz netbox/media/
3. 配置文件：configuration.py、ldap_config.py、local_requirements.txt、gunicorn.py
4. 自定义脚本：SCRIPTS_ROOT 目录
5. 密钥：如果存储在外部，请备份 SECRET_KEY 和 API_TOKEN_PEPPERS
6. 使用 psql -v ON_ERROR_STOP=1（或 pg_restore --exit-on-error）进行恢复，并检查退出状态——普通 psql 在部分恢复成功时也会报告成功。以这种方式恢复的 4.7.0 转储会悄悄丢失 ltree 级联触发器（已在 4.7.1 修复）；从 4.7.0 恢复或升级后，请运行 python manage.py rebuild_ltree_paths --check。

恢复流程请参阅 references/backup-restore.md。

升级流程

1. 查看当前版本与目标版本之间的所有发行说明；确认每个插件都支持目标版本
2. 备份数据库和媒体文件
3. 根据参考文档中的兼容性矩阵，检查版本兼容性（Python、PostgreSQL、Redis）
4. 不能跳过主版本——先升级到当前主版本的最新次版本
5. 停止工作进程前，等待 RQ 队列清空（Admin > Background Tasks）
6. 解压/检出新版本，复制配置文件
7. 运行 sudo ./upgrade.sh
8. 重启服务：sudo systemctl restart netbox netbox-rq

NetBox 4.7：Python 3.12–3.14，必须使用 PostgreSQL 15+（系统检查会在 14 上中止 migrate），必须使用 Redis 6.0+，Django 6.1。需要 PostgreSQL ltree 扩展；如果 NetBox 数据库用户拥有数据库的 CREATE 权限，迁移会自动安装该扩展（GRANT CREATE ON DATABASE netbox TO netbox;），否则 DBA 可以预先使用 CREATE EXTENSION IF NOT EXISTS ltree; 安装。升级耗时较长，且实际上不可逆：MPTT→ltree 迁移在回填数据时会持有 ACCESS EXCLUSIVE 锁，随后 rebuild_config_context_cache 会针对每台设备/虚拟机执行一次 UPDATE——请备份并规划维护窗口。升级前排队的 send_webhook 作业会因 TypeError 失败，因此请先清空队列。请运行 ≥4.7.3（4.7.0/4.7.1 存在令牌明文泄露问题；4.7.0 存在 pg_dump 触发器丢失问题；4.7.3 修复了分支安全的后台写入和配置上下文省略性能问题）。 NetBox 4.5–4.6：Python 3.12–3.14，PostgreSQL 14+（PostgreSQL 14 在 4.6 中已弃用——请在升级到 4.7 前迁移到 15+），Redis 5.0+。4.6 使用 Django 6.0，4.5 使用 Django 5.x。

请参阅 references/upgrade-procedures.md 了解逐步操作说明。

性能调优

关键参数

参数	默认值	影响
CONN_MAX_AGE（在 DATABASES 中）	300	持久数据库连接；减少开销
MAX_PAGE_SIZE	1000	限制 API 响应大小；防止查询失控
LOGIN_PERSISTENCE	False	若为 True，则每次经过身份验证的请求都会写入数据库
CHANGELOG_RETENTION	90 天	自动清理 core_objectchange（增长最快的表）
RQ_DEFAULT_TIMEOUT	300	后台任务超时时间；运行繁重脚本时可调高。(4.7) 必须大于 WEBHOOK_DEFAULT_TIMEOUT
WEBHOOK_DEFAULT_TIMEOUT (4.7)	60	每个请求的 Webhook 超时时间（1–3600 s）；Webhook 自身的 timeout 字段会覆盖此值
BULK_UPDATE_CHUNK_SIZE (4.7)	5000	每条批量 UPDATE 语句处理的行数；如果大型回填任务触发 statement_timeout，请调低此值（设为 None 可禁用分块）

Redis：必须使用独立数据库

务必为 tasks 和 caching 使用不同的 Redis DB ID。 如果共用同一个数据库，清空缓存数据库会删除排队中的后台作业。

PostgreSQL 调优

对于大型部署，请在 PostgreSQL 层面进行调优：

• shared_buffers — RAM 的 25%
• work_mem — 根据查询复杂度设置为 4-16MB
• effective_cache_size — RAM 的 50-75%
• 监控 core_objectchange 表的大小——它的增长最快

反模式

问题	原因	解决方法
无法使用 v2 令牌	未配置 API_TOKEN_PEPPERS	在配置中添加 pepper 字典
轮换 SECRET_KEY 会导致会话失效	所有会话和令牌均会失效	规划迁移窗口；用户必须重新验证身份
EXEMPT_VIEW_PERMISSIONS = ['*'] 不完整	通配符会排除敏感模型	如有需要，明确列出其他模型
CHANGELOG_RETENTION = 0	永久保留；数据库会无限增长	将其设为非零值（默认保留 90 天）
只读备用节点无法验证身份	会话存储在数据库中	使用 SESSION_FILE_PATH 存储基于文件的会话
指标端点返回 404	METRICS_ENABLED = False	将其设为 True 并重启
运行 NetBox 4.6.0	可通过模板 environment_params 远程执行代码（CVE-2026-29514）	运行 ≥4.6.1；将 ExportTemplate/配置模板的编辑权限视为代码执行级别的权限并加以限制
运行 NetBox 4.7.0/4.7.1	通过 ?background=true 批量请求创建的令牌明文会记录在作业结果中	运行 ≥4.7.3（4.7.3 还带来了分支安全的后台写入和配置上下文省略优化）；将此类令牌视为已泄露并予以更换
升级到 4.7 后 NetBox 无法启动（webhook 超时错误）	RQ_DEFAULT_TIMEOUT ≤ 60，而默认的 WEBHOOK_DEFAULT_TIMEOUT = 60	将 WEBHOOK_DEFAULT_TIMEOUT 设为小于 RQ_DEFAULT_TIMEOUT
NetBox 发送邮件时出现 InvalidMailer（4.7）	未设置 EMAIL['SERVER']	设置 EMAIL = {'SERVER': ..., ...} — Django 的 EMAIL_* 设置不会再自动填充
新建或编辑的对象未出现在全局搜索中（4.7）	搜索索引更新延后到后台作业执行	确保 netbox-rq 正在运行；短暂延迟属于预期行为（仅在没有 worker 时才会同步更新）
重命名或移动区域、位置等后，后代对象未相应更新（4.7）	使用未指定 ON_ERROR_STOP 的 4.7.0 转储恢复数据库 — 缺少 ltree 触发器	升级到 ≥4.7.1，运行 rebuild_ltree_paths --check，然后运行 rebuild_ltree_paths <app.model>

版本说明

NetBox 4.7（2026-09-02）

• 平台：PostgreSQL 15+（带 ltree）、Redis 6.0+、Django 6.1。升级耗时较长，且实际上无法回退 — 参见 references/upgrade-procedures.md。运行 ≥4.7.3（4.7.0/4.7.1 存在令牌泄露问题；4.7.3 新增分支安全的后台写入和配置上下文省略优化）。
• 已移除：housekeeping 管理命令；SENTRY_DSN/SENTRY_SAMPLE_RATE/SENTRY_SEND_DEFAULT_PII/SENTRY_TRACES_SAMPLE_RATE（改用 SENTRY_CONFIG）。
• 配置：JINJA2_FILTERS → JINJA_FILTERS；新增 WEBHOOK_DEFAULT_TIMEOUT、BULK_UPDATE_CHUNK_SIZE；必须设置 EMAIL['SERVER']；Django MAILERS 替代 EMAIL_* 设置（读取 EMAIL_HOST 等设置或使用显式后端调用 get_connection() 的插件代码会失效）。
• 安全性：创建 REST 令牌时，token 字段为只读；REST 脚本执行需要写入权限令牌；自定义链接的 request 上下文是经过清理的子集（id、path、path_info、method、GET、user — 不含 Cookie、请求头或会话）；URL 自定义字段会根据 ALLOWED_URL_SCHEMES 验证（未指定 scheme 的值会以 https:// 存储）。
• 行为：全局搜索索引更新延后到后台作业执行；当对象数量超过 BULK_UPDATE_CHUNK_SIZE 时，带默认值创建自定义字段及删除自定义字段的操作会延后到作业执行；配置上下文会按设备/VM 预渲染并缓存（rebuild_config_context_cache）。
• 已弃用：核心自定义脚本（支持至 4.8，5.0 移除），以及与之配套的 SCRIPTS_ROOT — 参见 netbox-custom-scripts。
• 安装方式：NetBox 已发布到 PyPI；通过 Python 包安装/升级（netbox upgrade --no-input）仍属实验性功能 — 不适用于生产环境。

NetBox 4.6（2026-05-05）

• Django 6.0；PostgreSQL 14 已弃用；housekeeping 命令已弃用（FutureWarning）；LOGIN_REQUIRED 已弃用；v1 令牌已弃用（5.0 中移除）；创建时仅返回一次 v2 明文令牌，并新增 HTTP_CLIENT_IP_HEADERS（4.6.1+）；新增 CHANGELOG_RETAIN_CREATE_LAST_UPDATE。请运行 ≥4.6.1（CVE-2026-29514）。