来源与分类
问题元数据
- 问题编号：ZSV-9030。
- 组件/产品：ZSphere、分布式交换机和端口组。
- 状态：部分已修复；历史环境中已经存在的不一致网桥名称不会在升级时自动统一。
- 优先级/严重程度：P0。
- 受影响版本：4.10.11及以前版本中已经形成网桥名称不一致数据，并计划升级至4.10.12及以后版本的环境。
- 首个修复版本：4.10.12修复修改VLAN后再扩容主机时的网桥名称一致性；4.10.13修复历史网桥名称不一致时的主机重连兼容问题。
- 问题定义日期：2025-06-06。
- 工程确认日期：2025-06-09。
- 最后更新时间：2026-09-01。
问题描述
在 4.10.12 之前的版本中，集群内修改端口组 VLAN 后再新增主机，新主机可能按照修改后的 VLAN 重新生成网桥名称，而老主机继续使用修改前的网桥名称。这样会导致同一个端口组在不同主机上的网桥名称不一致。
正确行为是同一个端口组在集群内所有主机上使用相同的网桥名称。ZSphere 4.10.12 调整了网桥名称生成逻辑，后续扩容时优先沿用该端口组已有的网桥名称记录，但升级过程不会自动修改历史环境中已经不一致的宿主机网桥和控制面记录。
ZSphere 4.10.12还增加了网桥名称一致性检查。历史环境直接升级到4.10.12时，已有网桥名称不一致的主机可能无法重连。ZSphere 4.10.13通过ZSV-9054兼容了历史主机重连，但不会自动统一已经存在的不一致网桥，跨主机迁移风险仍需在升级前处理。
现象
- 在管理节点运行检查脚本后，同一个端口组对应的数据库内部资源标识（字段名为
l2NetworkUuid）存在多个不同的bridgeName，脚本输出：
bridgeName不相同: no- 修改端口组VLAN后新增主机，老主机和新主机上的网桥名称不同。例如老主机使用
br_dvs17_60，新主机使用br_dvs17。 - 虚拟机在网桥名称不同的主机之间迁移失败，可能显示：
Cannot get interface MTU on 'br_dvs17_60': No such device- 历史环境直接升级到4.10.12后，部分主机可能无法重新连接，并提示主机实际网桥名称与默认交换机记录的网桥名称必须一致。
影响
- 使用受影响端口组的虚拟机可能无法在网桥名称不同的主机之间迁移。
- 直接升级到4.10.12时，历史网桥名称不一致的主机可能无法重新连接。
- 4.10.13及以后版本允许历史主机重连，但不会自动修复宿主机真实网桥与控制面记录不一致，迁移限制仍可能存在。
- 当前没有证据表明该问题会直接造成虚拟机磁盘数据丢失。
规避方案
升级前检查
- 在管理节点创建
4.10.12-upgrade-network-check.sh，并写入以下内容：
#!/bin/bash
# 数据库连接配置
DB_USER="root"
DB_PASS="zstack.mysql.password"
DB_NAME="zstack"
if [ $# -ge 1 ]; then
DB_PASS="$1"
echo "使用用户传入的密码"
else
echo "未传入密码参数, 使用默认密码"
fi
# 查询所有端口组对应的数据库内部资源标识
l2NetworkUuids=$(mysql -u $DB_USER -p$DB_PASS $DB_NAME -N -e "SELECT DISTINCT l2NetworkUuid FROM L2NetworkHostRefVO;")
# 检查是否获取到资源标识
if [ -z "$l2NetworkUuids" ]; then
echo "没有找到任何l2NetworkUuid"
exit 1
fi
# 遍历每个资源标识
for uuid in $l2NetworkUuids; do
echo "处理 l2NetworkUuid: $uuid"
# 查询该资源标识在不同主机上记录的网桥名称
bridgeNames=$(mysql -u $DB_USER -p$DB_PASS $DB_NAME -N -e "SELECT bridgeName FROM L2NetworkHostRefVO WHERE l2NetworkUuid = '$uuid';")
# 检查是否获取到网桥名称
if [ -z "$bridgeNames" ]; then
echo "没有找到bridgeName"
continue
fi
# 判断所有网桥名称是否相同
firstBridgeName=$(echo "$bridgeNames" | head -n 1)
allSame=true
for name in $bridgeNames; do
if [ "$name" != "$firstBridgeName" ]; then
allSame=false
break
fi
done
# 输出检查结果
if $allSame; then
echo "bridgeName相同: yes"
else
echo "bridgeName不相同: no"
echo "该l2NetworkUuid对应的所有信息:"
mysql -u $DB_USER -p$DB_PASS $DB_NAME -e "SELECT * FROM L2NetworkHostRefVO WHERE l2NetworkUuid = '$uuid';"
fi
echo "----------------------------------------"
done- 在管理节点执行脚本：
bash 4.10.12-upgrade-network-check.sh如果现场数据库密码不是脚本中的默认值，可将数据库root用户密码作为第一个参数传入：
bash 4.10.12-upgrade-network-check.sh '<数据库root用户密码>'- 检查脚本输出：
- 所有端口组资源记录均显示
bridgeName相同: yes时，继续完成其他升级前检查。 - 任意端口组资源记录显示
bridgeName不相同: no时，停止升级并保存完整输出。
Note:
该脚本只检查数据库中L2NetworkHostRefVO.bridgeName的一致性，不会修改配置，也不能代替宿主机实际网桥检查。
发现不一致后的处理
- 不要直接修改数据库中的
L2NetworkHostRefVO.bridgeName或SystemTagVO，也不要在宿主机上直接重命名、删除或重建网桥。 - 收集以下信息并联系研发制定针对当前环境的修复方案：
- 当前版本、计划升级的目标版本和升级路径；
- 扫描脚本完整输出；
- 受影响的集群、分布式交换机、端口组、端口组对应的数据库内部资源标识和主机 UUID；
- 每台相关主机的实际网桥、VLAN子接口和
bridge link输出； - 使用该端口组的虚拟机及其所在主机；
- 相关VLAN修改、主机扩容和迁移失败的操作时间。
- 在维护窗口内停止或迁出使用受影响端口组的虚拟机。若跨主机迁移已经失败，应按研发方案安排虚拟机停机。
- 由研发提供与现场版本和网络状态匹配的修复脚本或操作方案，同时统一以下三类状态：
- 宿主机上的真实Linux网桥；
- 数据库中的
L2NetworkHostRefVO.bridgeName； - 端口组对应的
kvm::bridge::<bridgeName>网桥系统标签。
- 修复后重新运行扫描脚本，并验证：
- 同一个
l2NetworkUuid在所有主机上的bridgeName一致； - 相关主机可以正常重连；
- 使用受影响端口组的虚拟机可以正常启动；
- 虚拟机可以在相关主机之间双向迁移。
- 完成上述验证后再继续升级。
当前没有适用于所有历史环境的通用无停机修复方案。目标网桥名称需要结合现有系统标签、各主机真实网桥、当前VLAN和虚拟机分布确定，不能直接采用扫描结果中的第一条网桥名称。
受影响产品
- 产品：ZSphere。
- 产品线：ZVF。
- 组件：分布式交换机、端口组和主机网络。
- 版本：4.10.11及以前版本中已经形成网桥名称不一致数据，并计划升级至4.10.12及以后版本的环境。
- 触发条件：修改端口组VLAN后新增主机，且新老主机为同一个端口组记录或创建了不同的网桥名称。
修复状态
- 当前状态：部分已修复。
- 修复版本：
- 4.10.12：ZSV-9030修复后续修改VLAN并扩容主机时的网桥名称一致性问题。
- 4.10.13：ZSV-9054允许历史网桥名称不一致的主机在升级后重连。
- 修复限制：以上版本不会自动统一升级前已经存在的不一致网桥。升级前扫描发现不一致时，仍需由研发提供针对性修复方案。
- 关联补丁/修复包：暂无独立通用修复包。