跳到主要内容
版本：1.5.0

URL 重写

AISIX AI 网关可以在所有路由匹配之前重写请求路径，包括按 Host 匹配的透传路由。代理监听器入口处会按顺序执行重写规则列表：第一条同时满足可选 hosts 条件和 match 正则表达式的规则会重写路径。之后请求进入正常端点流程——认证、访问控制、限流和遥测的应用方式与客户端直接发送重写后路径时完全相同。

当现有客户端配置了 AISIX 原生不提供的 URL 形式时，可使用 URL 重写。例如，某些网关为每台 MCP 服务器暴露一个 URL，或者外部监控已经探测某个内部约定的健康检查路径。

配置重写规则​

重写规则是 config.yaml 中 proxy 块下的启动配置：

proxy:
  addr: "0.0.0.0:3000"
  url_rewrites:
    - name: per-server-mcp-compat
      match: "^/mcp-servers/([^/]+)/mcp$"
      rewrite: "/mcp/$1"
字段是否必需说明
name否规则触发时在网关日志中使用的标签。
hosts否限定规则生效范围的入站主机名。省略表示匹配所有 Host；显式列表不能为空。匹配忽略大小写和请求中的端口，支持精确主机名和仅匹配额外一层域名的 *. 前缀，例如 *.example.com。条目不能包含协议、端口或路径。
match是针对原始、百分号编码的请求路径进行测试的正则表达式（不包含查询字符串），且不会执行解码或规范化。使用 ^ 和 $ 锚定整个路径。
rewrite是用于替换路径匹配部分的内容。$1 … 会展开编号捕获组，${server} 会展开 match 中定义为 (?P<server>…) 的命名组。当引用后紧跟字面文本时，请使用带花括号的形式（${1}text）。不得包含 ?、# 或空白字符——查询字符串会自动保留。

与其他启动配置一样，更改规则需要重启网关。启动验证会拒绝错误规则，并在错误中指出规则名称，包括无效正则表达式、引用了模式中未定义的捕获组、模板中包含禁用字符，以及可能匹配空字符串的模式。这样，拼写错误会立即暴露，而不会悄然将流量路由到错误位置。

如果网关完全通过环境变量配置，例如由 Helm 管理的部署，请将整个列表设置为一个 JSON 数组：

export AISIX_PROXY__URL_REWRITES='[{"name":"per-server-mcp-compat","match":"^/mcp-servers/([^/]+)/mcp$","rewrite":"/mcp/$1"}]'

规则的应用方式​

  • 规则按声明顺序执行；第一条同时匹配 Host 和路径的规则生效且只应用一次——重写后的路径不会再次进入规则列表。Host 不匹配时继续检查下一条。请将范围较窄的规则放在同样可能匹配的宽泛规则之前。
  • rewrite 会替换路径中匹配的部分。如果 match 未使用锚点，未匹配的前缀和后缀会保留。
  • 查询字符串会按原样保留。
  • 未匹配任何规则的请求会原样通过，规范路径可以与重写形式同时正常工作。
  • 重写先于代理监听器上的所有业务路由执行，按 Host 和按路径匹配的透传路由都会看到重写后的路径。不影响 Admin 和指标监听器。

重写用于选择处理请求的网关端点，绝不会绕过治理。重写后的请求由目标端点进行认证和授权，指标与访问日志会记录重写后的路由。

重写规则只改变路径，不改变 Host 或路由选择策略。匹配的 Host 透传路由仍然优先于网关内置端点，即使重写后的路径是 /v1/chat/completions。

与 1.2.0 相比，按 Host 匹配的透传请求现在也会执行 URL 重写。请检查现有全局规则，为只应作用于网关自身主机名的规则添加 hosts。

示例：将 Chat 别名限定到一个 Host​

若要在一个主机名上将 /chat 用作标准 Chat Completions 端点，同时保留其他服务的 /chat 路径：

proxy:
  url_rewrites:
    - name: chat-alias
      hosts: ["gateway.example.com"]
      match: "^/chat$"
      rewrite: "/v1/chat/completions"

只要该主机名未被 Host 透传路由接管，发往 gateway.example.com/chat 的请求就会进入标准 Chat 流程。发往 agent.example.com/chat 的请求不受这条规则影响，可以使用已配置的透传路由。若需为 /pjt/chat 设置别名，将 match 改为 "^/pjt/chat$"。请求体仍须使用标准 Chat Completions 格式，包括已配置的模型名称和 messages。

hosts 优先使用请求 URI 中的 authority，包括代理链传入的 absolute-form 请求；URI 中没有 authority 时，读取入站 Host 请求头。不使用 X-Forwarded-Host。例如，GATEWAY.EXAMPLE.COM:8443 匹配 gateway.example.com。*.example.com 通配符匹配 agent.example.com，但不匹配 example.com 或 one.agent.example.com。

使用 AISIX Helm chart 时，通过现有的 extraEnvVars 配置：

extraEnvVars:
  - name: AISIX_PROXY__URL_REWRITES
    value: '[{"name":"chat-alias","hosts":["gateway.example.com"],"match":"^/chat$","rewrite":"/v1/chat/completions"}]'

示例：提供按服务器划分的 MCP URL​

一些网关会在独立 URL 上暴露每台 MCP 服务器，例如 /mcp-servers/github/mcp，客户端则使用工具的原始名称调用工具。AISIX 通过按服务器划分的 MCP 端点 /mcp/{server} 原生提供此约定——一条重写规则即可将旧版 URL 形式连接到该端点：

proxy:
  url_rewrites:
    - name: per-server-mcp-compat
      match: "^/mcp-servers/([^/]+)/mcp$"
      rewrite: "/mcp/$1"

配置了 https://gateway.example.com/mcp-servers/github/mcp 的客户端现在会访问 /mcp/github。AISIX 通常以原始名称列出 github 服务器的工具并接受使用这些名称的调用，因此无需更改客户端。如果原始名称与已注册服务器的前缀存在歧义，AISIX 会公布仍可调用的带命名空间名称。调用方 API Key 的工具访问权限、限流和安全护栏也会照常应用。匹配的 AISIX Cloud 预算同样继续生效。

只有声明的 URL 形式会得到服务：使用上述规则时，/mcp-servers/github/sse 不匹配任何内容并返回 404，而不会被悄然路由。

示例：为任意路径设置别名​

规则并非 MCP 专用。任何路径都可以映射到任意代理端点：

proxy:
  url_rewrites:
    - name: legacy-health
      match: "^/healthz-compat$"
      rewrite: "/livez"