客户端 Agent 说明
一句话版：客户端 Agent 是住在你服务器里的自动管家——隧道不用手动敲命令，管家自动拉起来；再组个 Agent 集群，就是一支互相顶班的队伍：谁倒下了，活儿自动有人接。
一、它是什么
以前建隧道，你要在自己的服务器上手动运行 nssh 命令。客户端 Agent 把这一步自动化了：在 Web 端创建 Agent 设备，复制部署命令到你的服务器执行，服务器上就常驻了一个"管家"：
- 自动拉活：自动拉取分配给这台设备的隧道，并用 nssh 建立连接；
- 常驻守护：自动注册系统服务，开机自启、崩溃自动重启；
- 自动更新：nssh 与 Agent 版本落后了，下轮心跳自动升级；
- 托管模式：在「我的隧道」的隧道设置中选择「托管 Agent 集群」，隧道就交给 agent 自动建立并维护，断线自动重连，无需人工干预。
二、Agent 集群：一支互相顶班的队伍
同一局域网内的多台设备可以组成一个 Agent 集群，托管隧道由集群成员一起扛：
| 概念 | 说明 |
|---|---|
| Agent 设备 | 你局域网内一台部署了 agent 的服务器 |
| Agent 集群 | 一组设备的逻辑分组；托管隧道由集群内成员分摊执行 |
| default 集群 | 新建设备自动归属的默认分组；不建集群也能享受分摊与接管 |
工作原理：
「我的隧道」→ 隧道设置 → 托管 Agent 集群
│
▼
Web 把任务清单下发给集群各成员
│
┌──────┴───────┐
▼ ▼
设备 A 设备 B
跑自己名下的隧道 跑自己名下 的隧道
└──────┬───────┘
▼
局域网内互相探活（默认端口 9801）
B 宕机 → 其余成员很快发现 → B 的隧道由存活成员顶上
B 恢复 → 活儿自动还回去
- 分摊：集群内的托管隧道自动分给各成员执行，谁名下谁跑；
- 接管：某台设备宕机，其余成员通过局域网互相探活很快发现，它的隧道由存活成员自动瓜分接管，全程无人工介入；
- 回迁：故障设备恢复后，接管的活儿自动还回去。
三、怎么用
- 进入用户后台 → 左侧菜单 「客户端 Agent」；
- （可选）点「创建集群」，把设备按局域网/用途分组（不建就直接用 default 集群）；
- 在集群表头点「新建 Agent」→ 生成一次性部署命令；
- 复制部署命令，在你的服务器上执行，即完成激活接入；
- 到「我的隧道」的隧道设置中，选择「托管 Agent 集群」并保存。
之后的事（拉起 nssh、断线重连、版本升级）全由 agent 代劳。
部署命令的几个要点
| 要点 | 说明 |
|---|---|
| 平台支持 | Linux / macOS / Windows / Docker，脚本自动识别架构 |
| 有效期 | 命令含一次性激活令牌，24 小时内有效，激活后作废 |
| 重跑 = 重装/修复 | 已安装设备重跑同一命令即为重装/修复，无需新令牌 |
| 卸载 | 部署命令弹窗里有「卸载」标签页，本机执行即可 |
四、注意事项与常见误区
- 集群成员必须同一局域网：分摊与接管依赖局域网内互相探活，跨公网组集群不适用；
- 探活端口要放行：agent 会在本机监听一个局域网探活端口（默认 9801），防火墙记得放行（仅局域网使用）；
- 绑集群的隧道，本地服务地址必须填内网 IP：填
127.0.0.1/localhost的隧道无法绑集群——因为在接管设备上，127.0.0.1 指向的是接管设备自己，语义就错了； - 状态标识怎么看：托管隧道列表里有「待分配」「设备离线」「已退集群」等标识，离线/退集群的隧道会在下个心跳周期自动改派给在线成员；
- 解散集群：成员设备自动转入 default 集群，其托管隧道转为手动模式，隧道不会丢。
五、相关文档
记住内网云：Agent 是管家，隧道自动拉；集群互顶班，倒下有人接。