01-NetBox 源码安装部署指南

上一篇明确了 NetBox 的定位和数据治理边界。本篇进入传统 Linux 安装路线：在 Ubuntu 24.04 上准备 PostgreSQL、Redis、NetBox 应用、Gunicorn、后台 worker 和 Nginx，最终得到一套可通过 systemd 管理、可升级、可备份。

NetBox 源码安装部署决策

作者：数字卢语 · 发布：2026-05-01 · 更新：2026-06-12

上一篇明确了 NetBox 的定位和数据治理边界。本篇进入传统 Linux 安装路线：在 Ubuntu 24.04 上准备 PostgreSQL、Redis、NetBox 应用、Gunicorn、后台 worker 和 Nginx，最终得到一套可通过 systemd 管理、可升级、可备份和可回退的自托管实例。

本文依据 2026 年 6 月 12 日检索的当前 NetBox 官方安装文档编写。官方当前文档说明，其安装步骤已在 Ubuntu 24.04 上测试，依赖范围为 Python 3.12、3.13 或 3.14，PostgreSQL 14 及以上，Redis 4.0 及以上。实际部署必须选择一个明确 NetBox release，并再次核对该版本文档和 release notes。文中 vX.Y.Z、域名、地址和密码都是需要替换的变量，不代表当前机器已执行安装。

源码安装适合希望精细控制 Python 虚拟环境、systemd、反向代理、插件、自定义脚本和日志的团队。若团队更擅长容器并希望用镜像完成依赖封装，下一篇 Docker Compose 路线可能更合适。两种方式没有绝对高下，关键是能否稳定完成升级、备份、监控和恢复。

先定义目标架构

最小生产链路是：用户通过 HTTPS 访问 Nginx；Nginx 把动态请求转发给 Gunicorn；Gunicorn 运行 NetBox Django 应用；NetBox 访问 PostgreSQL 保存持久对象，通过 Redis 处理缓存和后台任务；netbox-rq worker 执行后台任务。静态文件由 HTTP 服务提供，媒体文件按配置持久化。

本篇采用单机实验或小型生产架构，把 PostgreSQL、Redis、应用和 Nginx放在一台主机，便于理解完整链路。中大型环境可以把数据库和 Redis 分离，部署多个应用节点，但需要额外处理网络、TLS、数据库高可用、媒体文件、负载均衡和一致的插件版本。不要在没有恢复目标的情况下直接把单机命令复制成“高可用架构”。

安装前记录以下变量：

变量	示例	用途
NetBox 版本	`vX.Y.Z`	下载、升级和回滚
主机名	`netbox01.example.internal`	操作系统与监控
访问域名	`netbox.example.com`	`ALLOWED_HOSTS`、证书和 API
应用目录	`/opt/netbox`	官方默认路径
数据库主机	`127.0.0.1`	NetBox 数据库连接
Redis 主机	`127.0.0.1`	缓存和任务队列
备份位置	受控备份存储	数据库与配置恢复
维护窗口	变更时段	安装、升级和回退

生产环境还要明确 RPO、RTO、身份认证、证书来源、出站代理、邮件、监控、日志保留和插件清单。安装只是平台生命周期的第一步。

主机和依赖预检查

官方当前安装文档以 Ubuntu 24.04 为已测试环境。其他发行版也可部署，但包名、Python、systemd 和 Nginx 路径可能不同，应使用对应发行版文档。本文不承诺命令适用于所有 Linux。

建议使用受支持的 Ubuntu LTS，完成安全更新、时间同步、DNS 和静态地址配置。确认主机能解析 PostgreSQL、Redis、软件仓库、GitHub 或内部制品库。生产环境不应直接暴露 PostgreSQL 和 Redis 到不可信网络。

在 Ubuntu 24.04 上，先安装基础依赖。具体包集合可能随 NetBox release 的依赖变化，执行前对照目标版本官方安装页：

sudo apt update
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 \
  postgresql redis-server nginx git curl

验证版本：

python3 --version
psql --version
redis-server --version
nginx -v

Python 必须落在目标 NetBox 支持范围内，PostgreSQL 和 Redis 同理。不要通过修改版本检查强行运行在不受支持组件上。若操作系统仓库版本不满足要求，应使用官方受信仓库或调整 NetBox 版本，不要从未知来源安装二进制。

检查时间和空间：

timedatectl
df -h
free -h

磁盘规划至少区分操作系统、PostgreSQL、日志、媒体和备份。数据库与备份放在同一块磁盘无法覆盖磁盘故障。容量不能只按设备数量估算，还要考虑变更日志、插件、自定义字段、附件和历史增长。

创建 PostgreSQL 数据库

NetBox 只支持 PostgreSQL，不能用 MySQL 代替。先确认服务运行：

sudo systemctl enable --now postgresql
sudo systemctl status postgresql

进入 PostgreSQL 管理会话：

sudo -u postgres psql

创建数据库和专用用户。将占位密码替换为从密钥系统生成的强随机值，不要把真实密码保留在 shell 历史或本文中：

CREATE USER netbox WITH PASSWORD 'REPLACE_WITH_STRONG_PASSWORD';
CREATE DATABASE netbox OWNER netbox;
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;
\q

官方安装文档要求数据库使用 UTF-8 编码，并在 PostgreSQL 15 及以上场景处理 public schema 创建权限。创建后以应用用户测试：

psql --username netbox --password --host 127.0.0.1 netbox

进入后执行：

\conninfo
\q

验证的目标是确认认证、数据库、网络和权限，不要用管理员账号长期供应用连接。若数据库在远程主机，必须同时配置 listen_addresses、pg_hba.conf、主机防火墙和 TLS，并限制只允许应用节点访问。

数据库密码通过受控配置文件或密钥注入提供。configuration.py 中出现密码意味着该文件本身是秘密，权限、备份和代码仓库都要按敏感信息处理。

准备 Redis

NetBox 使用 Redis 支持任务队列和缓存。单机可以使用同一个 Redis 实例的不同逻辑数据库，生产架构是否分离实例取决于可靠性和运维要求。

启动并验证：

sudo systemctl enable --now redis-server
redis-cli ping

预期返回 PONG。这只是本地连通性，不代表生产安全已完成。默认 Redis 不应对公网或普通业务网开放。远程 Redis 应配置认证、网络限制和按当前组件能力支持的加密方式，并监控内存、连接、延迟和持久化。

缓存数据可以重建，但任务队列中的执行状态可能影响业务流程。团队要明确 Redis 故障后哪些任务需要重试、是否允许重复执行，以及 webhook 或自定义脚本是否幂等。

获取明确版本的 NetBox

生产环境使用明确 release tag，不直接运行 main。可以从 GitHub release 下载发布包，也可以克隆仓库并切换到 tag。发布包通常更适合作为不可变安装来源；Git 方式便于查看版本和切换，但仍要锁定 tag。

创建服务账号和安装根目录。官方 systemd 文件默认使用 netbox 用户和组：

sudo useradd --system --home /opt/netbox --shell /usr/sbin/nologin netbox

使用发布包时：

cd /tmp
curl -fL -o netbox-vX.Y.Z.tar.gz \
  https://github.com/netbox-community/netbox/archive/refs/tags/vX.Y.Z.tar.gz
sudo tar -xzf netbox-vX.Y.Z.tar.gz -C /opt
sudo ln -sfn /opt/netbox-X.Y.Z /opt/netbox
sudo chown -R netbox:netbox /opt/netbox-X.Y.Z

这里采用版本目录加 /opt/netbox 符号链接，便于保留旧版本回退。官方示例可能直接把代码放在 /opt/netbox，两种布局都可以，但 systemd、脚本和升级流程必须保持一致。使用符号链接时，要确认升级脚本、服务文件和本地配置引用正确。

使用 Git 时：

sudo git clone https://github.com/netbox-community/netbox.git /opt/netbox-X.Y.Z
cd /opt/netbox-X.Y.Z
sudo git checkout vX.Y.Z
sudo ln -sfn /opt/netbox-X.Y.Z /opt/netbox
sudo chown -R netbox:netbox /opt/netbox-X.Y.Z

下载后核对 release 来源和 tag。受限环境应把发布包进入内部制品库并记录校验值，不要在生产窗口临时从互联网获取未验证文件。

配置 NetBox

配置文件位于应用目录的 netbox/netbox/configuration.py。从示例复制：

cd /opt/netbox/netbox/netbox
sudo -u netbox cp configuration_example.py configuration.py

生成 SECRET_KEY：

sudo -u netbox /opt/netbox/netbox/generate_secret_key.py

最小配置示意如下。字段以目标版本的 configuration_example.py 和官方配置文档为准：

ALLOWED_HOSTS = [
    "netbox.example.com",
]

DATABASE = {
    "NAME": "netbox",
    "USER": "netbox",
    "PASSWORD": "REPLACE_WITH_DATABASE_PASSWORD",
    "HOST": "127.0.0.1",
    "PORT": "",
    "CONN_MAX_AGE": 300,
}

REDIS = {
    "tasks": {
        "HOST": "127.0.0.1",
        "PORT": 6379,
        "DATABASE": 0,
        "SSL": False,
    },
    "caching": {
        "HOST": "127.0.0.1",
        "PORT": 6379,
        "DATABASE": 1,
        "SSL": False,
    },
}

SECRET_KEY = "REPLACE_WITH_GENERATED_SECRET_KEY"

ALLOWED_HOSTS 只放实际访问域名和必要地址，不为省事长期使用 *。反向代理通过正式域名访问时，域名必须在列表中。数据库和 Redis 远程部署时替换主机，并按官方配置支持的认证和 TLS 字段设置。

不同 NetBox 版本可能增加强制配置或安全选项。不要把旧版 configuration.py 不经比较复制到新版本。升级时以新版本示例为基准合并本地配置，并查 release notes 中的 breaking changes。

收紧权限：

sudo chown netbox:netbox /opt/netbox/netbox/netbox/configuration.py
sudo chmod 600 /opt/netbox/netbox/netbox/configuration.py

如果配置由配置管理生成，应确保模板仓库不含明文生产秘密。可以使用环境变量、独立 secrets 文件或企业密钥系统，但具体方式必须符合 NetBox 当前配置加载能力。

执行官方升级脚本完成初始化

NetBox 提供 /opt/netbox/upgrade.sh，用于创建或更新虚拟环境、安装 Python 依赖、执行数据库迁移、收集静态文件等。新安装同样使用它完成初始化：

cd /opt/netbox
sudo ./upgrade.sh

不要在脚本执行失败后连续盲目重跑。根据错误定位：

Python 包编译失败：检查系统依赖、网络和 Python 版本。
数据库连接失败：检查密码、host、pg_hba.conf 和数据库服务。
数据库权限失败：检查数据库 owner 与 schema CREATE 权限。
Redis 失败：检查地址、认证、逻辑数据库和网络。
配置错误：对照当前示例和异常栈修复字段。
插件失败：先禁用不兼容插件，验证核心版本，再按插件文档升级。

脚本完成后进入虚拟环境并执行检查：

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py check
python3 manage.py migrate --plan

migrate --plan 用于查看当前是否仍有待执行迁移，不应凭空假设输出。若 check 报错，先解决再配置生产服务。

创建管理员和最小应用验证

创建第一个超级管理员：

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

超级管理员只用于初始治理和紧急管理，日常用户应通过组、权限和身份系统获得最小权限。创建后不要共享账号。

可以短时使用 Django 开发服务验证应用、数据库和静态资源：

python3 manage.py runserver 127.0.0.1:8000

在同一主机另一个终端测试：

curl -I http://127.0.0.1:8000/

开发服务不适合生产，不要绑定公网地址长期运行。验证结束后停止它，再配置 Gunicorn。

配置 Gunicorn 与后台 worker

官方文档说明 NetBox 作为 WSGI 应用运行，Gunicorn 会随 NetBox 安装。复制默认配置到安装根目录，避免升级覆盖本地调整：

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo chown netbox:netbox /opt/netbox/gunicorn.py

初次部署先使用官方默认配置，不要根据网上公式立即增加大量 worker。上线后根据请求延迟、CPU、内存和数据库能力调整。更多 worker 会增加内存和数据库并发，不一定提高整体性能。

复制 systemd 服务：

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

验证：

systemctl status netbox.service
systemctl status netbox-rq.service

失败时查看：

journalctl -eu netbox
journalctl -eu netbox-rq

官方服务文件假定用户和组名为 netbox。如果现场使用不同账号，必须修改 unit。还要检查 unit 引用的 /opt/netbox、虚拟环境和 Gunicorn 配置是否与符号链接布局一致。

测试 Gunicorn 本地端口。默认值以复制的 gunicorn.py 为准：

sudo ss -lntp
curl -I http://127.0.0.1:8001/

如果端口不同，后续 Nginx upstream 必须一致。不要把 Gunicorn 直接暴露到公网。

配置 Nginx 与 HTTPS

NetBox 提供 Nginx 参考配置：

sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox

编辑前先备份。将 server_name、证书路径、静态文件目录和 upstream 改为实际值。生产入口应使用 HTTPS，证书来自企业 CA 或公开受信 CA。若在上游负载均衡终止 TLS，要正确传递 Host、协议和客户端信息，并限制只有负载均衡器可以访问后端。

启用站点：

sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -sfn /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx

必须先通过 nginx -t 再 reload。验证 HTTPS：

curl -I https://netbox.example.com/

检查证书名称、有效期、跳转、响应头和登录页。不要使用 curl -k 作为生产验收；它会绕过证书验证，只适合短时诊断。

配置上传大小、请求超时和安全头时，结合实际附件与反向代理链路。无限扩大超时和上传大小会增加资源与安全风险。Nginx 日志要轮转并纳入监控。

安装后的功能验收

基础验收按层进行，避免只看登录页。

第一层是服务：

systemctl is-active postgresql
systemctl is-active redis-server
systemctl is-active netbox
systemctl is-active netbox-rq
systemctl is-active nginx

第二层是应用：

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

第三层是 API。创建专用低权限 token 后验证：

export NETBOX_URL="https://netbox.example.com"
export NETBOX_TOKEN="REPLACE_WITH_TEST_TOKEN"

curl --fail --silent \
  -H "Authorization: Token ${NETBOX_TOKEN}" \
  -H "Accept: application/json" \
  "${NETBOX_URL}/api/status/" | jq .

不要把 token 写入共享 shell 脚本或命令记录。验证结束后删除测试 token。

第四层是重启：

sudo systemctl reboot

维护窗口内重启后，确认所有服务自启动、DNS 和证书正常、数据库对象仍在、后台 worker 能执行任务。无法通过重启的部署不算完成。

安全基线

操作系统按周期更新，SSH 使用密钥和受控入口。PostgreSQL、Redis 和 Gunicorn 只监听需要的地址，由主机防火墙限制。Nginx 提供 HTTPS，管理入口不直接暴露公网，必要时接入 VPN、反向代理认证或企业 SSO。

NetBox 的 SECRET_KEY、数据库密码、Redis 密码、邮件凭据、API token peppers、OAuth/LDAP secrets 和证书私钥都属于秘密。记录负责人、存储位置和轮换流程，备份时加密。不要把 configuration.py 提交到包含生产秘密的普通 Git 仓库。

创建日常管理员、数据维护组和只读用户，减少超级管理员。自动化使用专用账号和最小权限 token。启用并审计变更日志，对异常登录、权限变化和大量删除建立告警。

插件是应用代码的一部分。只安装可信且支持目标 NetBox 版本的插件，固定版本，记录来源和许可证。在测试环境执行迁移与回退，不允许普通用户自行安装。

单机、分离和高可用怎么选择

单机部署把 PostgreSQL、Redis、NetBox、worker 和 Nginx 放在一起，优点是链路短、备份和排障直观，适合试点、小规模和缺少数据库平台团队的场景。它的主要风险是主机故障影响全部功能，资源竞争也更明显。单机不等于不可靠，只要恢复目标允许，并有可用备份、备用主机和演练，它可能是最合适的第一阶段方案。

应用与数据库分离适合数据库已有统一运维、需要独立扩容或希望降低应用主机故障影响的环境。分离后必须关注网络延迟、连接数、TLS、DNS 和数据库维护窗口。NetBox 的请求和后台任务都会访问 PostgreSQL，数据库网络抖动会表现为整个应用变慢，而不是只影响某个页面。

Redis 分离通常与应用横向扩展一起出现。多个 NetBox 应用和 worker 应连接到一致的 Redis 与 PostgreSQL。不能让不同应用节点各自使用本地 Redis，否则缓存和任务队列会分裂。远程 Redis 的认证、备份或持久化能力要按实际用途设计，不能因为它常被称为缓存就忽略任务队列。

应用高可用需要至少两个一致的 NetBox 节点和前端负载均衡。节点必须运行相同 NetBox、插件和配置版本，拥有相同秘密，并能访问共享数据库、Redis 和媒体文件。部署流水线应先更新一个非承载或测试节点，完成健康检查，再逐步替换。若所有节点同时运行不同 schema 期望的代码，数据库迁移期间可能出现兼容问题。

媒体文件是容易遗漏的共享状态。若用户上传附件或图片，多应用节点必须看到相同内容，可以使用受控共享存储或对象存储集成，具体能力按目标版本与插件核对。把媒体只保留在某个应用节点，会造成负载均衡后随机丢失。

数据库高可用属于 PostgreSQL 专业领域。复制、自动故障转移、备份和连接入口应由成熟方案承担。NetBox 只需要稳定连接到可写主库，但应用端如何在故障后重连、DNS 或代理如何切换、事务是否回滚，都要演练。不要仅部署两台 PostgreSQL 就宣称高可用。

选择架构时，先写出故障模型。希望覆盖的是进程崩溃、应用主机故障、数据库主机故障、机房故障还是误删除？不同架构覆盖范围不同。双应用节点无法防数据库误删除，数据库复制无法防错误迁移，高可用也无法替代离线备份。

配置分层与秘密管理

随着环境增长，configuration.py 会包含数据库、Redis、邮件、认证、插件、日志和功能开关。若所有配置都手工编辑在一个文件中，测试与生产差异难以审计，升级时也容易遗漏。建议把不敏感的环境配置纳入配置管理，把秘密通过受控文件、环境或密钥系统注入。

分层时至少区分三类。第一类是所有环境一致的应用策略，例如语言、时区、分页和插件列表；第二类是环境差异，例如域名、数据库地址、Redis 地址和邮件服务器；第三类是秘密，例如密码、token peppers、OAuth secret 和私钥。不同类别使用不同存储与审批。

秘密文件应只有 NetBox 服务账号可读，备份加密并限制恢复权限。systemd 环境文件也不是天然安全，读取权限和日志输出仍要检查。任何脚本都不应把完整配置打印到 CI 日志。发生泄露时，要能轮换数据库密码、Redis 密码、API token、OAuth secret 和证书，而不是只能重装系统。

SECRET_KEY 关系到 Django 安全和部分数据处理，恢复时必须与数据库和应用配置配套。随意重新生成可能让已有会话或依赖该秘密的数据失效。轮换前查目标版本官方说明并在副本验证，不要把它当普通服务密码处理。

配置变更也需要发布流程。每次修改说明原因、影响、验证和回退；先运行 manage.py check 和 Nginx 语法检查，再 reload 或 restart。配置文件语法正确不代表业务正确，还要登录、调用 API、执行后台任务并检查权限。

插件和自定义代码生命周期

插件最容易让源码安装失去可维护性。每个插件都可能带来 Python 依赖、数据库模型、URL、权限、后台任务和静态文件。采用前记录插件用途、维护仓库、版本、支持的 NetBox 范围、许可证、数据迁移和退出方案。

安装插件的一般步骤包括在 NetBox 虚拟环境安装固定版本、加入 PLUGINS、配置 PLUGINS_CONFIG、运行迁移与静态文件收集，再重启应用和 worker。具体命令必须使用插件当前文档。不要使用无版本上限的 pip install plugin 让下次重建自动获得不同版本。

插件升级与 NetBox 升级应分别测试。先在恢复副本安装目标 NetBox 和当前插件，确认是否兼容；再升级插件，运行迁移和功能测试。若多个插件存在依赖冲突，需要选择受支持组合，而不是在生产虚拟环境强制降级共享库。

删除插件也不是从配置中删名字这么简单。插件可能已创建数据库表、自定义对象和业务依赖。先导出所需数据，停止外部消费，按插件卸载文档执行迁移或清理。数据库表是否保留、未来是否可能重装，都要做决定。

Custom scripts 和 reports 也属于受控代码。它们应进入版本控制，有代码评审、测试和权限。能修改大量对象的脚本先提供 dry-run 或结果预览，并限制可执行用户。脚本错误可能在几秒内破坏 Source of Truth，风险不低于应用插件。

监控与日志

NetBox 成为事实来源后，需要监控的不只是进程在线。最小监控包括 HTTPS 可达与证书、请求延迟和错误、Gunicorn 进程、netbox-rq、后台任务失败、PostgreSQL、Redis、主机资源、文件系统、备份和恢复演练。

HTTP 检查应访问健康或轻量端点，确认应用、数据库和认证链路的实际状态。只检查 443 端口可能在 Nginx 正常而 Gunicorn 故障时仍显示成功。另一方面，不要每隔几秒执行高成本 API 查询作为健康检查。

Gunicorn 监控关注 worker 重启、超时、内存和请求积压。worker 频繁被杀可能是内存、超时或应用错误。增加 worker 前先看主机内存和数据库连接。单个插件页面慢不应通过全局扩大 timeout 隐藏。

后台 worker 监控关注服务状态、队列长度、任务失败、最长等待和执行时间。Web 页面正常但 worker 停止时，Webhook、报表、脚本或其他后台任务可能积压。告警中应能区分应用入口与后台执行。

PostgreSQL 监控包括连接、事务、锁、磁盘、备份、复制和慢查询。Redis 监控包括内存、连接、延迟、驱逐和持久化。磁盘告警要留出数据库迁移和备份空间，不能等到百分之百才处理。

NetBox、Gunicorn、Nginx、PostgreSQL 和 Redis 日志应有时间同步、轮转和保留。集中日志时过滤秘密，限制访问。临时调试提高日志级别后要恢复，避免长期产生敏感或大量数据。

监控还要覆盖数据服务能力。可以定期用低权限 token 读取 /api/status/ 或一个固定对象，确认 API 和权限。关键自动化流水线记录最近一次成功同步和数据时间，NetBox可用但消费停止时也能告警。

上线前的故障演练

第一项演练是应用进程故障。停止 netbox，确认 Nginx 返回明确错误且监控告警；启动后验证登录和 API。再停止 netbox-rq，确认 Web 仍可用但后台任务告警，恢复后积压能处理。这样值班人员能区分两类故障。

第二项演练是 Redis 不可用。观察 Web、缓存和后台任务表现，确认日志和告警。恢复后检查失败任务是否自动重试、是否需要人工重新执行，以及重复执行是否会产生副作用。

第三项演练是数据库不可用。停止测试数据库或阻断连接，确认应用错误、超时和监控；恢复后检查连接重建、未完成事务和对象一致性。生产演练可在隔离副本完成，不能为测试随意中断真实平台。

第四项演练是证书到期或域名错误。测试监控能在到期前告警，客户端严格验证证书。API 消费者不应通过永久关闭证书验证来规避问题。

第五项演练是应用升级失败。在副本中模拟 upgrade.sh 或插件迁移失败，执行预定回退：停止新版本、恢复数据库和配置、切回旧应用、启动并验证。演练会暴露“旧代码仍在，但数据库已经不可逆迁移”的假回退。

第六项演练是整机丢失。从空白 Ubuntu 主机开始，用部署文档、制品和备份恢复。记录实际 RTO、缺失秘密、手工步骤和依赖。如果只有原管理员能恢复，说明文档和自动化不足。

变更和日常运维节奏

每日关注服务、队列、数据库、磁盘、证书和备份。每周复审后台失败任务、应用错误、异常登录和容量趋势。每月检查操作系统更新、依赖支持状态、token 和账号。每季度执行恢复抽查、权限复审和插件维护状态检查。

所有变更进入统一记录。普通配置调整、插件安装、NetBox 升级、Python 或 PostgreSQL 升级的风险不同，应使用不同维护窗口和验证范围。变更后更新版本清单和架构文档，避免实际状态与交付文件分叉。

应用和数据库不要长期停留在停止支持的版本，但也不应无测试追逐最新 release。建立版本观察、测试、批准和发布节奏。安全更新和重大兼容问题可以加速，普通功能版本按组织窗口执行。

容量扩展基于证据。前端慢要区分 Nginx、Gunicorn、插件和数据库；后台任务慢要看队列和 worker；数据库增长要看对象、变更日志和附件。不要因为设备数翻倍就机械把所有资源翻倍。

日常创建对象的操作不应依赖超级管理员。按数据域分组授权，定期检查离职账号、长期 token 和自动化权限。平台管理员负责系统可用，数据 owner 负责对象正确，两种责任不能混为一人。

备份与恢复

最关键的是 PostgreSQL。一个基础逻辑备份示意：

export BACKUP_DIR="/srv/backup/netbox"
sudo install -d -m 0700 "${BACKUP_DIR}"
sudo -u postgres pg_dump --format=custom \
  --file="${BACKUP_DIR}/netbox-$(date +%F-%H%M).dump" netbox

该命令需在目标数据库环境验证，远程数据库要使用受控 .pgpass 或备份系统，不在脚本中写密码。大规模数据库可能需要物理备份、WAL 归档和专业 PostgreSQL 工具。

同时备份：

configuration.py 和其他本地配置。
gunicorn.py、Nginx 配置和 systemd 本地修改。
媒体文件、自定义脚本、reports 和插件配置。
NetBox 与插件版本清单。
证书与密钥，采用独立加密和权限控制。
部署和恢复文档。

恢复演练使用与备份匹配的 NetBox 版本。先恢复 PostgreSQL，再恢复配置、媒体和插件，运行必要检查，启动服务。隔离环境要禁用真实 webhook、邮件和自动化执行，防止恢复测试产生生产变更。

恢复验收包括登录、对象数量、关键关系、附件、API、后台任务、插件和一个自动化消费者。只有实际恢复成功，备份策略才可信。

升级流程

升级不是简单 git pull。先阅读目标版本 release notes 和官方 upgrading guide，确认支持的 Python、PostgreSQL、Redis、插件和必经版本。跨多个大版本时按官方升级路径逐段执行。

升级前：

保存当前 NetBox、Python、数据库、Redis 和插件版本。
备份数据库、配置、媒体和自定义内容。
在恢复副本上演练升级。
记录数据库迁移时长和额外空间。
建立维护窗口和回退条件。

使用版本目录时，可把新 release 解压到新目录，将本地配置、插件和自定义内容按官方方式迁移，然后运行新目录的 upgrade.sh。确认成功后切换 /opt/netbox 符号链接并重启服务。不要直接覆盖旧目录导致无法快速恢复应用代码。

数据库迁移一旦写入新 schema，单纯切回旧代码可能不安全。真正回退通常需要恢复升级前数据库和对应配置。因此升级前备份和演练是硬条件。

升级后验证服务、manage.py check、登录、API、后台任务、插件、静态文件、权限和关键自动化。观察日志与性能一个业务周期，再删除旧版本。

故障定位

浏览器返回 502 时，先检查 Nginx upstream 和 Gunicorn：

sudo nginx -t
systemctl status nginx netbox
journalctl -eu netbox
curl -I http://127.0.0.1:8001/

页面返回 400 或 DisallowedHost 时，检查访问域名与 ALLOWED_HOSTS，以及反向代理是否保留 Host。不要用 * 长期掩盖配置错误。

NetBox 服务启动失败时，进入虚拟环境运行 manage.py check，再检查数据库和 Redis：

sudo -u netbox /opt/netbox/venv/bin/python \
  /opt/netbox/netbox/manage.py check
pg_isready -h 127.0.0.1
redis-cli ping

后台任务不执行时检查 netbox-rq、Redis、队列和任务日志。Web 正常不代表 worker 正常。

静态文件丢失时检查 upgrade.sh 是否完成 collectstatic、Nginx alias 和文件权限。不要给目录 chmod 777；应让 Nginx 只读静态文件，让 NetBox 服务账号拥有必要写目录。

数据库迁移失败时停止继续发布，保存错误和备份状态。确认目标版本、插件迁移和权限，不要手工修改 Django migration 表来“跳过”失败。

交付清单

源码部署完成后，交付物应包括：版本与 release 来源、架构与端口、主机与 DNS、PostgreSQL 和 Redis位置、服务账号、配置与秘密位置、证书、systemd unit、Nginx 配置、备份恢复记录、升级回退手册、监控告警、管理员与权限、插件清单和责任人。

运行监控至少覆盖服务状态、HTTP 健康、证书到期、主机资源、PostgreSQL、Redis、后台任务失败、磁盘、备份和恢复演练。日志要集中或可检索，并控制敏感信息。

验收会议不只演示登录，还要演示重启、创建对象、API 查询、后台任务、备份与一次隔离恢复证据。这样交付的是可运行的平台，而不是一台“今天能打开”的服务器。

正式上线检查表

正式切换前先冻结部署变量。确认生产域名解析到正确入口，证书覆盖域名且证书链完整，Nginx upstream 与 Gunicorn 监听一致，ALLOWED_HOSTS 不包含无关通配，数据库和 Redis 只允许应用网络访问。DNS TTL 若需要切换，应提前调整并记录恢复时间。

检查操作系统服务账号没有交互式登录和不必要 sudo 权限。configuration.py、秘密文件和证书私钥只允许必要账号读取；应用代码、静态文件和媒体目录的所有权分别符合读写需求。不要通过放宽整个 /opt/netbox 权限解决单个目录问题。

检查数据库创建者、owner、schema 权限和备份用户。应用账号不应拥有 PostgreSQL 超级权限。数据库备份至少完成一次，并在隔离环境确认可以读取。若使用远程数据库，验证应用节点重启、数据库切换和网络短时中断后的连接恢复。

检查 Redis 是否只监听受控地址，是否配置了现场要求的认证和持久化。确认任务与缓存使用的逻辑数据库或实例符合配置，避免与其他应用共享后键空间冲突。执行一个后台任务并观察 netbox-rq 完成，不能只测试 redis-cli ping。

检查管理员和日常用户。初始超级管理员启用强认证并限制使用；普通数据维护通过组与对象权限授权；自动化 token 绑定专用账号、注明用途和到期时间。使用每类账号实际登录或调用 API，验证能做和不能做的操作。

检查邮件、Webhook、SSO 或 LDAP 等可选集成。只启用当前需要的能力，失败时日志和告警明确。Webhook 接收端使用测试地址完成一次创建和更新事件，再切换生产目标，避免首次上线直接触发真实流水线。

检查数据初始化。至少建立一个测试 Site、Role、Manufacturer、Device type、Device、Prefix 和 IP，验证对象关系、搜索和 API。测试对象在验收后删除或明确标记，不要让演示数据进入正式自动化。

检查浏览器和 API 行为。使用支持的浏览器访问 HTTPS，确认没有混合内容和证书警告；通过反向代理访问时确认生成 URL 使用正式协议和域名；上传并下载一个测试附件；执行 REST API 查询和权限负向测试。

检查监控。人为停止一次 netbox-rq，确认告警到达；恢复后确认关闭。模拟磁盘阈值和证书到期可以使用测试规则，不必真正耗尽磁盘。备份任务失败也必须告警，而不是只记录日志。

切换窗口中安排明确角色：执行人、数据库负责人、网络与证书负责人、业务验收人和回退决策人。实时记录每一步开始、结果和证据。出现超出预期的问题时暂停，不在压力下同时修改多个层面。

分阶段回退判定

安装阶段失败且尚未写入生产数据时，回退相对简单：停止 NetBox 服务，保留日志，删除或隔离失败版本目录，修复依赖后重新执行。不要删除 PostgreSQL 数据库，除非确认它是空白测试库并经过批准。

首次上线后但尚未对外开放时，如果 Nginx、证书或权限配置不符合要求，可以继续保持入口关闭，修复后重新验收。此时不需要恢复数据库，因为 schema 和应用版本没有改变，但要确认没有外部自动化开始写入。

配置变更后出现故障，优先恢复上一个受控配置，运行语法和应用检查，再 reload。不要在同一窗口连续叠加多个“试试”的修改。保存失败配置用于复盘，不能只在 shell history 中寻找差异。

插件安装失败时，先判断数据库迁移是否执行。尚未迁移可以移除插件配置和包并恢复环境；已经迁移则必须按插件官方卸载或恢复升级前数据库。直接删除 Python 包可能让 Django 启动时仍引用插件模型。

NetBox 版本升级失败时，回退需要应用代码、Python 环境、配置、插件和数据库一致。若数据库迁移已运行，切换旧符号链接不一定可用。标准做法是停止服务，恢复升级前 PostgreSQL 和配套文件，再启动旧版本并验证。

发生数据误删除时，不要继续大量写入或用手工 SQL猜测修复。确定受影响时间和对象，保护当前数据库副本，在隔离环境恢复最近备份并分析差异。根据 RPO 选择整库恢复、对象级重建或审计记录辅助恢复。恢复动作由数据 owner 批准。

回退完成的标准不是进程变绿，而是登录、API、后台任务、关键对象、权限和自动化消费都恢复。记录丢失的数据窗口和后续补录计划，并更新部署或变更手册，防止同类故障再次发生。

小结

NetBox 源码安装的核心链路是 PostgreSQL、Redis、NetBox、Gunicorn、netbox-rq 和 Nginx。可靠部署要锁定明确 release，使用受支持的依赖版本，保护配置秘密，逐层验证数据库、缓存、应用、worker 和 HTTPS，并把备份恢复、升级回退和监控纳入同一份交付。

下一篇使用社区维护的 netbox-docker 项目完成 Docker Compose 部署，重点讨论仓库与镜像版本匹配、override、secrets、持久化、健康检查、备份和升级，而不是只运行一次 docker compose up。

参考资料

NetBox Documentation：Installation，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/
NetBox Documentation：PostgreSQL，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/1-postgresql/
NetBox Documentation：Redis，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/2-redis/
NetBox Documentation：NetBox Components，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/3-netbox/
NetBox Documentation：Gunicorn，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/4a-gunicorn/
NetBox Documentation：HTTP Server，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/5-http-server/
NetBox Documentation：Upgrading NetBox，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/installation/upgrading/
NetBox Documentation：Configuration，检索日期 2026-06-12，https://netboxlabs.com/docs/netbox/configuration/
netbox-community/netbox Releases，检索日期 2026-06-12，https://github.com/netbox-community/netbox/releases
PostgreSQL Documentation：Backup and Restore，检索日期 2026-06-12，https://www.postgresql.org/docs/current/backup.html