公网直达：子域路由
适用于设备有公网 IPv4、可用 IPv6，或已经通过边缘平台回源的环境。fn-knock 根据访问域名转发请求，访客先经过统一登录，再进入对应服务。
- 网络拓扑：公网直达
- 路由方式：按
Host区分服务 - 建议策略：登录优先
- 后台位置：
系统设置 → 模式 → 子域模式
开始前
需要准备：
- 一个可管理 DNS 的域名，例如
example.com。 - 公网入口能够到达 fn-knock 网关。飞牛原生 FPK、Docker Compose 和 OpenWrt 默认使用
7999；飞牛 Docker FPK 向导默认使用8999。以下将它统称为“实际网关端口”。 - 至少一种可用的登录方式：TOTP、密码、Passkey 或已配置的 OIDC。
- fn-knock 所在设备能够访问业务服务。
没有公网入口时，改用内网穿透：子域路由。需要保护 SSH、远程桌面等原始 TCP/UDP 端口时，参见原始端口访问：直连授权。
部署边界
| 部署方式 | 可用性 | 注意事项 |
|---|---|---|
| 飞牛 fnOS FPK | 完整支持 | 可使用自动 HTTPS、主机防火墙和智能连接 |
| Docker Compose / Docker FPK | 支持子域路由 | 不管理宿主机防火墙；不提供智能连接和自动 HTTPS |
| OpenWrt 插件 | 支持子域路由 | 可配合宿主机防火墙；不提供自动 HTTPS，局域网分流 DNS 需自行配置 |
| Windows x86_64 | 不作为公网直达入口 | 新安装的网关仅回环监听，管理程序没有受支持的公开监听范围设置 |
Docker 中的 127.0.0.1 指容器自身。业务服务在宿主机或其他设备时，应填写容器可访问的地址。
1. 配置公网入口和 DNS
将认证域名和业务域名解析到公网入口。例如：
| 域名 | 用途 | 解析目标 |
|---|---|---|
auth.example.com | 统一登录 | 192.0.2.10 |
nas.example.com | NAS 服务 | 192.0.2.10 |
也可以使用 *.example.com 的通配解析。
路由器应把公网端口转发到 fn-knock 网关：
- 公网
443→ 实际网关端口：访问时通常不需要写端口。 - 公网自定义端口 → 实际网关端口：访问地址需要保留该公网端口。
管理入口只用于配置 fn-knock，不应作为公网回源目标。各部署方式的端口见端口与入口。
2. 切换为子域模式
进入 系统设置 → 模式，选择 子域模式 并保存。
保存后，侧边栏应出现 子域映射。如果此前使用内网穿透，切换模式会停止相关隧道；路径映射也可能被清理，切换前应备份现有配置。
Docker 部署不会自动修改宿主机防火墙，需要自行只开放计划中的公网端口。
3. 设置根域名
进入 子域映射，展开 子域模式配置，填写：
域名：example.com鉴权服务所使用的端口：填写访客实际访问的公网端口。例如公网443转发到实际网关端口时填写443边缘网络真实 IP 识别：仅在使用 EdgeOne 或 ESA 时按对应平台开启
根域名决定子域映射的完整访问地址。修改后检查已有鉴权服务和业务映射是否仍然匹配。
4. 添加鉴权服务
在 子域映射 中点击 添加鉴权服务，添加 auth.example.com。保存后，它会显示在 子域模式配置 → 当前鉴权服务。
鉴权服务必须满足：
- 只有一个当前生效的认证入口。
- 允许公开访问，否则访客无法进入登录页。
- 历史映射若仍带有严格白名单规则，不能直接作为鉴权服务；记录原配置后重新创建鉴权服务。
- DNS 和公网端口已经能到达 fn-knock 网关。
先使用手机蜂窝网络打开认证地址，确认能看到登录页，再继续添加业务服务。
5. 添加业务映射
进入 子域映射，新增服务。例如：
| 配置项 | 示例 |
|---|---|
| 子域 | nas |
| 目标 | http://192.168.1.20:5666 |
| 要求登录 | 开启 |
| Host 响应 | 默认保留访客访问的 Host；只有上游只接受自身地址 / Host 时才关闭 |
保存后，业务入口为 https://nas.example.com，或带有实际公网端口的对应地址。
上游连接使用 Basic Auth 时，在映射的高级配置中启用 Basic Auth 跳过 并填写上游凭据。它只影响 fn-knock 到上游的请求，不是访客登录方式。
Host 响应也适用于 内网穿透 → 子域映射。除非上游明确拒绝外部 Host，否则保持默认的“保留 Host”，避免应用生成错误的回调地址或跳转。
Host 响应在运行时按上游 Target 生效。多个 Host 复用同一个 Target 时，它们会共用这一设置；需要不同响应策略时，为它们使用不同 Target。
6. 设置访问策略
编辑 Host 映射时，当前界面提供 要求登录 开关：
| 设置 | 行为 |
|---|---|
关闭 要求登录（当前登录优先映射） | 公开访问，不检查 fn-knock 登录和白名单 |
开启 要求登录 | 手动来源授权可独立放行；自动 IP 授权通常允许同一来源继续访问，但不覆盖已携带的服务范围拒绝；没有可用来源授权时再检查会话 |
| 历史严格白名单规则 | 即使关闭 要求登录 也不一定公开；只按有效来源授权记录判断（手动或登录后自动创建），会话 Cookie 本身不能替代来源条件 |
新建个人服务通常开启 要求登录。当前界面不提供严格白名单选择；升级后若已有这种规则，应同时检查手动与自动 IP 授权记录。若要退出历史严格规则，先记录完整映射后按当前界面重新创建；只关闭 要求登录 不足以让它变为公开。若严格规则只允许手动来源，关闭登录后自动 IP 授权并清理遗留自动记录。
7. 配置 HTTPS
为 *.example.com 配置通配证书，并将证书关联到对应域名。通配证书通常不覆盖根域名 example.com；如果根域名也提供服务，需要把它加入证书 SAN。
飞牛 fnOS FPK 可以使用自动 HTTPS。Docker 和 OpenWrt 需要自行准备证书或在前置代理、边缘平台终止 TLS。具体配置见 SSL 证书。
8. 公网地址变化时配置 DDNS
动态公网地址应使用 DDNS 更新 DNS。只为实际可从公网到达的地址族创建记录；无可用 IPv6 入站时，不要发布 AAAA 记录。
9. 从外网验证
关闭手机 Wi-Fi，按以下顺序测试：
- 打开认证地址，确认登录页可达。
- 打开业务地址，确认未登录时进入认证流程。
- 完成登录，确认返回原业务地址。
- 在
请求日志中确认命中的域名、上游地址和响应状态。
内网测试成功不能代替外网测试。家庭网络的 NAT 回环、分流 DNS 和缓存可能掩盖配置错误。
常见故障
| 症状 | 优先检查 |
|---|---|
| 域名超时 | DNS、公网地址、端口转发、运营商入站限制 |
| 打开后进入管理页 | 公网回源端口错误；应指向网关，不是管理入口 |
| 登录后循环跳转 | 认证域名、根域名、Cookie 作用域、公开协议及前置代理的 Host / X-Forwarded-* 是否一致；从原业务 Host 重新发起访问 |
| 返回 502 | fn-knock 无法访问上游，或上游协议、端口填写错误 |
| 子域进入错误服务 | Host 未被保留，或前置代理覆盖了 Host |
| HTTPS 证书错误 | 证书未覆盖该子域，或证书未关联到正确域名 |
完整排查入口见 FAQ。