子域映射

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

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

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

在 映射管理 → 子域 管理 Host 映射；同页的 协议 页签用于 TCP / UDP 映射。

请求链路

浏览器 -> 公网直连或隧道 -> fn-knock 网关 -> 按 Host 匹配 -> 反代 Target 或静态响应
                                  |
                                  +-> 公开 / 要求登录 / 高级认证临时凭据

公网直达且保留默认端口时，访问形式通常为 https://nas.example.com:7999。前置 EdgeOne、ESA 或 Cloudflared 后，访客通常使用标准 https://nas.example.com，但源站仍回到实际网关端口。

配置顺序

1. 在 系统设置 → 模式 选择 子域模式，或选择 内网穿透 → 子域映射。
2. 在 子域映射 保存根域名，例如 example.com。
3. 点击 添加鉴权服务，创建 auth.example.com。
4. 配置公网 DNS、路由器转发或 Tunnel Public Hostname，使相关 Host 都进入同一网关。
5. 添加业务 Host，选择反向代理、单个文件或目录响应，并决定是否开启 要求登录。
6. 需要按来源或请求特征放行时，从映射右侧菜单进入 高级认证配置。
7. 使用移动网络验证登录跳转、返回地址和请求日志中的客户端 IP。

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

子域模式配置

字段	作用	建议
域名	生成业务 Host 的父域，例如 example.com	先保存，再添加鉴权服务和业务映射
当前鉴权服务	未登录时的统一登录入口	使用 auth.example.com；只能有一条
鉴权服务公网 HTTPS 端口	生成登录跳转 URL 时使用的访客侧 HTTPS 端口	公网直连或 FRP 按实际端口填写；托管 Cloudflare Tunnel 不显示此项并固定使用标准 HTTPS
边缘网络真实 IP 识别	在公网直连子域模式中读取 EdgeOne / ESA 的访客地址	只在对应平台回源时显示；托管 Cloudflare Tunnel 不显示此项

鉴权服务公网 HTTPS 端口只影响外部 URL，不会修改程序监听端口，也不会替路由器、容器或边缘平台开放端口或建立 NAT 转发。

使用托管 Cloudflare Tunnel 时，子域列表、鉴权地址、登录跳转和 redirect_uri 都使用 https://host.example.com，不会附加旧配置中残留的 :7999。Cloudflare 的外部端口与 fn-knock 的本地 Tunnel 入口由托管流程处理。

根域名和 Host 映射都不能包含 *。根域应填写 example.com，业务映射填写 nas 或 nas.example.com；DNS 中是否同时配置 *.example.com 泛解析是另一层设置，不要把通配符写进 fn-knock 的根域或 Host。

EdgeOne / ESA

公网直连子域模式可开启腾讯云 EdgeOne / 阿里云 ESA 支持。开启后，公开 URL 可省略 :7999，子域列表、映射地址和鉴权服务也只显示公开 Host，不再附加历史配置中残留的网关端口；这只是访客侧展示，边缘平台回源仍需指向 fn-knock 实际监听端口。网关同时按平台头读取真实客户端 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
photos.example.com -> http://127.0.0.1:5666/photos/
download.example.com -> 单个文件 /srv/downloads/manual.pdf
docs.example.com -> 目录 /srv/docs

字段	行为
Host / 子域名	匹配请求的 Host；已保存根域名时可只填 nas
响应类型	选择反向代理、单个文件或目录；鉴权服务固定使用反向代理
Target	仅反向代理使用；HTTP、HTTPS、WS 或 WSS 上游地址，可包含基础路径，且必须能从 fn-knock 所在环境访问
服务器路径	仅静态响应使用；可手工填写绝对路径，或点击 浏览 从 fn-knock 网关进程可见的文件系统中选择文件 / 目录，确认后仍需保存映射
目标路径用法	Target 含非根路径时选择 仅作为入口 或 固定前缀；鉴权服务固定使用入口模式
要求登录	未登录时跳到鉴权 Host，完成后返回原地址
禁用 / 定时启用或禁用	手动下线，或按服务器本地时间每天控制开放窗口
分组	把业务 Host 放入已有分组；鉴权服务不能分组
显示传送门	控制登录后页面上的应用切换与退出入口
展示标题	覆盖列表、传送门和书签中的显示名称
应用图标	使用自动采集图标，或上传当前业务 Host 的自定义图标
Basic Auth 跳过	向上游请求注入 Basic Auth 用户名和密码
网关可见性	继承全局规则、用当前 Host 的规则覆盖，或只关闭当前 Host 的可见性限制
启用 WAF	业务 Host 默认启用；关闭后当前 Host 跳过全局 WAF

直接编辑已保存映射的 Host / 子域名会按一次重命名处理，并保留该映射的登录策略、可见性和高级认证；反向代理映射还会保留 Basic Auth 凭据注入。不要用新建相同 Target 或服务器路径的别名来代替重命名；别名是独立映射，不会继承原 Host 的受保护配置。

反向代理的业务服务尽量只监听回环或内网地址，避免绕过网关。Docker 中的 127.0.0.1 指容器自身；代理宿主机服务时应使用容器可达的宿主机地址。Docker 部署的 Target 输入框会提示检测到的可达局域网 IP 候选，但提示不会修改容器网络、端口发布或上游监听范围。

静态响应不需要上游服务。单文件只在 Host 根路径返回指定文件；目录响应支持默认文档、目录列表和安全渲染 README。服务器路径、安全边界和 Docker 只读挂载见静态文件与目录响应。

反向代理 Target 包含非根路径时，编辑器会显示 目标路径用法：

• 仅作为入口（兼容模式）：默认值。只有访客访问域名根路径时才使用 Target 中的路径，其他请求路径保持原样。例如 Target 为 /login 时，访问 / 进入上游 /login，而 /assets/app.js 仍进入上游 /assets/app.js。适合入口页在子路径、但静态资源或登录回调仍位于上游根目录的应用。
• 固定前缀（目录挂载）：把 Target 中的路径加到每个上游请求前。例如 Target 为 /webdav 时，访客 /floccus/a 会转发到上游 /webdav/floccus/a。适合 WebDAV 或明确支持目录挂载的服务。

已有映射缺少该字段时按 仅作为入口 处理。无论选择哪种模式，都应实际验证首页、静态资源、重定向、Cookie 和 WebSocket；这个选项只决定上游请求路径的组合方式，不能替上游完成 HTML、Cookie Path 或绝对 URL 改写。标题与图标采集会使用完整 Target，并正确保留显式端口。

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

分组视图

打开列表上方的 分组视图 后，可在 管理分组 中创建、重命名、排序或删除分组，并通过单条编辑、批量移动或拖拽把业务 Host 放入分组。最多可创建 32 个分组；名称需为 1～40 个字符，且忽略大小写后不能重复。删除仍有映射的分组不会删除 Host，而会把它们移到“未分组”。

分组顺序和 Host 顺序会同步到登录后的传送门及内置 /__select__ 选择页；导出浏览器书签时也会生成对应的分组文件夹。切回列表视图后，分组归属仍会保留，但传送门、选择页和新导出的书签使用扁平顺序。搜索时页面只显示命中的分组和 Host，并临时展开结果；折叠状态只保存在当前浏览器。

分组只改变导航和管理顺序，不改变认证、可见性、WAF 或 Target。鉴权服务始终位于分组之外，凭据的 Host 服务范围仍按实际访问权限判断。

窄屏设备会把映射显示为卡片列表，不再要求横向滚动桌面表格。每张卡片保留标题、Host、响应目标（反代地址或服务器路径）、状态、实时流量和更多操作；分组仍可折叠或整组选中，拖动左侧把手可在组内或组间排序。进入多选后，可以全选当前结果或选择单个分组。

手机上编辑映射并聚焦输入框时，对话框会按软键盘可见区域调整高度并把当前输入项滚入视野，底部的取消、保存或路径选择操作保持可用；软键盘收起后，对话框恢复底部面板布局。

Basic Auth 是反向代理的上游凭据注入

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

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

用户名和密码必须同时填写，且用户名不能包含英文冒号。保存不完整或不合法的配置时，系统会关闭该项并清空凭据，而不是保留半配置状态。

应用图标

编辑普通业务 Host 时，打开 应用图标 可预览当前来源、重新采集上游图标，或上传自定义图片。支持 PNG、JPG、WebP、AVIF、SVG 和 ICO，原文件不能超过 5 MB；浏览器会清理 SVG 中的外部内容，服务端也会拒绝包含不安全 DOCTYPE 或实体声明的 SVG，再将图片完整缩放到方形画布并转换为不超过 128 KiB 的内嵌图标。

自定义图标优先显示在子域列表和传送门中，导出浏览器书签、导航面板同步和网关图标接口也会使用同一内容。保存到配置的图标必须是受支持图片类型的 Base64 data:image/...;base64,...；外部 URL、非 Base64 Data URL、无法解码或超过限制的旧图标不会下发给网关或导出。正常的页面上传和自动采集会完成转换；从旧备份或外部配置导入后图标消失时，重新采集或上传即可。

点击 恢复自动采集 会清除自定义覆盖并重新读取反向代理 Target；Target 无法返回受支持图标时，页面会显示尚未采集。静态映射不会自动读取文件标题或图标，应手工填写标题并上传自定义图标。鉴权服务不支持自定义图标。图标会进入配置与 .knock 备份，敏感内部图形不应作为普通排障附件分享。

单个 Host 的可见性与 WAF

启用全局网关可见性后，业务 Host 的高级设置可选“继承全局”“自定义”或“关闭”。自定义规则替换全局规则，关闭只让当前 Host 跳过可见性检查；认证 Host 必须继承全局规则。配置方法和回退建议见网关可见性。

业务 Host 默认启用 WAF，可单独关闭来跳过全局 WAF。全局 WAF 本身关闭时，这个开关不会产生防护；认证 Host 不能通过 Host 设置绕过 WAF。详细策略见 WAF。

高级认证

开启 要求登录 的 HTTP / HTTPS 业务 Host 会在右侧菜单显示 高级认证配置。它可按源 IP、地区、URL 路径、请求 Header、Query 参数或 HTTP 方法签发仅限当前 Host 的临时凭据；未命中规则的请求继续使用正常登录流程。

规则命中后放行的是当前 Host，而不是只放行触发规则的路径或请求。它也不是系统登录，不会创建传送门或授予其他 Host。配置前先阅读子域高级认证。

访问策略与 local_exempt

当前界面配置	未获授权的公网请求
关闭 要求登录（当前登录优先映射）	直接进入上游
开启 要求登录	没有有效来源 IP 授权或会话时，跳转到鉴权 Host
开启 要求登录 与高级认证	规则命中时签发当前 Host 的临时凭据；未命中时继续检查来源授权和登录

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

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

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

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

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

批量接入与维护

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

扫描窗口可选择“跟随设备推荐”（默认）或低、中、高、极高强度。档位只改变并发、速度和设备负载，不改变扫描范围或发现结果；默认会结合 CPU、可用内存和文件句柄预算选择较安全的档位。NAS、路由器等资源较紧张的设备优先保留自动或低强度。

扫描端口、CIDR 允许范围、Docker 网络视角和批量保存规则见服务发现与批量接入。

列表动作包括：

• 多选：进入选择模式后，可选择当前搜索结果、单个分组或任意业务 Host，批量移动分组、启用、停用、应用同一每日开放时间窗或删除；鉴权服务不参与批量选择。搜索条件或视图变化会清空当前选择，批量删除不可恢复。
• 刷新图标和标题：重新抓取反向代理上游元数据；静态映射会跳过。
• 清理过期服务：先用 HEAD、失败后用 GET 检查 HTTP / HTTPS 上游，由管理员确认后删除不可达映射；静态映射不参与。
• 导出为书签：导出业务 Host，不包含鉴权服务。
• 同步到导航面板：把已启用的业务 Host 单向同步到 Sun-Panel、OneNav 或 Van-Nav；详细边界见导航面板同步。
• 清空所有配置：经两次确认删除鉴权服务和全部 Host 映射，保留根域名等模式设置。

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

目标地址优化

映射列表右上角的维护菜单提供 目标地址优化。它只处理反向代理映射，用于在本机回环地址与检测到的宿主机局域网地址之间批量改写 Target，适合部署方式变化后统一修正回源地址；静态文件和目录映射不会出现在预览中：

• 选择局域网地址时，只列出当前指向 127.0.0.1 的映射；
• 选择本机回环地址时，只列出当前指向已检测局域网地址的映射；
• 预览会保留原协议、端口和路径，只替换主机地址；
• 只有勾选并确认的映射会保存。

候选地址来自 fn-knock 所在环境的网络探测，不代表该地址一定能访问目标服务。Docker 容器中的 127.0.0.1 只指向容器自身；改写前应确认容器到宿主机地址的路由和目标端口，保存后再逐条验证业务 Host。

深度监控

需要定位普通请求日志无法解释的 HTTP 或 WebSocket 问题时，可在单个业务 Host 的 更多 → 深度监控 中启动限时采集。监控只接受已经配置的精确 Host，默认持续 30 分钟，最长 2 小时；页面显示实时摘要，并可下载包含请求、响应、上游和 WebSocket 载荷信息的 ZIP。

深度监控会把 Cookie、Authorization、请求体、响应体及 WebSocket 原始帧以未脱敏形式写入网关磁盘。只在复现问题所需的短时间内开启，完成后立即停止并清空；未手工删除的数据会在会话停止 24 小时后自动清理。导出的压缩包应按凭据文件处理，不要直接上传到公开 Issue 或群聊。

实时文本区只保留最近 1000 行摘要；看到丢弃计数、配额耗尽、写入过载或存储错误时，以下载包和会话停止原因为准。深度监控用于临时故障取证，不替代常开的请求日志、WAF或上游应用日志。

Host 路由的补充能力

• 路径响应 只给某个 Host 增加少量特殊路径；未命中时仍回到该 Host 的默认 Target。
• 静态文件与目录响应 让整个业务 Host 直接读取本机文件，不需要反向代理上游。
• 协议映射 为公网直连子域模式补充 TCP / UDP 端口，不适用于内网穿透子域映射。
• 飞牛分享直通 只旁路合法的飞牛 /s/... 分享链路，不公开整站。

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

平台边界

• Host 路由及静态响应可在飞牛 FPK、Docker、OpenWrt、Linux、macOS、群晖 DSM 7 SPK 和 Windows 中使用；静态路径必须能从网关进程所在文件系统读取，实际公网可达性仍取决于各平台的端口发布与网络链路。
• 自动写入宿主机防火墙和智能连接只由具备对应运行时能力的飞牛标准 FPK 提供；Docker、OpenWrt、Linux、macOS、群晖和 Windows 不提供这些能力。
• 协议映射只在公网直连子域模式显示。Docker 即使额外发布端口，也不会由 fn-knock 管理宿主机防火墙。
• OpenWrt 中的端口放行和局域网 DNS 分流由 OpenWrt 自身管理；fn-knock 不提供直连、宿主机防火墙管理、智能连接、SSH 安全或应用内 FPK 更新。Web 终端可连接管理员配置的远程 SSH 目标，也可启用默认关闭、继承 fn-knock 服务身份的 OpenWrt 本机 PTY。
• fn-knock 不会自动关闭上游服务原有的公网监听，也不能替代上游更新、备份和最小权限配置。

验证与排错

按请求链路检查：

1. DNS 或 Tunnel 是否把当前 Host 送到正确网关；托管 Cloudflared 先检查对账状态、通配 DNS 和 Ingress。
2. 请求日志中的 Host 和客户端 IP 是否正确。
3. 鉴权服务是否存在，且未开启登录或 Basic Auth。
4. 业务映射是否启用，当前时间是否在开放窗口内。
5. 反向代理 Target 是否能从 fn-knock 运行环境访问；静态映射则重新检查服务器路径、类型、权限和挂载。
6. 登录凭据是否允许当前 Host；若启用了高级认证，再确认规则组、条件和临时凭据状态。
7. 若存在历史严格白名单规则，检查当前公网来源是否获放行。
8. HTTPS 证书是否覆盖当前 Host，前置平台是否允许 WebSocket 且未缓存认证响应。

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