子域映射

子域映射 按 HTTP Host 把多个域名分发到本地 Web 服务，是新部署的默认路由方式。它可用于两种网络拓扑：

• 子域模式：域名直接解析到可达的公网入口。
• 内网穿透 → 子域映射：FRP 或 Cloudflared 把各子域请求送入网关。

两者都使用 auth.example.com 作为登录入口，并让 nas.example.com、alist.example.com 等业务 Host 共用同一网关。路径映射是旧部署的兼容方案，不是子域映射的前置条件。

请求链路

浏览器 -> 公网直连或隧道 -> fn-knock 网关 -> 按 Host 匹配 -> 本地 Target
                                  |
                                  +-> 公开 / 要求登录

公网直达且保留默认端口时，访问形式通常为 https://nas.example.com:7999。前置 EdgeOne、ESA 或 Cloudflared 后，访客通常使用标准 https://nas.example.com，但源站仍回到实际网关端口；飞牛 Docker FPK 的默认端口是 8999，其他常见部署为 7999。

配置顺序

1. 在 系统设置 → 模式 选择 子域模式，或选择 内网穿透 → 子域映射。
2. 在 子域映射 保存根域名，例如 example.com。
3. 点击 添加鉴权服务，创建 auth.example.com。
4. 配置公网 DNS、路由器转发或 Tunnel Public Hostname，使相关 Host 都进入同一网关。
5. 添加业务 Host，并决定每条映射是否开启 要求登录。
6. 使用移动网络验证登录跳转、返回地址和请求日志中的客户端 IP。

公网直连的完整流程见 子域模式上手 和 直连访问教程。

子域模式配置

字段	作用	建议
域名	生成业务 Host 的父域，例如 example.com	先保存，再添加鉴权服务和业务映射
当前鉴权服务	未登录时的统一登录入口	使用 auth.example.com；只能有一条
鉴权服务所使用的端口	生成登录跳转 URL 时使用的外部端口	填写访客实际看到的端口
边缘网络真实 IP 识别	在公网直连子域模式中读取 EdgeOne / ESA 的访客地址	只在对应平台回源时开启

鉴权服务端口只影响外部 URL，不会替路由器、容器或边缘平台开放端口。

EdgeOne / ESA

公网直连子域模式可开启腾讯云 EdgeOne / 阿里云 ESA 支持。开启后，公开 URL 可省略 :7999，网关按平台头读取真实客户端 IP：

平台	客户端 IP 头
腾讯云 EdgeOne	EO-Connecting-IP
阿里云 ESA	Ali-Real-Client-IP

ESA 还需在站点的托管转换中启用“添加真实客户端 IP 标头”。该开关只覆盖 EdgeOne / ESA，不是任意 CDN 的通用信任开关；Cloudflared 应使用 内网穿透 → 子域映射 的专用链路。

边缘平台负责外部 80 / 443 时，回源仍应指向 fn-knock 的实际网关端口，并关闭会缓存登录响应的规则、允许 WebSocket。证书和解析分别见 SSL 证书 与 DDNS 管理。

Host 映射

一条映射至少包含 Host 和 Target：

nas.example.com   -> http://127.0.0.1:5666
alist.example.com -> http://127.0.0.1:5244

字段	行为
Host / 子域名	匹配请求的 Host；已保存根域名时可只填 nas
Target	HTTP / HTTPS 上游地址，必须能从 fn-knock 所在环境访问
要求登录	未登录时跳到鉴权 Host，完成后返回原地址
禁用 / 定时启用或禁用	手动下线，或按服务器本地时间每天控制开放窗口
显示传送门	控制登录后页面上的应用切换与退出入口
展示标题	覆盖列表、传送门和书签中的显示名称
Basic Auth 跳过	向上游请求注入 Basic Auth 用户名和密码

业务服务尽量只监听回环或内网地址，避免绕过网关。Docker 中的 127.0.0.1 指容器自身；代理宿主机服务时应使用容器可达的宿主机地址。

鉴权服务是一条特殊 Host 映射：它必须公开，不能再开启要求登录或 Basic Auth 注入，否则登录入口会形成循环或被自身拦截。

Basic Auth 是上游凭据注入

Basic Auth 跳过 保存的是目标服务自己的 Basic Auth 凭据。网关在代理请求、抓取页面标题和 favicon 时把凭据发给上游，以免浏览器再次弹出 Basic Auth 对话框。

它不创建 fn-knock 账号，不替代 auth.example.com 登录，也不改变 要求登录 或已有 strict_whitelist 规则。凭据按敏感配置处理；只有确实需要时才保存。

访问策略与 local_exempt

当前界面配置	未获授权的公网请求
关闭 要求登录（当前登录优先映射）	直接进入上游
开启 要求登录	没有有效来源 IP 授权或会话时，跳转到鉴权 Host

后端仍兼容已有配置中的 strict_whitelist 规则：它即使关闭 要求登录 也不一定公开，仍按有效来源授权记录判断（手动或登录后自动创建），浏览器会话 Cookie 本身不能替代来源条件。当前 Host 编辑界面没有新建或切换严格白名单规则的控件；需要退出它时，记录完整映射后按当前界面重新创建。新映射中，手动来源授权可独立放行；自动 IP 授权通常允许同一来源继续访问，但不会覆盖已携带的服务范围拒绝。IP 白名单 不是严格来源限制开关。需要在请求到达映射前收窄来源时，使用网关可见性或外部网络层规则。

登录凭据可以限制允许访问的 Host 范围。一个凭据成功登录，不代表它自动拥有所有业务子域。

认证服务会先判断网关识别到的来源 IP。回环、私网、链路本地等来源返回 local_exempt，会跳过常规登录和严格白名单检查。这意味着局域网属于默认信任边界：

• 已有严格白名单规则也不会让局域网来源必须登录。
• 凭据的 Host 服务范围也不会用于限制本地豁免来源；它是网络信任边界，不适合验证凭据范围。
• 局域网测试不能证明公网策略有效。
• FRP、Cloudflared、EdgeOne 或 ESA 前置时，应从请求日志确认真实公网 IP 已传到网关；代理私网地址被误当成访客来源会改变授权结果。

来源网络配置见 IP 白名单 和 网关可见性。

批量接入与维护

一键发现 会扫描允许的本地 IPv4 网段并生成候选 Host。扫描最多接受 16 个 CIDR、合计 1024 台主机；只扫描回环、网卡、Docker 宿主机、已有映射和手动保存的本地范围，不用于探测公网。

列表动作包括：

• 刷新图标和标题：重新抓取上游元数据。
• 清理过期服务：先用 HEAD、失败后用 GET 检查 HTTP / HTTPS 上游，由管理员确认后删除不可达映射。
• 导出为书签：导出业务 Host，不包含鉴权服务。
• 清空所有配置：经两次确认删除鉴权服务和全部 Host 映射，保留根域名等模式设置。

单个 Host 的流量详情可查看实时流量和活跃 IP，并把异常来源加入 通用黑名单。

Host 路由的补充能力

• 路径响应 只给某个 Host 增加少量特殊路径；未命中时仍回到该 Host 的默认 Target。
• 协议映射 为公网直连子域模式补充 TCP / UDP 端口，不适用于内网穿透子域映射。
• 飞牛分享直通 只旁路合法的飞牛 /s/... 分享链路，不公开整站。

这些能力都不改变 Host 是 Web 主路由的事实。

平台边界

• Host 路由本身可在飞牛 FPK、Docker、OpenWrt 和内网穿透拓扑中使用。
• 自动写入宿主机防火墙、智能连接依赖宿主机管理能力；Docker 不提供这些能力。
• 协议映射只在公网直连子域模式显示。Docker 即使额外发布端口，也不会由 fn-knock 管理宿主机防火墙。
• OpenWrt 具备 root 宿主机能力时可管理防火墙；局域网分流 DNS 需自行配置，不能把智能连接当作一键能力。它不提供 Web 终端或应用内 FPK 更新。
• fn-knock 不会自动关闭上游服务原有的公网监听，也不能替代上游更新、备份和最小权限配置。

验证与排错

按请求链路检查：

1. DNS 或 Tunnel Public Hostname 是否把当前 Host 送到正确网关端口。
2. 请求日志中的 Host 和客户端 IP 是否正确。
3. 鉴权服务是否存在，且未开启登录或 Basic Auth。
4. 业务映射是否启用，当前时间是否在开放窗口内。
5. Target 是否能从 fn-knock 运行环境访问。
6. 登录凭据是否允许当前 Host；若存在历史严格白名单规则，再检查当前公网来源是否获放行。
7. HTTPS 证书是否覆盖当前 Host，前置平台是否允许 WebSocket 且未缓存认证响应。

先接入一两个服务并完成外网验证，再批量发现和收紧访问策略。