安全升级到最新版:netbox-proxbox版本配对与升级完整指南

原创2026-11-15 12:39:201,676 阅读

安全升级到最新版:netbox-proxbox版本配对与升级完整指南

netbox-proxbox 是一款将 Proxmox VE 虚拟化集群与 NetBox 集成在一起的 NetBox 插件,它能自动同步虚拟机、集群、存储、防火墙等数据到 NetBox 中。而它的安全升级关键在于版本配对(version pairing):插件必须与独立的后端服务 proxbox-api 按官方推荐的组合版本一起部署。本指南带你走完从检查、配对到升级验证的完整流程,让升级过程安全可控、零惊吓。

netbox-proxbox 插件与 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

几个升级前必做的小检查:

  1. 确认你当前的插件版本。版本常量声明在 netbox_proxbox/compat.py(稳定区间 4.5.8–4.7.99)与 netbox_proxbox/__init__.py(version = "0.0.31")中;
  2. 备份数据库和配置——这是官方文档反复强调的第一步;
  3. 如果从很旧的版本(如 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 部署,拉取新的镜像标签并重建容器即可。升级后打开插件首页,确认后端状态卡片显示正常。

proxbox-api 后端端点配置详情,用于确认后端版本配对与连接状态

第 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 保持运行,否则同步任务不会执行。

升级后的验证清单 ✅

重启后建议依次验证三件事:

  1. 插件已注册:用 Django shell 打印 apps.is_installed('netbox_proxbox'),确认为 True,而不是只看 NetBox 能启动;
  2. 后端认证正常:首页 FastAPI 状态卡片能完成一次带鉴权的版本检查,proxbox_fix_tokens 诊断显示密钥已注册(针对迁移 0075 的密钥目标指纹绑定);
  3. 执行一次真实同步:在 Proxbox 首页点击 Sync Actions 发起一次作用域同步,确认状态为 Completed。

Proxbox 首页:端点状态卡片与 Latest Sync Jobs 同步任务历史,用于升级后验证

如果后端是从早于 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 回执,失败或超时后可安全重试。

0.0.31 原生集群绑定对应的 NetBox Clusters 集群列表页

常见问题(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 起只是纯库存记录,不会触发任何后端连接,这属于设计行为。

参考资料

记住黄金法则:先备份 → 先升后端 → 再升插件 → 迁移 + 审计 → 重启 → 验证同步。按这个顺序走完,你的 netbox-proxbox 升级就能又快又稳地到达最新版。🚢

登录后查看全文
netbox-proxbox