故障排除¶
防火墙¶
由于防火墙设置和自定义的性质，bifrost 不会更改节点上的任何本地防火墙。用户必须确保运行 bifrost 的节点的防火墙允许被引导的节点连接到以下端口
67/UDP for DHCP requests to be serviced
69/UDP for TFTP file transfers (Initial iPXE binary)
6385/TCP for the ironic API
8080/TCP for HTTP File Downloads (iPXE, Ironic-Python-Agent)
如果您遇到任何其他问题，强烈建议在尝试部署单个节点时使用 tcpdump 来捕获和检查两个节点之间的流量交换。
节点锁定错误¶
这是由于 ironic 中的节点状态检查线程，它是一个锁定操作，因为它利用 IPMI。最佳操作是重试该操作。如果这种情况经常发生，可能需要进行调整。
示例错误
NodeLocked: Node 00000000-0000-0000-0000-046ebb96ec21 is locked by
host $HOSTNAME, please retry after the current operation is completed.
构建 IPA 镜像¶
排查涉及 IPA 的问题可能非常耗时。IPA 开发人员强烈建议用户构建自己的自定义 IPA 镜像，以便注入诸如 SSH 密钥之类的内容，并启用代理调试，这必须在自定义镜像中完成，因为目前没有机制可以通过内核命令行启用调试。
可以使用多种方式构建自定义 IPA 镜像，最常用的机制是使用 diskimage-builder，因为这些发行版通常比 Tiny Core Linux 具有更好的硬件支持。
- DIB 镜像
https://docs.openstack.org/ironic-python-agent-builder/2025.2/admin/dib.html
- TinyIPA
https://docs.openstack.org/ironic-python-agent-builder/2025.2/admin/tinyipa.html
- 有关 diskimage-builder 的文档，请参阅：
应该注意的是，diskimage-builder 的安装和使用步骤，以创建 Bifrost 的 IPA 镜像与 ironic 相同。请参阅：https://docs.openstack.org/ironic/2025.2/install/deploy-ramdisk.html
完成构建后，您需要将镜像文件复制到 /var/lib/ironic/httpboot 文件夹中。
IPA 代理出现意外/未知错误¶
许多由于 IPA 代理导致的问题可以通过构建自定义 IPA 镜像来解决。请参阅 构建 IPA 镜像，了解有关构建您自己的 IPA 镜像的信息。
通过控制台获取 IPA 日志¶
默认情况下，bifrost 将代理日志设置为记录到系统控制台。由于硬件差异，您可能需要调整传递到部署 ramdisk 的参数。这可以完成，如下所示在 ironic.conf 中所示
kernel_append_params=nofb nomodeset vga=normal console=ttyS0 systemd.journald.forward_to_console=yes
参数会因您的硬件类型和配置而异，但是
systemd.journald.forward_to_console=yes设置是默认设置，并且仅适用于基于 systemd 的 IPA 镜像。上面的示例有效地禁用了内核尝试设置视频模式的所有尝试，将控制台定义为 ttyS0 或第一个串行端口，并指示 systemd 将日志定向到控制台。
设置后，重新启动 ironic 服务，例如
systemctl restart ironic并尝试重新部署节点。您将需要查看正在发生的系统控制台。如果可能，您可以使用ipmitool并将输出写入日志文件。
获取对运行自定义镜像 IPA 的节点的 SSH 访问权限¶
自定义构建的镜像需要将用户刻录到镜像中。通常，用户会使用 diskimage-builder devuser 元素来实现这一点。有关此的更多详细信息，请参见 https://docs.openstack.org/diskimage-builder/2025.2/elements/devuser/README.html。
示例
export DIB_DEV_USER_USERNAME=customuser
export DIB_DEV_USER_PWDLESS_SUDO=yes
export DIB_DEV_USER_AUTHORIZED_KEYS=$HOME/.ssh/id_rsa.pub
ironic-python-agent-builder -o /path/to/custom-ipa -e devuser debian
ssh_public_key_path is not valid¶
Bifrost 要求执行 bifrost 的用户在其用户主目录中有一个 SSH 密钥，或者用户定义一个变量来告诉 bifrost 在哪里识别此文件。定义此变量为有效文件后，可以重新运行部署 playbook。
生成新的 ssh 密钥¶
请参阅 ssh-keygen 命令的手册页。
定义特定的公钥文件¶
用户可以通过使用 ssh_public_key_path 变量来定义特定的公钥文件。这可以在 group_vars/inventory/all 文件中设置，或在 ansible-playbook 命令行中使用 -e 命令行参数设置。
示例
ansible-playbook -i inventory/bifrost_inventory.py deploy-dynamic.yaml -e ssh_public_key_path=~/path/to/public/key/id_rsa.pub
注意：需要使用匹配的私钥才能登录到部署的机器。
从 TinyIPA 切换到另一个 IPA 镜像¶
在 Newton 周期内，Bifrost 的默认 IPA 镜像已更改为基于 Tiny Core Linux 的 TinyIPA，这大大缩短了测试的启动时间，但预计硬件支持较少。在 Yoga 周期中，默认镜像已更改为基于 CentOS 的镜像。
如果全新安装或重新安装，您希望更改为基于 DIB 或任何其他 IPA 镜像，则需要执行以下步骤
删除现有的 IPA 镜像 ipa.kernel 和 ipa.initramfs。
编辑
playbooks/roles/bifrost-ironic-install/defaults/main.yml文件，并更新ipa_kernel_upstream_url和ipa_kernel_upstream_url设置为新的 URL。对于基于 DIB 的镜像，这些 URL 将是https://tarballs.opendev.org/openstack/ironic-python-agent/dib/files/ipa-centos9-master.kernel和https://tarballs.opendev.org/openstack/ironic-python-agent/dib/files/ipa-centos9-master.initramfs分别。执行安装 playbook，并将自动下载设置的文件。如果未在重新安装之前删除文件，则不会替换它们。或者，可以直接在磁盘上替换文件。内核和 ramdisk 所在的默认位置是在
/httboot/中。
测试环境中的节点注册和配置¶
以下是在测试环境中排查节点注册和配置的几个步骤
节点电源和配置状态¶
如果节点注册失败，请确保节点的电源状态为“On”。默认情况下，电源状态可能是“None”。您可以使用以下命令打开节点电源并使其可用
baremetal node power on <NODE>
baremetal node manage <NODE>
baremetal node provide <NODE>
一旦节点电源打开并且配置状态为 available，请重新运行注册过程
./bifrost-cli enroll baremetal-inventory.json
成功注册后，继续进行部署
./bifrost-cli deploy baremetal-inventory.json
有关测试环境的文档，请参阅 Bifrost 测试环境指南。
有关使用 Baremetal CLI 的更多信息，请参阅 Bifrost 用户 HOWTO。
