OpenStack 故障往往跨越多个服务。一个实例处于 ERROR，可能来自配额、调度、镜像、网络、存储、计算节点或消息队列。有效的排障方法不是同时重启所有服务，而是先确定请求停在哪一层，再围绕 request ID 串联证据。
## 1. 先保存基本信息
```bash
openstack server show VM_NAME -f yaml
openstack server event list VM_NAME
openstack port list --server VM_NAME
openstack volume list --server VM_NAME
openstack console log show VM_NAME
```
记录实例 ID、项目、状态、task_state、power_state、host、instance_name、镜像、flavor、端口、卷、错误信息和最近变更。不要在收集证据前删除实例或强制改状态。
## 2. 使用 Request ID 串联日志
OpenStack API 响应和实例事件通常包含 request ID。先从客户端增加调试输出或查看 server event，再在 nova-api、nova-scheduler、nova-conductor、nova-compute、neutron-server、cinder 和 glance 日志中查询同一个 ID。
```bash
openstack --debug server create ...
openstack server event list VM_NAME
```
日志路径随容器化部署、发行版和运维框架不同。不要假设所有服务都位于 /var/log，应先确认部署方式和日志平台。
## 3. 实例创建失败的分层排查
### API 与配额
症状：请求立即失败、401/403、Quota exceeded、资源引用不存在。
检查：
```bash
openstack token issue
openstack quota show
openstack flavor show FLAVOR
openstack image show IMAGE
openstack network show NETWORK
```
### 调度与 Placement
症状：NoValidHost，实例很快进入 ERROR。
检查：
```bash
openstack compute service list
openstack hypervisor list --long
openstack resource provider list
openstack resource provider inventory list RP_UUID
openstack resource provider allocation show CONSUMER_UUID
```
确认资源库存、allocation、主机聚合、可用区、extra specs、NUMA、Huge Page、CPU pinning 和 PCI/SR-IOV 约束。hypervisor 显示有空闲资源，不代表所有调度条件都满足。
### 计算节点与虚拟化
症状：实例已经调度到主机，但 Spawn failed、libvirt error 或卡在 BUILD。
检查：
```bash
openstack server show VM_NAME -c OS-EXT-SRV-ATTR:host \
-c OS-EXT-SRV-ATTR:instance_name
openstack compute service list --host COMPUTE_HOST
systemctl status nova-compute
virsh list --all
```
继续检查 nova-compute、libvirt、qemu、容器运行时、磁盘空间、权限、镜像缓存、KVM 模块和消息队列连接。
## 4. 网络不通的排查顺序
1. 实例系统是否正确识别网卡、MAC 和 IP。
2. Neutron Port 是否 ACTIVE，fixed IP 与 MAC 是否一致。
3. Port 的 binding host、vnic_type 和 profile 是否正确。
4. 安全组入口与出口规则是否允许流量。
5. DHCP、Metadata、L2 agent、OVN/OVS 控制面是否正常。
6. 子网网关、Router 和 Floating IP 关联是否正确。
7. 物理网桥、physnet、VLAN Trunk、MTU 和上联交换机是否一致。
常用命令：
```bash
openstack port show PORT_ID -f yaml
openstack security group rule list SECURITY_GROUP
openstack network agent list
openstack router show ROUTER
openstack floating ip show FLOATING_IP
```
在计算节点检查 tap、vnet、OVS/OVN 端口和 libvirt 网卡映射时，必须先通过实例属性确认正确主机和 instance_name。不要根据 VM 名称猜测底层设备。
## 5. SR-IOV 端口不通
除了普通网络检查，还要确认：
- BIOS 和 IOMMU 已启用，内核启动参数正确。
- PF/VF 数量、驱动和链路状态正常。
- sriov-nic-agent Alive，physical_device_mappings 正确。
- 端口 binding:vnic_type=direct，绑定到预期计算节点。
- VLAN、MAC、spoof check、trusted mode 与交换机配置一致。
- NUMA、PCI alias 或 Placement 资源没有冲突。
Guest 修改 MAC 可能导致 SR-IOV agent 把端口标记为 DOWN。先对照 Neutron 记录与 VF 实际 MAC，再判断是否允许 guest 改动。
## 6. 控制台能打开但 SSH 不通
优先检查：
- 系统是否完成启动，cloud-init 是否失败。
- SSH 服务是否监听。
- SSH Key 是否注入正确，用户名称是否匹配镜像。
- 安全组是否放行 TCP 22 和正确来源网段。
- 路由、Floating IP、NAT 和上游 ACL 是否正确。
- 镜像内部防火墙、SELinux 和网卡配置是否阻断。
不要为了排障长期开放全部端口或使用镜像内固定弱密码。
## 7. 卷挂载与分离异常
控制面检查：
```bash
openstack volume show VOLUME_ID -f yaml
openstack volume attachment list --volume-id VOLUME_ID
openstack server volume list VM_NAME
openstack volume service list
```
底层检查应根据 Ceph RBD、iSCSI、FC、NVMe-oF 等后端执行。重点对照：Cinder 状态、Nova attachment、计算节点设备映射、libvirt XML 和存储后端连接。
卷卡在 in-use 不等于设备仍在使用，也不能直接把数据库改成 available。先确认 guest 已卸载、实例已停止写入、libvirt 不再引用设备、后端映射已断开，再使用受支持的 attachment 修复或状态管理命令。
## 8. 镜像启动失败
常见原因：
- 实际格式与 disk_format 元数据不一致。
- 镜像缺少 VirtIO 驱动或 bootloader。
- 文件损坏、校验不一致或 Glance 后端不可达。
- 镜像属性与 flavor、架构、固件模式不匹配。
- 计算节点缓存损坏或磁盘空间不足。
使用 openstack image show、qemu-img info、控制台日志和 nova-compute 日志交叉确认。修改镜像属性前先验证真实格式，避免掩盖问题。
## 9. 服务和消息队列
```bash
openstack compute service list
openstack network agent list
openstack volume service list
```
服务显示 down 时检查主机时间、进程、数据库、消息队列、TLS、网络和心跳配置。批量重启可能造成更多重复任务和状态错乱，应一次处理一个服务，并观察队列和请求恢复情况。
## 10. 修复后的验证
- 实例状态、任务状态和电源状态一致。
- 新建测试实例能完整通过调度、网络和存储流程。
- 实际业务网络从源到目标可达。
- 卷经过 guest 读写和重启验证。
- 监控、告警和服务心跳恢复。
- 清理临时安全组、测试端口、调试账号和快照。
- 记录时间线、根因、影响、修复和预防措施。
如果故障涉及数据库不一致、孤儿资源或底层存储残留，应在备份后制定明确修复步骤，并优先使用项目提供的管理工具；直接 SQL 只能作为经过验证的最后手段。
## 参考资料
- https://docs.openstack.org/nova/latest/admin/support-compute.html
- https://docs.openstack.org/nova/latest/admin/troubleshooting.html
- https://docs.openstack.org/neutron/latest/admin/index.html
- https://docs.openstack.org/cinder/latest/admin/index.html