认证、会话与服务范围

fn-knock 的认证用于保护网关后的服务，不等同于 Docker 或 OpenWrt 管理面板的访问密码。前者决定访问者能否通过网关；后者只保护管理后台入口。

一次登录会经过什么

对于非本地来源的受保护服务，通常会经过以下步骤：

1. 网关按映射规则判断该服务是否需要认证，并检查是否已有来源授权或当前 Host 的高级认证临时凭据。
2. 没有其他放行路径时，登录页执行已启用的人机验证。
3. 按登录模式完成身份验证。
4. 创建会话，并按会话设置决定是否授予当前 IP。
5. 访问 Host 或受保护的协议映射时，再检查该凭据的服务范围。

局域网、回环和其他私网来源默认属于本地豁免，不会完整经历上述流程，凭据的服务范围也不会用于限制它们。公网验证请使用真实外部网络。

登录回跳被暂停时

认证页检测到目标指回当前验证页、同一目标持续循环或回跳地址不安全时，会暂停自动跳转并显示提示。此时不要反复刷新认证页；回到原始业务 Host 重新发起访问，再依次检查认证 Host、根域与 Cookie 作用域、访问协议，以及前置代理传递的 Host、X-Forwarded-Host 和 X-Forwarded-Proto。边缘平台不应缓存登录或重定向响应。

登录模式

模式	可用方式	适合场景
TOTP 登录模式	TOTP；已绑定时可使用 Passkey、OIDC / OAuth 或 LDAP / Active Directory 账号	个人或小团队使用、需要快捷登录或企业目录接入
账号密码登录模式	用户名和密码	多人使用、需要独立账号

两种模式在 认证配置 中切换。切换前，系统会检查必要的密码或 TOTP 是否已准备好；切换后，未启用方式创建的会话需要重新登录。

切换操作会同步账号名称、权限和关联 TOTP，重复执行不会重复创建账号，也不会重置已经设置的密码或复制快捷登录绑定。切到账号密码模式前，每个投影出的账号都必须设置密码；切回 TOTP 模式前，每个账号都必须关联仍存在的 TOTP。确认切换后，系统会销毁由被停用登录方式创建的会话：

切换目标	会失效的会话
账号密码模式	TOTP、Passkey、OIDC 和 LDAP 会话
TOTP 模式	账号密码会话

凭据与权限的关系

• TOTP 是一个可命名的身份凭据，可限制其可访问的子域和协议映射；关联的 Passkey、OIDC / OAuth 和 LDAP / Active Directory 登录会继承该范围。
• 账号密码模式中的账号同样可以配置服务范围。
• 服务范围设为 自定义 时，权限窗口会分别列出受保护的子域、内置选择页和已开启鉴权的 TCP / UDP 协议映射。未选择任何范围项时，该凭据不能进入任何受保护入口；内置选择页 /__select__ 也需要单独选择。
• 对 要求登录 的 Host，有效手动来源授权可独立放行；登录后自动创建的 IP 授权通常允许同一来源继续访问。自动授权不会覆盖浏览器中已携带的服务范围拒绝；没有可用来源授权时，网关才按会话和凭据范围继续判断。
• 登录后的自动 IP 授权由 系统设置 → 会话 控制。它是来源 IP 的放行路径，不是凭据范围控制；手动白名单过宽时，该来源无需浏览器登录也可能直接进入受保护 Host。
• 服务范围受限的登录凭据不会创建可放行任意 Host 或原始端口的通用自动 IP 授权，以免来源 IP 扩大凭据范围。这包括受限的 TOTP、其关联 Passkey / OIDC / LDAP，以及受限服务范围的账号密码账号；它们不适合用作直连模式的自动放行凭据。
• 自定义范围可以例外地选中具体协议映射。登录后 IP 授权未关闭时，系统会按精确的 TCP/UDP + 对外端口 和当前来源 IP 建立范围内授权，有效期跟随会话设置；它不会放行未选择的协议映射，也不会变成通用 IP 白名单。

管理面板密码不是网关登录

Docker、OpenWrt 等部署会先要求设置管理面板密码。这个密码保护的是 7991 管理入口；它不会自动成为访问者登录网关服务的账号，也不会替代 TOTP 或账号密码认证。

在使用独立面板密码的平台中，如果子域映射里加入了 fn-knock 管理面板，认证列表会显示 管理面板 权限。为某个 TOTP 或账号开启后，该身份通过受保护子域访问管理面板时可以免去第二次面板密码；它不开放原始 7991 端口，也不会让该身份获得未选中的业务 Host。

凭据导入与导出

认证配置 → 更多操作 → 导入/导出凭证 按当前登录模式工作：

当前模式	导出内容
TOTP	TOTP secret、名称和权限
账号密码	账号、密码哈希、权限以及关联 TOTP secret

导入文件必须是 JSON，管理页限制为 512 KB。导入会合并可识别记录并跳过同 ID、同用户名、同 secret 或文件内重复项，不会恢复 Passkey 和外部账号绑定。导出内容足以用于登录，应与 .knock 系统备份同等级保护。

高级认证不是登录方式

子域高级认证在请求命中来源、路径、Header、Query 或 HTTP 方法规则时，签发仅限当前 Host 的临时凭据。它不创建系统登录会话，不产生登录后 IP 授权，也不继承或修改 TOTP、Passkey、OIDC、LDAP 和账号密码的服务范围。

这是一条独立放行路径：即使当前浏览器会话的服务范围不包含该 Host，只要请求满足高级认证规则，仍可获得当前 Host 的临时访问权。因此，不要用它给已有凭据“再加一道限制”；需要收紧凭据范围时，应修改凭据本身的服务范围。规则配置见子域高级认证。

推荐顺序

1. 设置一种主登录方式，并准备至少一个备用凭据。
2. 为需要隔离的人员或设备建立独立凭据。
3. 给每个凭据设置可访问的子域范围。
4. 再给常用设备绑定 Passkey，或把 OIDC / OAuth、LDAP / Active Directory 账号绑定到对应 TOTP。
5. 最后调整会话时长、记住我 和登录后 IP 授权策略。

• 登录模式与账号密码登录
• TOTP 与密码器
• Passkey
• 绑定 QQ 快捷登录
• 外部账号登录（OIDC / OAuth / LDAP）
• 子域高级认证
• 会话、IP 授权与 IP 漂移