让 Control Plane 可远程访问

浏览器、移动端、聊天消息中的会话链接，以及采用反向连接的 Node Agent，都需要一个稳定的 Control Plane 地址。生产环境建议使用独立域名和 HTTPS 反向代理，不要直接公开未加密的监听端口。

准备公网地址

1. 为 Control Plane 配置稳定域名，例如 control.example.com。
2. 将 DNS 指向反向代理或 Control Plane 所在服务器。
3. 为域名签发受信任的 TLS 证书。
4. 将 HTTPS 请求代理到 Control Plane 的实际监听地址，服务器安装的默认端口为 8081。
5. 在防火墙中只开放反向代理使用的端口，通常为 443。

移动端使用的 Origin 必须是 https://主机[:端口]，不能包含路径、query、内嵌用户名密码或依赖重定向。配置完成后不要随意更换 Origin；已有移动端配置会把 Control Plane ID 和签名密钥指纹与该连接一起校验。

反向代理要求

反向代理必须同时支持：

• 普通 HTTP API 请求和响应流；
• /api/events 的 WebSocket 升级；
• 实例终端、浏览器等功能使用的其他 WebSocket 路由；
• 图片、附件及安装产物所需的请求体和响应大小；
• 足够长的读取和空闲超时，避免运行中的会话流被提前关闭。

不要只为 /api/events 开启 WebSocket。TaskHandoff 的实例代理和远程传输还会使用其他 WebSocket 路由，稳妥的做法是让整个 Control Plane Origin 正确转发升级头。

启用登录认证

公网部署必须启用账号认证。首次启动后创建管理员，再通过“设置 → 用户与权限”创建普通用户、限制角色以及可访问的节点和实例。

不要依赖一个难以猜测的 URL 作为访问控制，也不要把 Node Agent 的 Bearer Token、join token 或配对 Token 当作用户登录凭据。

设置公开访问地址

打开“设置 → 基本 → 公开访问地址”，填写用户实际访问的外部 Origin。聊天桥接生成会话链接时会使用该地址。

公开访问地址只是链接生成和客户端访问配置，不负责配置 DNS、证书、端口映射或防火墙。修改后应从外部网络实际打开一次链接进行验证。

验证部署

至少完成以下检查：

1. 在非服务器所在局域网中打开登录页，确认证书受信任且没有重定向到内网地址。
2. 登录后打开一个 AI 会话，确认消息和执行状态可以持续更新。
3. 打开终端或浏览器应用，确认对应 WebSocket 不会立即断开。
4. 上传一个接近日常大小的附件，确认代理没有返回 413 或超时。
5. 若远程节点采用反向连接，确认“设置 → 节点”中的连接状态为已连接，并在重启 Node Agent 后自动恢复。

常见问题

现象	优先检查
页面能打开，但状态不更新	WebSocket 升级头、/api/events、代理读取超时
登录后循环跳转	外部 Origin、代理协议头、Cookie 的 Secure 属性
终端或浏览器打不开	其他 WebSocket 路由是否被代理，空闲超时是否过短
上传失败	请求体大小、上游超时和临时存储空间
Node Agent 一直重连	公网 URL、DNS、证书链以及 Control Plane 的 WebSocket 支持