跳到主要内容

URL 重写

AISIX AI 网关可以在路由前重写请求路径。代理监听器入口处会按顺序执行重写规则列表：第一条 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否规则触发时在网关日志中使用的标签。
match是针对原始、百分号编码的请求路径进行测试的正则表达式（不包含查询字符串），且不会执行解码或规范化。使用 ^ 和 $ 锚定整个路径。
rewrite是用于替换路径匹配部分的内容。$1 … 会展开编号捕获组，${server} 会展开 match 中定义为 (?P<server>…) 的命名组。当引用后紧跟字面文本时，请使用带花括号的形式（${1}text）。不得包含 ?、# 或空白字符——查询字符串会自动保留。

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

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

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

规则的应用方式​

  • 规则按声明顺序执行；第一条匹配的规则生效且只应用一次——重写后的路径不会再次进入规则列表。
  • rewrite 会替换路径中匹配的部分。如果 match 未使用锚点，未匹配的前缀和后缀会保留。
  • 查询字符串会按原样保留。
  • 未匹配任何规则的请求会原样通过，规范路径可以与重写形式同时正常工作。
  • 重写适用于代理监听器上的所有请求，不影响 Admin 和指标监听器。

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

示例：提供按服务器划分的 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，以原始名称列出 github 服务器的工具，并使用这些名称调用工具——无需更改客户端，调用方 API Key 的工具访问权限、限流、预算和护栏也会照常应用。

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

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

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

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