问题说明

适用于排查弹性裸金属添加网关节点、添加裸金属节点、获取硬件信息、PXE 启动、创建实例、打开控制台、挂载云盘和获取就绪状态等异常。此类问题需要同时检查管理节点、网关节点、部署网络、IPMI、BIOS、PXE/TFTP、裸金属 Agent、iSCSI 和 Guest OS 内部组件。

现象

• 添加网关节点失败，提示 LUN 未加载或存储访问异常。
• 添加裸金属节点失败，提示 IPMI 用户名密码错误、超时或无法建立 IPMI 会话。
• 获取硬件信息失败，PXE 启动后卡住，或报 Failed to load ldlinux.c32。
• PXE 启动失败，裸金属无法从网关节点获取部署网络地址或无法访问 TFTP。
• Windows 弹性裸金属打开控制台失败，报 open remote baremetal instance console port failed。
• 弹性裸金属添加云盘失败，提示无 iSCSI 会话。
• 获取就绪状态失败，报 502 bad gateway。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；弹性裸金属、网关节点、部署网络、IPMI、PXE、TFTP、iSCSI、VNC Server、裸金属 Agent
• 版本：4.x-4.8.38

可能原因

• SAN 主存储 LUN 只映射给计算节点，未映射给弹性裸金属网关节点，导致添加网关节点失败或存储访问异常。
• 网关节点部署网络与裸金属 PXE 网卡不在同一二层/VLAN，或裸金属节点同时接入其他 DHCP 网络，导致 PXE 获取到错误地址。
• 网关节点网卡、bond、bridge 配置残留 IP，平台绑定的部署网络网卡与实际提供 DHCP/TFTP 的地址不一致，导致裸金属节点无法获取部署网络地址或无法访问 TFTP。
• 管理节点到裸金属 IPMI 网络不通、丢包严重、UDP 623 双向策略未放通，或 BIOS 未开启 LAN 上 IPMI，导致添加裸金属节点时提示 IP、端口、用户名、密码错误或会话超时。
• 底层修改过 IPMI 密码或 BMC 信息，但平台侧未同步更新，导致裸金属节点电源状态未知、实例就绪状态未连接。
• 裸金属 BIOS 未开启目标网卡 PXE/UEFI 启动，或服务器存在带内/带外多个 IPMI 地址、IPMI network sharelink 未关闭，导致获取硬件信息时回传 IPMI 地址与平台记录不一致。
• iPXE、vmlinuz、initrd.img、网卡固件或网卡驱动与服务器硬件不兼容，表现为 Failed to load ldlinux.c32、x86_64/vmlinuz no such file or directory、no more network device、加载 initrd 后卡住或缺少 bnx2x 等网卡固件。
• 裸金属实例镜像未按弹性裸金属要求制作，Guest OS 内缺少裸金属 Agent、Python 运行环境、open-iscsi/iSCSI 组件，或 Agent 版本存在已知兼容问题，导致获取就绪状态、挂载云盘或探测失败。
• 裸金属实例内部部署网络 IP 与平台分配 IP 不一致，或纳管原系统未重新通过 DHCP 获取部署网络地址，导致网关无法通过部署网络访问实例 Agent。
• Windows 弹性裸金属镜像未安装 VNC Server 或裸金属 Agent，导致打开控制台失败。
• 后端存储正在变更、iSCSI target 不可用或实例与网关节点无法建立 iSCSI 会话，导致获取就绪状态超时、挂载云盘失败或实例启动后出现 I/O 异常。

排查步骤

1. 明确故障阶段

• 记录裸金属实例 UUID、网关节点 UUID、裸金属节点 IPMI 地址、部署网络、存储类型和故障时间。
• 区分异常发生在添加网关节点、添加裸金属节点、获取硬件信息、创建实例、控制台、挂载云盘还是就绪探测阶段。
• 对 PXE/硬件信息问题，建议打开 IPMI 控制台，观察裸金属节点从网卡启动后的实时输出。

2. 检查网关节点、存储映射和部署网络

添加网关节点失败或 PXE 无法获取部署网络地址时，先确认网关节点基础条件。

ip addr
ip route
bridge link
systemctl status zstack-baremetal-tftpd
ss -lunpt | egrep "dhcp|tftp|:69"

• 如果使用 SAN 主存储，确认主存储 LUN 已同时映射给网关节点；只映射给计算节点会导致网关节点添加失败或 LUN 未加载。
• 确认平台上填写的网关节点 IP 与网关节点实际部署网络 IP 一致。
• 确认网关节点部署网络网卡与裸金属 PXE 网卡在同一二层/VLAN。
• 确认网关节点 bond 或物理网卡上没有残留 IP。若平台基于 bond 创建 bridge，但 IP 残留在 bond 或旧 bridge 上，DHCP/TFTP 可能绑定到错误地址。
• 如果部署网络配置错误，先按现场变更流程清理残留地址，再重新配置平台中的部署网络 IP；完成后重新添加或重连网关节点。

3. 检查 IPMI、BMC 与 BIOS 设置

ping <ipmi-ip>
ipmitool -I lanplus -H <ipmi-ip> -U <user> -P '<password>' chassis power status
ipmitool -I lanplus -H <ipmi-ip> -U <user> -P '<password>' lan print 1

• 确认管理节点到 IPMI 地址网络稳定，无明显丢包。
• 检查 BIOS 中是否启用 LAN 上 IPMI、目标网卡 PXE/UEFI 启动。
• 如果 ipmitool 报 Unable to establish IPMI v1.5/RMCP session、Unable to establish LAN session 或超时，检查 UDP 623 双向访问策略，尤其是返回方向 UDP 623 -> 10240-65535 是否放通。
• 如果服务器存在带内和带外两个 IPMI 地址，需关闭不使用的共享网络或 IPMI network sharelink，避免获取硬件信息时识别到与平台记录不一致的 IPMI 地址。
• 如果底层修改过 IPMI 密码或 BMC 信息，需同步更新平台侧裸金属节点 IPMI 信息；旧版本不支持 UI 修改时，需要通过受控 CLI/API 方式更新。

4. 检查 PXE 第一阶段 DHCP 和 TFTP 下载

tail -n 200 /var/log/zstack/baremetalv2/dnsmasq.log
tail -n 200 /var/log/messages
ls -l /var/lib/zstack/baremetalv2/tftpboot/
ls -l /var/lib/zstack/baremetalv2/tftpboot/x86_64/

• 在 dnsmasq.log 中检查 DHCP offer 的 MAC 地址是否为裸金属 PXE 网卡 MAC。
• 如果出现多个 MAC 地址，确认裸金属是否接入了其他 DHCP 网络，或非 PXE 网卡是否干扰了启动流程。
• 在 /var/log/messages 中检查 TFTP 访问记录，确认 ipxe.efi、boot.ipxe、x86_64/vmlinuz、x86_64/initrd.img 是否被正常请求和下载。
• 如果报 Failed to load ldlinux.c32，优先确认当前启动模式，通常建议改为 UEFI 引导后复测。
• 如果报 x86_64/vmlinuz no such file or directory，确认 tftpboot/x86_64/ 下文件是否存在、权限是否正常，并检查网关节点是否重连或重新部署过裸金属服务。

5. 检查 PXE 第二阶段和硬件兼容性

• 第一阶段：网卡固件 PXE 从 DHCP 获取地址。
• 第二阶段：加载 vmlinuz/initrd.img 后，临时 Linux 系统再次获取地址并回传硬件信息。
• 第一阶段成功并不表示第二阶段成功；如果第二阶段拿不到地址，需检查 initrd 驱动、网卡兼容性、DHCP/TFTP 服务和交换机 VLAN。
• 如果加载 initrd 后卡住，或控制台提示缺少 bnx2x、ngbe 等网卡固件/驱动，通常是 initrd 内缺少对应硬件驱动，需要收集服务器型号、网卡型号、固件版本、控制台截图和网关节点日志后联系技术支持评估驱动或引导文件适配。
• 如果控制台提示 no more network device，可在技术支持确认后评估更换新版 iPXE 或升级网卡固件。
• 如果服务器存在特殊显卡、较新网卡、Hygon CPU 或厂商固件兼容问题，需打开 IPMI 控制台记录卡住位置，并优先联系硬件厂商确认固件升级方案。
• 不建议在未确认版本和硬件型号的情况下自行替换 ipxe.efi、vmlinuz 或 initrd.img；如必须替换，应先备份原文件并由技术支持确认替换包来源和回退方法。

6. 检查创建实例失败和镜像模板

• 创建实例前确认裸金属镜像已按弹性裸金属要求制作，包含裸金属 Agent、必要的网络配置、iSCSI/open-iscsi 组件以及对应操作系统依赖。
• 如果创建实例时报 failed to create provision configurations for baremetal2 instance，检查网关节点是否已按存储类型完成必要配置；使用企业版 ZCE 等特定存储时，确认网关节点是否已添加对应 xdc 配置。
• 如果实例启动后无法进入系统，检查镜像内 initramfs、网卡命名、根盘识别、iSCSI 启动依赖和系统日志。

7. 检查就绪状态、Agent 和部署网络连通性

获取就绪状态失败时，优先按 “MN -> 网关节点 nginx -> 裸金属实例 Agent” 链路排查。

# 裸金属实例内部
systemctl status zstack-baremetal-instance-agent.service
journalctl -u zstack-baremetal-instance-agent.service -n 100 --no-pager
tail -n 200 /var/log/zstack/baremetal2/bm-instance-agent.log
ip addr
ss -tlnp

# 网关节点
tail -n 100 /var/log/nginx/error.log
curl -v http://<instance-provision-ip>:<agent-port>/

• 如果报 502 Bad Gateway 或 BM.1001 nginx connection error，说明管理节点通常已访问到网关节点 nginx，但 nginx 到实例 Agent 的 upstream 不通。继续根据 nginx error 日志区分 Connection refused、timed out、no live upstreams 或配置错误。
• 如果实例 Agent 未启动，检查 Python 运行环境、Agent 安装状态和服务日志；缺少 Python 依赖时需补齐依赖后重启 Agent。
• 如果 Agent 正常但网关访问超时，检查实例部署网络 IP 是否与平台分配 IP 一致，必要时在实例内重新通过 DHCP 获取部署网络地址。
• 纳管原系统场景中，若实例内部仍使用旧部署网络地址，可在系统内执行 dhclient 重新获取 IP；确认有效后再评估是否写入开机脚本。
• 如果报 failed to ping baremetal2 instance through gateway 且日志包含 iSCSI 相关错误，检查实例内 open-iscsi/iSCSI 组件是否安装并运行。
• 如果网关节点重连后出现就绪探测超时，可在无生产业务影响时停用相关弹性裸金属资源后重连网关节点，再逐步启用资源验证。

8. 检查控制台、Agent 和 VNC Server

• Windows 弹性裸金属实例控制台依赖 Agent 和 VNC Server，例如 TigerVNC。若报 open remote baremetal instance console port failed，先确认镜像模板是否已安装 VNC Server 并允许服务自启动。
• 检查 Windows 防火墙、VNC 服务监听端口和实例 Agent 状态。
• 如果是裸金属节点带外控制台打开无内容，确认服务器 BMC 是否要求 HTTPS 访问；部分型号使用 HTTP 打开不会自动跳转 HTTPS，需要手动使用 HTTPS 访问带外管理界面。

9. 检查云盘挂载和 iSCSI 会话

# 裸金属实例内部
systemctl status iscsid
iscsiadm -m session
iscsiadm -m node
rpm -qa | egrep "iscsi|open-iscsi"

• 添加云盘失败并提示无 iSCSI 会话时，先确认实例内部是否安装 iSCSI 组件、iscsid 是否运行、实例到网关节点或存储网络是否可达。
• 如果实例底层可看到网关节点 iSCSI 会话但平台仍提示无会话，检查裸金属 Agent 版本；旧版本 Agent 可能存在会话识别异常，需要升级到与当前云平台版本匹配的 Agent。
• 如果实例中出现其他 target 或未知磁盘，检查 open-iscsi 是否开机自动登录历史 target，必要时清理无关 session/node 记录并调整 node.startup 策略。
• 如果存储侧正在变更或 iSCSI target 不稳定，需等待存储变更完成后再执行就绪探测、挂载云盘或启动实例。

10. 验证恢复

zstack-ctl status
systemctl status zstack-baremetal-tftpd

• 重新获取裸金属节点硬件信息，确认 IPMI 控制台中的 PXE、TFTP、vmlinuz/initrd 加载过程正常。
• 创建或重试弹性裸金属实例，确认实例能进入系统。
• 在实例内部确认 Agent、VNC Server、iscsid 和网络地址状态正常。
• 在平台侧重新获取就绪状态、打开控制台、挂载云盘，并记录恢复时间和验证结果。

注意事项

• 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
• 涉及网关节点重连、部署网络变更、iPXE/vmlinuz/initrd 替换、Agent 升级、iSCSI session 清理、存储配置调整或数据库修改等高风险操作时，应先完成备份、审批和技术支持确认。
• 以上信息仅作为排查方向参考，不能替代当前现场日志、控制台输出、网络抓包和版本兼容性确认。