第10章 重定向配置
第10章 重定向(Redirects)
重定向可以将你域名或资源上的某个路径的请求转发到另一个 URL,用于淘汰旧域名、迁移现有资源的路径,或把流量从一个源转发到另一个源。
你可以在组织的 Settings -> Redirects 中管理重定向。
绑定到域名或资源
每个重定向都必须绑定到以下两者之一:
| 绑定对象 | 监听主机 | 使用场景 | | --- | --- | --- | | Domain(域名) | 你名下某个域名的 hostname(子域名或基础域名) | 需要在非(或不只是)公开资源的 hostname 上做重定向时,比如淘汰旧域名 old.example.com。即使 hostname 上有资源,但不想让重定向跟随该资源的生命周期,也可以用这种方式 | | Resource(资源) | 绑定的公开资源的完整 hostname | 想让现有资源的部分路径重定向、其余路径仍正常访问该资源,并且接受资源删除时重定向一并删除 |
绑定到域名(Domain)
当你只需要填入组织内某个域名的子域名或基础域名、不管上面有没有资源时,选择 Domain。
- 选一个域名和可选的子域名,监听主机就是 subdomain.baseDomain,子域名为空时就是基础域名本身。 - 重定向有独立的 TLS 设置。Pangolin 会为该主机签发证书。自建部署中可以关闭 SSL 以使用纯 HTTP;Pangolin Cloud 上则始终启用 HTTPS。 - 该主机上不需要有公开资源。 - 可以与现有资源使用相同的 hostname(相同的域名和子域名)。重定向与资源互不关联,删除或禁用资源不影响重定向。 - 删除域名会同时删除其上所有重定向。
绑定到资源(Resource)
当你想使用资源的完整 hostname(资源使用通配符时也包含通配符)时,选择 Resource。
- 监听主机即资源的完整域名(含通配符,如资源使用了通配符)。 - TLS 跟随资源——重定向上没有单独的 SSL 开关。 - 未匹配重定向的路径照常访问资源。 - 重定向的匹配发生在资源鉴权之前,所以即使资源受保护,访客无需登录就会被重定向。 - 资源被禁用或没有绑定域名时,重定向不生效。 - 删除资源会同时删除其上所有重定向。
请求如何匹配
当以下两个条件同时满足时,请求才算匹配到一个重定向:
- Host 与绑定对象的监听主机一致(域名 hostname 或资源完整域名)。 - 路径符合重定向的路径规则——如果没有设置路径规则,则匹配该主机上的所有路径。
路径匹配类型:
| 类型 | 行为 | | --- | --- | | Exact | 路径必须与匹配路径完全一致 | | Prefix | 路径必须以匹配路径作为路径段开头(例如 /products 能匹配 /products/shoes,但不能匹配 /productsforsale) | | Regex | 路径必须匹配正则表达式 |
把匹配路径留空,即可重定向该主机上的所有请求。
当重定向与公开资源共用一个主机时,重定向总是优先评估。多个重定向之间则按优先级决定先后。
目标地址与路径改写
目标地址只能是一个 origin,即协议、主机和可选端口,例如 https://example.com 或 https://example.com:8443。不要在目标地址里填写路径、查询字符串或锚点。
最终的重定向 URL 构成为:
目标 origin + 改写后的路径 + 原查询字符串
默认保留原始请求路径。你也可以选择配置路径改写:
| 改写类型 | 行为 | | --- | --- | | Exact | 替换整个路径 | | Prefix | 替换匹配到的前缀,保留剩余部分 | | Regex | 按匹配模式替换;替换串支持捕获组($1、$2、…) | | Strip prefix | 移除匹配的前缀;可选追加新前缀 |
捕获组
当改写类型为 Regex 时,匹配路径(匹配类型为 Regex)中的括号定义捕获组。在改写路径中用 $1、$2 等引用它们,替换规则与 JavaScript 的 String.replace 相同。
例如:把 /blog/2020/post 迁移到 /archive/post-2020:
| 字段 | 值 | | --- | --- | | 路径匹配类型 | Regex | | 匹配路径 | ^/blog/(\d+)/(.*)$ | | 改写类型 | Regex | | 改写路径 | /archive/$2-$1 |
当匹配类型为 Prefix、改写类型为 Regex 时,前缀之后的内容可用 $1 引用(例如匹配 /old、改写为 /new$1,会把 /old/x 变成 /new/x)。
如果只想改路径、让访客留在同一主机上,可以启用 Use Same Domain as Source。
原始查询字符串始终会被保留。
永久与临时
| 设置 | 状态码 | 行为 | | --- | --- | --- | | Temporary(默认) | 307 | 浏览器和客户端不应无限期缓存该重定向 | | Permanent | 308 | 浏览器可以缓存该重定向,适用于永久性迁移 |
只有在希望客户端记住新地址时才开启 Permanent。
优先级
每个重定向的优先级取值范围为 1 到 1000,数值越高越先评估。
重定向始终优先于同一主机上的公开资源,即使界面上优先级看起来相近,匹配到的重定向也会胜出。优先级主要用于排列多个重定向之间的先后顺序。