边缘 Agent:为什么是它连出来,而不是平台连进去
Alioth 技术笔记 · 第 16 篇 · 边缘计算 / 连接模型 仓库:github.com/aide-family... | 在线演示:web.alioth.asia/
导语
"平台管机器"最直觉的实现是:平台存 SSH 凭据,需要执行命令时就连过去。这在单机房内网很好用,一旦机器散落在客户机房、家庭宽带、云上不同 VPC 里,就会撞上三个问题:机器没有公网入口、平台不该持有每台机器的 SSH 私钥、控制面多副本后不知道请求该找谁。Alioth 的边缘 Agent(摇光 alkaid)把连接方向反过来:Agent 主动出站连控制面,控制面从不回拨。这篇讲这个反转带来的连锁设计。
一、方向反转换来了什么
Agent 部署在目标机器上(systemd 单机,或 Kubernetes 里一个实例),启动后主动连 alioth 的内部 gRPC 端口。于是:
- 不需要公网入口:NAT 后面的机器也能接入,只要能出站;
- 不需要开放管理端口:Agent 不监听管理端口,攻击面少一个;
- 控制面不需要保存 SSH 私钥来执行命令:运行时命令走已建立的流,凭据只在部署时用一次;
- 连接是长连接:控制面要下发命令,直接往这条流里写帧,不需要"发起连接"这个动作。
代价也很明确:控制面永远无法主动叫醒一个离线的 Agent。所以 Alioth 的语义是"离线即失败",不排队(下一节讲)。
二、鉴权:独立令牌,每帧检查吊销
Agent 使用自己的令牌,而不是用户 JWT:
go
token, _ := actor.AgentToken(ctx)
if token == "" { token = bearerFromMetadata(ctx) }
agent, err := registry.AuthenticateToken(ctx, token)
if err != nil { return err }
流建立之后,每次收到帧都会重新读一次 Agent 状态:
go
current, err := registry.agents.GetAgentByUID(ctx, agent.UID)
if current.Status == "REVOKED" {
_ = streamSendClose(session, "revoked")
return merr.Forbidden("agent token revoked")
}
这是有意的:令牌在建立连接时校验一次,之后如果管理员吊销了这台机器,下一条帧就会被拒绝 ,而不是等连接自然断开。轮换令牌(RotateAgentToken)也是同一机制------旧流在下一次心跳时失效,Agent 拿到新令牌后重连。
三、会话只在内存里,所以每个副本一条流
会话(agenthub.Session)是一个进程内的结构:发送通道、等待中的执行结果、Web Shell 的通道。Hub 就是这个进程里的 map[agentUID]*Session。
这意味着:请求打到哪个副本,那个副本必须已经持有这条流。Alioth 的解法不是"副本间转发",而是让 Agent 对每个控制面副本各建一条流:
go
// Connector 作为 kratos Server 跑出站流。
// 控制面是多副本时,Agent 对每个副本各建一条流,任意副本都能直接处理该 Agent 的请求。
实现上靠 DNS:expandEndpoint 把 alioth:9000 解析成所有 Pod IP,为每个地址维护一条独立的循环。控制面扩缩容时,30 秒一次的重新解析会为新地址补流、为消失的地址关流。
这是一个很实在的取舍:用 N 条流的资源开销,换掉了一套跨副本路由。如果只有一条流 + 一个共享注册表,那么每次命令都要先查"Agent 现在连着谁"再转发,还要处理转发过程中的节点故障。而多流方案下,任何副本都能就地处理,天然没有路由表。
四、离线就是失败,不排队
go
func (h *Hub) SendExec(agentUID string, frame *v1.AgentFrame) (<-chan *v1.AgentExecResult, error) {
session, ok := h.Get(agentUID)
if !ok || frame.GetExecRequest() == nil {
return nil, merr.Invalid("agent is offline")
}
...
if !session.send(frame) {
h.Drop(agentUID, reqUID)
return nil, merr.Invalid("agent is offline")
}
}
两个分支都是"立即失败":没有会话、或者发不出去(缓冲满),都返回 agent is offline。这与"任务队列"的语义完全不同------SSH 命令是对人操作的实时响应,如果排队等 5 分钟再执行,用户早就刷新页面了。
代价是网络抖动会导致一次操作失败。但对"执行命令"这类高危动作,失败并让用户确认状态,比"排队后悄悄执行"安全得多。
五、会话结束时的三件事
流断开时,defer 里做三件事:
go
defer func() {
registry.hub.Remove(agent.UID, session)
_ = registry.agents.SetOnline(context.Background(), agent.UID, false, "", "", "", "", "")
}()
- 从 Hub 移除,后续请求直接走"离线"分支;
- 把 DB 里的在线状态置为 false,页面显示离线;
- 让所有在途请求失败:
go
// failPending 让还在等待结果的请求立即失败。
// 进程退出时不能只关闭连接,否则 HTTP 处理协程会等到自己的超时。
第 3 条是很多人会漏的:关闭连接不等于通知等待者。如果不主动往结果通道写一个错误,那些 HTTP 处理协程会一直等到自己的超时(可能是 30 秒),用户看到的是一个转圈很久的"命令执行失败"。
六、重连与背压
Agent 侧的重连是每个地址独立的指数退避:
go
backoff := time.Second
...
if time.Since(started) > 30*time.Second {
backoff = time.Second // 稳定运行过一段时间,重置退避
}
...
if backoff < 30*time.Second { backoff *= 2 }
"稳定超过 30 秒就重置"这个判断避免了一个常见问题:网络闪断后连接立刻重建、又立刻断开,如果每次都从 1 秒开始翻倍,抖动期反而会退避得越来越久。反过来,如果每次断开都重置,疯狂重连会把控制面打爆。用"存活时长"作为信号,是这两者之间最简单可靠的折中。
控制面侧还有一个背压设计:发送通道容量 128,满了就快速失败:
go
// 发送缓冲满时快速失败,避免请求线程一直等到 HTTP 超时。
default:
return false
队列满说明 Agent 处理不过来(或者网络已经卡住),这时候继续往里塞帧只会让内存涨、延迟更长。直接失败,让调用方决定要不要重试。
七、几个真实的坑
- 重连会替换旧会话。
Hub.Put发现同一 Agent 已有会话时,先finishShell("replaced")再close()旧的。否则会出现两条流同时写同一个 Agent,命令结果可能送错会话。 - Web Shell 一次只允许一个。
ClaimShell的注释写着"新的登录会结束上一份终端"。终端是独占资源,两个用户同时操作同一台机器会互相覆盖输入。 - 关闭要发 Close 帧。 进程退出时
CloseAll先给 Agent 发{Close:{Reason:"shutdown"}}再断开,让 Agent 知道这是主动下线而不是网络故障,可以走正常的重连节奏而不是立刻重试。 - 输出有上限。 Agent 执行命令的输出限制 64KB,超出的部分截断------一条
cat /var/log/huge.log不该把整条流撑爆。 - GracefulStop 会被长连接拖住。 所以
CloseAll必须在停机钩子里调用,并且注释特意说明"先释放 Hub 锁再逐个结束会话",避免某个异常会话拖住整个退出流程。
八、怎么验证
app/alioth/internal/biz/agenthub/hub_test.go 正好覆盖了上面三件事:会话替换(TestPutReplacesAndClosesOldSession)、离线后执行立即失败(TestSendExecAfterRemoveFailsWithoutPanic)、关闭时回收在途请求(TestCloseFailsPendingResults);app/alioth/internal/biz/agent/labels_test.go 覆盖机器标签匹配。手工验证:
bash
git clone https://github.com/aide-family/moon.git && cd moon
make dev-up
open http://127.0.0.1:8080
创建一个 Agent 拿到令牌,用 alkaid 连接到本地控制面,页面上的机器应该变成"在线";kill 掉 Agent 进程,几秒内状态变"离线",此时点执行命令应该立刻返回"agent is offline"而不是转圈。再启动两个 alioth 副本,观察 Agent 的日志里应该出现两条流(每个副本一条)。
结语
边缘 Agent 的设计核心不是"能执行命令",而是把连接方向、鉴权时机、失败语义这三件事定死:由内向外连、令牌独立且每帧可吊销、离线就立刻失败不排队。多副本靠"每个副本一条流"绕开了跨节点路由,代价是流的数量乘以副本数------在边缘节点规模有限的场景里,这是一笔划算的交易。
下一篇:SSH 命令审核流------为什么"能执行"必须先"被批准"。