Traefik HTTP 路由规则（Rules）与优先级（Priority）完全指南：匹配器用法、RuleSyntax 与排序机制

HTTP Router（HTTP 路由器）是 Traefik 反向代理的流量中枢：它负责把进入 EntryPoint 的每个请求，根据**匹配规则（Rules）**连接到能够处理该请求的 Service。本文以 Traefik 仓库中 HTTP 路由规则与优先级参考文档 为主体，系统讲解全部 11 个匹配器（Matcher）的语义与写法、Host 通配符的精确边界、v2/v3 规则语法的混用迁移，以及路由优先级（Priority）的默认计算与手动覆盖机制，并对照 pkg/muxer/http、pkg/rules/parser.go 等源码给出底层实现依据。

读完本文，你将能写出精确、可排错的规则表达式，正确使用 Host('*')、*.example.com 等特殊形态，理解"两条规则同时命中时由谁接管"的完整决策链，并在多 Provider 场景下正确设置优先级。

一、路由匹配流程：规则如何把请求导向 Service

在 Traefik 中，一条 HTTP Router 的职责是"把满足条件的入站请求连接到能处理它们的 Service"。其完整处理链如下：

1. 请求进入某个 EntryPoint；
2. 由该 EntryPoint 上的 HTTP Muxer 对请求按 规则（Rule） 逐个求值，规则由一组"匹配器（matcher）+ 取值"构成，判断请求是否符合某一特定条件；
3. 一旦某条规则被验证为真，对应的 Router 即被激活：先调用该 Router 上挂载的 Middlewares 链，最终把请求转发到其引用的 Service。

从实现上看，这一步发生在 pkg/server/router/router.go 构建的每个 EntryPoint handler 中，而真正的逐条求值则在 pkg/muxer/http/muxer.go 的 ServeHTTP 中完成：Muxer 按优先级降序遍历已注册路由，第一个命中者接管请求并直接返回，全部未命中则落到默认的 404 handler。这也解释了为什么"规则的优先级"会直接影响流量去向——见本文第六部分。

Router 的完整字段（rule、service、middlewares、entryPoints、tls、ruleSyntax、priority 等）可继续阅读 HTTP Router 字段文档。

二、规则的基本语法

Traefik 的规则是一段布尔表达式，其编写约束如下（对应参考文档 "Rules" 一节）：

• 值的写法：必须使用反引号 ` 或转义双引号 \" 包裹值。单引号 ' 不被接受，因为值本身按 Go 字符串字面量（Go's String Literals）处理。
• 正则语法：接受正则表达式（regexp）的匹配器，一律使用 Go 风格的正则语法（对应 pkg/muxer/http/matcher.go 中 regexp.Compile 的编译行为）。
• 逻辑运算符：支持常规的 AND（&&）与 OR（||），遵循常规优先级规则，可用括号表达复杂规则；NOT（!）运算符用于反转匹配器。
• 解析实现：规则先被 pkg/rules/parser.go 解析为 Tree 树（基于 github.com/vulcand/predicate），再被 Muxer 编译成 matchersTree 求值。需要留意的是，对 ! 的处理发生在语法树层：对 !(A && B) 这类组合表达式取反时，会按德摩根律把 && 改写为 || 并逐叶反转（见 pkg/rules/parser.go 中的 invert），因此 ! 可以直接作用在复合规则上。

可用匹配器总览

匹配器	说明
Header(key, value)	匹配包含名为 key、值为 value 的请求头
HeaderRegexp(key, regexp)	匹配包含名为 key、值匹配 regexp 的请求头
Host(domain)	匹配 Host 为 domain 的请求，支持通配符子域（如 *.example.com）
HostRegexp(regexp)	匹配 Host 与 regexp 相符的请求
Method(method)	匹配 HTTP 方法为 method 的请求
Path(path)	匹配路径恰好为 path 的请求
PathPrefix(prefix)	匹配路径前缀为 prefix 的请求
PathRegexp(regexp)	用 regexp 匹配请求路径
Query(key, value)	匹配查询参数中名为 key 且值为 value 的请求
QueryRegexp(key, regexp)	匹配查询参数名为 key 且值匹配 regexp 的请求
ClientIP(ip)	按客户端 IP 匹配请求，支持 IPv4、IPv6 与 CIDR 格式

从源码结构看，v3 语法下每个匹配器对参数个数都有严格校验：例如 expectNParameters(host, 1) 要求 Host 恰好 1 个参数，Header 恰好 2 个，而 Query/QueryRegexp 则允许 1 或 2 个（对应"仅判断参数存在/带值"两种形态），参数数量不合法会在配置解析期报错，参见 pkg/muxer/http/matcher.go。

三、逐类匹配器详解

3.1 Header 与 HeaderRegexp：按请求头匹配

Header 与 HeaderRegexp 用于匹配携带特定请求头的请求。Header 做的是等值判断：在 matcher.go 中，Header 名先经 http.CanonicalHeaderKey 规范化，再在请求头的值列表里做精确包含判断；HeaderRegexp 则把第二个参数编译为正则，逐个请求头值执行 MatchString（若含 .，可用 (?i) 前缀做大小写不敏感匹配）。

行为	规则
匹配 Content-Type 为 application/yaml 的请求	Header(`Content-Type`, `application/yaml`)
匹配 Content-Type 为 application/json 或 application/yaml 的请求	HeaderRegexp(`Content-Type`, `^application/(json|yaml)$`)
大小写不敏感地匹配头部（case-insensitively）	HeaderRegexp(`Content-Type`, `(?i)^application/(json|yaml)$`)

3.2 Host 与 HostRegexp：按主机名匹配

Host/HostRegexp 用于匹配定向到特定主机的请求，是路由配置中使用最频繁的匹配器之一，注意以下几点边界：

• 不支持非 ASCII 字符：此类匹配器拒绝含非 ASCII 字符的值（源码中 muxer.IsASCII 校验失败会直接报错）。如需匹配国际化域名，请使用 punycode 编码的值（RFC 3492）。
• 回退到 Host 头：若请求 URL 中没有设置 Host（例如直接以 IP 访问），匹配器会回退到读取请求的 Host 头。
• 小写比较：匹配器对请求 Host 一律按小写形式比较。
• CNAME 与尾点：从 matcher.go 的 host 实现可见，除了域名通配比较外，还处理了 CNAME flatten 结果与末尾带点（.）的 FQDN 形态，行为与测试用例 matcher_test.go 相互印证。

单级通配符子域（仅 v3 规则语法）：Host 支持单级前缀通配符 *.example.com，可匹配 example.com 的任意直接子域。相比 HostRegexp，通配符写法推荐优先使用——它允许在 TLS 场景下挂接对应的 TLS Option，且匹配效率更高。

通配符只精确匹配一个子域标签：

• *.example.com 可以匹配 foo.example.com；
• 不能匹配 foo.bar.example.com，也不能匹配 example.com 本身。

从实现看，这一语义由 pkg/muxer/muxer.go 的 DomainMatchHostExpression 保证：它把请求域名按 . 拆分后，仅将第一个标签替换为 * 再与规则比较，因此多级子域与裸域自然不命中。注意：单级通配符能力只适用于 v3 规则语法（v3 为默认）。

例外：裸 * 是兜底而非子域通配符：Host('*') 会匹配所有请求，无论其 Host 是什么，包括完全没有 Host 的请求。这一行为刻意与 TCP 侧的 HostSNI(`*`) 匹配器保持一致（见 TCP 规则与优先级文档）。在 matcher.go 的 host 函数中能看到这条特判分支：值为 * 时直接返回恒真的匹配函数。

行为	规则
匹配 Host 为 example.com 的请求	Host(`example.com`)
匹配所有请求，无论 Host 为何（见上述例外）	Host(`*`)
匹配发送到 example.com 任意子域的请求	HostRegexp(`^.+\.example\.com$`)
匹配 Host 为 example.com 或 example.org 的请求	HostRegexp(`^example\.(com|org)$`)
大小写不敏感地匹配 Host	HostRegexp(`(?i)^example\.(com|org)$`)

测试用例 TestHostMatcher 进一步印证了这些行为：Host('*.example.com') 对 test.example.com 返回 200 而对 example.com、test.otherexample.com 返回 404；Host('*') 则对所有请求一律 200。

3.3 Method：按 HTTP 方法匹配

Method 匹配器按请求的 HTTP 方法（请求动词）过滤。实现上会把规则中的方法名统一 ToUpper 后再与请求方法比较，因此大小写写错也能被容错：

行为	规则
匹配 OPTIONS 请求	Method(`OPTIONS`)

3.4 Path、PathPrefix 与 PathRegexp：按 URL 路径匹配

这三类匹配器基于请求的 URL 路径进行匹配：

• 精确匹配用 Path；
• 前缀匹配用 PathPrefix；
• 正则匹配用 PathRegexp。

关键约定：除 PathRegexp 外，路径必须以 / 开头。源码中 path 与 pathPrefix 若收到不以 / 开头的值会直接返回"path does not start with a '/'"错误（matcher.go）。

另一个值得了解的底层细节：Muxer 在求值前会先对请求路径做预处理（withRoutingPath），把 URL 中非保留字符的百分号编码（如 %20）解码后放进路由上下文再参与匹配，因此 PathPrefix(/foo bar) 也能命中实际路径 /foo%20bar 的请求，见 pkg/muxer/http/muxer.go。

行为	规则
匹配 /products，但不匹配 /products/shoes、也不匹配 /products/	Path(`/products`)
匹配 /products 及其下的一切，如 /products/shoes、/products/，甚至 /products-for-sale	PathPrefix(`/products`)
匹配 /products/shoes 与 /products/socks，并带形如 /products/shoes/31 的 ID	PathRegexp(`^/products/(shoes|socks)/[0-9]+$`)
匹配路径以 .jpeg、.jpg 或 .png 结尾的请求	PathRegexp(`\.(jpeg|jpg|png)$`)
大小写不敏感地匹配 /products 及其下的一切（含 /products-for-sale）	PathRegexp(`(?i)^/products`)

3.5 Query 与 QueryRegexp：按查询参数匹配

Query/QueryRegexp 基于请求 URL 的查询参数匹配。因为 v3 下 Query 允许 1 或 2 个参数，所以存在"只给 key、不给 value"的形态——此时只要查询字符串里存在该 key（即使值为空）即命中；在实现中，req.URL.Query()[key] 不存在时直接返回 false，存在时再做等值包含判断，见 matcher.go。

行为	规则
匹配 mobile 查询参数为 true 的请求（如 /search?mobile=true）	Query(`mobile`, `true`)
匹配 mobile 查询参数无值的请求（如 /search?mobile）	Query(`mobile`)
匹配 mobile 参数为 true 或 yes 的请求	QueryRegexp(`mobile`, `^(true|yes)$`)
匹配 mobile 参数为任意值（包括空值）的请求	QueryRegexp(`mobile`, `^.*$`)
大小写不敏感地匹配查询参数	QueryRegexp(`mobile`, `(?i)^(true|yes)$`)

3.6 ClientIP：按客户端 IP 匹配

ClientIP 匹配来自指定客户端 IP 的请求，支持 IPv4、IPv6 与 CIDR 三种形式（如 10.76.105.11、::1、192.168.1.0/24、fe80::/10）。

需要特别强调的是：该匹配器只看请求的真实客户端 IP，绝不使用 X-Forwarded-For 头参与匹配。源码佐证在 matcher.go：它通过 ip.NewChecker 构造检查器，并使用 ip.RemoteAddrStrategy{} 提取远端地址，而不是取转发头。若你的流量要经过多层代理、希望在匹配中使用 X-Forwarded-For，应改用 forwardedHeaders 相关中间件处理后再路由（可参考 IP 策略实现）。

行为	规则
匹配来自某 IP（IPv4）的请求	ClientIP(`10.76.105.11`)
匹配来自某 IP（IPv6）的请求	ClientIP(`::1`)
匹配来自某子网（IPv4）的请求	ClientIP(`192.168.1.0/24`)
匹配来自某子网（IPv6）的请求	ClientIP(`fe80::/10`)

四、规则语法选择：RuleSyntax（v2 与 v3）

⚠️ 弃用警告：ruleSyntax 选项已被弃用，并将在下一个大版本移除。请不要使用该字段，并请将 Router 规则改写为 v3 语法。

Traefik v3 引入了新的规则语法（详见 v2 到 v3 迁移指南）。为便于迁移过渡，ruleSyntax 选项允许按 Router 粒度指定规则解析所用的语法，从而支持异构的 Router 配置。

• ruleSyntax 的默认值继承自安装配置（即原"静态配置"）中的 core.defaultRuleSyntax 选项；
• core.defaultRuleSyntax 默认值为 v3，因此各 Router 的默认规则语法也是 v3。

v2 与 v3 语法在匹配器族上存在差异，从源码可见有两套独立的注册表：v3 使用 matcher.go 中的 httpFuncs（新增了 Header/HeaderRegexp/HostRegexp/PathRegexp/QueryRegexp/ClientIP 等更细粒度匹配器），而 v2 使用 matcher_v2.go 中的 httpFuncsV2（对应旧的 Headers、HeadersRegexp、HostHeader 等）。两套语法在启动时分别编译为独立 parser，由 parser.go 的 SyntaxParser 统一按 ruleSyntax 分派。

配置示例：同一配置中混用 v2 与 v3

以下配置通过 File Provider（结构化配置） 声明两条 Router：Router-v2 走 v2 语法（使用 {subdomain:[a-z]+} 命名分组写法），Router-v3 走 v3 语法（使用 [a-z]+ 裸分组写法）。

## 动态配置（Structured YAML）
http:
  routers:
    Router-v3:
      rule: HostRegexp(`[a-z]+\.traefik\.com`)
      ruleSyntax: v3
    Router-v2:
      rule: HostRegexp(`{subdomain:[a-z]+}.traefik.com`)
      ruleSyntax: v2

## 动态配置（Structured TOML）
[http.routers]
  [http.routers.Router-v3]
    rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
    ruleSyntax = "v3"
  [http.routers.Router-v2]
    rule = "HostRegexp(`{subdomain:[a-z]+}.traefik.com`)"
    ruleSyntax = "v2"

## 容器/服务 Labels
labels:
  - "traefik.http.routers.Router-v3.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
  - "traefik.http.routers.Router-v3.ruleSyntax=v3"
  - "traefik.http.routers.Router-v2.rule=HostRegexp(`{subdomain:[a-z]+}.traefik.com`)"
  - "traefik.http.routers.Router-v2.ruleSyntax=v2"

// 支持 Tags 的 Provider
{
  // ...
  "Tags": [
    "traefik.http.routers.Router-v3.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
    "traefik.http.routers.Router-v3.ruleSyntax=v3",
    "traefik.http.routers.Router-v2.rule=HostRegexp(`{subdomain:[a-z]+}.traefik.com`)",
    "traefik.http.routers.Router-v2.ruleSyntax=v2"
  ]
}

注意 Labels / Tags 场景下 \\ 需要按各自转义规则书写（YAML 与 JSON 中反斜杠本身要被转义）。

五、优先级计算（Priority Calculation）

当多条 Router 规则可能同时命中同一个请求时，Traefik 用优先级来决定把请求交给谁。优先级机制的完整事实如下：

1. 默认按规则长度降序排序：为了避免路径重叠产生的歧义，路由默认按规则长度降序排列。优先级数值直接等于规则字符串的长度，因此规则越长、优先级越高。

   • 源码依据：pkg/muxer/http/muxer.go 的 GetRulePriority 实现为 return len(rule)；排序逻辑在 mux.go 的 routes.Less 中体现为"优先级大者在前"。

2. 0 被忽略：显式设置 priority: 0 意味着放弃手动指定，仍走"按规则长度默认排序"的逻辑。在 pkg/server/router/router.go 中可以看到：当 Priority == 0 时，Traefik 用 httpmuxer.GetRulePriority(rule) 回填默认值。

3. 支持负值：负优先级是合法的。

4. 保留区间上限：Traefik 为内部 Router 保留了一段优先级区间，用户可定义的最大优先级为：

   • 32 位平台：(MaxInt32 - 1000) = 2147482647；
   • 64 位平台：(MaxInt64 - 1000) = 9223372036854774807。

   超过该上限的普通用户 Router 会被拒绝（源码中 const maxUserPriority = math.MaxInt - 1000，router.go）。

5. 跨 Provider 平局裁决：当不同 Provider 的两条路由具有相同数值优先级时，Traefik 使用安装配置中的 providers.precedence 选项决定谁胜出——在 precedence 列表中排在前面的 Provider 赢。对应实现中，每条路由会记录 providerPriority（即其在 precedence 列表中的下标），排序比较时先比用户优先级、再比 Provider 下标，见 muxer.go 的 route 结构。

默认优先级的问题示例

下面配置里有两条 Router 同时监听 foobar.traefik.com 的请求：

## 动态配置（Structured YAML）
http:
  routers:
    Router-1:
      rule: "HostRegexp(`[a-z]+\.traefik\.com`)"
      # ...
    Router-2:
      rule: "Host(`foobar.traefik.com`)"
      # ...

## 动态配置（Structured TOML）
[http.routers]
  [http.routers.Router-1]
    rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
    # ...
  [http.routers.Router-2]
    rule = "Host(`foobar.traefik.com`)"
    # ...

## Labels
labels:
  - "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
  - "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"

// Tags
{
  // ...
  "Tags": [
    "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
    "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"
  ]
}

由于默认优先级 = 规则长度，两条规则的优先级计算如下：

Name	Rule	Priority
Router-1	HostRegexp(`[a-z]+\.traefik\.com`)	34
Router-2	Host(`foobar.traefik.com`)	26

可以看到 Router-1 的默认优先级高于 Router-2，于是所有 Host 为 foobar.traefik.com 的请求都会被 Router-1 接管，而不是语义上更精确的 Router-2。要修正这类"长正则误伤精确域名"的问题，就必须手动设置优先级。

手动设置优先级的完整示例

## 动态配置（Structured YAML）
http:
  routers:
    Router-1:
      rule: "HostRegexp(`[a-z]+\\.traefik\\.com`)"
      entryPoints:
      - "web"
      service: service-1
      priority: 1
    Router-2:
      rule: "Host(`foobar.traefik.com`)"
      entryPoints:
      - "web"
      priority: 2
      service: service-2

## 动态配置（Structured TOML）
[http.routers]
  [http.routers.Router-1]
    rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
    entryPoints = ["web"]
    service = "service-1"
    priority = 1
  [http.routers.Router-2]
    rule = "Host(`foobar.traefik.com`)"
    entryPoints = ["web"]
    priority = 2
    service = "service-2"

## Labels
labels:
  - "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
  - "traefik.http.routers.Router-1.entryPoints=web"
  - "traefik.http.routers.Router-1.service=service-1"
  - "traefik.http.routers.Router-1.priority=1"
  - "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"
  - "traefik.http.routers.Router-2.entryPoints=web"
  - "traefik.http.routers.Router-2.service=service-2"
  - "traefik.http.routers.Router-2.priority=2"

// Tags
{
  // ...
  "Tags": [
    "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
    "traefik.http.routers.Router-1.entryPoints=web",
    "traefik.http.routers.Router-1.service=service-1",
    "traefik.http.routers.Router-1.priority=1",
    "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)",
    "traefik.http.routers.Router-2.entryPoints=web",
    "traefik.http.routers.Router-2.service=service-2",
    "traefik.http.routers.Router-2.priority=2"
  ]
}

上例通过手动指定 priority: 2（高于 Router-1 的 priority: 1），让 Router-2 成功接管 Host 为 foobar.traefik.com 的请求。

六、小结与排查建议

• 写规则时牢记值必须用反引号或转义双引号、正则遵循 Go 语法；涉及 Host 先想清楚是"单级通配 *.example.com"、"全量兜底 *"还是"精确 example.com"，避免被默认长度排序"劫持"。
• 对路径类匹配，Path/PathPrefix 的值必须 / 开头；Header、Query、ClientIP 各自有严格的参数个数与取值约束，配置错误会在规则解析期被明确报错。
• 当"看起来更精确的规则"没有生效时，优先检查：是否两条规则的默认优先级与你的直觉相反（规则更长者优先）、是否跨 Provider 同优先级需要配置 providers.precedence、以及是否有旧版 v2 语法遗留（趁早迁移到 v3，参考 v3 迁移指南）。

若需要继续深挖，可直接在仓库中阅读这些一手材料：匹配器求值核心 pkg/muxer/http/matcher.go、v2 语法族 pkg/muxer/http/matcher_v2.go、规则树解析 pkg/rules/parser.go、路由注册与默认优先级回填 pkg/server/router/router.go、以及大量行为级测试用例 pkg/muxer/http/matcher_test.go。