go-oam：一个给网管 Agent 用的 Go 通信 SDK

项目地址：https://github.com/TsMask/go-oam

go-oam 是一个用 Go 编写的网络运维（OAM，Operations, Administration, Maintenance）场景 SDK。它将 WebSocket 通信、HTTP 数据推送、系统状态采集与远程连接能力打包成独立模块，用于搭建 Agent 与网管系统（NMS）之间的通信层。

它的定位是「通信层工具箱」：可以只引入某个独立模块，例如单独使用 pkg/ 下的文件与系统工具；也可以将 ws/ 与 push/ 组合，搭出 OAM Agent 与 NMS 之间的完整通信基座。

核心功能与技术栈

ws/ 模块提供 WebSocket 服务端与客户端，支持 JSON / MsgPack / Protobuf 三种编解码方式，内置发布订阅（Pub/Sub）模型、中间件机制（鉴权、日志、限流）、心跳保活与客户端自动重连。

push/ 模块实现 HTTP 数据推送框架：同步方式支持失败重试，异步方式通过队列与重试策略解耦高频上报和网络抖动。配套的 Metrics 与 History 均支持分片存储，另有 Timer 周期定时器用于定时采集与上报。

pkg/ 为基础工具包，包含系统状态采集（基于 gopsutil/v4，读取 CPU、内存、磁盘）、SSH / SFTP / Telnet 远程连接、命令执行与 PTY 伪终端、文件上传与归档、ringbuffer 环形缓冲、TCP/UDP Socket 封装，以及加密摘要、时间解析、随机生成等工具。

主要依赖：

• WebSocket：github.com/coder/websocket
• HTTP 客户端：github.com/go-resty/resty/v2
• MsgPack / Protobuf：vmihailenco/msgpack/v5、google.golang.org/protobuf
• 系统状态采集：github.com/shirou/gopsutil/v4
• PTY：github.com/creack/pty
• SSH / SFTP：golang.org/x/crypto/ssh、github.com/pkg/sftp
• 语言版本：Go 1.25+

架构设计

SDK 采用分层模块化设计。顶层入口为 oam.New()，目前负责版本配置与查询；下层按职责拆分为两个通信模块和一个基础工具包。ws/ 内部包含 server（连接管理与发布订阅）、client（状态机与自动重连）、codec（编解码）与 protocol（Protobuf 定义）；push/ 由 client（Worker 队列与重试）、history、metrics、timer 组成。pkg/ 不依赖前两者，可独立引入。

目录结构（精简）：

go-oam/
├── oam.go          # SDK 入口与版本
├── ws/             # WebSocket：server/client/codec/protocol/types
├── push/           # 推送：client/history/metrics/timer
├── pkg/            # 工具：cmd/crypto/file/ssh/state/socket/telnet...
└── examples/       # ws 与 push 示例

各模块均带有独立的 README 文档说明。

快速开始

引入 SDK（需 Go 1.25+）：

go get github.com/tsmask/go-oam

运行最小示例，启动 WebSocket 服务端并连接：

go run ./examples/ws/server
go run ./examples/ws/client

push/ 模块另提供 usage（综合示例）与 stats（指标/历史基准）可一键运行。

适用与需谨慎的场景

适合用在网管平台、设备监控或运维中台这类需要与大量设备维持长连接、可靠上报采集指标、偶尔远程执行命令的场景。ws/ + push/ 可以组装成 Agent 到 NMS 的通信链路，或单独取用 pkg/ 下的 SSH、文件、系统采集等工具嵌入现有项目。模块间零耦合的设计，按需引入的成本较低。

需要留意的是：gopsutil 对于跨平台指标的支持并不完全一致，在 Linux 之外的环境需要针对采集项做验证；项目整体面向 Go 服务端集成，若 Agent 端是其他语言或需要极小的二进制体积，需要自行评估依赖开销。此外 WebSocket 生产部署涉及 TLS 与反向代理层配置，接入前要做好对应规划。