安全升级到最新版:netbox-proxbox版本配对与升级完整指南
安全升级到最新版:netbox-proxbox版本配对与升级完整指南
netbox-proxbox 是一款将 Proxmox VE 虚拟化集群与 NetBox 集成在一起的 NetBox 插件,它能自动同步虚拟机、集群、存储、防火墙等数据到 NetBox 中。而它的安全升级关键在于版本配对(version pairing):插件必须与独立的后端服务 proxbox-api 按官方推荐的组合版本一起部署。本指南带你走完从检查、配对到升级验证的完整流程,让升级过程安全可控、零惊吓。
为什么版本配对如此重要 🤝
netbox-proxbox 由两部分组成:
- 插件本体:安装在 NetBox 中的
netbox-proxbox(即本仓库),负责界面、模型与同步编排; - 后端服务:独立部署的
proxbox-api,负责与 Proxmox API 通信,插件通过 REST、SSE 和 WebSocket 与它通信。
两者版本不对齐,同步任务、认证密钥、数据库结构都可能出现不兼容。更隐蔽的坑是:如果你只升级了 NetBox 而没有升级整套 Proxbox 插件族,NetBox 启动时会静默跳过这些插件——导航栏、同步任务、API 路由全部消失,健康探测却仍返回 200。这就是为什么升级前必须确认配对版本。
💡 官方在 COMPATIBILITY.md 中明确警告:升级到 NetBox 4.7 之前,请先升级所有 Proxbox 家族插件(netbox-proxbox、netbox-pbs、netbox-pdm、netbox-ceph、netbox-packer),并用
manage.py shell验证每个插件都真正注册成功。
升级前检查:当前版本配对矩阵 🔍
当前官方发布的运行时配对(详见 COMPATIBILITY.md 与 docs/installation/upgrading.md):
| 组件 | 当前配对版本 | 说明 |
|---|---|---|
| netbox-proxbox | v0.0.31 |
本仓库最新稳定版 |
| proxbox-api | v0.0.29 |
⭐ 必须先于插件部署 |
| proxmox-sdk | v0.0.15 |
后端内部依赖 |
| netbox-sdk | v0.0.13 |
后端 REST 依赖(不含语义 MCP 桥接) |
| NetBox | 4.5.8 – 4.7.99 |
支持整个 4.5/4.6/4.7 稳定线 |
| Python | ≥ 3.12 |
几个升级前必做的小检查:
- 确认你当前的插件版本。版本常量声明在 netbox_proxbox/compat.py(稳定区间
4.5.8–4.7.99)与 netbox_proxbox/__init__.py(version = "0.0.31")中; - 备份数据库和配置——这是官方文档反复强调的第一步;
- 如果从很旧的版本(如
0.0.29.post6配对proxbox-api 0.0.27.post4)跨版本升级,先阅读 docs/release-notes/index.md 中每一版的变更摘要,尤其是中间版本引入的数据库迁移。
五步安全升级流程 🚀
第 1 步:先升级 proxbox-api 后端
顺序是本流程的灵魂——先部署 proxbox-api 0.0.29,再升级插件(0.0.31 依赖 0.0.29 新增的端点级集群绑定能力)。
系统方式:
source /opt/proxbox-api/venv/bin/activate
pip install -U proxbox-api
sudo systemctl restart proxbox
如果是 Docker 部署,拉取新的镜像标签并重建容器即可。升级后打开插件首页,确认后端状态卡片显示正常。
第 2 步:升级 netbox-proxbox 插件
进入 NetBox 目录并升级插件(PyPI 安装):
cd /opt/netbox/netbox
source /opt/netbox/venv/bin/activate
pip install -U netbox-proxbox
如果你是从 Git 检出目录安装的,改为执行 pip install -e /opt/netbox/netbox/netbox-proxbox。
第 3 步:运行数据库迁移
python3 manage.py migrate netbox_proxbox
升级 0.0.31 会依次应用两个迁移:0107_v0_0_30_release(创建原生集群绑定、端点级 SSH 服务与云镜像 SSH 绑定表)和 0108_v0_0_31_schema_validation(只读校验,不做自动修复)。两者在独立事务中提交:即使 0108 失败,0107 仍保留,回滚 0108 是空操作,重新应用会再次校验。遇到意外 schema 时,官方建议保留现场并获取经过评审的修复方案,而不是"静默修复"。
第 4 步:静态文件与 SSH 凭据审计
python3 manage.py collectstatic --no-input
python3 manage.py audit_node_ssh_credentials --fail-on-missing
第二条命令是自 0.0.27 起的强制升级闸门:它检查所有启用了 API + SSH 的节点是否都建立了本地 NodeSSHCredential。对报告为阻塞(blocking)的节点补齐本地凭据后重跑,直到零阻塞再重启。禁用节点和纯 API 节点只作提示,不阻塞重启。
第 5 步:重启 NetBox 并验证
sudo systemctl restart netbox
注意:较新的版本已将同步任务迁移到 NetBox Jobs 和默认 RQ 队列,请确保标准的 NetBox RQ worker 保持运行,否则同步任务不会执行。
升级后的验证清单 ✅
重启后建议依次验证三件事:
- 插件已注册:用 Django shell 打印
apps.is_installed('netbox_proxbox'),确认为True,而不是只看 NetBox 能启动; - 后端认证正常:首页 FastAPI 状态卡片能完成一次带鉴权的版本检查,
proxbox_fix_tokens诊断显示密钥已注册(针对迁移0075的密钥目标指纹绑定); - 执行一次真实同步:在 Proxbox 首页点击 Sync Actions 发起一次作用域同步,确认状态为
Completed。
如果后端是从早于 0.0.13 的版本升级上来的,还请在首页点一次 Full Update,它会重建 ProxboxVirtualMachineSyncState(包括 proxmox_vm_id),修复早期创建的虚拟机的同步状态。
0.0.31 新特性速览 ✨
这次升级你拿到的不只是"安全",还有新能力(详见 docs/release-notes/version-0.0.31.md):
- 原生 NetBox 集群绑定:每个 Proxmox 端点可以拥有一个原生 NetBox Cluster,受保护的
sync-cluster动作在一个事务中对齐端点、集群与同步状态,且不会按名字抢占已有归属的集群; - 端点级 SSH 应用服务:SSH 访问采用
SSH 凭据 → 应用服务(type SSH)→ IP 地址 → Proxmox 端点的归属链,凭据支持本地 Fernet 加密或可选的 netbox-openbao 集成; - 可验证的云镜像 SSH 绑定:Cloud Image 构建可将选定的 Proxmox 节点与后端身份文件路径绑定到端点,写入持久的 SHA-256 回执,失败或超时后可安全重试。
常见问题(FAQ)❓
Q:我从 0.0.25 或更早版本直接升到 0.0.31,会跳过什么东西吗?
不会。迁移按序原子应用,数据库只需跑一次 migrate netbox_proxbox。但请务必逐版浏览 docs/release-notes/index.md 的变更摘要——例如 0.0.27 的 SSH 凭据闸门、0.0.29 的敏感数据授权都属于行为变化。
Q:反向代理后的 proxbox-api 升级后连不上了?
如果你在升级前后使用了 *-nginx 镜像,请在 FastAPI 端点编辑页勾选 Use HTTPS(使用捆绑 mkcert 证书时同时取消 Verify SSL)。
Q:升级后某些端点功能"消失"了?
先确认是不是插件被 NetBox 静默跳过了(检查 apps.is_installed)。另外,enabled=False 的端点从 0.0.20.post3 起只是纯库存记录,不会触发任何后端连接,这属于设计行为。
参考资料
- 官方升级文档:docs/installation/upgrading.md
- 兼容性矩阵:COMPATIBILITY.md
- 0.0.31 版本说明:docs/release-notes/version-0.0.31.md
- NetBox 版本支持策略实现:netbox_proxbox/compat.py
- 完整版本历史:docs/release-notes/index.md
记住黄金法则:先备份 → 先升后端 → 再升插件 → 迁移 + 审计 → 重启 → 验证同步。按这个顺序走完,你的 netbox-proxbox 升级就能又快又稳地到达最新版。🚢



