只要手动搭过 OpenStack，多少都见过这个画面：明明 provider network 创建成功，subnet 也都是 ACTIVE，结果 openstack server create 一执行，实例状态直接变成 ERROR，fault 里写着 PortBindingFailed: Binding failed for port…。第一次遇到这个报错的人十有八九是懵的，因为从网络侧看，好像什么都不缺，但虚拟机就是起不来。
这篇文章就专门拆解这个坑。我会把我在实验环境里排查 PortBindingFailed 的思路、命令和修复过程完整写出来，包括这个报错到底出在哪一层、为什么 provider network 特别容易触发、以及改完配置之后怎么验证。无论你是自己搭 all-in-one 环境，还是在多节点环境里做网络配置，按这条链路走一遍，基本都能定位问题。
1. 报错现场还原：什么样子的配置组合会触发 PortBindingFailed
1.1 一套典型到不能再典型的 flat 网络配置
先说我在环境里复现时的操作。假设控制节点和计算节点在一台设备上，物理网卡是 eth1，准备做一个 flat 类型的 provider network，让虚拟机直接接入物理二层网络。创建网络和子网的命令大概长这样：
openstack network create \ --provider-network-type flat \ --provider-physical-network physnet1 \ --external \ --share provider_net openstack subnet create \ --network provider_net \ --subnet-range 10.10.200.0/24 \ --allocation-pool start=10.10.200.100,end=10.10.200.200 \ --gateway 10.10.200.1 \ provider_subnet接着用最小规格的镜像创建实例：
openstack server create \ --image cirros \ --flavor m1.tiny \ --nic net-id=provider_net \ --availability-zone nova:compute-1 \ demo-instance这里指定--availability-zone是为了把实例固定在某个计算节点上复现问题。如果不指定，调度器可能会把实例分到其他节点，排查时反而要花时间确认到底落在哪台机器上。
执行完命令之后等十几秒，再用openstack server show demo-instance查看，发现 status 是 ERROR，fault 字段里出现了本文标题里的那个报错。
1.2 报错的实际形态和容易混淆的兄弟报错
PortBindingFailed 这个错误会在不同地方出现，最常见的两个位置是 openstack server show 的 fault 字段，以及 nova-compute 日志里。日志中类似：
nova.compute.manager ... PortBindingFailed: Binding failed for port 6f8a...这个报错经常被和另外两个问题搞混，我提一下方便区分。一个是NoValidHost，这是调度阶段找不到合适主机；另一个是 libvirt 启动时报internal error，这已经是 qemu 层面的问题，和端口绑定无关。PortBindingFailed 的关键特征在于：实例已经完成了调度，也已经分配到了计算节点，但是在真正启动虚拟机之前，nova 向 neutron 请求的虚拟端口没能成功绑定到宿主机的网络设施上。
1.3 先理解这个错到底发生在哪一层
很多人一看到 PortBindingFailed 就想去 neutron 那边找原因，方向是对的，但容易忽略一点：端口绑定动作的实际执行者不是 neutron-server，而是各计算节点上的 neutron agent。nova 负责把实例调度到某台计算节点，然后告诉 neutron"我要在这台机器上用这个网络"，neutron 收到请求后，让对应节点上的 agent 去做物理层面的绑定。
所以这个报错的核心矛盾通常集中在三个方面：创建网络时声明的物理网络名称和 agent 配置里的映射名是否一致、agent 本身是否在线且配置正确、以及计算节点上是否真的存在可用的物理网桥或物理网卡。后面我会逐个展开。
2. PortBinding 到底在"绑"什么：nova、neutron 与 agent 的一次接力
2.1 一次实例创建过程中的端口接力
要理解为什么一个小小的端口绑定失败能把整个实例卡死，得先看清楚一条虚拟网线是怎么从 neutron 数据库一路插到物理网卡上的。整个链条是这样走的：
nova 在决定启动实例之后，会先为每个网卡调用一次 neutron 的 create port 操作。neutron-server 接收到请求，先由 ML2 plugin 判断这个网络属于什么类型，比如 flat、vlan 还是 vxlan，然后看它挂在哪个 mechanism driver 下。如果部署用的是 linuxbridge 或 openvswitch，plugin 就会请求对应计算节点上的 agent 去执行绑定。
agent 在宿主机上会完成一系列操作，比如创建 linux bridge，或者向 OVS 网桥添加端口，把虚拟机的虚拟网卡和物理网卡桥接起来。绑定成功之后，agent 把结果回报给 neutron-server，端口状态才会变成 ACTIVE。只有等这一步完成，nova 才敢调用 libvirt 去真正启动虚拟机。
整个过程中，nova 并不会一直无限期等待。如果 agent 在规定时间内没有完成绑定，或者直接返回了失败状态，nova 就把实例标记为 ERROR，抛出的就是这个 PortBindingFailed。
2.2 谁在负责绑定：linuxbridge 与 ovs 的差异
同样叫 PortBinding，底层机制其实不一样。linuxbridge agent 的工作方式是创建一个 brq 开头的 linux bridge，把物理网卡和虚拟机的 tap 设备都加进去。ovs agent 则是通过 openvswitch 网桥实现，常见做法是把物理网卡加进 br-ex 网桥，再把虚拟机的虚拟网卡通过 internal port 或 patch port 接进来。
这两种机制在 provider network 场景下有个共同点：计算节点必须有一条真实的物理链路，连接到目标二层网络中。区别只在于桥接工具不同，一个用的是内核自带的 bridge 模块，一个用的是 ovs 的 datapath。
2.3 为什么 provider network 的坑比 tenant network 多
这个问题我思考过很久，最后发现根本原因在于物理依赖。租户网络如果是 vxlan，agent 创建的是隧道接口，对物理网卡的映射要求没那么敏感，只要网络上能通就行。但 provider network 是直接把虚拟机和外部物理网络放在同一个二层域里，计算节点必须真实接入这个二层域，靠的就是物理网卡或者桥接到物理网卡的网桥。
这导致一个结果：所有计算节点的 agent 配置必须统一正确，只要有一台机器的物理接口映射写错，调度器一旦选中它，就必然出现 PortBindingFailed。所以排查这类问题时，不要只看网络本身，要优先检查宿主机的 agent 配置和实际网桥状态。
3. 几个最容易踩中的根因：映射错位、agent 失联与 vnic_type 不匹配
3.1 physical_network 名字对不上：最隐蔽的低级错误
在所有 PortBindingFailed 案例里，我见到最多的是"名字对不上"。创建网络时指定了--provider-physical-network physnet1，但 agent 配置里写的映射名可能叫 provider，或者反过来。这个字段的作用就是让 neutron 知道，这个 external network 应该落在宿主机的哪条链路上。
linuxbridge agent 的配置在 /etc/neutron/plugins/ml2/linuxbridge_agent.ini：
[linux_bridge] physical_interface_mappings = physnet1:eth1ovs agent 的配置在 /etc/neutron/plugins/ml2/openvswitch_agent.ini：
[ovs] bridge_mappings = physnet1:br-ex创建网络时写的值、agent 配置里冒号前面的 key、以及实际物理网卡或网桥，三者的对应关系必须一致。我整理成一张表方便对照：
| 位置 | 参数 | 示例值 | 说明 |
|---|---|---|---|
| 网络创建命令 | --provider-physical-network | physnet1 | 管理员自己定义的名字 |
| linuxbridge agent | physical_interface_mappings | physnet1:eth1 | key 必须等于物理网络名 |
| OVS agent | bridge_mappings | physnet1:br-ex | key 必须等于物理网络名 |
| 宿主机网桥 | br-ex | 包含 eth1 | OVS 场景的硬性要求 |
如果你在 OVS 场景下把bridge_mappings = physnet1:br-ex配好了，但宿主机上根本没有 br-ex，让虚拟机插队的"面板"不存在，绑定自然失败。这时候需要在每台计算节点上创建网桥并添加物理网卡：
ovs-vsctl add-br br-ex ovs-vsctl add-port br-ex eth1 ip link set br-ex up这是很多教程里一笔带过、但实际部署时最容易漏掉的关键步骤。
3.2 agent 状态异常或配置不完整
第二个高发原因是 agent 本身出了问题。这里要说明的是，ML2 的 mechanism driver 配置必须和实际运行的 agent 匹配。假如 ml2_conf.ini 里写的是 linuxbridge，但计算节点上起的是 openvswitch agent，绑定就会失败，因为 neutron-server 在等待一个不存在的 agent 回报。
先看 agent 在线状态：
openstack network agent list输出里每一行代表一个 agent，重点关注 Alive 和 State 两列。如果某个 agent 显示 dead，或者 host 对应的 agent 没有出现在列表里，那基本可以确定问题出在这里。修完 agent 配置后重启服务，再等几秒钟心跳上报，然后重新查看列表。
另一个特别容易被忽略的情况是：配置文件改了，但 agent 没有重启。linuxbridge agent 和 ovs agent 都不会动态加载配置文件，修改之后必须 systemctl restart，这是我在实际环境里替别人擦过无数次屁股的坑。
3.3 vnic_type 与底层能力不匹配
还有一种场景：端口本身要求了某种虚拟网卡类型，但底层物理设施根本不支持。比如手动创建端口时用了 --vnic-type direct，这通常意味着要求 SR-IOV 直通，如果物理网卡和宿主机的 SR-IOV 配置没跟上，agent 根本无从下手，只会返回 binding 失败。
排查时用端口 id 查看：
openstack port show <port_id> -c vnic_type -c binding:vif_type正常情况下普通虚拟机使用 vnic_type=normal 或者不指定。如果你在 provider network 上遇到绑定失败，而且端口显示 vnic_type=direct，先确认是不是创建端口时指定过特殊类型。很多情况下，删掉端口重新用默认模式创建就能解决。
3.4 OVN 部署下的另类场景
如果用的是较新的发行版，默认架构可能是 ML2/OVN，这时候端口绑定的执行者变成了 ovn-controller，而不是传统意义上的 linuxbridge agent 或 OVS agent。报错信息虽然一样，但排查入口不同：优先看 openstack network agent list 里有没有 ovn-controller，确认 agent 是否 UP，以及对应计算节点是否已经注册到 OVN 的 chassis 列表中。
OVN 场景下，传统网桥查不到是正常的，不需要在计算节点上找 brq 网桥。如果 agent 在线但绑定失败，重点去看 OVN 层面的日志，通常会有更明确的上下文提示。这类案例不多，但既然标题是"使用 provider network 创建实例"，大版本差异还是值得提一句。
4. 一步一步追日志：从 nova-compute 到 neutron-server 再到 agent
4.1 先从 nova 日志里找到端口 id
排查 PortBindingFailed 的第一件事，不是马上改配置，而是通过 nova 日志找到那个绑定失败的端口 id，后面所有动作都围绕它展开。
在计算节点上执行：
grep -i "PortBindingFailed" /var/log/nova/nova-compute.log | tail -n 20日志里会包含类似 "Binding failed for port 6f8a..." 的记录，把这个端口 id 抄下来。如果有多条记录，以时间靠后、和当前实例对应的那一条为准。
拿到端口 id 之后，去看端口详情：
openstack port show 6f8a...重点看三个字段：
- binding:host_id：应为目标计算节点的主机名。如果为空，说明 agent 根本没绑定。
- binding:vif_type：正常应该是 bridge、ovs 或 dvs，如果为空或不合理，说明绑定流程中断。
- status：DOWN 是正常的，绑定完成后才会 ACTIVE。
这一步能快速判断问题到底出在 agent 没响应，还是绑定之后状态上报异常。
4.2 用 agent 状态和宿主机网桥互相验证
接下来看两件事：agent 是否在线，以及宿主机上的网络设施是不是符合预期。
查看整体 agent 状态：
openstack network agent list如果是 linuxbridge 场景，还要在计算节点上看网桥实际状态：
brctl show正常情况下，应该能看到一个和该端口对应的 brq 网桥，桥上有物理网卡（比如 eth1）以及一个待接入的 tap 设备。如果网桥上只有 tap 没有物理网卡，说明桥接链路上少了一环，绑定不可能成功。
如果是 OVS 场景：
ovs-vsctl show检查 br-ex 是否存在、是否 up、物理网卡是否已经加入。这一步是判断"面板是否接好"的最直接证据。
4.3 在 neutron-server 和 agent 日志里找最终原因
端口、agent、网桥都查完以后，大概率已经能定位问题了。但如果你还是不确定，或者想看到更精确的失败原因，可以去翻 neutron-server 和 agent 的日志。
控制节点上的 neutron-server 日志位置通常在 /var/log/neutron/neutron-server.log，搜索关键字：
grep -i "binding" /var/log/neutron/neutron-server.log | tail -n 100计算节点上的 agent 日志根据部署产物不同，可能是 /var/log/neutron/neutron-linuxbridge-agent.log 或 /var/log/neutron/neutron-openvswitch-agent.log，搜索失败相关的关键字：
grep -i "fail\|error" /var/log/neutron/neutron-linuxbridge-agent.log | tail -n 100日志里如果出现 "no physical bridge"，那就是映射没对上；如果出现 "agent not alive" 或管理端的通信超时，重点查 agent 服务和心跳；如果有 "vnic_type" 相关字样，检查端口类型。日志位置以你的发行版实际路径为准，但关键字思路是通用的。
4.4 重建验证：删掉错误实例，清理残留端口
找到根因并修改配置之后，不要直接在原 ERROR 实例上反复尝试，最干净的做法是删除实例，清理可能残留的端口，然后重新创建。
openstack server delete demo-instance删除后执行：
openstack port list --device-id <instance_uuid>如果还有端口残留，手动删除：
openstack port delete <port_id>然后重新执行 openstack server create。这一步很多人会忽略，导致明明配置已经改对，但因为旧端口还残留在错误的绑定状态里，重建实例时依然失败。
5. 修复手法与预防清单：怎么改配置、怎么重建、怎么避免再犯
5.1 修正映射配置并重启 agent
到这里就该动手修了。以 linuxbridge 为例，打开 /etc/neutron/plugins/ml2/linuxbridge_agent.ini，确认 [linux_bridge] 段：
[linux_bridge] physical_interface_mappings = physnet1:eth1冒号前面的 key 必须和创建网络时的 --provider-physical-network 一致，冒号后面的接口必须是宿主机上真实存在、且连接到目标二层网络的物理网卡。修改完成后重启服务：
systemctl restart neutron-linuxbridge-agent systemctl status neutron-linuxbridge-agent需要注意，如果你的环境有多台计算节点，必须确认每一台的映射都一致。nova 调度器可能把实例分配到任何一台满足条件的节点，只要有一台配置不完整，就存在间歇性失败的风险。这也是为什么实际运维中建议把这类映射关系集中登记，而不是靠记忆。
5.2 重建网络前的几个确认点
我见过太多人遇到这个问题后第一反应是"删网重建"，但网络本身没有错，错的是主机侧映射。删网重建不但浪费时间，还可能掩盖真正的问题。重建之前，按这个顺序确认一遍：
- openstack network show 里的 provider:physical_network 和 provider:network_type 是否符合预期。
- 每一台计算节点的 agent 是否在线，Alive 是否为 True。
- agent 配置里的物理网络名、物理接口和实际网桥是否对应。
- 如果是 OVS，确认 br-ex 真的存在且物理网卡已经加入。
其中第 4 条是最容易被忽略的。br-ex 不存在时，日志里不会给你一个特别显眼的报错，但端口绑定就是会失败。
5.3 后续运维检查清单
最后分享一份我平时检查网络绑定问题的清单，每次改完网络相关配置都会照着走一遍：
| 检查项 | 命令/位置 | 预期结果 |
|---|---|---|
| 网络类型与物理网络名 | openstack network show | provider:physical_network 有值 |
| agent 在线状态 | openstack network agent list | Alive / True |
| linuxbridge 配置 | /etc/neutron/plugins/ml2/linuxbridge_agent.ini | 映射 key 与网络名一致 |
| OVS 网桥状态 | ovs-vsctl show | br-ex 存在且物理网卡已加入 |
| nova 日志报错 | grep -i "PortBinding" /var/log/nova/nova-compute.log | 无新增错误 |
这套清单不仅适用于 PortBindingFailed，遇到其他网络绑定方面的疑难杂症也可以复用。
最后说句实在话，PortBindingFailed 这个错看着吓人，本质就是一个断言：虚拟机需要的虚拟网线没能插到物理交换机上。排错时不用急着删网重建，按 nova 日志 → 端口详情 → agent 状态 → 宿主机网桥的顺序走一遍，基本十几分钟就能落地。我见过太多人把 provider 网络删了重建好几遍，最后发现不过是 agent 配置里 physnet 的名字少了一个字母，或者改了配置忘了重启。希望这篇能帮你少走点弯路。
