摘要

  • 这篇文章不再讨论新功能，而是聚焦生产环境最实际的升级、验证和回滚问题。
  • 核心目标是把 4.4.7 -> 4.5.3 的升级流程做成可重复、可验证、可快速撤回的操作手册。
  • 如果你的 NetBox 已经接入脚本、插件或生产流程，这篇比功能扩展更值得优先准备。

一、背景

从 NetBox 1.0 写到 4.0 后，我在自动化中心里踩过一个很典型的坑：

我以为“数据有了、脚本有了”，后面只要继续堆能力就行。 结果一到生产变更窗口，大家最关心的不是“新功能”，而是：

  • 升级会不会中断现网
  • 插件会不会炸
  • 出问题能不能 10 分钟内回滚

说白了，NetBox 要成为事实源，前提不是“功能新”，而是“可持续升级且可控回退”。

所以这篇 5.0，我只做一件事： 把 4.0 -> 4.5.3 升级，做成一套我自己在生产环境可复用的流程。

二、目标

升级回滚

这次升级我定了 3 个目标：

  1. 升级过程可重复，不靠个人经验
  2. 出问题可快速回滚，不赌运气
  3. 升级后可验证，结论可量化

我最终采用的流程是：

三、环境准备

基础环境

  • NetBox 当前版本：4.4.7
  • 目标版本：4.5.3
  • Python：3.10+
  • PostgreSQL：建议 14+
  • Redis：按官方兼容版本

我会提前准备的内容

  • 变更窗口（建议 60~120 分钟）
  • 回滚窗口（建议预留 30 分钟）
  • 预生产一套同版本环境（很关键）

备份范围（必须全量）

  • PostgreSQL 数据库
  • media/（附件、图片等）
  • NetBox 配置文件（如 configuration.py）
  • 反向代理与 systemd 配置（如果有改动）

四、步骤一：升级前预检查

我先把“能提前爆雷的点”一次性扫出来。

1）版本与依赖检查

bash
# 当前 NetBox 版本
cd /opt/netbox
source /opt/netbox/venv/bin/activate
python3 netbox/manage.py --version

# Python 版本
python3 -V

# 数据库连通性
python3 netbox/manage.py dbshell -c "SELECT version();"

2）插件兼容性检查（重点）

bash
# 导出当前插件列表
pip freeze | grep -E "netbox|plugin" > /tmp/netbox_plugins_before.txt
cat /tmp/netbox_plugins_before.txt

我自己的原则是： 插件没确认兼容 4.5.3，就先下线插件再升级主程序。

3）系统健康检查

bash
python3 netbox/manage.py check
python3 netbox/manage.py showmigrations | tail -n 20

五、步骤二：全量备份（可直接回滚）

这一步我不省。

1）数据库备份

bash
export PGPASSWORD='你的数据库密码'
pg_dump -h 127.0.0.1 -U netbox -Fc netbox > /backup/netbox_$(date +%F_%H%M).dump

2）媒体与配置备份

bash
tar -czf /backup/netbox_media_$(date +%F_%H%M).tar.gz /opt/netbox/netbox/media
tar -czf /backup/netbox_config_$(date +%F_%H%M).tar.gz /opt/netbox/netbox/netbox/configuration.py /etc/nginx /etc/systemd/system

3）备份有效性抽检（我会做）

  • 随机恢复到预生产，确认数据库可导入
  • 确认 media/ 能正常读取
  • 确认服务可启动并可登录

六、步骤三：预生产演练（强烈建议）

我会先在预生产完整跑一遍升级脚本，记录耗时和报错点。 这个步骤能把“生产故障”提前变成“演练问题”。

演练通过标准：

  • 首页可访问
  • 登录正常
  • 设备/IP/接口查询正常
  • 自动化脚本调用 API 正常
  • 核心插件可用（或已明确下线）

七、步骤四：生产升级到 4.5.3

以下以源码部署思路为例，Docker 部署同理，核心是流程一致。

1）进入维护窗口并停服务

bash
sudo systemctl stop netbox netbox-rq

2）拉取目标版本并安装依赖

bash
cd /opt/netbox
git fetch --all --tags
git checkout v4.5.3

source /opt/netbox/venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

3）执行数据库迁移与静态文件处理

bash
python3 netbox/manage.py migrate
python3 netbox/manage.py collectstatic --no-input
python3 netbox/manage.py remove_stale_contenttypes --no-input
python3 netbox/manage.py clearsessions

4）启动服务并观察日志

bash
sudo systemctl start netbox netbox-rq
sudo systemctl status netbox netbox-rq --no-pager
journalctl -u netbox -u netbox-rq -n 200 --no-pager

八、步骤五：升级后验收（我用的清单）

1）页面与核心对象验收

  • 能登录
  • Device/IP/Interface/Cable 可正常增删改查
  • 标签、自定义字段、Webhook 正常

2）API 验收（自动化中心最关心）

bash
curl -H "Authorization: Token <TOKEN>" \
  -H "Content-Type: application/json" \
  https://your-netbox/api/status/

3）自动化联调验收

  • 现有同步脚本可跑通
  • 关键接口无 401/403 异常
  • 关键任务耗时与升级前对比无明显劣化

九、步骤六：失败回滚（标准动作）

如果出现以下情况，我会立刻回滚：

  • 数据迁移异常且无法快速修复
  • 核心 API 持续不可用
  • 自动化中心关键链路中断

回滚流程

  1. 停服务
  2. 切回旧版本代码
  3. 恢复数据库 dump
  4. 恢复 media/config
  5. 启动服务并验收

示例：

bash
sudo systemctl stop netbox netbox-rq

cd /opt/netbox
git checkout v4.0.x   # 你的上一稳定版本标签

dropdb -h 127.0.0.1 -U netbox netbox
createdb -h 127.0.0.1 -U netbox netbox
pg_restore -h 127.0.0.1 -U netbox -d netbox /backup/netbox_xxx.dump

tar -xzf /backup/netbox_media_xxx.tar.gz -C /
tar -xzf /backup/netbox_config_xxx.tar.gz -C /

sudo systemctl start netbox netbox-rq

十、这次升级后的实际收益

对我来说，最大的变化不是“版本号变了”，而是：

  • 升级变成了流程，不再是个人英雄主义
  • 回滚有预案，团队心理负担明显下降
  • 自动化中心敢接入更多动作，因为底座更稳了

换句话说： NetBox 作为事实源，终于从“能用”进入“可运营”。

十一、结语

以前我总觉得，NetBox 升级是“运维动作”。 现在我更认可一句话：

升级能力本身，就是平台工程能力。

因为你只有把升级和回滚做成标准件，后面的自动化、AIOps、智能运维，才有长期演进的基础。