跳到主要内容

自托管与远程接入

你在公司内网用 Helix 干了一天活，回到家想继续同一个工作区；或者你的代码只能留在公司服务器上，不想经过任何第三方；又或者你有三台机器，希望它们像一个局域网一样互相访问。

Helix 的答案不是「把一切都搬上云」，而是提供三种互补的接入方式，让 Agent 运行在你自己的基础设施上，连接方式随场景切换：

  • 本地直连 —— 同一局域网内，客户端直接连到 Agent
  • 自托管隧道 —— 通过你自己的网关穿透 NAT，在任意网络下访问内网 Agent
  • VPN 组网 —— 把多台设备接入同一个虚拟局域网，像在同一台路由器下一样互通

为什么需要自托管​

对很多团队来说，把代码和提示词交给第三方云服务是不可接受的。自托管的核心价值在于：

  • 数据主权 —— 会话历史、代码库、工具输出全部留在你自己的机器或服务器上，不经第三方存储
  • 私有网络接入 —— Agent 运行在公司内网，也能从任意位置访问
  • 合规与治理 —— 满足数据出境、审计与访问控制要求
  • 成本可控 —— 复用已有服务器资源，不按席位或用量付费

Helix 的桌面端、后端与 Web 端都支持指向你自己的 Agent 实例，配合下面的连接能力，就构成一套完整的自托管方案。

自托管隧道：穿透 NAT 的安全通道​

家里或公司的机器通常没有公网 IP。Helix 的做法不是要求你改路由器、配端口映射，而是提供一个 自托管的网关（EasyGateway），在你的服务器上建立一条加密通道。

工作流程​

┌────────────┐   加密连接    ┌──────────────────┐   反向代理   ┌──────────────┐
│ 你的设备    │ ◄──────────► │  EasyGateway 网关  │ ◄─────────► │  内网 Agent   │
│ (任意网络)  │   mTLS/会话  │  (你的服务器)     │  子域名路由  │  (家里/公司)  │
└────────────┘              └──────────────────┘              └──────────────┘
  1. Agent 节点注册 —— 内网中的 Helix Agent 启动后，作为节点连接到你部署的网关，完成身份注册与凭据签发
  2. 子域名分配 —— 网关为每个节点分配一个专属子域名，例如 mybox.gw.example.com
  3. 客户端接入 —— 你在任何网络下访问该子域名，网关把流量安全转发给内网 Agent
  4. 实时监控 —— 网关侧可以查看每个节点的连接状态与实时流量速度

关键设计​

  • 证书双向认证（mTLS） —— 节点通过 CSR 申请客户端证书，网关验证后才能接入；传输全程加密
  • 心跳保活与自动重连 —— 控制通道带心跳检测，网络抖动断开后自动恢复；长时间静默也会被及时识别并重连
  • 会话凭证 —— 节点使用会话 token 认证，凭据可轮换，吊销后节点立即失效
  • 免注册部署模式 —— 网关支持自包含模式：不依赖任何外部服务，用一份配置即可独立运行，适合完全离线的内网环境
  • 用户信息联动（可选） —— 网关可与你的用户体系打通，在网关侧展示每个节点的归属用户，便于审计

典型场景​

  • 远程办公 —— 在公司服务器上跑 Agent，回家用桌面端接着干，工作区、会话、工具链完全一致
  • 内网服务暴露 —— 需要临时把内网的一个 Web 服务给外部同事看一眼，不用动防火墙
  • 多设备共享 —— 团队共用一个自托管 Agent，各自从自己的客户端连接

VPN 组网：让多台机器像一个局域网​

隧道解决「访问单个 Agent」的问题；当你有 多台机器需要互相访问（这台连那台的数据库、那台调这台的 API）时，Helix 还提供基于 TUN 的 VPN 组网能力。

工作原理​

Helix 的 VPN 客户端在每台设备上创建一个虚拟网卡（TUN 设备）——macOS 使用系统 utun，Linux 使用原生 TUN——并接入网关维护的虚拟局域网：

  • CIDR 路由表 —— 每台设备把自己的网段（如 192.168.1.0/24）注册到路由表，其他设备按最长前缀匹配决定如何转发
  • 纯用户态实现 —— 数据包转发完全在应用层完成，无需管理员权限配置系统级路由（macOS/Linux 均无 CGO 依赖）
  • 自动重连 —— 网络切换（如 Wi-Fi → 热点）后自动恢复连接，不中断工作

三种接入模式​

模式用途
tunnel仅通过网关访问特定服务，适合按需暴露单个端口
proxy经网关代理访问，适合需要统一出口的场景
vpn完整组网，设备间直接互通，适合多机协同

典型场景​

  • 本地开发连测试库 —— 笔记本上的 Helix 直接访问办公室服务器上的数据库，像在同一局域网
  • 多机协同 —— 一台跑模型、一台跑构建、一台做测试，Agent 通过 VPN 统一调度
  • 跨地区团队 —— 成员设备接入同一个虚拟局域网，共享内网资源

双链路自动选优​

连接不再只有一条路。Helix 会同时维护直连与隧道两条链路，并持续探测延迟：

  • 同一局域网内 → 自动走直连，延迟最低
  • 跨网络 → 自动切换/并行使用隧道
  • 链路质量变化 → 自动重选最优路径，无需手动切换

实际体验是：你在办公室和在家，Helix 都「无感」地用着当前最快的那条路。

与其他能力的协同​

与 Workspace​

每个 Workspace 都可以绑定到不同位置的 Agent——本地、远程服务器、VPN 组网内的机器。Workspace 的会话历史、工具配置与模型选择完全独立，切换 Workspace 即切换连接目标。

与多机器管理​

在自托管 + VPN 的网络之上，Helix 的机器管理能力让你以机器为视角统一查看所有 Agent 的连接状态：在线、离线、项目分布，一目了然。

与 HelixVM​

HelixVM 创建的是本机隔离环境；自托管/VPN 则把 Agent 扩展到其他机器。两者叠加，就得到「本地沙箱 + 远程执行」的完整矩阵。

与安全模型​

Helix 的 API 使用长期凭证 + 配对流程保护，自托管场景同样适用：首次配对后颁发凭据，之后的请求全部携带身份校验。配合网关的 mTLS，形成「传输加密 + 节点认证 + 用户鉴权」三层防线。

快速开始​

  1. 在服务器上部署 EasyGateway 网关（单二进制，一条命令启动）
  2. 在需要接入的机器上安装 Helix Agent，配置网关地址并完成节点注册
  3. 在你的 Helix 客户端中添加对应的 Workspace，选择连接方式（直连 / 隧道 / VPN）
  4. 验证连通性——客户端会自动测速并选择最优链路

更详细的部署步骤与配置项，参见 API 与配置文档。

相关文档​