路径响应
这页解决什么问题
路径响应 用来给某一个子域 Host 额外添加路径级规则。
它只在子域映射模式下生效，入口是：
系统设置 → 网关 → 路径响应
可以把它理解成：
Host 仍然决定这个站点是谁，路径响应只处理这个 Host 下少数特殊路径。
例如你已经有：
app.example.com→http://127.0.0.1:3000
然后希望：
app.example.com/api转发到另一个上游app.example.com/healthz直接返回固定文本
这类需求就适合用路径响应。
它和路径映射不是一回事
反代模式里的路径映射是主路由模型：
/alist/jellyfin/photos
子域模式里的路径响应是 Host 映射的补充规则：
alist.example.com/specialfnos.example.com/status
所以它不应该被用来把子域模式重新改回“所有服务都靠路径组织”。
如果你要大规模按路径组织服务，优先看：
如果你要让每个服务拥有独立子域，优先看：
一条路径规则包含什么
当前 Host
进入页面后，先选择要维护的 Host。
可选对象来自已有 Host 映射，并且不会包含鉴权服务映射。
也就是说，路径响应通常配置在业务子域上，而不是配置在：
auth.example.com
路径
路径必须以 / 开头，例如：
/api/healthz/public/status
不允许配置根路径：
/
因为根路径仍然应该由当前 Host 的默认目标接管。
下面这些保留路径也不能使用：
- 以
/__开头的路径 /s/s/
这些路径已经被认证、分享直通或内部能力占用。
匹配方式
路径响应支持两种匹配：
精确匹配：只命中完全相同的路径前缀匹配：命中这个路径及其后续子路径
同一个 Host 下，不能存在相同匹配方式和相同路径的重复规则。
动作
路径规则有两类动作：
| 动作 | 适合场景 |
|---|---|
反代 | 把这个路径转发到另一个 HTTP 上游 |
固定响应 | 直接由网关返回状态码、内容类型、响应头和正文 |
如果选择 反代，需要填写目标地址。
如果选择 固定响应，需要填写：
- HTTP 状态码，范围
100-599 Content-Type- 响应正文
- 可选响应头
固定响应不能自定义一些传输级响应头，例如：
ConnectionContent-LengthContent-TypeTransfer-EncodingUpgrade
其中 Content-Type 应该通过页面里的内容类型字段配置。
反代规则里的两个开关
剥离匹配路径
开启后，上游看到的路径会去掉当前匹配前缀。
例如规则是：
/api→http://127.0.0.1:8080
访问：
/api/users
上游可能收到：
/users
关闭后，上游仍然收到完整路径：
/api/users
改写 HTML 路径
这个开关用于处理一些上游页面里的相对资源路径。
如果你只是代理 API，通常影响不大。
如果你代理的是带页面和静态资源的子路径，开启后更容易避免资源继续指向错误位置。
它会继承哪些 Host 设置
路径响应规则会继承当前 Host 映射的这些设置：
- 登录要求
- 严格白名单
- Host 响应设置
- Basic Auth 跳过凭据
- 代理头策略
也就是说，路径响应不是绕过当前 Host 安全策略的后门。
如果当前 Host 要求登录，那么这条路径规则也仍然在同一套 Host 访问控制之下。
未命中时会发生什么
如果请求没有命中任何路径响应规则，会回到当前 Host 映射的默认目标。
例如：
app.example.com默认目标是http://127.0.0.1:3000- 只配置了
/healthz固定响应
那么访问：
/healthz：由路径响应处理/dashboard：仍然进入http://127.0.0.1:3000
典型用法
给某个 Host 加健康检查
可以添加：
- 路径：
/healthz - 匹配：精确匹配
- 动作：固定响应
- 状态码：
200 - 内容类型：
text/plain; charset=utf-8 - 正文：
ok
这样前置平台或自己排查时，可以快速确认网关和 Host 路由是否正常。
给同一 Host 下的 API 单独换上游
可以添加：
- 路径：
/api - 匹配：前缀匹配
- 动作：反代
- 目标：
http://127.0.0.1:8080
其他页面仍然进入当前 Host 的默认目标。
临时挡住某个路径
可以添加固定响应：
- 路径：
/legacy - 匹配：前缀匹配
- 状态码：
410 - 正文：
gone
这比临时改上游应用配置更直接。
排错顺序
如果路径响应没有按预期生效，建议按这个顺序看：
- 当前是否在子域映射模式下
- 是否选中了正确的 Host
- 路径是否以
/开头，并避开保留路径 - 匹配方式是精确还是前缀
- 当前请求是否先被 Host 的登录或白名单策略拦住
- 如果是反代规则，上游目标是否能从 fknock 所在机器访问
- 请求日志里路由类型和上游目标是否符合预期