Envoy HTTP Cache 过滤器（Cache Filter）实战指南：配置、语义与存储后端

Envoy HTTP Cache 过滤器Cache Filter实战指南配置、语义与存储后端【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoyHTTP Cache 过滤器是 Envoy 原生实现 RFC 7234 缓存语义的 HTTP 过滤器负责判定请求/响应是否可缓存、计算新鲜度freshness lifetime、并在内存或磁盘后端中存储与检索缓存对象。本文基于当前仓库的 cache_filter.rst 文档及其 API 定义与源码实现完整讲解该过滤器的配置方法、请求/响应两侧的缓存判定规则、CacheConfig全部可用字段以及SimpleHttpCache内存与FileSystemHttpCache磁盘 LRU两种内置存储后端的接入方式。读完本文你将能够在一个真实 Envoy 静态配置中落地 HTTP 缓存并理解缓存键、Vary 处理与过滤链语义背后的底层机制。一、过滤器定位与基本约束HTTP Cache 过滤器通过 HTTP 过滤器链http_filters接入其 v3 配置类型为type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig完整字段定义见 cache.proto存储后端配置见 SimpleHttpCacheConfig 与 FileSystemHttpCacheConfig。使用该过滤器时需要明确以下几点约束不支持 virtual host 级别的配置缓存配置只能挂在 HTTP 过滤器链上不能针对某个虚拟主机单独开关。过滤链语义特殊当缓存启用后可缓存cacheable的请求只会经过upstream_http_filters链即 Router.upstream_http_filters 中定义的过滤器而不会经过普通过滤器链中位于 Cache 过滤器更上游further upstream的其他过滤器不可缓存的请求则照常走完整的监听器过滤器链。推荐放置位置为了保证两条路径行为一致官方文档明确建议——在监听器过滤器链中Cache 过滤器更上游的位置只应放置 router 过滤器。换言之典型排布是... - cache - router避免可缓存请求绕过中间过滤器而产生语义差异。二、请求侧缓存语义对于进入的 HTTP 请求Cache 过滤器遵循以下判定逻辑对应源码source/extensions/filters/http/cache/cacheability_utils.cc中的可缓存性判断尊重请求的Cache-Control指令例如请求携带Cache-Control: no-store时该请求不会被缓存。唯一的例外是当CacheConfig.ignore_request_cache_control_header被置为true此时过滤器将忽略这类指令。不缓存 HEAD 请求HTTP Cache 不会存储 HEAD 请求HEAD 通常用于探测资源是否存在其响应体为空且不应污染缓存条目。此外从 cache.proto 的注释可以看出默认情况下请求中的cache-control: no-cache或pragma: no-cache头会导致缓存即使命中也会回源upstream做校验revalidation设置ignore_request_cache_control_header true可跳过这一行为。三、响应侧缓存语义对于上游返回的 HTTP 响应Cache 过滤器只会存储满足以下全部条件的对象足以计算新鲜度生命周期的响应过滤器的缓存判定以 RFC 7234 的新鲜度计算 为准——响应中必须携带足够的信息如Cache-Control: max-age、Expires或Last-Modified等来推导 freshness lifetime否则不缓存。尊重上游的Cache-Control指令例如状态码 200、携带Cache-Control: max-age60且没有vary头的响应会被缓存而携带no-store或no-cache等指令的响应则按指令语义处理。状态码在白名单内只缓存以下状态码的响应200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451, 501可以看出白名单同时覆盖了成功类200/203/204/206、重定向类300/301/308以及错误类404/405/410/414/451/501响应但排除了例如 500、502 等 5xx 服务端错误与 401/403 等需要按用户区分的响应。Vary 头允许列表allowed_vary_headersStringMatcher列表在插入阶段充当白名单——如果响应的vary头中提及了任何未被allowed_vary_headers规则匹配的请求头名称该响应将不被缓存在查找阶段它又决定了哪些请求头会被传给缓存存储后端用于命中判定。这在处理内容协商如Accept-Encoding、Accept-Language响应时尤其关键。四、CacheConfig 配置字段详解CacheConfig目前共 7 个字段位#next-free-field: 7其中部分已实现、部分在 proto 中标注为#not-implemented-hide:。逐项说明如下字段类型状态说明typed_configgoogle.protobuf.Any✅ 已实现缓存存储后端的嵌套配置通过扩展类别envoy.http.cache选定实现。除非disabled为 true否则该字段为必填。allowed_vary_headersrepeated StringMatcher✅ 已实现定义允许的Vary头规则同时控制插入白名单与查找时传给后端的请求头集合详见上文第三节。key_creator_paramsKeyCreatorParams⚠️ 未实现计划用于定制缓存键是否排除 scheme/host、包含或排除哪些 query 参数proto 中已预留结构但标注not-implemented-hide。max_body_bytesuint32⚠️ 未实现计划限制写入缓存的响应体大小0 表示不限制存储后端仍可能有自身限制。disabledgoogle.protobuf.BoolValue✅ 已实现为 true 时过滤器退化为 no-op空操作。典型用途是与 ECDS扩展配置发现服务配合实现在线开关。ignore_request_cache_control_headerbool✅ 已实现默认 false置 true 后忽略请求中的cache-control: no-cache与pragma: no-cache避免每次命中都强制回源校验。KeyCreatorParams子消息当前仅用于预留包含exclude_scheme、exclude_host、query_parameters_included与query_parameters_excluded四个字段其中 query 参数匹配复用config.route.v3.QueryParameterMatcher说明未来的缓存键定制将支持精确到 query 参数粒度的包含/排除。五、架构与扩展点HttpCache 接口Envoy 的 HTTP 缓存体系被拆分为两个可独立扩展的层次HTTP Cache 过滤器扩展名envoy.filters.http.cache类别envoy.filters.http——通过CacheConfig配置负责实现 HTTP 缓存的全部语义判定可缓存性、新鲜度、命中/未命中决策等。缓存存储后端扩展类别envoy.http.cache——过滤器将对象的存储与检索委托给后端实现。后端通过CacheConfig.typed_config嵌套选定。从源码结构看存储抽象由 http_cache.h 中的HttpCache接口承担各实现需要提供查找lookup与插入insert两条上下文路径过滤器主体位于 cache_filter.cc可缓存性判定与新鲜度逻辑集中在 cacheability_utils.cc缓存键结构定义在 key.proto。这种语义内核 可插拔存储的设计使得后端可以覆盖持久化、性能、分布式的任意组合点从本地 RAM 缓存到全局分布式持久化缓存既可以是完全自研的实现也可以是本地或远端开源/商业缓存的包装器wrapper/adaptor。内置后端目前有两个SimpleHttpCacheConfig——内存实现简单快速适合单实例、小规模或测试场景FileSystemHttpCacheConfig——磁盘持久化实现默认采用 LRU最近最少使用逐出策略适合跨重启保留缓存的大规模场景。六、示例一SimpleHttpCache内存缓存以下配置来自仓库示例 http-cache-configuration.yaml展示了在http_filters链中挂载内存缓存后端的完整写法static_resources: listeners: - address: socket_address: address: 0.0.0.0 port_value: 8000 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: AUTO stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: backend domains: - * routes: - match: prefix: /service/1 route: cluster: service1 - match: prefix: /service/2 route: cluster: service2 http_filters: - name: envoy.filters.http.cache typed_config: type: type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig typed_config: type: type.googleapis.com/envoy.extensions.http.cache.simple_http_cache.v3.SimpleHttpCacheConfig - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: - name: service1 type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: service1 endpoints: - lb_endpoints: - endpoint: address: socket_address: address: service1 port_value: 8000 - name: service2 type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: service2 endpoints: - lb_endpoints: - endpoint: address: socket_address: address: service2 port_value: 8000要点拆解过滤器名必须为envoy.filters.http.cache其typed_config类型为CacheConfigCacheConfig.typed_config内再嵌套一层后端类型SimpleHttpCacheConfig。从 config.proto 可以看到该消息体目前是空的——内存后端无需任何额外参数过滤器链中 Cache 位于router 之前即上文第一节约束中推荐的排布路由规则将/service/1与/service/2分别指向两个 STRICT_DNS 集群。七、示例二FileSystemHttpCache磁盘 LRU 缓存需要跨重启持久化缓存时改用磁盘后端。以下配置来自仓库示例 http-cache-configuration-fs.yamlstatic_resources: listeners: - address: socket_address: address: 0.0.0.0 port_value: 8000 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: type: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: AUTO stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: backend domains: - * routes: - match: prefix: /service/1 route: cluster: service1 - match: prefix: /service/2 route: cluster: service2 http_filters: - name: envoy.filters.http.cache typed_config: type: type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig typed_config: type: type.googleapis.com/envoy.extensions.http.cache.file_system_http_cache.v3.FileSystemHttpCacheConfig manager_config: thread_pool: thread_count: 2 cache_path: /var/cache/envoy max_cache_size_bytes: 1073741824 - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: - name: service1 type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: service1 endpoints: - lb_endpoints: - endpoint: address: socket_address: address: service1 port_value: 8000 - name: service2 type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: service2 endpoints: - lb_endpoints: - endpoint: address: socket_address: address: service2 port_value: 8000FileSystemHttpCacheConfig的字段在 file_system_http_cache.proto 中定义完整参数语义如下字段示例值说明manager_configthread_pool.thread_count: 2必填validate 规则为required: true。异步文件管理器配置指定如何以异步方式使用文件系统。cache_path/var/cache/envoy缓存文件存储路径同时充当缓存唯一标识不同路由可共享同一cache_path的缓存不同路径则各自独立。若多个CacheConfig使用相同cache_path其余配置必须一致且共享同一缓存实例。max_cache_size_bytes10737418241 GiB缓存总大小上限按文件大小之和计包含 header/trailer/元数据不含文件系统开销与块填充。达到上限触发逐出不设置则仅受文件系统容量限制。max_individual_cache_entry_size_bytes未设置单个缓存条目大小上限超限响应不缓存不设置则无限制当前标注未实现。max_cache_entry_count未设置缓存条目数量上限达到上限触发逐出不设置则无限制。cache_subdivisions未设置默认 1将缓存细分为多个子目录的数量。对于单目录大量 inode 会拖慢性能的文件系统可设为sqrt(期望条目数)来提升性能inode 友好的文件系统建议保持默认 1当前标注未实现。evict_fraction未设置默认 0每次逐出时清理的比例。例如上限 10 MB、evict_fraction0.2超限后会逐出至 ≤ 8 MB为 0 则只逐出至 ≤ 10 MB。逐出比例越大逐出线程唤醒频率越低省 CPU但额外逐出的条目会带来更多缓存未命中当前标注未实现。max_eviction_period未设置两次逐出扫描的最大间隔。即使没有超限只要距上次扫描超过该时长也会唤醒逐出线程做一次状态同步——这对多实例并行访问同一缓存很关键例如两个实例各写入 10 MB 到 15 MB 上限的缓存彼此不知情需要同步扫描来发现超限当前标注未实现。min_eviction_period未设置两次逐出扫描的最小间隔。可减少逐出抖动代价是缓存可能在max_cache_size_bytes基础上多增长该时段内可写入的量。官方建议min_eviction_period与evict_fraction二选一当前标注未实现。create_cache_path未设置默认 false为 true 且cache_path不存在时自动创建含缺失的父目录失败则拒绝配置为 false 且路径不存在时直接拒绝配置当前标注未实现。从源码目录 source/extensions/http/cache/file_system_http_cache/ 看该后端由 file_system_http_cache.cc 实现主体另含 cache_eviction_thread.ccLRU 逐出线程、cache_file_header.proto磁盘文件头格式与 stats.cc统计指标实现细节可进一步阅读该目录下的 DESIGN.md。内存后端则非常轻量主体仅有 simple_http_cache.cc 与对应的头文件。八、源码级补充过滤器内部工作流结合 source/extensions/filters/http/cache/ 目录中的源码组织可以梳理出 Cache 过滤器内部的职责划分cache_filter.cc / cache_filter.h过滤器主逻辑负责接入 HTTP 解码/编码链路协调查找、命中回放与未命中回源cacheability_utils.cc集中实现请求/响应可缓存性判定即上文第二、三节的规则所在cache_headers_utils.cc解析与计算Cache-Control、Expires、Age等缓存相关头支撑新鲜度计算http_cache.h定义HttpCache存储接口查找/插入上下文是接入新存储后端的扩展点cache_insert_queue.cc负责插入操作的排队与合并避免同一资源并发回源时重复写入upstream_request.cc管理未命中时向上游发起的请求及其与缓存插入的衔接range_utils.cc处理 Range 请求与缓存片段206 响应的切片逻辑filter_state.h在过滤器与后端之间传递缓存键、命中信息等状态。这些文件共同印证了文档所述HTTP Cache 过滤器实现了 HTTP 缓存语义的大部分复杂性——语义判定全部集中在过滤器内存储后端只需要实现纯粹的读写接口。九、进一步学习路径交互式沙箱Envoy 提供了 Cache 过滤器逐步实操沙箱可结合官方 Cache Sandbox 按步骤验证配置效果。V2 版本仓库同时保留了缓存过滤器的 v2 变体见 cache_v2 proto 及其存储后端 simple_http_cache v2 与 file_system_http_cache v2新配置应优先使用 v3。API 现状提示从 proto 标注可以看出KeyCreatorParams、max_body_bytes及FileSystemHttpCacheConfig的多个容量/逐出调优字段仍处于not-implemented-hide状态生产使用时请以当前版本实际生效行为为准。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考