最早知道 Agent Client ProtocolACP这个词的时候我正在折腾一个跨平台远程运维系统核心需求之一是让用户在网页上打开一个“用起来跟本地终端几乎一样”的会话。一开始我把精力全放在传输通道上想着把两端字节流打通就算万事大吉结果被现实狠狠教育了一轮字节能搬过去不代表会话是可管理的。后来我顺着 ACP 的方向重新整理协议层才把问题理顺。这篇文章把我拆解这个协议时看到的、实验过的东西整理出来ACP 解决什么问题、和典型通信方案的边界在哪里、握手和消息帧怎么设计、数据流怎么管理、以及几个真实项目里最容易翻车的异常恢复细节。如果你也在做远程终端、浏览器控制台、自动化运维面板这类东西这篇应该能帮你省不少弯路。1. ACP要解决的到底是什么问题1.1 传统远程会话缺的不是通道而是“语义层”如果只看传输层SSH、WebSocket、MQTT 都能把远程数据从一个端点搬到另一个端点但搬到之后呢终端会话并不是一条永远向前流的字节河它有一个随时变化的状态窗口尺寸多大、当前环境变量是什么、进程是否在等待输入、按 CtrlC 时信号怎么表达、整个会话退出后退出码是多少。传统方案把这些语义全部交给应用各自处理于是每个做远程管理的项目都从零发明一套规则而且彼此还不兼容。这就是 ACP 想补上的那层东西它把远程终端交互中反复出现的——建会话、发输入、收输出、改窗口、传退出码、判断对端是否活着——定义成一套统一的消息交互规则。客户端只需要认识这套规则代理进程负责把它翻译成真实终端的系统调用。结果是业务代码不必再关心对方到底跑在哪个操作系统上、用什么方式打开终端只需要跟“一个会话”打交道。1.2 ACP的定位在字节流之上定义会话规则定位上ACP 强调了两类角色。一类是客户端运行在控制端负责发指令、接收输出、把内容渲染给用户另一类是代理Agent运行在被管理的主机上负责维护真实终端进程并把终端输入输出转换成协议消息。客户端不直接碰 shell代理也不关心 UI。两者只通过一套明确定义的消息交往这就把前端展示、后端进程管理、网络传输三者解耦了。打个不太严谨的比方传统远程方案像给你一把门钥匙保证你能进屋但屋里设备怎么看、谁先去按哪个按钮没有约定。ACP 则是把整个屋子的仪表都画成一张清单哪个旋钮管音量、哪个开关管电源、出故障时怎么报错。它不讲物理传输细节只约定交互规则。1.3 我接触到ACP的契机浏览器终端翻车现场我最初是在做一个跨平台远程管理面板时被逼到这条路上来的。那个系统要在浏览器里直接打开目标主机终端最开始图省事用 WebSocket 把原生字节流透传过去。单机、无强交互的场景demo 很快跑通一旦进入真实使用场景问题就全部冒出来了。用户按 CtrlC前端不知道该怎么把信号发给远端服务端输出稍微多一点网页上就开始乱序和丢行进程退出后客户端连退出码都读不到更别提做后续自动化。那几周我除了填坑就是填坑每修一个问题又会冒出一个新的。后来我把消息路径重新改造成 ACP 风格很多以前要靠 hack 解决的问题变成了协议里的正常字段。这个转变让我意识到这类问题的根源不是网络不稳而是从一开始就没有会话语义层。2. 从握手到长连接ACP的通信链路拆解2.1 会话发起一个HTTP风格的带参数握手请求ACP 的会话通常从一个握手开始。客户端先向代理暴露出的管理端口发送建会话请求常见形态是 HTTP POST 带上鉴权和终端参数。写成例子是下面这样我基于常见的参考实现整理不同版本字段名会有差异但骨架一致POST /connect HTTP/1.1 Host: agent-host:4822 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... Content-Type: application/json { cols: 120, rows: 32, term: xterm-256color, env: { LANG: en_US.UTF-8, SHELL: /bin/bash } }这个请求里有几个信息值得留意终端类型term告诉远端用什么样的终端行为兼容模式窗口宽高cols/rows让代理创建进程时第一时间设置正确尺寸env 则用于设定环境变量。为什么用这个姿态而不是直接接裸 TTY因为接口设计可以复用现有成熟的 HTTP 框架鉴权、跨域、负载均衡、超时控制都有现成方案不需要从协议层面重新发明一套。服务端响应一般会返回 session_id、服务端版本、心跳间隔等拿到这些信息以后这条连接就算建立成功后续所有消息都在这条连接上按行流动响应大概长这样{ session_id: s_01HZXV..., server_version: acp/1.0, heartbeat_interval: 30, status: ready }2.2 消息帧设计为什么是JSON而不是自定义二进制建会话之后ACP 里最常见的数据单元是一条条 JSON 消息。JSON 不是性能最优的选择但它的几个特点正中这个场景的需求自描述看一条消息就能知道它的意图跨语言几乎每一种编程语言都有现成解析器易调试把日志打印出来就能定位问题。对终端这种低频但交互要求细腻的场景这点性能开销完全可接受。参考实现中常见的消息类型大概有以下几种我列个表方便对应type方向主要字段含义input客户端 - 代理seq, data把键盘输入/粘贴内容送给终端进程output代理 - 客户端seq, data把终端输出送回给客户端渲染resize客户端 - 代理cols, rows通知窗口尺寸变化ack代理 - 客户端ack_seq确认已处理某条消息exit代理 - 客户端exit_code, duration_ms会话结束携带退出码heartbeat双向无特殊字段判活用ping 或 pong字段不一定要完全一致但核心都包含这种结构。消息用换行分隔也就是 JSON Lines 风格一条消息就是一个请求或事件这样接收方可以逐行读取不必设计额外的分包逻辑。很多人会问这样每条消息都带 JSON 外层开销到底多大以一条 output 消息为例如果终端输出是 100 字节内容JSON 包装后会多出大约 40 字节左右的字段开销总带宽增加不到 50%。对日常交互终端来说这很小但如果你拿它去回传每秒几十 MB 日志就会看到明显膨胀。这类场景我会在第 5 章再展开说。2.3 连接状态的流转从握手到正常关闭连接不是建好后就一直不变的 socket它内部有明显状态机。大体上是Idle初始→ Connecting发起握手、等待响应→ Ready会话可交互→ Closing收到退出指令等待最终 exit 消息→ Closed释放资源。如果放在程序里就是对同一个连接对象维护一个 status 字段并在每次收发消息时校验状态是否合法。正常关闭和异常断开要分别对待。正常关闭时终端进程退出代理发出 exit 消息并附上退出码之后等客户端 ack 或者直接断开 TCP。异常断开则是连接突然中断客户端收不到 exit 消息这种场景需要走重连和状态对账逻辑。你如果在实现 ACP 客户端最好把这两条路径分开写不要混用一个 return。3. 双向数据流与终端会话管理的内核细节3.1 输入侧按键、粘贴、窗口尺寸怎么走输入侧最容易忽略的问题是回显。终端有两种回显本地回显和远端回显。ACP 代理创建的终端进程会自己处理回显客户端这边就不需要再实现一遍。如果你在客户端又做了一次本地回显就会出现字符重复显示。我自己踩过这个坑某次集成测试里按下一个字母屏幕上出现两个排查了半天发现就是客户端把 input 发给代理的同时又自作主张把字符画了一遍。正确的做法是客户端只负责收集按键并打包成 input 消息回显与否交给远端终端进程决定。粘贴和输入法也比较麻烦。输入法组合过程中会产生多段状态变化不能把中间状态当普通按键直接发出去否则远端会收到一堆垃圾序列。简单可靠的方案是在输入法候选区未确认前本地缓存不发送确认上屏后把最终文本一次性作为 data 发出。大段粘贴同理不要把几 MB 文本整个塞进一条消息按 4KB 到 8KB 分片发送中间夹心跳或短暂延迟避免把输出端的渲染队列挤爆。窗口尺寸变化则通过 resize 消息处理。重点在于代理收到 resize 后要真正触发底层终端进程重新查询窗口尺寸并重绘例如向进程发送对应窗口变化的信号光把 cols/rows 存下来是不够的。如果不做这一步前端窗口放大后远端的文本还会按旧宽度折行表现就是一行碎成几段。3.2 输出侧ANSI转义序列与流式输出的拆分难题输出侧看起来简单其实最容易出隐蔽问题的地方在于终端输出不是干净的纯文本而是夹杂着大量 ANSI 控制序列的字节流。例如常见的颜色控制、光标移动、清屏指令。对 ACP 来说最好的策略是不要去解析这些控制序列原样放进 output 消息的 data 字段渲染层需要颜色就解析需要纯文本就剥离。传输层保持原样是正道做过一次中间层转换的二次转义之后很难不出乱码。流式输出还有一个拆分的问题。终端输出是持续到达的可能一条命令的输出在几毫秒内分几十次返回。如果接收方每收到一小段就刷新一次 UI会造成频繁重绘和高闪烁如果等完整命令结束再一次性渲染实时性又没了。实际工程里常用的办法是合并渲染接收端缓存最近 30 到 50 毫秒的 output 消息按序号排序后再统一呈现。这样既不会丢内容也不会把终端卡成幻灯片。注意合并不能把不同消息的数据混在一起消息边界必须保留否则 ANSI 转义序列可能被拦腰截断颜色串到别的地方。另外如果项目里还要做操作审计、日志留痕可以在存储层再做一次控制序列清洗。不要在传输层做清洗因为渲染层需要原始数据来还原颜色和格式你在传输层剥掉之后就再也找不回来了。3.3 退出与挂断退出码怎么传、心跳怎么判活进程退出时代理要发一条 exit 消息携带退出码。一个容易忽略的细节是退出消息到达客户端并不代表连接可以立即关闭。客户端可能还有最后一段输出还没渲染或者还在等待某些 ack。所以实际的关闭时序一般是代理发 exit 后保留连接一小段时间客户端读完剩余输出回一个 ack再关闭。如果你实现的是反向顺序先关连接再收数据大概率会丢尾部日志。心跳是另一件最容易做过头的事。先明确一个原则心跳不是保活机制TCP 本身不需要靠应用层心跳来维持心跳的唯一用途是探测对端或网络是否真的死了让双方尽快从半开连接里解脱出来。心跳间隔不要拍脑袋设得太短。我见过一个配置把心跳调到 5 秒结果局域网一抖动几十台机器的会话全被误杀。一个比较稳的取法是心跳间隔设为 30 秒连续 3 次未收到响应才判定死链超时窗口大约 90 秒。跨机房或弱网环境间隔可以走到 60 秒。4. 异常恢复、安全边界与调试避坑4.1 鉴权与访问控制会话令牌怎么设计ACP 握手里的 Authorization 字段是整条链路的第一道门。这里我有两条来自实践的补充。第一握手令牌一定要做短期化建议有效期控制在分钟级权限粒度最好能绑定到具体主机或者具体会话不要用一个全局长期 token。第二连接建立后代理应该把 session_id 与令牌的关系解耦后续消息不再依赖原始 token 鉴权而是依赖已建立的会话 ID 和连接状态。这样即使 token 在连接期间过期当前会话也不会被误杀同时新会话又必须重新认证。如果令牌是自包含签名格式常见的自包含签名 token注意在代理侧校验签名和过期时间时要有明确的失败分支返回 401 还是 403 要分开。401 代表认证失败客户端不应当无限重试而应该重新获取凭据403 代表身份没问题但没权限重试同样没有意义。调试时这两个错误最容易混淆一混淆当天的日志就会像开了闸一样往外涌。不要用长期明文密钥做测试。即使只是内网联调也建议用临时生成的一次性令牌否则一旦测试包被截图或进日志等于把主机访问权直接交出去了。4.2 服务端异常退出的识别与重试策略网络里最常见的不是协议问题而是代理进程悄然消失。信号上看主要有几种连接被 reset、对方正常关闭了 socket、握手阶段直接返回 HTTP 错误、以及连接没断但长时间没有任何可读数据。不同情况对应处理策略完全不同。重试也不是简单包一层 for 循环。给一个我常用的退避思路把连接函数封装成可重试调用每失败一次按 1 秒、2 秒、4 秒、8 秒退避最多尝试 5 次超过上限就向控制端报错而不是无限循环。示例逻辑大致是attempt 0 base 1 max_tries 5 backoff 0 while attempt max_tries: try: return create_session() except SessionError as exc: if exc.is_permanent: raise backoff min(base * (2 ** attempt), 8) log.warning( session attempt %d failed: %s, retry in %ss, attempt 1, exc, backoff ) time.sleep(backoff) attempt 1 raise ConnectionError(session create failed after 5 attempts)注意 try 的作用域只包 create_session 这一次握手不要傻等整个会话生命周期一旦进入 Ready 状态后断线走的不是这里而是第 3.3 节说的异常断开通路。两套路径混用一个循环恢复逻辑会变得特别难追。我维护的某套跨平台系统上线第一周异常断开率在 4% 左右其中一大半来自代理机器被动重启重试策略生效后绝大多数会话都能在 1 秒到 8 秒内自动恢复用户几乎无感知。这个数字说明一件事重连做得够快协议层的短暂失败可以变成产品层的不在场。4.3 心跳、超时和误判一次调参踩坑记录这里讲一次具体的调参踩坑。当时为了尽早发现服务端挂掉我把心跳间隔从默认值改成 5 秒连续 2 次未响应就断开。结果上线当天晚上某段网络的瞬时抖动让大量会话同时断线重连日志被打爆业务侧投诉也来了。复盘时发现连接本身没有死只是因为网络把心跳包延迟了几百毫秒而我的超时窗口太窄根本没等到重试机会。后来我把参数改成心跳间隔 30 秒连续 3 次丢失才判定死链总判定窗口 90 秒误杀率降到几乎为零。这里可以给一个经验参考判定窗口至少要大于心跳间隔乘以 3 再乘一个安全余量给网络抖动两个周期自我恢复的余地。间隔和窗口都搞太短省的那点时间远不够弥补误杀造成的重连风暴。还有一个坑是超时后立刻销毁连接对象。你可能会想既然都已经判定死链了关就是了。但有时候对端只是处理慢exit 消息可能正排在路上瞬间断开会直接把客户端准备读取退出码的通道砍掉。稳妥做法是判定死链后先读一次带超时的缓冲确认没有 pending 消息再进入关闭流程。多等 100 到 200 毫秒成本极低收益是退出码能正确记录。5. 对比其他方案什么时候该用ACP何时绕开它5.1 和SSH远程Exec、WebSocket自定义协议放在一起看现在把你面前的方案摊开看最常被拿来和 ACP 比较的是三条路直接基于 SSH 的远程命令与终端、WebSocket 加自定义消息、以及 ACP 这种专门协议。单个维度比较不好讲我列一个表。对比维度基于 SSH 远程 ExecACP 参考实现WebSocket 自定义 JSON传输层安全内置加密成熟需要自己建立在 HTTPS / 长连接之上可以放在 TLS 上但要自己管终端会话语义只有字节流和简单退出状态有专门消息承载会话状态完全自定义语义靠约定信号与退出码通过通道间接做细节费劲协议内建关闭流程与退出码需要自己编码实现开发成本低现成库多中等需要代理端与客户端配合初期低后期通信细节全自己扛适用场景面向人、单次运维操作多面向平台化管控、多终端统一管理前后端完全自控的强定制场景可以看到SSH 在建立成熟基础设施和加密传输上无可挑剔但它本身对“我要做一套可编程、可观测的终端会话管理”并不友好WebSocket 自定义方案灵活但等于把 ACP 要做的那层语义全部重新实现一遍。ACP 的位置介于两者之间它不碰传输安全默认跑在可信通道或 TLS 上专注解决会话语义和消息编排。5.2 哪些场景不该用ACP不是所有远程操作都值得引入 ACP。我遇到过一些团队连跑一条一次性脚本都先建 ACP 会话反而把简单问题搞复杂了。第一类一次性命令执行。比如定时拉取主机负载、执行完就返回结果的脚本用一个任务式接口甚至纯粹的请求调用就够了。犯不着维持常驻连接也不需要考虑心跳重连——因为没有长期活着的会话。为这种场景强行上 ACP等于拿牛刀杀鸡还要承担额外的稳定性和维护成本。第二类高吞吐日志回传。如果源端每秒产生数十 MB 文本ACP 那种面向人机交互的 JSON 包装开销就太明显了。日志场景更适合用块式二进制协议配上压缩重心在吞吐而不是语义精致度。你可以设想一下一条日志本来就 200 字节包上外层字段后变成 250 字节整体增长 25%在每秒百万条日志的场景里这是毁灭性的浪费。第三类零散小工具场景。只是想给单台机器开个远程 shell 玩一下直接用现成的组件或者标准命令工具即可不需要自研 ACP。协议设计的收益来自规模和多端复用一两台机器体现不出来。归根结底ACP 解决的是“很多终端会话需要被统一管理”这个问题。如果你的问题只是“把终端窗口接到网页上”那不需要升级到协议层如果你的问题是“几百个代理节点、上千个会话前端和后端都要以统一方式对接”那 ACP 就很值得。5.3 从零实现最小ACP客户端的路径如果要自己实现一个最小可用的 ACP 客户端不要一上来就铺量。先把闭环走通再逐步加细节。我的推荐顺序是五步。第一步实现握手。能发起 HTTP 风格建会话请求能解析 session_id。第二步实现消息循环。能够逐行读取 JSON 消息并将 input 消息发送出去。第三步实现 output 渲染。把收到的 data 原样送到终端渲染器这一步可以先不做 ANSI 解析能显示文本就算成功。第四步补上异常路径。处理连接断开、握手失败、心跳超时并做好重试退避这部分最花时间。第五步再加上细节。比如窗口 resize、发送 ack、退出码处理、日志审计字段。消息循环的核心结构其实很薄一个大概的骨架是def message_loop(session): while True: line read_json_line(session) if line is None: handle_connection_lost() break msg json.loads(line) if msg[type] output: render(msg[data]) elif msg[type] exit: finalize(msg.get(exit_code, 1)) break elif msg[type] heartbeat: send_ack(msg[seq]) elif msg[type] ack: resolve_pending(msg[ack_seq])这里要特别注意 read_json_line 的底层不要用裸 readline 去处理不完整的最后一行。TCP 是字节流没有消息边界ACP 通过换行符定义消息边界但一次读到的 buffer 可能包含半条 JSON。稳妥做法是维护一个行缓冲先收满一行再解析半行留在缓冲区里等下一段到达。跑通最小闭环之后再考虑把消息类型扩展到信号传递、多路复用、权限审计等高级功能。你会发现后面那些设计在最初的消息格式里就已经留有扩展空间这才是协议值得花时间投入的部分。真在自己项目里把它跑起来之后我的体会是协议本身不复杂复杂的是它上面挂着的一堆关于状态、异常、鉴权的决策。我现在回头看最开始那个 WebSocket 透传方案并不是不能救而是救起来要把所有会话规则都堆在业务代码里最后变成一团没有边界的胶水。ACP 这类设计最大的价值就是给这些规则画了一条清晰的边界让网络、前端、代理各自只关心自己的事。如果你准备在自己的系统里引入类似思路我建议从最小闭环开始先把握手、输出、退出码三条路径打通再去考虑心跳重连和高级消息——那时候每一步都有明确的测试依据踩坑也会少得多。 
长河君 · 2026/10/17 14:13:56 · 阅读 1.2k ACP协议详解：远程终端会话管理的语义层设计与实践
最早知道 Agent Client ProtocolACP这个词的时候我正在折腾一个跨平台远程运维系统核心需求之一是让用户在网页上打开一个“用起来跟本地终端几乎一样”的会话。一开始我把精力全放在传输通道上想着把两端字节流打通就算万事大吉结果被现实狠狠教育了一轮字节能搬过去不代表会话是可管理的。后来我顺着 ACP 的方向重新整理协议层才把问题理顺。这篇文章把我拆解这个协议时看到的、实验过的东西整理出来ACP 解决什么问题、和典型通信方案的边界在哪里、握手和消息帧怎么设计、数据流怎么管理、以及几个真实项目里最容易翻车的异常恢复细节。如果你也在做远程终端、浏览器控制台、自动化运维面板这类东西这篇应该能帮你省不少弯路。1. ACP要解决的到底是什么问题1.1 传统远程会话缺的不是通道而是“语义层”如果只看传输层SSH、WebSocket、MQTT 都能把远程数据从一个端点搬到另一个端点但搬到之后呢终端会话并不是一条永远向前流的字节河它有一个随时变化的状态窗口尺寸多大、当前环境变量是什么、进程是否在等待输入、按 CtrlC 时信号怎么表达、整个会话退出后退出码是多少。传统方案把这些语义全部交给应用各自处理于是每个做远程管理的项目都从零发明一套规则而且彼此还不兼容。这就是 ACP 想补上的那层东西它把远程终端交互中反复出现的——建会话、发输入、收输出、改窗口、传退出码、判断对端是否活着——定义成一套统一的消息交互规则。客户端只需要认识这套规则代理进程负责把它翻译成真实终端的系统调用。结果是业务代码不必再关心对方到底跑在哪个操作系统上、用什么方式打开终端只需要跟“一个会话”打交道。1.2 ACP的定位在字节流之上定义会话规则定位上ACP 强调了两类角色。一类是客户端运行在控制端负责发指令、接收输出、把内容渲染给用户另一类是代理Agent运行在被管理的主机上负责维护真实终端进程并把终端输入输出转换成协议消息。客户端不直接碰 shell代理也不关心 UI。两者只通过一套明确定义的消息交往这就把前端展示、后端进程管理、网络传输三者解耦了。打个不太严谨的比方传统远程方案像给你一把门钥匙保证你能进屋但屋里设备怎么看、谁先去按哪个按钮没有约定。ACP 则是把整个屋子的仪表都画成一张清单哪个旋钮管音量、哪个开关管电源、出故障时怎么报错。它不讲物理传输细节只约定交互规则。1.3 我接触到ACP的契机浏览器终端翻车现场我最初是在做一个跨平台远程管理面板时被逼到这条路上来的。那个系统要在浏览器里直接打开目标主机终端最开始图省事用 WebSocket 把原生字节流透传过去。单机、无强交互的场景demo 很快跑通一旦进入真实使用场景问题就全部冒出来了。用户按 CtrlC前端不知道该怎么把信号发给远端服务端输出稍微多一点网页上就开始乱序和丢行进程退出后客户端连退出码都读不到更别提做后续自动化。那几周我除了填坑就是填坑每修一个问题又会冒出一个新的。后来我把消息路径重新改造成 ACP 风格很多以前要靠 hack 解决的问题变成了协议里的正常字段。这个转变让我意识到这类问题的根源不是网络不稳而是从一开始就没有会话语义层。2. 从握手到长连接ACP的通信链路拆解2.1 会话发起一个HTTP风格的带参数握手请求ACP 的会话通常从一个握手开始。客户端先向代理暴露出的管理端口发送建会话请求常见形态是 HTTP POST 带上鉴权和终端参数。写成例子是下面这样我基于常见的参考实现整理不同版本字段名会有差异但骨架一致POST /connect HTTP/1.1 Host: agent-host:4822 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... Content-Type: application/json { cols: 120, rows: 32, term: xterm-256color, env: { LANG: en_US.UTF-8, SHELL: /bin/bash } }这个请求里有几个信息值得留意终端类型term告诉远端用什么样的终端行为兼容模式窗口宽高cols/rows让代理创建进程时第一时间设置正确尺寸env 则用于设定环境变量。为什么用这个姿态而不是直接接裸 TTY因为接口设计可以复用现有成熟的 HTTP 框架鉴权、跨域、负载均衡、超时控制都有现成方案不需要从协议层面重新发明一套。服务端响应一般会返回 session_id、服务端版本、心跳间隔等拿到这些信息以后这条连接就算建立成功后续所有消息都在这条连接上按行流动响应大概长这样{ session_id: s_01HZXV..., server_version: acp/1.0, heartbeat_interval: 30, status: ready }2.2 消息帧设计为什么是JSON而不是自定义二进制建会话之后ACP 里最常见的数据单元是一条条 JSON 消息。JSON 不是性能最优的选择但它的几个特点正中这个场景的需求自描述看一条消息就能知道它的意图跨语言几乎每一种编程语言都有现成解析器易调试把日志打印出来就能定位问题。对终端这种低频但交互要求细腻的场景这点性能开销完全可接受。参考实现中常见的消息类型大概有以下几种我列个表方便对应type方向主要字段含义input客户端 - 代理seq, data把键盘输入/粘贴内容送给终端进程output代理 - 客户端seq, data把终端输出送回给客户端渲染resize客户端 - 代理cols, rows通知窗口尺寸变化ack代理 - 客户端ack_seq确认已处理某条消息exit代理 - 客户端exit_code, duration_ms会话结束携带退出码heartbeat双向无特殊字段判活用ping 或 pong字段不一定要完全一致但核心都包含这种结构。消息用换行分隔也就是 JSON Lines 风格一条消息就是一个请求或事件这样接收方可以逐行读取不必设计额外的分包逻辑。很多人会问这样每条消息都带 JSON 外层开销到底多大以一条 output 消息为例如果终端输出是 100 字节内容JSON 包装后会多出大约 40 字节左右的字段开销总带宽增加不到 50%。对日常交互终端来说这很小但如果你拿它去回传每秒几十 MB 日志就会看到明显膨胀。这类场景我会在第 5 章再展开说。2.3 连接状态的流转从握手到正常关闭连接不是建好后就一直不变的 socket它内部有明显状态机。大体上是Idle初始→ Connecting发起握手、等待响应→ Ready会话可交互→ Closing收到退出指令等待最终 exit 消息→ Closed释放资源。如果放在程序里就是对同一个连接对象维护一个 status 字段并在每次收发消息时校验状态是否合法。正常关闭和异常断开要分别对待。正常关闭时终端进程退出代理发出 exit 消息并附上退出码之后等客户端 ack 或者直接断开 TCP。异常断开则是连接突然中断客户端收不到 exit 消息这种场景需要走重连和状态对账逻辑。你如果在实现 ACP 客户端最好把这两条路径分开写不要混用一个 return。3. 双向数据流与终端会话管理的内核细节3.1 输入侧按键、粘贴、窗口尺寸怎么走输入侧最容易忽略的问题是回显。终端有两种回显本地回显和远端回显。ACP 代理创建的终端进程会自己处理回显客户端这边就不需要再实现一遍。如果你在客户端又做了一次本地回显就会出现字符重复显示。我自己踩过这个坑某次集成测试里按下一个字母屏幕上出现两个排查了半天发现就是客户端把 input 发给代理的同时又自作主张把字符画了一遍。正确的做法是客户端只负责收集按键并打包成 input 消息回显与否交给远端终端进程决定。粘贴和输入法也比较麻烦。输入法组合过程中会产生多段状态变化不能把中间状态当普通按键直接发出去否则远端会收到一堆垃圾序列。简单可靠的方案是在输入法候选区未确认前本地缓存不发送确认上屏后把最终文本一次性作为 data 发出。大段粘贴同理不要把几 MB 文本整个塞进一条消息按 4KB 到 8KB 分片发送中间夹心跳或短暂延迟避免把输出端的渲染队列挤爆。窗口尺寸变化则通过 resize 消息处理。重点在于代理收到 resize 后要真正触发底层终端进程重新查询窗口尺寸并重绘例如向进程发送对应窗口变化的信号光把 cols/rows 存下来是不够的。如果不做这一步前端窗口放大后远端的文本还会按旧宽度折行表现就是一行碎成几段。3.2 输出侧ANSI转义序列与流式输出的拆分难题输出侧看起来简单其实最容易出隐蔽问题的地方在于终端输出不是干净的纯文本而是夹杂着大量 ANSI 控制序列的字节流。例如常见的颜色控制、光标移动、清屏指令。对 ACP 来说最好的策略是不要去解析这些控制序列原样放进 output 消息的 data 字段渲染层需要颜色就解析需要纯文本就剥离。传输层保持原样是正道做过一次中间层转换的二次转义之后很难不出乱码。流式输出还有一个拆分的问题。终端输出是持续到达的可能一条命令的输出在几毫秒内分几十次返回。如果接收方每收到一小段就刷新一次 UI会造成频繁重绘和高闪烁如果等完整命令结束再一次性渲染实时性又没了。实际工程里常用的办法是合并渲染接收端缓存最近 30 到 50 毫秒的 output 消息按序号排序后再统一呈现。这样既不会丢内容也不会把终端卡成幻灯片。注意合并不能把不同消息的数据混在一起消息边界必须保留否则 ANSI 转义序列可能被拦腰截断颜色串到别的地方。另外如果项目里还要做操作审计、日志留痕可以在存储层再做一次控制序列清洗。不要在传输层做清洗因为渲染层需要原始数据来还原颜色和格式你在传输层剥掉之后就再也找不回来了。3.3 退出与挂断退出码怎么传、心跳怎么判活进程退出时代理要发一条 exit 消息携带退出码。一个容易忽略的细节是退出消息到达客户端并不代表连接可以立即关闭。客户端可能还有最后一段输出还没渲染或者还在等待某些 ack。所以实际的关闭时序一般是代理发 exit 后保留连接一小段时间客户端读完剩余输出回一个 ack再关闭。如果你实现的是反向顺序先关连接再收数据大概率会丢尾部日志。心跳是另一件最容易做过头的事。先明确一个原则心跳不是保活机制TCP 本身不需要靠应用层心跳来维持心跳的唯一用途是探测对端或网络是否真的死了让双方尽快从半开连接里解脱出来。心跳间隔不要拍脑袋设得太短。我见过一个配置把心跳调到 5 秒结果局域网一抖动几十台机器的会话全被误杀。一个比较稳的取法是心跳间隔设为 30 秒连续 3 次未收到响应才判定死链超时窗口大约 90 秒。跨机房或弱网环境间隔可以走到 60 秒。4. 异常恢复、安全边界与调试避坑4.1 鉴权与访问控制会话令牌怎么设计ACP 握手里的 Authorization 字段是整条链路的第一道门。这里我有两条来自实践的补充。第一握手令牌一定要做短期化建议有效期控制在分钟级权限粒度最好能绑定到具体主机或者具体会话不要用一个全局长期 token。第二连接建立后代理应该把 session_id 与令牌的关系解耦后续消息不再依赖原始 token 鉴权而是依赖已建立的会话 ID 和连接状态。这样即使 token 在连接期间过期当前会话也不会被误杀同时新会话又必须重新认证。如果令牌是自包含签名格式常见的自包含签名 token注意在代理侧校验签名和过期时间时要有明确的失败分支返回 401 还是 403 要分开。401 代表认证失败客户端不应当无限重试而应该重新获取凭据403 代表身份没问题但没权限重试同样没有意义。调试时这两个错误最容易混淆一混淆当天的日志就会像开了闸一样往外涌。不要用长期明文密钥做测试。即使只是内网联调也建议用临时生成的一次性令牌否则一旦测试包被截图或进日志等于把主机访问权直接交出去了。4.2 服务端异常退出的识别与重试策略网络里最常见的不是协议问题而是代理进程悄然消失。信号上看主要有几种连接被 reset、对方正常关闭了 socket、握手阶段直接返回 HTTP 错误、以及连接没断但长时间没有任何可读数据。不同情况对应处理策略完全不同。重试也不是简单包一层 for 循环。给一个我常用的退避思路把连接函数封装成可重试调用每失败一次按 1 秒、2 秒、4 秒、8 秒退避最多尝试 5 次超过上限就向控制端报错而不是无限循环。示例逻辑大致是attempt 0 base 1 max_tries 5 backoff 0 while attempt max_tries: try: return create_session() except SessionError as exc: if exc.is_permanent: raise backoff min(base * (2 ** attempt), 8) log.warning( session attempt %d failed: %s, retry in %ss, attempt 1, exc, backoff ) time.sleep(backoff) attempt 1 raise ConnectionError(session create failed after 5 attempts)注意 try 的作用域只包 create_session 这一次握手不要傻等整个会话生命周期一旦进入 Ready 状态后断线走的不是这里而是第 3.3 节说的异常断开通路。两套路径混用一个循环恢复逻辑会变得特别难追。我维护的某套跨平台系统上线第一周异常断开率在 4% 左右其中一大半来自代理机器被动重启重试策略生效后绝大多数会话都能在 1 秒到 8 秒内自动恢复用户几乎无感知。这个数字说明一件事重连做得够快协议层的短暂失败可以变成产品层的不在场。4.3 心跳、超时和误判一次调参踩坑记录这里讲一次具体的调参踩坑。当时为了尽早发现服务端挂掉我把心跳间隔从默认值改成 5 秒连续 2 次未响应就断开。结果上线当天晚上某段网络的瞬时抖动让大量会话同时断线重连日志被打爆业务侧投诉也来了。复盘时发现连接本身没有死只是因为网络把心跳包延迟了几百毫秒而我的超时窗口太窄根本没等到重试机会。后来我把参数改成心跳间隔 30 秒连续 3 次丢失才判定死链总判定窗口 90 秒误杀率降到几乎为零。这里可以给一个经验参考判定窗口至少要大于心跳间隔乘以 3 再乘一个安全余量给网络抖动两个周期自我恢复的余地。间隔和窗口都搞太短省的那点时间远不够弥补误杀造成的重连风暴。还有一个坑是超时后立刻销毁连接对象。你可能会想既然都已经判定死链了关就是了。但有时候对端只是处理慢exit 消息可能正排在路上瞬间断开会直接把客户端准备读取退出码的通道砍掉。稳妥做法是判定死链后先读一次带超时的缓冲确认没有 pending 消息再进入关闭流程。多等 100 到 200 毫秒成本极低收益是退出码能正确记录。5. 对比其他方案什么时候该用ACP何时绕开它5.1 和SSH远程Exec、WebSocket自定义协议放在一起看现在把你面前的方案摊开看最常被拿来和 ACP 比较的是三条路直接基于 SSH 的远程命令与终端、WebSocket 加自定义消息、以及 ACP 这种专门协议。单个维度比较不好讲我列一个表。对比维度基于 SSH 远程 ExecACP 参考实现WebSocket 自定义 JSON传输层安全内置加密成熟需要自己建立在 HTTPS / 长连接之上可以放在 TLS 上但要自己管终端会话语义只有字节流和简单退出状态有专门消息承载会话状态完全自定义语义靠约定信号与退出码通过通道间接做细节费劲协议内建关闭流程与退出码需要自己编码实现开发成本低现成库多中等需要代理端与客户端配合初期低后期通信细节全自己扛适用场景面向人、单次运维操作多面向平台化管控、多终端统一管理前后端完全自控的强定制场景可以看到SSH 在建立成熟基础设施和加密传输上无可挑剔但它本身对“我要做一套可编程、可观测的终端会话管理”并不友好WebSocket 自定义方案灵活但等于把 ACP 要做的那层语义全部重新实现一遍。ACP 的位置介于两者之间它不碰传输安全默认跑在可信通道或 TLS 上专注解决会话语义和消息编排。5.2 哪些场景不该用ACP不是所有远程操作都值得引入 ACP。我遇到过一些团队连跑一条一次性脚本都先建 ACP 会话反而把简单问题搞复杂了。第一类一次性命令执行。比如定时拉取主机负载、执行完就返回结果的脚本用一个任务式接口甚至纯粹的请求调用就够了。犯不着维持常驻连接也不需要考虑心跳重连——因为没有长期活着的会话。为这种场景强行上 ACP等于拿牛刀杀鸡还要承担额外的稳定性和维护成本。第二类高吞吐日志回传。如果源端每秒产生数十 MB 文本ACP 那种面向人机交互的 JSON 包装开销就太明显了。日志场景更适合用块式二进制协议配上压缩重心在吞吐而不是语义精致度。你可以设想一下一条日志本来就 200 字节包上外层字段后变成 250 字节整体增长 25%在每秒百万条日志的场景里这是毁灭性的浪费。第三类零散小工具场景。只是想给单台机器开个远程 shell 玩一下直接用现成的组件或者标准命令工具即可不需要自研 ACP。协议设计的收益来自规模和多端复用一两台机器体现不出来。归根结底ACP 解决的是“很多终端会话需要被统一管理”这个问题。如果你的问题只是“把终端窗口接到网页上”那不需要升级到协议层如果你的问题是“几百个代理节点、上千个会话前端和后端都要以统一方式对接”那 ACP 就很值得。5.3 从零实现最小ACP客户端的路径如果要自己实现一个最小可用的 ACP 客户端不要一上来就铺量。先把闭环走通再逐步加细节。我的推荐顺序是五步。第一步实现握手。能发起 HTTP 风格建会话请求能解析 session_id。第二步实现消息循环。能够逐行读取 JSON 消息并将 input 消息发送出去。第三步实现 output 渲染。把收到的 data 原样送到终端渲染器这一步可以先不做 ANSI 解析能显示文本就算成功。第四步补上异常路径。处理连接断开、握手失败、心跳超时并做好重试退避这部分最花时间。第五步再加上细节。比如窗口 resize、发送 ack、退出码处理、日志审计字段。消息循环的核心结构其实很薄一个大概的骨架是def message_loop(session): while True: line read_json_line(session) if line is None: handle_connection_lost() break msg json.loads(line) if msg[type] output: render(msg[data]) elif msg[type] exit: finalize(msg.get(exit_code, 1)) break elif msg[type] heartbeat: send_ack(msg[seq]) elif msg[type] ack: resolve_pending(msg[ack_seq])这里要特别注意 read_json_line 的底层不要用裸 readline 去处理不完整的最后一行。TCP 是字节流没有消息边界ACP 通过换行符定义消息边界但一次读到的 buffer 可能包含半条 JSON。稳妥做法是维护一个行缓冲先收满一行再解析半行留在缓冲区里等下一段到达。跑通最小闭环之后再考虑把消息类型扩展到信号传递、多路复用、权限审计等高级功能。你会发现后面那些设计在最初的消息格式里就已经留有扩展空间这才是协议值得花时间投入的部分。真在自己项目里把它跑起来之后我的体会是协议本身不复杂复杂的是它上面挂着的一堆关于状态、异常、鉴权的决策。我现在回头看最开始那个 WebSocket 透传方案并不是不能救而是救起来要把所有会话规则都堆在业务代码里最后变成一团没有边界的胶水。ACP 这类设计最大的价值就是给这些规则画了一条清晰的边界让网络、前端、代理各自只关心自己的事。如果你准备在自己的系统里引入类似思路我建议从最小闭环开始先把握手、输出、退出码三条路径打通再去考虑心跳重连和高级消息——那时候每一步都有明确的测试依据踩坑也会少得多。