路径映射

这页解决什么问题

路径映射 是反代模式最核心的页面。

它决定的是：

• 外部用户访问哪个路径
• 请求最终会被转发到哪个本地服务
• 这条路径是否需要先登录
• 目标服务是否需要 重写 HTML、去除前缀 或 根目录模式

如果你把反代模式理解成“统一入口 + 多个子服务”，那路径映射就是把这个模型真正落地的地方。

如果你已经有公网入口和正式域名，并且希望每个 Web 服务都有独立子域，通常更推荐优先使用：

• 子域映射

一条映射包含哪些信息

最基本的一条映射至少有两个字段：

• 触发路径
• 目标地址

例如：

• /alist → http://127.0.0.1:5244
• /jellyfin → http://127.0.0.1:8096
• /nav → http://127.0.0.1:3000

映射是怎么匹配的

fknock 使用的是“最长前缀匹配”。

例如你同时有：

• /app
• /app-admin

那么访问 /app-admin/users 时，会优先命中 /app-admin，不会误走 /app。

这也是为什么建议你在路径命名上保持清晰，避免容易混淆的短前缀。

两种添加方式

一键发现

适合：

• 机器上已经跑了不少服务
• 你不知道它们具体端口
• 想先批量拉出来，再逐个微调

一键发现会扫描本地常见服务并给出建议规则。默认建议通常会偏向：

• use_auth = true
• rewrite_html = true
• strip_path = true

但这只是建议，不代表一定适合你的应用。

最近这一块的识别能力也更完整了一些，像下面这些服务会更容易被识别并给出建议规则：

• AList
• 小雅 AList
• OpenList
• Sun-Panel

手动添加

适合：

• 你已经知道服务的本地地址
• 想自己控制路径和选项

这是多数正式部署最终会回到的方式。

目标地址有什么边界

目标地址只能是：

• 回环地址
• 局域网地址
• 本机或内网的私有服务

换句话说，你通常应该填：

• 127.0.0.1
• localhost
• 192.168.x.x
• 10.x.x.x

而不是直接转发到公网网站地址。

四个常见选项分别什么时候用

重写 HTML

适合大多数“前端页面型服务”。

如果你遇到下面问题，优先尝试打开它：

• CSS 丢失
• JS 资源加载不到
• 页面里的链接跳回根路径

它的核心作用是：

• 把页面里常见的绝对路径引用改写成带前缀的路径

要求身份认证

如果你希望某个服务必须先经过 fknock 认证，再能访问，就打开它。

典型场景：

• 管理后台
• 私有文件服务
• 个人面板
• 内部工具

根目录模式

适合“非常依赖运行在网站根路径 / 下”的应用。

这个模式的实际行为不是简单地改写路径，而是：

• 记录用户命中的路径
• 再引导浏览器回到 /
• 后续请求继续按记录的映射处理

如果某个应用普通路径映射总是表现异常，可以优先尝试这个模式。

去除前缀

适合目标服务本身不认识 /alist、/nav 这种前缀，只认识根路径 / 的场景。

如果你对外想暴露 /alist，但目标应用实际上只会处理 / 开头的路径，那么通常就需要打开这个选项。

默认路由是什么

默认路由决定“访问根路径 / 时，优先进入哪个服务”。

但在大多数实际使用场景里，这一项通常不需要手动设置。

推荐的产品策略是：

• 通过服务发现接入服务后，让系统自动把 飞牛 OS 设置为默认服务
• 一般建议保持这个默认设置，不要主动改动

这样做有两个好处：

1. 根路径行为更稳定
2. 新手不容易因为误改默认路由，导致入口体验和预期完全不一致

只有当你非常明确地希望访问 / 时直接进入某个别的服务时，才建议手动调整默认路由。

修改映射后为什么还要“同步路由”

因为映射配置不仅要保存在后台，还需要同步到 Go 网关。

以下情况建议手动执行一次 同步路由：

1. 刚改完多条映射
2. 你明确手动调整过默认路由
3. 你怀疑规则还没生效

推荐的排错顺序

如果某条映射打不开，不要一开始就怀疑 fknock。

建议按下面顺序排查：

1. 目标服务在本机能否直接打开
2. 目标地址和端口是否填写正确
3. 路径是否冲突
4. 是否需要 去除前缀
5. 是否需要 重写 HTML
6. 是否应该启用 根目录模式
7. 改完后是否执行过 同步路由

相关阅读

• 反代模式上手
• 内网穿透
• 用 fknock 搭建反代访问