remote auth fallback 和 tlsFingerprint 应该什么时候用

官方最近的 Remote Access 文档补了两条非常值得单独拎出来看的边界：

• gateway.remote.* 并不总是主认证来源
• gateway.remote.tlsFingerprint 只在特定远程 TLS 场景里有意义

这两条如果没看清，远程排障时很容易把问题方向带偏。

gateway.remote.* 更像远程连接兜底层

从官方当前表述看，本地调用路径只有在 gateway.auth.* 没显式配置时，才会把 gateway.remote.* 当 fallback。

这意味着：

• 它不是“永远会接管认证”
• 也不是“配置了就一定优先生效”

更准确地说，它只在主认证链没有明确写死时，才承担兜底角色。

为什么官方强调 unresolved SecretRef 要 fail closed

Remote 文档里最近特别补了一句很关键的话：

• 如果 gateway.auth.token 或 gateway.auth.password 是通过 SecretRef 显式配置的
• 但运行时没有解析出来
• 系统会 fail closed

这条规则的意义很大，因为它避免了另一种更危险的行为：

• 明明主认证没有准备好
• 却悄悄退回到 remote fallback

官方现在明确不让这种“蒙混过关式的兜底”发生。

什么时候该优先检查主认证，不是 remote

如果你碰到的是下面这些现象：

• 明明远程地址是对的，但还是 unauthorized
• 切换实例后浏览器状态异常
• SecretRef 刚改完，结果认证链突然不一致

那更适合先查：

• gateway.auth.token
• gateway.auth.password
• SecretRef 是否真的已解析

而不是先假设 gateway.remote.* 会自动帮你补上。

tlsFingerprint 真正解决的是什么

官方还补了一条容易被忽略的能力：

• 当你通过 wss:// 连远程 Gateway 时
• 可以配置 gateway.remote.tlsFingerprint
• 用来 pin 远程 TLS 证书

它保护的不是“网页能不能打开”，而是：

• 你连接到的这台远程 Gateway
• 是否真的是你预期的那台 TLS 终点

这更像一层远程证书身份确认。

它什么时候值得配置

更适合考虑 tlsFingerprint 的情况通常是：

• Gateway 长期跑在另一台主机
• 你明确走 wss://
• 你希望把远端证书固定下来
• 你不想只依赖默认 TLS 信任链

如果你只是本机 localhost、SSH tunnel，或者纯 tailnet 内部短链路，这个配置通常不会是第一优先级。

哪些误判最常见

1. 把 gateway.remote.* 当成万能补丁

它不是所有认证问题的兜底保险，尤其当主认证链已被显式配置时。

2. 把 tlsFingerprint 当成浏览器 token 问题的解法

它处理的是远端 TLS 终点可信度，不处理浏览器 tab 的 token、pairing 或 session drift。

3. SecretRef 没解析出来时还期待 fallback 自动顶上

官方当前策略就是 fail closed，这类情况本来就该停下来排主认证。

更稳的排障顺序

如果你在远程接入里卡住，更适合按这个顺序看：

1. 主认证链是否明确配置
2. SecretRef 是否已正确解析
3. 当前是否真的在走 wss://
4. 若走 wss://，再考虑 tlsFingerprint
5. 最后再看 remote fallback 是否应该参与

这个顺序会比“所有 remote 配置一起猜”清楚很多。

下一步推荐

• 远程访问与 Tailscale / SSH
• Dashboard 遇到 unauthorized、1008 和 AUTH_TOKEN_MISMATCH 时怎么恢复
• Dashboard 的 SecretRef token、sessionStorage 和非 token 化 URL 应该怎么理解