信令鉴权

本项目存在多条采用不同鉴权机制的连接路径，绝不能混淆。

连接	鉴权方法
Desk Server → 本地信令	settings.system.local_signaling_token（自动生成；凡内嵌信令服务器的模式都会生成：default / signaling / service-daemon）
Desk Server → 远程信令	WebSocket URL 中的 ?token=<settings.system.signaling_token>
Desk Server → Manager	WebSocket URL 中的 ?token=<settings.system.manager_api_token>
浏览器 → 信令 / Manager	**不带令牌参数。**仅使用 Actix-Session Cookie 鉴权。

角色裁定

信令服务器自行裁定每条连接的 remote_desk_type——绝不信任客户端自报的角色：

• 出示有效节点令牌的连接，按其声明的角色鉴权；被控端声明为 server。
• 出示非空但无效令牌的连接会直接返回 401，不会悄悄降级为浏览器会话。这样客户端可以清理失效凭据并重新签发，而不是以匿名身份反复连接。
• 不带令牌的连接使用会话 Cookie 鉴权，并一律视为浏览器角色，无论客户端声明什么角色。

开源信令服务器与企业版 Manager 遵循同一套规则。

权限受限会话（设备码 / 协助码）

控制端可以在连接框输入访问码，连接在线被控端（POST /api/desk/redeem-code）。访问码可以是长期设备码，也可以是有时效、按需签发的短期协助码；后者在有效期内可重复兑换以支持重连，每次兑换单独审计。两者都连接同一个被控端，不存在单独的协助连接通道。

通过访问码建立的会话不是设备所有者会话，因此权限受到限制，并由被控端强制执行：

• **每个访问码都带有权限上限。**设备所有者可把各项权限设为允许、询问或拒绝，覆盖远程控制、剪贴板、防窥屏、白板、终端、文件浏览、文件删除和文件传输。未配置时默认全部询问，绝不会自动获得完整权限。详见访问码。
• **三项限制中最严格的结果生效。**每次操作都会同时检查访问码权限上限、被控端全局设置和本地用户现场审批。任一项拒绝时，操作都会被拒绝；任一项未配置时，都会弹窗询问本地用户。
• **特权信令按白名单放行。**受限会话上只放行会话建立与控制面帧；任何可能泄露被控端凭据（signaling_token / manager_api_token）的帧都在被控端信令门被拒。
• **会话有时限。**协助码会过期；被控端本地用户也可以随时结束协助，而且只会关闭当前连接。

协助码由 Manager 签发；开源信令服务器只负责转发连接，不提供协助码。在纯开源信令服务器中，Support 与普通浏览器角色一样，只能参与路由，没有设备在线登记或额外权限。设备码兑换和权限限制则属于开源版本的基础能力。

获取被控端令牌（POST /api/tokens）

已登录的客户端若要以 host（remote_desk_type=server）身份连接，通过 POST /api/tokens（凭会话 Cookie 调用）获取须出示的令牌。两端该端点的请求/响应形态一致，故客户端无需探测服务器类型：

• 开源 desk-server 返回同机的 local_signaling_token（即内嵌 host worker 所用的密钥），忽略请求中的 name、不落库。仅在内嵌信令服务器的模式（default / signaling / service-daemon）注册；纯 desk-server 不提供它。
• 企业版 Manager 会在令牌表中为用户签发令牌。

出站传输安全

上述令牌用于向信令服务器或 Manager 证明被控端身份，其安全性取决于传输链路。被控端向外连接远程信令服务器或 Manager 时，系统会在建连前根据解析出的 IP 地址执行安全检查：

• 云元数据底线（始终拦截）。 链路本地元数据段（169.254.0.0/16，含 169.254.169.254）及同类地址在任何配置下都不会被连接，没有任何开关能削弱它。
• 私网 / 回环 / 局域网（始终允许明文）。 127.0.0.1、192.168.x.x、10.x 等自建信令服务器通常不带 TLS，其流量也不经过不可信网络，故允许明文（ws:// / http://）。
• 公网地址（默认要求 TLS）。 当 require_secure_signaling 开启（默认）时，以明文协议连接公网目标会在建立任何 TCP 连接之前被拒绝，从而避免访问令牌与全部信令在公网上明文传输。请改用 wss:// / https://；若确需在可信网络中例外，可在出站连接设置页关闭该开关（system.require_secure_signaling = false）。

由于校验在连接时基于解析出的 IP（而非 URL 字符串）执行，解析到公网地址的域名无法绕过它，日后重绑定到内网地址的域名也会在下次连接时被拦截。每次连接的协议是固定的，故明文 / TLS 判定基于唯一一次权威 DNS 解析、不做二次解析。初始化向导与出站连接页会以可操作的提示呈现公网明文被拒（改用 wss:///https://，或关闭强制）。

该出站守护与模型供应商 SSRF 守护（ProviderSsrfMode，strict / relaxed）相互独立——后者管辖另一条出站路径（AI 模型 API）及其私网访问策略。

说明

• 浏览器连接不带令牌，使用 Actix-Session Cookie 鉴权。路由提取器必须使用 Option<web::Query<VersionInfo>>，且 Manager 信令路由要排除在全局 Session 中间件之外。
• local_signaling_token 是被控端凭据，日志会自动遮蔽它和其他密钥，绝不明文输出。
• 远程信令与 Manager 的令牌通过 WebSocket URL 查询参数传递。

Manager 凭据证明与本地租约

连接 Manager 的被控端每 30 秒发送一次 SendHeartbeat。只有令牌和设备所有者快照仍然有效时，Manager 才会返回同 request_id 的 HeartbeatAcknowledged 与凭据证明。被控端使用单调时钟维护 120 秒凭据租约；开源、本地或远程信令返回的普通确认不能延长该租约。

• 永久撤销会关闭相关会话，并停止使用同一令牌自动重连。
• 可恢复暂停同样会关闭会话，但会以逐渐延长且有上限的间隔重试原令牌；恢复后最长约 330 秒自动连接。
• 快照过期或后端不可用时不会返回凭据证明，也不会立即关闭 WebSocket。既有会话只在租约内保留； 新建桌面/终端按相邻间隔 2/5/10/20 秒自动重试，累计窗口 37 秒。
• 删除或到期通常会在约 90 秒内断开；即使致命通知丢失，也不会超过 3 分钟。
• 替换 Manager 令牌会建立新的凭据标识，新凭据证明不会延长旧令牌会话；旧会话 最迟 120 秒内拆除且不会复活。

这些机制刻意彼此独立；混用即为安全缺陷。