Higress traffic-tag 流量染色插件基于内容与权重的请求打标配置全指南【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本篇技术指南以 Higress 内置 Wasm 插件traffic-tag流量染色为核心系统讲解如何通过追加特定请求头按请求内容或权重比例对流量进行标记。读完本文你将掌握conditionGroups内容匹配与weightGroups权重分配的完整配置语法、七种操作符的判定语义、percentage与weight的本质区别并能结合源码理解该插件在 Higress 网关中的实际运行机制与校验规则直接用于灰度发布、A/B 实验和链路观察等生产场景。一、功能概述与典型应用场景traffic-tag插件允许根据权重或特定请求内容通过添加特定请求头的方式对请求流量进行染色Tagging。它支持复杂逻辑可根据用户自定义的标准决定如何标记流量。其插件类型在 config.yaml 中定义为enterprise级、分类为traffic即流量治理类插件。典型应用场景包括灰度发布与金丝雀发布将一部分比例的流量打上x-mse-tag: gray标签路由规则据此把带标签的请求转发到灰度版本基于身份的差异化路由根据请求头如role、查询参数或 Cookie 识别用户类型打上不同标签后分流A/B 实验按固定哈希比例或随机权重划分实验组与对照组链路观测与计费审计在网关入口统一打标使下游服务能基于标签做统计、限流或追踪。二、运行属性插件在 Higress 网关 Wasm 运行时中以 Proxy-Wasm 方式加载运行属性如下属性值说明插件执行阶段默认阶段Default Phase在请求头处理阶段执行对应源码中onHttpRequestHeaders钩子插件执行优先级400数值越大越先执行与其他插件协同编排上述属性同时记录在插件元信息文件 config.yaml 的spec.phase: default与spec.priority: 400中并在 main.go 中通过wrapper.SetCtx将请求头处理函数注册到ProcessRequestHeadersBy即每个请求到达网关时在请求头阶段完成打标。三、顶层配置字段插件配置整体是一个 JSON/YAML 对象顶层字段如下字段名称类型默认值是否必填描述conditionGroupsarray of object-否定义基于内容的标记条件组详细结构见下文条件组配置weightGroupsarray of object-否定义基于权重的标记条件组详细结构见下文权重组配置defaultTagKeystring-否默认标记键名当未匹配到任何条件时使用仅当同时配置了defaultTagVal时生效defaultTagValstring-否默认标记值当未匹配到任何条件时使用仅当同时配置了defaultTagKey时生效需要特别说明的是defaultTagKey/defaultTagVal的联动关系源码 parse.go 中只有两者同时存在k.Exists() v.Exists()才会写入默认标签配置在 utils.go 的setDefaultTag中任一项为空则直接返回、不添加任何头。因此要启用兜底打标必须成对配置。四、条件组配置基于内容匹配4.1 条件组conditionGroups 项字段conditionGroups中每一项的配置字段说明如下字段名称类型默认值是否必填描述headerNamestring-是要添加或修改的 HTTP 头名称headerValuestring-是HTTP 头的值logicstring-是条件组内多个条件的逻辑关系支持and、or必须为小写conditionsarray of object-是描述具体的标记条件详细结构见 4.2从源码 parse.go 可以看到headerName、headerValue、logic任一为空或logic既不是and也不是or配置解析会直接报错invalid condition group插件启动失败。logic会被强制转为小写后再校验。4.2 具体条件conditions 项字段conditions中每一项的配置字段说明如下字段名称类型默认值是否必填描述conditionTypestring-是条件类型支持header、parameter、cookiekeystring-是条件的键名header为请求头名parameter为 URL 查询参数名cookie为 Cookie 名operatorstring-是操作符支持equal、not_equal、prefix、in、not_in、regex、percentagevaluearray of string-是条件的值仅当操作符为in和not_in时支持配置多个值其余操作符只允许一个值4.3 三种条件类型的数据来源结合 content.go 的getConditionValue实现三种conditionType实际取值方式如下header直接通过proxywasm.GetHttpRequestHeader(key)读取请求头键即请求头名称cookie读取完整的Cookie请求头再按;分隔、keyvalue解析出目标 Cookie 值解析逻辑见 utils.goCookie 不存在时返回cookie not found错误parameter从:path伪头获取完整 URL再通过url.Parse与u.Query()[key]取出首个查询参数值utils.go参数缺失时返回parameter not found错误。五、操作符说明操作符描述equal精确匹配实际值与指定值完全相等not_equal不等匹配实际值与指定值不相等时满足条件prefix前缀匹配指定值是实际值的前缀时满足条件in包含匹配实际值需要在指定的值列表中not_in排除匹配实际值不在指定的值列表中时满足条件regex正则表达式匹配按正则规则匹配percentage百分比匹配原理hash(get(key)) % 100 value成立时满足条件注意当operator为regex时使用的正则表达式引擎是RE2Google 出品线性时间复杂度、无回溯灾难。源码 parse.go 会在配置解析阶段对正则进行预编译并缓存到regexCache中parse.go编译失败会导致插件启动失败运行期命中时直接复用缓存content.go避免每次请求重复编译的开销。5.1 value 取值规则的源码级约束操作符对value数组长度的校验在ConditionRule.validate()parse.go中实现规则非常严格in/not_in至少包含 1 个元素percentage有且仅有 1 个元素且必须为 0~100 之间的整数其余操作符equal、not_equal、prefix、regex有且仅有 1 个元素。配置不满足上述约束时插件将返回OnPluginStartStatusFailed无法加载。对应测试用例见 main_test.go无效条件组、无效操作符均断言启动失败。六、权重组配置基于权重匹配weightGroups中每一项的配置字段说明如下字段名称类型默认值是否必填描述headerNamestring-是要添加或修改的 HTTP 头名称headerValuestring-是HTTP 头的值weightinteger-是流量权重百分比权重组的总权重以100为上限。源码中定义了常量TotalWeight 100main.go并在解析阶段做了两道校验parse.go每个weight必须满足0 weight 100各组权重按配置顺序累加累加和一旦超过 100 立即报错total weight exceeds: 100。命中判定采用**累计分布CDF**算法weight.go对每个请求生成一个[0, 100)的随机数randomValue按配置顺序找到第一个randomValue Accumulate的权重组打上对应标签。因此权重组是有序生效的且总和小于 100 时剩余比例的请求不会命中任何权重组也就不会打标签。七、percentage与weight的本质区别这是流量打标中最容易混淆的一对概念二者的判定依据完全不同percentage操作符用于条件表达式中基于指定百分比和指定键值对判断是否执行打标。其判定是确定性哈希对get(key)取到的实际值做 SHA-256 哈希取前 8 字节大端序整型对 100 取模实现见 content.go再与百分比阈值比较。对于同一个键值对多次匹配的结果是幂等的——这一次命中下一次同一值也必然命中非常适合按用户维度固定比例分流例如按user_id打标同一用户永远落在同一组。weight字段用于定义不同处理路径的流量权重基于随机权重分布。由于每次请求都重新取随机数、且没有固定的对比依据同一个请求的多次匹配可能得到不同结果适合整体流量按比例随机切分。一句话总结percentage做的是每个请求是否满足特定百分比条件的确定性判定weight做的是整体流量随机分配比例的静态分布。生产实践中若希望同一实体用户/设备的请求始终打同一个标签请使用percentage 稳定键如user_id若只关心整体流量的宏观比例使用weight即可。八、配置示例示例 1基于内容的匹配按照下例配置满足请求头role的值为user、viewer、editor其中之一且存在查询参数foobar的请求会被添加请求头x-mse-tag: gray。由于同时配置了defaultTagKey与defaultTagVal当未匹配到任何条件时请求会被添加请求头x-mse-tag: basedefaultTagKey: x-mse-tag defaultTagVal: base conditionGroups: - headerName: x-mse-tag headerValue: gray logic: and conditions: - conditionType: header key: role operator: in value: - user - viewer - editor - conditionType: parameter key: foo operator: equal value: - bar说明该组logic: and表示两个条件必须同时成立。条件组内各条件按顺序短路求值content.goand逻辑下任一条不满足即整组不匹配or逻辑下任一条满足即整组匹配。示例 2基于权重的匹配按照下例配置请求将有 30% 概率被添加请求头x-mse-tag: gray30% 概率被添加x-mse-tag: blue剩余 40% 概率不添加任何标签未配置的 40 权重不产生头# 权重总和为 100下例中未配置的 40 权重将不添加 header weightGroups: - headerName: x-mse-tag headerValue: gray weight: 30 - headerName: x-mse-tag headerValue: blue weight: 30综合示例WasmPlugin 完整配置仓库中的 SampleConfig.yaml 给出了一个可直接对照的完整WasmPlugin自定义资源示例同时演示了三种条件组or前缀匹配、and组合匹配 正则、percentage哈希比例与权重组30/70 金丝雀的混合用法apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: traffic-tag namespace: higress-system spec: defaultConfig: conditionGroups: - headerName: x-mse-tag-1 headerValue: gray logic: or conditions: - conditionType: header key: x-user-type operator: prefix value: - test - headerName: x-mse-tag-2 headerValue: blue logic: and conditions: - conditionType: header key: x-type operator: in value: - type1 - type2 - type3 - conditionType: header key: x-mod operator: regex value: - ^[a-zA-Z0-9]{8}$ - headerName: x-mse-tag-3 headerValue: green logic: and conditions: - conditionType: header key: user_id operator: percentage value: - 60 weightGroups: - headerName: x-higress-canary headerValue: gray weight: 30 - headerName: x-higress-canary headerValue: base weight: 70 url: file:///opt/plugins/wasm-go/extensions/traffic-tag/plugin.wasm其中url字段指向本地加载的 Wasm 二进制plugin.wasm实际部署时可根据安装方式替换为 OCI 镜像地址或远程文件地址。示例中的正则^[a-zA-Z0-9]{8}$匹配恰好 8 位字母数字组合可用于校验 token/ID 类请求头。九、请求处理流程与优先级语义源码级插件每次请求的处理入口是onHttpRequestHeadersmain.go整体执行顺序非常清晰先匹配条件组若配置了conditionGroups按顺序遍历各组命中即调用addTagHeader添加标签头并返回truecontent.go再匹配权重组仅当条件组未命中!add且配置了weightGroups时才执行随机权重打标weight.go最后兜底默认标签两步都未命中时若配置了defaultTagKey/defaultTagVal则添加默认标签头始终返回types.ActionContinue不中断请求仅做头追加。两个重要的工程细节条件组优先级高于权重组conditionGroups命中后权重组与默认标签都不会再执行混合配置时条件匹配结果优先生效测试用例 main_test.go 专门验证了这一优先级已存在的同名请求头不会被覆盖addTagHeaderutils.go先检查同名头是否已存在存在则记录日志并直接返回避免覆盖上游已设置的标签。十、配置校验规则速查插件在启动阶段parseConfig会对配置做全量校验任一规则不满足都会导致加载失败。速查如下校验项规则源码位置条件组基本字段headerName/headerValue/logic非空logic∈ {and,or}parse.go条件基本字段conditionType/key/operator非空parse.go操作符白名单∈ {equal,not_equal,prefix,in,not_in,regex,percentage}parse.go条件类型白名单∈ {header,parameter,cookie}parse.govalue元素个数in/not_in≥ 1percentage 10~100 整数其余 1parse.go正则可编译性regex在启动期预编译失败即报错parse.go权重取值范围单个weight∈ [0, 100]累加和 ≤ 100parse.go空配置{}是合法的插件记录plugin config is empty日志后正常加载此时所有请求都不打标签main.go。十一、深入阅读插件功能文档README_EN.md / README.md插件元信息与配置 Schemaconfig.yaml完整部署示例SampleConfig.yaml核心实现main.go入口与流程、content.go内容匹配、weight.go权重分配、parse.go配置解析与校验、utils.go取值与打标工具单元测试main_test.go覆盖配置解析、各操作符匹配、混合配置优先级等场景Higress 的 Wasm 插件统一托管于 plugins/wasm-go/extensions 目录traffic-tag可与 samples/wasmplugin 下的示例配置如 default-config.yaml、ingress-level-config.yaml配合理解网关级与路由级插件的挂载方式。流量染色后的标签头通常再配合 Higress 的路由匹配能力如 samples/nacos-discovery/canary.yaml 中的金丝雀路由思路实现完整的分流闭环。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
