Netbox 4.7 配置参数详解

目标：系统梳理 Netbox v4.7.3 的 configuration.py 全部配置参数——必填五参数的逐项落法、安全/认证/展示/运维四大类常用参数的默认值与调整时机，并给出可直接套用的生产配置模板。参数默认值与行为说明均对照随源码分发的官方文档（docs/configuration/，v4.7.3）核实；所有验证命令在 Ubuntu 24.04.5 LTS + Netbox 4.7.3（Django 6.1.2）环境实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• Netbox：v4.7.3（官方最新稳定版，2026-10-22 实查）
• 运行栈：Django 6.1.2 / gunicorn 26.1 / PostgreSQL 16.15 / Redis 7.0.15 / Python 3.12.3
• 安装方式：官方 Release Archive + venv（/opt/netbox-4.7.3/，软链 /opt/netbox），安装过程见本系列《Ubuntu 24.04 安装 Netbox 4.7 指南》
• 配置文件：/opt/netbox/netbox/netbox/configuration.py（由 configuration_example.py 复制而来，v4.7.3 中该示例文件共 264 行）
• 参数文档（随源码分发，本地可读）：/opt/netbox/docs/configuration/，共 13 个主题文件（required-parameters、system、security、default-values、miscellaneous、remote-authentication、data-validation、plugins、error-reporting、development、graphql-api 等）

二、前置条件

本文的参数修改与验证操作依赖已完成的安装与运行环境：

1. 已按安装指南完成 Netbox 4.7.3 部署并可正常登录（systemctl is-active netbox netbox-rq 均为 active）；
2. 操作者具备 root 或 sudo 权限（configuration.py 属主为 root，服务以 netbox 用户运行）；
3. 熟悉基本 Python 语法——configuration.py 本质是可执行的 Python 文件，参数即 Python 变量，支持 import、函数定义等完整语法。

验证当前环境（实测回显）：

systemctl is-active netbox netbox-rq
/opt/netbox/venv/bin/python3 -c "import django; print(django.get_version())"

active
active
6.1.2

三、参数查看与修改方式

3.1 唯一入口：configuration.py

Netbox 的全部自定义参数集中在一个文件：/opt/netbox/netbox/netbox/configuration.py。它与 Django 内置 settings.py 的关系是"覆盖式合并"——configuration.py 里定义的参数覆盖 Netbox 内部默认值，未定义的走内置默认。修改流程固定三步：

# 1. 编辑配置（示例：改时区）
vi /opt/netbox/netbox/netbox/configuration.py

# 2. 语法与完整性校验（不会改数据，安全执行）
source /opt/netbox/venv/bin/activate && cd /opt/netbox/netbox
python3 manage.py check

# 3. 重启两个服务使配置生效（worker 进程只读一次配置）
systemctl restart netbox netbox-rq

manage.py check 实测回显（配置合法时）：

System check identified no issues (0 silenced).

若参数值非法（如 SECRET_KEY 不足 50 字符），check 与服务启动都会直接报错提示，不会静默生效。

⚠️ 注意：改完必须 systemctl restart netbox netbox-rq——gunicorn 与 rqworker 都是常驻进程，仅在启动时读取一次配置，reload nginx 不等于让 Netbox 重新加载配置。

3.2 用 diffsettings 对比生效值

Django 的 diffsettings 列出与 Django 全局默认不同的生效配置（带 ### 标记的行即受 configuration.py/Netbox 内部 settings.py 影响的项），是核对"配置到底生效没有"的利器：

python3 manage.py diffsettings | head -8

实测回显（节选）：

ALLOWED_HOSTS = ['*']
API_TOKEN_PEPPERS = {1: 'UwJKwgp%SpYB+&s8RXB4_#BE7Sa@fftR%WafsYAFc2w_GSWbmq'}  ###
AUTHENTICATION_BACKENDS = ['netbox.authentication.RemoteUserBackend', 'netbox.authentication.ObjectPermissionBackend']
AUTH_USER_MODEL = 'users.User'
BASE_DIR = '/opt/netbox-4.7.3/netbox'  ###
BASE_PATH = ''  ###
BULK_UPDATE_CHUNK_SIZE = 5000  ###
CACHES = {'default': {'BACKEND': 'django_redis.cache.RedisCache', 'LOCATION': 'redis://localhost:6379/1', 'OPTIONS': {'CLIENT_CLASS': 'django_redis.client.DefaultClient', 'USERNAME': '', 'PASSWORD': ''}}}

关键行（grep 过滤后）：

python3 manage.py diffsettings | grep -E "^DATABASES|^LOGIN_REQUIRED"

实测回显：

DATABASES = {'default': {'ENGINE': 'django.db.backends.postgresql', 'NAME': 'netbox', 'USER': 'netbox', 'PASSWORD': 'q1w2e3r4', 'HOST': 'localhost', 'PORT': '', 'CONN_MAX_AGE': 300, 'ATOMIC_REQUESTS': False, 'AUTOCOMMIT': True, 'CONN_HEALTH_CHECKS': False, 'OPTIONS': {}, 'TIME_ZONE': None, 'TEST': {'CHARSET': None, 'COLLATION': None, 'MIGRATE': True, 'MIRROR': None, 'NAME': None}}}
LOGIN_REQUIRED = True  ###

3.3 在 nbshell 里读取运行时值

进入 Netbox 交互式 shell 直接读取 Django settings，适合确认单个参数的运行时取值：

echo "from django.conf import settings
print('TIME_ZONE =', settings.TIME_ZONE)
exit" | python3 manage.py nbshell 2>&1 | grep -vE "^(>>>|###|Use exit|now exiting)"

实测回显：

TIME_ZONE = UTC

⚠️ 实测发现：v4.7.3 中并非所有配置文档列出的参数都能从 django.conf.settings 读到——例如 PAGINATE_COUNT（getattr 实测返回 MISSING）。原因是官方已将其标注为 Dynamic Configuration Parameter（动态配置参数）：默认值仍可经 configuration.py 或管理界面调整，但运行时经动态配置体系（数据库）而非静态 settings 属性提供。判断某参数是否属动态配置，看官方文档该参数小节是否带 "Dynamic Configuration Parameter" 提示框。

四、参数总览

v4.7.3 官方配置文档按主题分为 10 类，共约 90 个参数。总览如下（各参数默认值均为 v4.7.3 官方文档标注值）：

💡 关键差异解读：必填 5 参数决定"能不能跑"，安全类决定"跑得稳不稳"，运维类决定"跑得久不久"——新装先落必填 5 项（安装指南已覆盖），上生产前优先复核安全类的 LOGIN_REQUIRED/SECURE_SSL_REDIRECT/SESSION_COOKIE_SECURE 与运维类的 CHANGELOG_RETENTION/JOB_RETENTION。

五、核心参数分类详解

5.1 必填参数（缺一不可启动）

ALLOWED_HOSTS —— HTTP Host 头校验白名单（列表类型，单值也要写成列表）。

ALLOWED_HOSTS = ['netbox.example.com', '192.168.10.10']

• 官方语义：防 HTTP Host header 攻击；该值同时用于生成 CSRF_TRUSTED_ORIGINS；
• 默认：无（必填）；['*'] 仅限临时调试；
• ⚠️ 反代部署时 Netbox 默认 USE_X_FORWARDED_HOST = True，要填用户访问反代所用的 FQDN，不是后端主机名。

API_TOKEN_PEPPERS —— v2 API Token 哈希加盐（v4.5+ 引入）。

API_TOKEN_PEPPERS = {
    1: 'UwJKwgp%SpYB+&s8RXB4_#BE7Sa@fftR%WafsYAFc2w_GSWbmq',
}

• 默认：{}（Netbox 可运行，但 v2 API Token 功能不可用）；
• 每条 ≥50 字符随机串，ID 从 1 起；官方建议首条用 ID 1，后续轮换时追加新 ID；
• ⚠️ 属高敏感值，官方建议初始化时从环境变量注入而非明文落盘；更换/删除 pepper 会使旧 Token 哈希失效。

DATABASES —— PostgreSQL 连接字典（v4.7 起新参数，替代已弃用的单数 DATABASE）。

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'netbox',
        'USER': 'netbox',
        'PASSWORD': 'q1w2e3r4',
        'HOST': 'localhost',
        'PORT': '',
        'CONN_MAX_AGE': 300,
    }
}

• 插件可要求额外库（'external1': {...}），多库时配合 DATABASE_ROUTERS 路由。

REDIS —— 必须提供 tasks 与 caching 两节，两节 DATABASE 编号必须不同。

REDIS = {
    'tasks':   {'HOST': 'localhost', 'PORT': 6379, 'USERNAME': '', 'PASSWORD': '', 'DATABASE': 0, 'SSL': False},
    'caching': {'HOST': 'localhost', 'PORT': 6379, 'USERNAME': '', 'PASSWORD': '', 'DATABASE': 1, 'SSL': False},
}

• ⚠️ 官方明确警告：tasks 与 caching 混用同一 DB 编号，清缓存时可能把后台任务一起冲掉；
• ⚠️ 官方将 Redis 定级为"可信组件"：worker 会反序列化执行 tasks 库里的任务，任何能写该库的人等于能在服务器上执行任意代码——务必加密码并限制在内网；
• 支持三种高级形态：UNIX socket（'URL': 'unix:///run/redis-netbox/redis.sock?db=0'）、Sentinel 高可用（SENTINELS/SENTINEL_SERVICE/SENTINEL_TIMEOUT）、SSL 细化（CA_CERT_PATH、INSECURE_SKIP_TLS_VERIFY、KWARGS 传客户端证书）。

SECRET_KEY —— 会话/Cookie 哈希盐，≥50 字符随机串。

• 默认：无（必填）；用 python3 ../generate_secret_key.py 生成；
• 可随时更换，但会令全部用户会话失效；多节点部署所有节点必须一致；
• 注意它不用于用户密码哈希与敏感字段加密，泄露后应尽快轮换。

5.2 系统参数（system.md）

EMAIL（邮件服务器，Webhook 之外唯一外发通道）：

EMAIL = {
    'SERVER': 'smtp.example.com',
    'PORT': 25,
    'USERNAME': '',
    'PASSWORD': '',
    'USE_SSL': False,
    'USE_TLS': False,
    'TIMEOUT': 10,
    'FROM_EMAIL': 'netbox@example.com',
}

• PORT 默认 25、TIMEOUT 默认 10；USE_SSL 与 USE_TLS 互斥；
• ⚠️ SERVER 缺失不会在启动时报错，而是发信时抛 InvalidMailer——配置邮件后应实测发一封。

LOGGING（默认 INFO+ 打到控制台，由 journald 收进 journalctl -u netbox）：

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/netbox.log',
        },
    },
    'loggers': {
        'django': {'handlers': ['file'], 'level': 'INFO'},
    },
}

可用 logger 域：netbox.auth.*（认证事件）、netbox.api.views.*、netbox.jobs.*、netbox.reports.*、netbox.scripts.*、netbox.event_rules 等。

STORAGES（上传文件后端，默认本地文件系统）：

STORAGES = {
    "default":     {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
    "scripts":     {"BACKEND": "extras.storage.ScriptFileSystemStorage",
                    "OPTIONS": {"allow_overwrite": True}},
}

• 接 S3 时把 default 的 BACKEND 换成 storages.backends.s3.S3Storage 并在 OPTIONS 里给 bucket_name/access_key/secret_key/region_name/endpoint_url；
• ⚠️ Netbox 不做环境变量自动探测：django-storages 的 AWS_* 环境变量约定在这里不生效，必须 import os 后在 configuration.py 里显式 os.environ.get() 读入。

JINJA_ENVIRONMENT_PARAMS / JINJA_FILTERS（配置渲染模板的沙箱与扩展）：

JINJA_ENVIRONMENT_PARAMS = ['WEBHOOK_TOKEN_*', 'DEFAULT_SECRET_ID']

def uppercase(x):
    return str(x).upper()

JINJA_FILTERS = {'uppercase': uppercase}

• JINJA_ENVIRONMENT_PARAMS 默认 []：只有名单内的环境变量才能被 Jinja 模板的 env 过滤器引用（通配符按 fnmatch 语法，大小写敏感）；
• ⚠️ v4.7 改名提示：JINJA_FILTERS 前身为 JINJA2_FILTERS，旧名兼容但将在 v5.0 移除。

5.3 安全与登录参数（security.md）

5.4 远程认证参数（remote-authentication.md）

反向代理（nginx + SSO/OIDC 等）托管的认证体系，核心开关三件：

⚠️ 信任链要求：REMOTE_AUTH_HEADER 是"代理说什么就信什么"，必须保证 8001 端口只有 nginx 能访问（默认如此），且代理层会剥离客户端伪造的同名头。

5.5 展示与默认值参数（default-values.md）

界面横幅四件套（miscellaneous.md，默认均 None）：BANNER_TOP、BANNER_BOTTOM、BANNER_LOGIN、BANNER_MAINTENANCE——支持 HTML，常用于公告与维护提示。

5.6 运维与数据保留参数（miscellaneous.md）

5.7 插件与开发调试参数

5.8 数据校验参数（data-validation.md）

六、生产配置模板

适用场景：2 vCPU / 4GB 内存 / 50GB 磁盘、单机承载 ≤1 万设备 / ≤2 万前缀的中小机房（gunicorn 5 worker × 3 threads，实测该规模下 netbox 服务稳态内存约 1.0G，留 3GB 给 PostgreSQL/Redis/系统充足余量）。直接替换到 configuration.py 即可（凭据换成自己的）：

ALLOWED_HOSTS = ['netbox.example.com', '192.168.10.10']

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'netbox',
        'USER': 'netbox',
        'PASSWORD': 'q1w2e3r4',
        'HOST': 'localhost',
        'PORT': '',
        'CONN_MAX_AGE': 300,
    }
}

REDIS = {
    'tasks':   {'HOST': 'localhost', 'PORT': 6379, 'USERNAME': '', 'PASSWORD': 'J5brHrAXFLQSif0K', 'DATABASE': 0, 'SSL': False},
    'caching': {'HOST': 'localhost', 'PORT': 6379, 'USERNAME': '', 'PASSWORD': 'J5brHrAXFLQSif0K', 'DATABASE': 1, 'SSL': False},
}

SECRET_KEY = '00JiVo2&PB4KdQ-e1iP(HPP(*-+yzoN%yiVaMTW*-jY6^z9Zas'

API_TOKEN_PEPPERS = {
    1: 'UwJKwgp%SpYB+&s8RXB4_#BE7Sa@fftR%WafsYAFc2w_GSWbmq',
}

# —— 安全（走 nginx HTTPS 后）——
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SECURE_SSL_REDIRECT = False      # nginx 层已做 301，此处无需重复
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
LOGIN_TIMEOUT = 3600             # 会话 1 小时过期

# —— 展示 ——
TIME_ZONE = 'Asia/Shanghai'
PAGINATE_COUNT = 50
MAX_PAGE_SIZE = 1000
POWERFEED_DEFAULT_VOLTAGE = 220  # 国内机房电压
BANNER_TOP = '内部资产管理系统，数据变更请通过审批流'

# —— 运维与保留 ——
CHANGELOG_RETENTION = 180        # 变更日志留半年（满足审计要求）
JOB_RETENTION = 30
METRICS_ENABLED = True           # 暴露 /metrics 给 Prometheus
CENSUS_REPORTING_ENABLED = False # 内网不外报
RQ_DEFAULT_TIMEOUT = 600         # 大报表脚本留足时间

# —— GraphQL 防滥用 ——
GRAPHQL_MAX_QUERY_DEPTH = 20
GRAPHQL_MAX_ALIASES = 10

逐段说明：安全段三项 HTTPS Cookie/HSTS 依赖 4.8 节的 nginx TLS 入口，组合后实现传输加密闭环；展示段把时区、电压等默认值调到国内机房习惯；运维段按"审计半年、任务一月"的常见合规口径设置保留期；GraphQL 两项在对外开放 API 时收敛查询复杂度。改完执行第三章三步走：manage.py check → systemctl restart netbox netbox-rq → 抽查页面与 /metrics。

💡 说明：Redis 模板里的密码 J5brHrAXFLQSif0K 演示"tasks/caching 连接需认证"的写法——先在 redis.conf 里 requirepass 配置同值；Redis 是官方定级的可信组件，禁止无密码裸奔。

七、常见问题（FAQ）

Q1：改了 configuration.py 不生效 没重启 worker。gunicorn/rqworker 只在进程启动时读配置，必须 systemctl restart netbox netbox-rq。

Q2：重启后 netbox 起不来，journalctl -eu netbox 显示 SECRET_KEY 相关报错 SECRET_KEY 少于 50 字符或含未转义字符（如直接手写 ' 引号冲突）。用 python3 ../generate_secret_key.py 重新生成并整体替换字符串。

Q3：登录后频繁被踢出 LOGIN_TIMEOUT 默认 None 时会话约两周，通常不是它；多节点部署的 SECRET_KEY 不一致会导致会话随机失效——所有节点必须同值。

Q4：Webhook 发不出去 按顺序排查：EVENTS_PIPELINE 是否被改坏；目标 URL 是否命中 HTTP_PROXIES（内网目标要配 NO_PROXY 类语义或走 PROXY_ROUTERS）；WEBHOOK_DEFAULT_TIMEOUT=60 是否短于对端响应。

Q5：API 翻页最多 1000 条就断了 MAX_PAGE_SIZE 默认 1000。大清单消费端应改用分页遍历，确有需要可临时调大该值（注意请求内存上限 DATA_UPLOAD_MAX_MEMORY_SIZE 与响应时间）。

Q6：升级后界面语言变英文 DEFAULT_LANGUAGE 默认 en-us；确认 TRANSLATION_ENABLED = True 后按用户偏好设置切换界面语言。

Q7：S3 上传附件报错"bucket 参数为空" django-storages 靠环境变量自动探测的约定在 Netbox 下不生效（configuration.py 是显式 Python 环境），必须在 STORAGES['default']['OPTIONS'] 里显式给 bucket_name/access_key 等值，或 import os 后显式读环境变量。

Q8：想临时禁止所有人改数据 设 MAINTENANCE_MODE = True 并重启，写操作被冻结（升级数据库、批量导入窗口期常用）；完成后记得改回 False。

八、参考链接

• 官方配置文档索引：https://netbox.readthedocs.io/en/stable/configuration/
• 必填参数：https://netbox.readthedocs.io/en/stable/configuration/required-parameters/
• 系统参数：https://netbox.readthedocs.io/en/stable/configuration/system/
• 安全参数：https://netbox.readthedocs.io/en/stable/configuration/security/
• 全部参数（默认值速查）：https://netbox.readthedocs.io/en/stable/configuration/default-values/

本系列其他文档：《Ubuntu 24.04 安装 Netbox 4.7 指南》（部署实测）、《Netbox 介绍与选型指南》（认知与选型）、《Netbox 4.7 常用 CLI 命令与工具详解》（manage.py 命令全集）。