Envoy 新版本扩展机制变化怎样影响过滤器

Envoy 新版本扩展机制的变化，重点不在于“所有过滤器都要改写成动态模块”，而在于过滤器已经有了更多实现载体：内置扩展、Lua、Wasm、External Processor，以及直接加载共享库的动态模块。真正影响升级的是配置协议、构建产物和运行时权限不再是一回事。

官方地址：https://www.envoyproxy.io/

当前官方文档对动态模块的定位很清楚：它可以在 Envoy 进程运行时加载共享库，支持包括 HTTP filter、network filter 在内的多个扩展点；但它与 Envoy 二进制必须保持 ABI 兼容，兼容约束比 Lua、Wasm 或 External Processor 更严格。因此，过滤器迁移要先做载体判断，再做版本切换。

先还原一次“过滤器突然不兼容”的现场

升级 Envoy 后，最容易误判的症状是：YAML 仍然能被控制面下发，但过滤器在新节点加载失败；或者配置没有变化，旧节点正常，新节点却出现模块找不到、类型不匹配或启动阶段退出。把问题简单归因于“新版本改了过滤器字段”往往不够，因为过滤器至少跨着三层边界。

第一层是配置识别。Envoy 的扩展配置通常通过 typed_config 携带带版本的 type URL，类型 URL 用来识别能够解释该配置的扩展；name 更像实例标识或注释，不是单独选择实现的开关。第二层是实现载体：同一个业务能力可能来自内置 C++、Wasm、外部处理服务或动态模块。第三层是交付产物：动态模块是共享库，加载时还要找到正确的文件并满足 ABI。

所以排查顺序应该是“配置类型—载体—产物—加载环境”，而不是先把所有字段改成新写法。

配置字段没有替你解决实现差异

Envoy 的扩展配置允许静态 typed_config，也允许通过 Extension Configuration Discovery Service 动态提供配置。对于动态过滤器，还要确认目标扩展点是否支持对应的发现方式，以及缺少配置时是拒绝连接、返回本地错误，还是移除会话。配置存在不代表实现已经可用。

# 这是静态结构示意：type URL 负责标识扩展配置的 schema
name: request-policy
typed_config:
  "@type": type.googleapis.com/example.filters.http.request_policy.v1.Config
  # 业务参数由扩展自己的 schema 定义，不能照搬其他载体的字段
  mode: observe
  header_name: x-request-id

上面最重要的是边界：name 是实例名称，@type 是配置类型，mode 和 header_name 是否存在则取决于具体扩展的 schema。若控制面没有对应 schema，可以使用 xds.type.v3.TypedStruct 携带内部 type URL，但它仍然不能绕过过滤器实现本身的兼容要求。

升级前要把配置仓库拆成三份清单：控制面能识别的类型 URL、目标 Envoy 镜像实际编译或加载的扩展、以及每个扩展的配置来源。这样才能区分“配置下发失败”和“共享库加载失败”。

动态模块为什么让版本升级更敏感

动态模块的优势是接近原生扩展的执行路径：官方文档说明它可以加载共享库，并提供 C++、Go、Rust SDK；HTTP filter 还能直接接触请求头和请求体，减少某些其他扩展机制中的复制开销。但这种能力意味着模块与 Envoy 进程共享更紧密的 ABI 和权限边界。

当前文档给出的兼容原则可以概括为四点：

• 已经发布的 ABI 冻结后不修改函数签名、结构布局、枚举编号和语义。
• ABI 通过新增实体演进，需要变化时通常增加带版本后缀的新函数，旧实体继续工作。
• 被替代的 ABI 至少保留四个 Envoy 发布周期，给模块迁移留下窗口。
• 尚未随正式分支发布的 main 分支实体不享有同样承诺，不能把开发版头文件当生产契约。

这解释了一个常见故障：团队升级了 Envoy 二进制，却沿用旧版本构建的 libxxx.so。即便 YAML 结构没有变化，模块仍可能因 ABI、SDK 或加载路径不匹配而失败。官方文档还提醒，动态模块在同一进程和权限级别运行，不能把它当成具备安全隔离边界的插件沙箱。

迁移过滤器时按四个动作拆开

第一步：先标注过滤器的实现载体

为每个 HTTP 或 network filter 增加一列“载体”：内置、Lua、Wasm、External Processor、动态模块，或控制器自带扩展。不要看到“扩展机制变化”就把载体统一替换。轻量脚本、跨语言可移植逻辑、需要进程外隔离的逻辑，与追求原生访问路径的逻辑，迁移约束并不相同。

第二步：固定版本化构建矩阵

动态模块至少要记录目标 Envoy 版本、SDK 版本、编译器工具链、模块名和共享库文件名。每次升级先用目标版本 SDK 重建，再在与生产相同的镜像和加载路径中验证。模块发现通常依赖 ENVOY_DYNAMIC_MODULES_SEARCH_PATH，配置中的模块名会映射到搜索路径下的 lib模块名.so；不要只在开发机当前目录里验证成功。

# 仅展示发布前的检查思路：搜索路径要与目标 Envoy 容器一致
export ENVOY_DYNAMIC_MODULES_SEARCH_PATH=/opt/envoy/modules
# 先确认共享库文件名遵循 lib.so 约定，再启动对应版本的 Envoy
ls -l /opt/envoy/modules/librequest_policy.so
# 加载失败时优先查看 dynamic_modules 日志，不要先改写过滤器 YAML

第三步：把配置状态和加载状态分开观察

扩展配置有成功更新、失败更新和冲突等统计；动态模块加载失败还会在 dynamic_modules 日志记录原因。发布时应同时采集控制面下发状态、Envoy 启动日志、过滤器实例统计和业务请求结果。只有看见“配置已接受”并不能证明共享库已按预期执行。

第四步：先并行，再按业务单元切换

保留旧过滤器包和旧镜像，给新模块单独的测试监听器或低风险域名。先验证请求头、请求体、异步回调、错误响应和资源释放，再切换正式流量。若新模块与旧过滤器作用相同，不要让两者在同一链路中重复修改同一个字段；链路顺序本身也要作为迁移记录的一部分。

哪些变化可以接受，哪些信号要立即回退

从根因角度看，最危险的不是某个字段被弃用，而是把四个不同问题合并成一次“升级成功”：配置能解析、模块能加载、过滤器能处理请求、业务结果符合预期。它们必须分别有证据和回退动作。

相关问题

动态模块是不是 Wasm 的直接替代品？

不是。动态模块更接近原生共享库，通常需要更严格的 ABI 和构建管理；Wasm 依赖 Proxy-Wasm 执行模型，适合另一类可移植扩展场景。应按性能、隔离、语言、运维和兼容周期选择。

只升级 Envoy 配置文件，能避免重新构建模块吗？

不能保证。配置协议与共享库 ABI 是两条独立边界。只要 Envoy 二进制或 SDK 发生影响 ABI 的变化，就应按目标版本重建并做同镜像验证。

扩展配置改成动态发现后，过滤器就能热更新吗？

不一定。动态发现解决的是配置来源，是否支持热更新以及已有连接如何处理，要看具体扩展点和 Envoy 文档。不能把 config discovery 自动等同于模块代码热替换。

参考资料

Envoy 官方网站：https://www.envoyproxy.io/

动态模块：https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/dynamic_modules

扩展配置：https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/extension

Wasm 扩展：https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/wasm