在网关世界里，插件能不能用从来不是最难的问题，谁先谁后才是。一个认证插件跑在限流插件后面，等于先放流量再查身份；一个意图识别插件跑在 AI 代理后面，等于请求已经被转发出去才想起来要分类。这类问题不会报错，只会悄悄把安全边界和业务逻辑撕开一道口子。

    本文把 Higress 插件体系里最容易混淆的两件事——phase（执行阶段）和 priority（优先级）——彻底讲清楚：它们各自决定什么、为什么不能混为一谈、内置插件是怎么排布的，以及在实际项目中应该如何设计插件编排。

一、先划清界限：phase 与 priority 是两个维度

    很多同学看到插件配置里的 priority 数字，第一反应是数字越大越先执行，于是顺手把某个插件调到 1000，以为它就能抢在所有人前面。结果发现并没有——因为它的 phase 决定了它插在过滤器链的哪个位置，而 priority 只在同一个 phase 内部才有意义。

    一句话总结：phase 决定插件在过滤器链中的阶段位置，priority 只在同一个 phase 内比较。跨 phase 谈优先级，是没有意义的。

二、Phase：决定插件在过滤器链中的位置

    phase 决定插件被插入到 Envoy 过滤器链的哪个阶段。可选值及含义如下：

    执行阶段决定了请求处理的大框架。认证类插件通常置于 AUTHN 阶段，限流类插件置于 AUTHZ 阶段，这样才能保证先认证、后限流的安全顺序——未通过身份校验的请求，不应该消耗限流配额，更不应该被计入业务统计。

    需要特别注意默认值 UNSPECIFIED_PHASE：它意味着插件被放在插件过滤器链的末端、路由器之前。这个位置适合做与安全无关的请求/响应加工，例如提示词修饰、内容转换等。把认证类插件留在默认阶段，是实践中非常常见的一个隐患。

三、Priority：同一 Phase 内的执行先后

    只有在相同 phase 下，才会比较 priority，且 priority 越大越先执行。例如两个插件都处于 UNSPECIFIED 阶段，priority 为 901 的插件会比 priority 为 360 的插件先执行；但如果两者 phase 不同，则以 phase 顺序为准，priority 不参与跨阶段比较。

    priority 是整数，默认为 0。在相同 phase 下，值越大越先处理请求，但越后处理响应。因此请求方向是高优先级先执行，响应方向则高优先级后执行，形成先进后出的栈式结构。理解这一点，才能在设计插件链时预判响应侧的行为。

四、内置插件的默认优先级参考

    Higress 为内置插件预设了合理的优先级，下表是部分插件的示例，可以作为自定义插件的参照基线：

    从这张表里能读出几条重要规律：认证类插件（basic-auth、ext-authz）集中在认证阶段，数值在 300 至 400 区间；AI 相关插件则分布在默认阶段，其中意图识别的优先级必须高于 ai-proxy，否则请求已经被代理转发，分类结果就无从生效；model-router 达到 900，是为了在认证阶段尽早拿到 model 参数并完成路由决策。

五、插件编排的实战建议

1.先定 phase，再定 priority。安全类插件一律进 AUTHN 或 AUTHZ，不要留在默认阶段。

2.认证必须先于限流。限流插件放在 AUTHZ 阶段，确保只有通过认证的请求才消耗配额。

3.依赖关系要显式表达。意图识别、提示词修饰等 AI 插件若依赖前置插件产出，priority 必须高于被依赖插件。

4.响应侧要反向推演。高优先级插件在响应方向后执行，若某插件需要在响应阶段最早收尾，就不应给它过高优先级。

5.避开默认值陷阱。priority 默认 0，phase 默认 UNSPECIFIED_PHASE，新增插件时不显式声明，往往就落在不理想的位置。

6.改动后必须回归验证。调整 phase 会改变整条过滤器链的拓扑，仅靠单元测试无法覆盖，需要端到端验证认证、限流与统计的实际顺序。

六、几个常见误区

    误区一：以为 priority 可以跨阶段生效。实际上跨 phase 比较 priority 没有意义，phase 顺序永远优先。

    误区二：把所有插件都塞进默认阶段，靠调大 priority 来排顺序。这在插件数量少时看似可行，一旦引入认证与限流，就会破坏安全顺序。

    误区三：忽略响应方向的执行顺序。请求方向调通了，响应方向可能完全相反，涉及响应改写、审计、脱敏的插件尤其要留意。

    误区四：照抄内置插件的数值。内置优先级是针对内置插件的行为设计的，自定义插件应当参照其依赖关系重新推导，而不是直接复制一个看起来差不多的数字。

七、小结

    插件编排的本质，是把安全边界和业务逻辑在过滤器链上正确落位。phase 解决在哪里，priority 解决在同一个位置上谁先谁后，两者缺一不可，也绝不能互相替代。

    把 phase 想清楚，把依赖关系画出来，再用 priority 精确排序，最后用端到端测试验证请求与响应两个方向的真实行为——这套方法比记住任何一张优先级表都更可靠。毕竟内置插件的数值会随版本演进，而对先认证、后限流、再加工这一安全顺序的理解不会过时。