Knock 敲门

外观切换

飞牛分享直通 ​

这是什么 ​

飞牛分享直通 解决的是一个非常具体的问题：

  • 你想把 飞牛 OS 生成的分享链接直接发给别人
  • 对方不需要先登录 fknock
  • 但你又不想因此把整个根入口、其他路径或其他应用一起放开

它不是“关闭认证”，而是：

  • 只对飞牛分享路径族生效
  • 只在确认该分享链接本身有效后放行
  • 只给这一个分享分配一个短时会话
  • 只允许这个分享后续需要的资源请求继续通过

一句话理解：

正常情况下，反代模式和子域模式下所有访问都要先过 fknock 登录；开启飞牛分享直通后，只有合法的飞牛分享链接可以走一条受限的旁路。

它不是什么 ​

为了避免误解，先把边界说清楚。

它不是：

  • 让飞牛整站免登录
  • 让所有 /、/fnos、/alist 之类的路径都变公开
  • 让直连模式也能随便把分享放出去
  • 替代正常的 TOTP、Passkey 或白名单认证
  • 适用于任意应用的“分享页直通”

它只针对飞牛分享请求族，也就是由 /s/... 承载的那部分访问链路。

什么时候该用 ​

适合下面这些场景：

  • 你在 反代模式 或 子域模式 下使用飞牛
  • 你希望别人直接打开飞牛生成的分享链接
  • 你不希望对方先看到登录页
  • 你又不想因为“方便分享”把整个网关认证关掉

如果你的目标其实是下面这些事，就不该用它：

  • 想让别人直接访问某个管理后台
  • 想把非飞牛应用的下载页、公开页做免登录
  • 当前还在 直连模式
  • 反代模式下，默认路由已经切到别的应用，而不是飞牛本身
  • 子域模式下，已经没有任何一条 Host 映射真正指向飞牛

生效前提 ​

这是这个功能最关键的一部分。下面几个前提缺一不可。

1. 必须在反代模式或子域模式下使用 ​

管理端界面只允许在 反代模式 和 子域模式 下启用它。

原因很简单：

  • 它依赖统一入口来接管 /s/... 请求
  • 依赖网关在认证前先做预检查和旁路判定
  • 也依赖飞牛上游目标必须能被系统稳定识别出来

所以这不是“分享链接专用的直连模式”。

2. 系统必须能定位到真正的飞牛上游 ​

这是最容易忽略，也是最容易导致“明明开了却没用”的前提。

有两种主要识别方式：

  1. 在 反代模式 下，优先读取当前 默认路由
  2. 在 子域模式 下，优先寻找真正指向飞牛的 Host 映射

这意味着：

  • 反代模式 下：如果默认路由指向的是飞牛，校验请求就会打到真正的飞牛分享页
  • 子域模式 下：如果仍保留一条真正指向飞牛的 Host 映射，系统也能定位到正确上游
  • 如果这两个条件都不满足，系统就可能去错误的上游校验，结果通常会失败

这也是为什么当前产品会提示你：

反代模式下建议把 5666 对应的飞牛路由保留为默认路由；子域模式下建议保留一条明确的飞牛 Host 映射，例如 fnos.example.com。

3. 外部访问必须真的经过 fknock 统一入口 ​

无论你走的是：

  • 本地 7999
  • FRP 暴露出来的地址
  • Cloudflared 绑定出来的域名

都要确保外部请求最终还是进入 fknock，再由它接管 /s/... 的预检查和放行。

如果你的链路中有其他前置代理把路径改坏了，或者根本没经过 fknock，这个功能自然不会生效。

4. 分享链接必须是飞牛标准分享入口 ​

系统识别的分享入口是 /s/{shareId} 这一路径模型，并且 shareId 必须满足飞牛现有分享链接格式。

文档层面你只需要记住：

  • 这是“飞牛原生分享链接”的直通
  • 不是任意自定义路径的直通

它到底怎么工作 ​

下面按真实链路讲一次。

第 1 步：先识别这是不是飞牛分享请求 ​

当访客访问 /s/... 时，fknock 会先在认证前执行一次预检查。

如果当前请求：

  • 不是 /s 路径族
  • 或者访问者本来就已经有正常访问上下文

那它就不会走这条“分享旁路”逻辑。

第 2 步：拿分享 ID 去飞牛上游做一次真实校验 ​

对入口型请求 /s/{shareId}，系统不会只看 URL 长得像不像，而是会主动请求上游飞牛的同一路径。

然后它会从返回的 HTML 里解析 share-data 脚本块。

只有在下面条件同时成立时，才认为这个分享有效：

  • 返回内容可以成功解析
  • code === 0
  • 能拿到有效的 token

也就是说，它信任的是“飞牛上游确认这个分享存在且可访问”，而不是“有人拼了一个像分享链接的 URL”。

第 3 步：先把入口规范化，再决定是否放行 ​

如果分享有效：

  • 访问的是干净入口 /s/{shareId}：允许继续
  • 访问的是带多余查询参数或非规范入口：先重定向到干净入口

如果分享无效，或者当前无法确认有效性：

  • 直接回到 /

这是一种典型的 fail closed 行为，也就是“宁可拒绝，也不盲放”。

第 4 步：在真正放行时签发一个短时分享会话 ​

当网关进入认证判定阶段时，如果它确认这次访问属于合法分享，会给浏览器写一个单独的分享会话 Cookie：

  • 名称：fn-knock-fnos-share-session
  • 作用域：只在 /s 下携带

这个 Cookie 用来告诉网关：

  • 这个浏览器刚刚通过了哪一个分享的校验
  • 后续属于同一分享的资源请求，可以继续放行

第 5 步：只放行这个分享真正需要的后续资源 ​

系统允许继续通过的，不是“所有 /s 请求”，而是和当前分享会话明确匹配的几类路径：

  • 分享入口本身 /s/{shareId}
  • 分享详情页下的后续子路径
  • 预览资源 /s/preview/{shareId}
  • 缩略图资源 /s/thumb/{shareId}
  • 分享静态资源 /s/static/...

这一步非常关键，因为它意味着：

  • 系统不是把整个站点切成“公开模式”
  • 而是只为当前分享保留一条受限访问通道

第 6 步：每次命中有效资源时刷新分享会话 TTL ​

只要请求仍然属于当前分享资源族，系统就会刷新分享会话的有效期。

所以实际体验是：

  • 刚进入分享页时会建立会话
  • 浏览图片、加载缩略图、继续点资源时会续期
  • 长时间不操作后，会自然过期

如果浏览器带着分享会话 Cookie 去访问：

  • 不属于当前分享的路径
  • 或者分享会话本身已经失效

系统会：

  • 清掉分享会话 Cookie
  • 把请求重定向到 /

这保证了分享旁路不会被无限外扩。

为什么说“不会引发其他安全风险” ​

这个说法不是宣传文案，实际链路里有几层收束。

只对 /s 路径族生效 ​

它不会影响：

  • 管理后台
  • 普通映射路径
  • 其他应用
  • 根路径下的常规登录流程

必须先经过飞牛上游校验 ​

它不会因为“URL 长得像分享链接”就直接放行，而是必须让上游飞牛返回合法分享数据。

分享会话只绑定到单个分享 ​

一个分享会话记录里会保存：

  • shareId
  • 规范入口路径
  • 飞牛返回的分享元数据

这意味着当前会话不是“对整个飞牛免登录”，而是“对这一条分享免登录”。

当前分享会话 Cookie 不会像普通登录会话那样挂在全站根路径，而是只作用于 /s。

这能显著减少它对其他业务路径的影响面。

无法确认时直接拒绝 ​

无论是：

  • 上游超时
  • HTML 结构无法解析
  • 分享已失效
  • 路径和当前分享会话不匹配

默认行为都不是“先放再说”，而是回退到拒绝或重定向。

参数说明 ​

下面这 4 个参数并不是“越大越好”，它们分别控制不同的链路阶段。

字段默认值后端范围作用
启用飞牛分享直通false布尔值是否启用这套分享旁路逻辑
上游校验超时2500 ms500 ~ 15000 ms第一次访问分享入口时，等待飞牛上游返回可校验页面的最长时间
校验缓存时长30 s5 ~ 300 s同一分享链接的校验结果在 Redis 中缓存多久，命中后不必每次都重新探测上游
校验锁时长5 s1 ~ 30 s多个并发请求同时探测同一个分享时，避免重复打爆上游的短锁时长
分享会话时长300 s30 ~ 3600 s访客通过校验后，分享会话可保持多久；命中同一分享资源时会续期

四个参数分别怎么理解 ​

上游校验超时 ​

这是“第一次确认分享是否合法”的等待时间。

如果设得太短：

  • 飞牛本机忙一点
  • 经过 Cloudflared / FRP 链路稍慢一点
  • 飞牛分享页响应略慢一点

都可能被误判成失败。

如果设得太长：

  • 非法分享或异常请求会占着连接等更久
  • 访客失败时也会感觉更慢

家庭网络、大多数本机部署先保留默认 2500 ms 就够了。

校验缓存时长 ​

这是“同一个分享最近已经探测过”的结果缓存。

默认值的好处是：

  • 连续打开同一分享时更快
  • 减少对飞牛分享页的重复探测

但也要知道它的副作用：

  • 如果一个分享刚刚失效或刚刚重新生成，结果可能会在这段缓存时间内延迟反映

  • 可明确解析出的“有效”或“无效”结果都可缓存

  • 上游超时、页面无法解析这类“不确定”结果不会缓存

校验锁时长 ​

这不是给用户感知的时间，而是给系统“防并发重复探测”用的。

典型场景：

  • 同一个分享页一打开，就会并发请求 HTML、预览图、缩略图
  • 或者多个访客在非常接近的时间同时打开同一个分享

这时系统先给这个分享挂一个短锁，优先等首个探测结果落入缓存，再让后续请求复用。

分享会话时长 ​

这个时间决定：

  • 访客在通过一次分享校验后，可以保持多久的连续访问体验

如果设得太短：

  • 分享页刚打开正常
  • 预览多一点、切换几次资源
  • 或在页面停留一会儿再继续操作

就可能突然被打回首页。

如果设得太长：

  • 分享旁路保持时间会更久
  • 虽然仍然只限 /s，但暴露窗口也会相应变大

所以它是“体验”和“收口速度”之间的平衡项。

推荐配置 ​

如果你不想一开始就做复杂调优，可以直接按下面来。

场景一：本机反代或子域直连，网络稳定 ​

保持默认值：

  • 上游校验超时：2500 ms
  • 校验缓存时长：30 s
  • 校验锁时长：5 s
  • 分享会话时长：300 s

场景二：飞牛机器偏慢，或链路经过隧道后延迟略高 ​

可以先把：

  • 上游校验超时调到 3500 ~ 5000 ms

其他先不动。

场景三：访客经常浏览图片预览、缩略图较多 ​

可以考虑：

  • 校验缓存时长：30 ~ 60 s
  • 分享会话时长：300 ~ 600 s

优先解决“刚进来正常，翻几页资源后又掉回首页”的体验问题。

场景四：同一分享会被很多人同时打开 ​

可以考虑：

  • 校验锁时长：5 ~ 10 s

避免高并发首次访问时反复探测同一个上游分享页。

正确的启用顺序 ​

推荐按下面顺序做，而不是先开开关再碰运气。

  1. 先确认当前处于 反代模式 或 子域模式
  2. 反代模式 下进入 路径映射，确认飞牛 5666 对应映射还在，且仍然是 默认路由
  3. 子域模式 下进入 子域映射，确认至少保留一条真正指向飞牛的 Host 映射
  4. 确认外部流量最终进入的是 fknock 统一入口
  5. 再进入 系统设置 → 飞牛
  6. 打开 启用飞牛分享直通
  7. 保留默认参数先保存
  8. 用一个真实有效的飞牛分享链接做外部测试

建议怎么测试 ​

不要只在内网、只在自己已登录的浏览器里测。

推荐这样测：

  1. 新建一个飞牛分享链接
  2. 复制外部访问地址
  3. 用浏览器无痕窗口或另一台未登录设备打开
  4. 确认它不是先进登录页，而是直接进入分享内容
  5. 再测试预览图、缩略图、二级资源是否正常
  6. 等待几分钟后继续操作，确认会话续期是否符合预期

如果你同时走 Cloudflared 或 FRP，最好再从真正外网环境测一次，而不是只在局域网回环测试。

最常见的失败原因 ​

原因一：系统已经找不到真正的飞牛上游 ​

这是第一高频问题。

症状通常是：

  • 开关明明已经开了
  • 分享链接却还是被打回首页
  • 或者根本没有进入分享内容

优先检查：

  • 反代模式 下，当前默认路由是不是还指向飞牛 5666
  • 子域模式 下，是否还保留着真正指向飞牛的 Host 映射

原因二：当前其实既不是反代模式，也不是子域模式 ​

界面上这个功能在直连模式就是不可用的。

如果你的目标是“让分享链接直接打开”，先确认访问模型本身是不是 反代模式 或 子域模式，而不是直连模式。

原因三：分享链接已经失效，或并不是标准飞牛分享链接 ​

如果上游飞牛自己都认不出这条分享，fknock 也不会放行。

最简单的排查方式是：

  • 先在飞牛本地或直达飞牛上游的环境里确认这个分享本身还能打开

原因四：上游太慢，被超时截断 ​

如果飞牛设备比较忙、磁盘压力大、或者链路经过隧道后延迟变高，可能只是“校验来不及完成”。

这时优先临时增大：

  • 上游校验超时

原因五：刚改完分享状态，但缓存还没过 ​

系统会缓存已解析出的有效或无效结果。

所以你如果：

  • 刚删除旧分享
  • 刚新建同名分享
  • 刚调整分享权限

短时间内看到旧结果，不一定是程序没生效，也可能只是还在缓存窗口里。

你应该记住的 5 个结论 ​

  1. 飞牛分享直通 是“分享路径旁路”，不是“整站免登录”。
  2. 它只建议在 反代模式 或 子域模式 下使用。
  3. 它强依赖“系统仍能正确识别飞牛上游”这个前提。
  4. 它会给合法分享签发一个只作用于 /s 的短时会话。
  5. 一旦请求越界、分享失效或无法确认合法性，系统会直接收口，而不是继续放。

相关阅读 ​

QQ群：1081609274

Copyright © fn-knock docs