1. 项目思路：为什么我会去折腾一个叫 OpenRig 的管理工具
先说背景。我手里长期维护着几十台零散的计算设备，有跑渲图的显卡工作站，有挂着推理模型的高内存机器，也有几台用来做数据清洗的旧服务器。设备一多，问题就跟着来了：每台机器都要单独登录看状态，显卡温度异常了没人管，某个节点磁盘满了还继续写，半夜收到一条告警邮件又得爬起来处理。这种状态持续了很长一段时间，直到有一天我实在受不了，决定自己写一套轻量的设备管理工具，OpenRig 就是在这个背景下慢慢成型的。
OpenRig 的核心定位很明确：它不是那种大而全的云管平台，也不是带复杂编排能力的集群调度系统，而是一个专门负责“把分散的计算设备统一纳入管理，实时采集状态，按规则预警，并支持批量下发简单任务”的开源小工具。你可以把它理解成设备的“值班室”，所有机器的 CPU、内存、磁盘、显卡温度和功耗都能在一个页面里看到，该告警的时候告警，该重启的时候重启，省掉了大量重复登录和反复检查的时间。
这个工具适合谁用？我总结下来有三类人最需要。第一类是像我一样设备不多但比较零散的个人维护者，可能家里几台、公司几台，没有专职运维，又不想被各种杂事绑住。第二类是小型工作室或者实验室，机器分布在不同的房间甚至不同的网段，需要一个低成本的统一监控方案。第三类是想学习设备管理底层逻辑的开发者，OpenRig 的代码量不大，结构清晰，非常适合拆开研究 Agent 和 Server 之间是怎么通信、怎么上报数据的。当然，如果你手头只有一两台机器，那确实没必要上这种工具，直接在终端里敲命令反而更快。
做这个项目的过程中，我逐渐意识到，很多时候大家缺的不是监控能力，而是一个“足够简单、不折腾部署、不依赖商业产品”的基础设施。市面上成熟的方案当然很多，但要么太重，部署一个监控系统比监控设备本身还累；要么收费，按节点数量收的那种计费方式对个人用户并不友好。OpenRig 走的是另外一个方向：单一二进制文件、配置文件写清楚、Agent 装好后自动上报，十分钟内就能看到第一台设备的数据。这种“够用就好”的设计思路，也是我在后面所有技术选型中反复坚持的原则。
1.1 最初遇到的场景：登录机器的疲惫感
我记得很清楚，有一次排查问题，需要在三台机器上分别看 GPU 利用率、确认一个定时任务有没有跑、再检查某个服务的日志。整个过程下来，我开了五个终端窗口，每个窗口都要手动 SSH，输入密码，敲各种命令，最后还得自己把数据拼在一起判断。问题最终是找到了，但时间浪费在“看状态”而不是“解决问题”上。做 OpenRig 的动机，本质上就是想把这种“看状态”的动作收敛到一个入口里。
这种需求听起来很朴素，但真正落地的时候你会发现有很多细节需要处理。比如每台机器的数据格式不一样，GPU 数据可能来自nvidia-smi，也可能来自 AMD 的rocm-smi；磁盘信息在 Linux 和 Windows 上的获取方式更是完全不同。如果只是用脚本临时抓一下，那没问题，但要稳定地、持续地采集，并且把数据统一成一个格式展示出来，就需要一个真正的 Agent 来做适配层。
1.2 OpenRig 解决的三个核心问题
我把需求收敛成三个问题：第一，设备状态如何统一采集和展示；第二，异常情况如何第一时间通知到人；第三，日常的重复性操作如何减少人工介入。
第一个问题通过 Agent 主动上报解决，第二个问题通过告警规则引擎解决，第三个问题通过任务下发机制解决。这三块是我认为一个“设备值班室”必须具备的基本能力。至于更高级的分布式调度、容器编排、自动扩缩容，OpenRig 刻意不去碰，因为那些功能会让系统复杂度急剧上升，而且和工具本身的定位不符。
实际使用下来，这三块能力的价值是依次递增的。状态采集解决的是“看不见”的问题，告警解决的是“来不及”的问题，任务下发解决的是“不想动手”的问题。如果你也在维护多台设备，我建议你优先把前两个做好，它们带来的体验提升是最直接的。
1.3 技术选型：Agent 主动上报还是 Server 主动拉取
这是我最先纠结的点。市面上两种方案都有：一种是被动拉取，Server 定期去连每台设备，SSH 上去执行命令拿数据；另一种是主动上报，每台设备装一个 Agent，Agent 自己采集好数据然后推给 Server。
被动拉取的优点是不用装 Agent，但缺点非常明显：需要每台设备都开放 SSH 端口，需要保存所有机器的登录凭据，网络环境复杂一点就很难打通，而且一旦设备数量多了，SSH 轮询的效率会很低。主动上报则刚好相反，Agent 只需要在设备上运行，由它主动往 Server 推数据，这样 Server 不需要主动连到任何设备上，网络模型更干净，安全性也更好。我最终选择了主动上报。
这个选择有两层考虑。第一层是现实原因，我的设备分布在多个网段，有些在同一个局域网，有些则在不同网络里，被动拉取意味着我必须处理复杂的网络连通性问题，而主动上报只需要 Agent 能访问到 Server 的地址即可，方向反过来了反而简单。第二层是扩展性考虑，主动上报模式下，Server 可以不关心设备数量规模，每一台设备都是数据的生产者，只要 Server 的吞吐量够，加设备只是加一个 Agent 的事情。
2. 核心细节设计与配置要点
确定了大方向之后，接下来的工作就是细化每一部分的实现。这里说的不是代码层面的具体函数，而是作为一个使用者需要理解的设计逻辑。你在配置 OpenRig 的时候，会接触到它的几个核心对象，把这些对象之间的关系搞清楚，配置起来就不会犯低级错误。
2.1 整体架构：Server、Agent 与 Web 面板
OpenRig 的架构可以说是“小但完整”。它包括三部分：Server 端负责接收数据、存储数据、评估告警规则、提供 HTTP API；Agent 端安装在每台被管理的设备上，负责采集本机状态并周期性地推送到 Server；Web 面板则是 Server 自带的一个前端页面，让你能在浏览器里看到所有设备的实时状态。除了这三个核心部分，还有一个可选的命令行工具，方便你在不打开浏览器的情况下快速查询设备列表。
Server 端的存储我选了 SQLite 作为默认的落地方式。理由很简单：对于几十台设备这个量级，SQLite 完全够用，而且它零配置、单文件备份方便，比引入 MySQL 或者 PostgreSQL 要轻得多。数据保留策略默认是七天的历史数据循环覆盖，你可以在配置里调整保留天数，也可以接上 Prometheus 之类的时序数据库做长期留存。考虑到 OpenRig 的定位是“值班室”而不是“数据仓库”，短期保留加上外部扩展的模式是我认为最合理的折中。
Agent 端的采集逻辑是这样的：每隔固定的时间间隔（默认 15 秒）采集一次 CPU 使用率、内存使用情况、磁盘空间、网络吞吐、显卡状态等指标，然后打包成一条 JSON 记录，通过 HTTP 接口推送给 Server。如果推送失败，Agent 会在本地缓冲区暂存数据，等网络恢复后再补推。这个设计能避免因为短暂网络抖动导致的数据丢失，我在实际使用中，确实遇到过网线松动导致断连的情况，靠这个补推机制保住了不少数据。
Web 面板做的事情就相对简单了，它通过 Server 的 API 拉取设备列表和状态数据，用表格和简单图表展示出来。我刻意没有做很花哨的图表，因为监控的核心是“能看到异常”，而不是“把图表画得多漂亮”。配合告警规则的提示，打开面板的第一眼就足够让你判断当前系统是否健康。
2.2 认证与通信：Token、加密与心跳保活
设备管理工具的设计里，安全一定不能忽略。Agent 推送数据时必须证明“我是合法的 Agent”，否则别人随便往 Server 推假数据，你的面板就会被污染。OpenRig 用的是简单的 Token 认证机制：Server 安装后会自动生成一个随机 Token，Agent 配置里写入这个 Token，推送数据时放进请求头，Server 校验通过才接受。
这个 Token 本质上就是一把钥匙，所以保管好 token 文件非常重要。在我的团队里，Token 是通过独立的安全通道分发的，不会写在普通文档里。如果 Token 意外泄露，Server 端需要及时执行命令重置，然后分批更新所有 Agent 的配置。这个操作虽然麻烦，但安全性比方便性更重要。
通信层面，为了不在公网传输明文敏感数据，Agent 和 Server 之间默认使用 AES 对负载做一层加密。当然，在完全内网部署的信任环境下，你可以在配置里关掉这层加密以换取更高的性能。我在方案里保留了这种灵活性，因为不同环境的安全诉求不一样。
心跳机制是维护设备在线状态的基础。Agent 每次推送数据的同时会带上本机标识和当前时间，Server 根据最近一次心跳时间来判定设备是否离线。默认设置下，超过 45 秒没收到新的数据就认为设备离线。这个阈值不是拍脑袋定的，它和采集间隔有关，15 秒采集一次，连续 3 个周期没有数据才判定离线，既能及时感知故障，又不会因为偶发网络抖动产生大量误报。
2.3 性能数据采集的坑：显卡指标、温度与功耗
这里我单独拿出来说，因为显卡相关指标是所有采集项里最容易出问题的。OpenRig 的 Agent 在适配 N 卡时直接调用了nvidia-smi的命令行输出并解析关键字段，比如核心利用率、显存使用率、核心温度和整卡功耗。这个方案在实际使用中比较稳定，但要注意nvidia-smi在某些精简版驱动或者容器环境下可能不存在，Agent 会因此拿不到显卡数据。
遇到过好几次“显卡显示为空”的情况，最后定位到的原因各不相同。有的是宿主机上的驱动没装完整，nvidia-smi本身就跑不起来；有的是容器环境里没有挂载对应的设备节点；还有的是 Agent 没有权限访问 GPU 文件系统。排查思路其实不复杂：先手动在设备上跑一遍命令，确认输出是否正常，再去看 Agent 日志里是否有解析异常。
温度数据比功耗数据更受大家关注，因为高温是导致硬件降频和损坏的头号原因。我建议在配置告警规则时，不要把温度阈值设得太激进。比如 GPU 温度，65 度设置为“提醒”，85 度设置为“严重”，中间留足缓冲，避免因为机器负载瞬间波动造成告警疲劳。告警疲劳是一个非常现实的问题，天天响铃也不会有人在意，那么告警系统的价值等于零。
2.4 告警规则的灵活配置
告警是 OpenRig 的招牌功能，也是配置中最容易玩出花来的部分。它的规则引擎支持“指标 + 比较符 + 阈值 + 持续时间”四要素，比单纯的仪表盘展示强大很多。例如，你可以设置一条规则：当任意一台设备的磁盘使用率超过 90% 且持续 10 分钟，就触发告警。这里的“持续 10 分钟”非常重要，它可以过滤掉瞬时抖动，让告警更贴近真实故障。
通知渠道方面，目前支持 Webhook、邮件和直接写日志。Webhook 是最好用的，你可以把告警消息转到办公群机器人或者自定义的接收程序里。我自己的用法是接了一个简单的通知脚本，把告警内容再转成短信发给值班手机号。邮件适合非紧急级别的汇总通知，比如每天上午九点发一份昨日所有设备的异常摘要。
配置告警规则时还有一个容易被忽略的维度：作用范围。你可以把规则应用到所有设备，也可以限制在某一组设备上。比如渲染农场里的显卡工作站和公司的资料存储服务器，它们的磁盘告警策略就完全不同。前者更关注显卡功耗和温度的异常，后者更关注磁盘空间和磁盘健康状态。给设备打上标签，然后按照标签来配置告警范围，会比全局一套规则灵活得多。
3. 从零部署 OpenRig 的完整实操
这一部分我会按照自己实际的部署顺序来写，尽量把每一步的注意点都交代清楚。OpenRig 的部署本身不复杂，但有些细节如果一开始没处理好，后面排查起来会很费劲。
3.1 准备环境与安装包获取
部署 OpenRig 之前，你先确认几点：Server 端需要一台 Linux 系统机器，建议使用 Ubuntu 20.04 或更新版本，2C4G 的配置足够支撑几十台 Agent 的接入；Agent 端可以跑在 Linux、Windows 和 macOS 上，其中 Linux 下的兼容性最好；端口方面，Server 默认监听 9668 端口，需要确保防火墙放行，Agent 只需要能访问到 Server 的地址和端口就行，不需要对外开放任何端口。
安装包的获取路径很简单，到项目的 release 页面下载对应平台的二进制文件即可。注意区分平台和架构的参数，比如 x64 和 arm64 是不同的包，搞错了会直接无法运行。下载完后放到一个固定目录，建议统一放在/opt/openrig下面，方便以后升级管理。对于个人设备，也可以直接放进用户目录然后加进 PATH，但我在实际操作中还是推荐标准目录，因为升级脚本和 systemd 服务的路径依赖它。
3.2 部署并初始化 Server 端
Server 端部署我一般分四步走。第一步，把二进制文件放到/opt/openrig/server并赋予执行权限。第二步，在相同目录下创建config.yaml配置文件。第三步，先手工执行一次初始化命令，让系统生成 Token 和 SQLite 数据库。第四步，把 Server 注册为 systemd 服务，实现开机自启和崩溃自动重启，这里我把服务文件的内容也分享给你参考。
配置文件的核心字段不多，但每个都很关键。监听地址默认是0.0.0.0:9668，表示接受所有网卡的连接，如果你只想让内网访问，可以改为内网 IP。数据保留天数我推荐先设置成 7 天，跑一段时间之后根据磁盘占用情况再做调整。Token 会在初始化时自动生成，生成后的路径会打印在终端里，妥善保存。
初始化命令执行完毕以后，你应该能在/opt/openrig/server目录下看到openrig.db文件和token.txt文件。这时 Server 还没有任何设备接入，面板打开只会看到空列表，这是正常的。下一步就是去其他设备上部署 Agent。
3.3 配置并启动 Agent
Agent 的部署思路和 Server 类似，但配置上多了一个指向 Server 的地址参数。你需要编辑 agent 配置，把server_url改成 Server 的访问地址，比如http://192.168.1.10:9668，同时把token填成刚才初始化生成的 Token。除此之外，你还可以在配置里指定需要采集的指标范围，比如是否采集 GPU 指标、是否开启磁盘 IO 统计等。
在 Windows 设备上部署 Agent 时，我建议把服务注册成系统服务，用 sc 命令实现。这样 Agent 在机器重启后会自动运行，不需要每次开机的都手动点一下。如果你在 Linux 设备上部署，则在/etc/systemd/system/下创建一个 service 文件，内容和 Server 端的服务文件相似，只是二进制路径和参数不同。装完后启动服务，观察日志。
Agent 启动成功的最直接标志是日志中出现“注册成功”或者“开始上报数据”之类的信息。如果日志一直显示连接不上 Server，优先检查网络连通性，用 curl 命令试一下 Server 的接口是否可达。通常这一步就能定位到 90% 的问题。
3.4 在 Web 面板中添加设备并验证监控
Agent 启动后，打开 Server 的 Web 面板，刷新设备列表，正常情况下新设备会在十几秒内出现在列表中。设备出现在列表里，说明 Server 已经收到了 Agent 的第一次心跳上报。如果你给设备配置了名称和标签，可以在面板里直接编辑，也可以提前在 Agent 配置中写死，两种方式效果一致。
第一次接入时我建议做一个基准测试：观察设备的 CPU 和内存曲线是否平稳，GPU 温度是否在正常范围，磁盘 IO 是否和实际负载匹配。这个“校准”过程很有必要，因为如果采集到的数据和实际状态偏差较大，后面的告警规则就没有意义了。比如我之前遇到过一台设备因为驱动问题，GPU 温度永远返回 0 度，这个值如果不检查出来，后面的高温告警就永远不会触发，等于一条裸奔的规则。
验证监控数据正常之后，强烈建议在 Web 面板上手动创建一个测试告警规则。把阈值设成一个肯定会触发的值，比如磁盘使用率大于 0% 且持续 1 分钟，然后静等系统推送。这样做的目的是验证从采集、入库、规则评估到通知推送的整条链路是否通畅，链路通了再调回正常阈值才会放心。
3.5 配置自动化任务：定时重启与脚本下发
OpenRig 除了监控，还有一块让我觉得很顺手的功能：自动化任务下发。简单来说，你可以预先编辑好一段命令或脚本，然后选择要执行的设备，OpenRig 会通过已有的 Agent 通道把命令推过去并执行。由于 Agent 和 Server 之间长连接本身是通的，所以不需要额外开放 SSH 端口，安全性和便利性都兼顾到了。
我在配置任务时，最常用的场景有两个。一是定时重启显卡工作站，因为渲染工作跑久了之后显存可能会泄漏，定时重启能有效降低故障率。二是批量更新某个公共脚本，用 OpenRig 一次性推到所有设备上，改成软链接的方式以后，新加设备也自动同步。这里要特别提醒：任务下发功能虽然方便，但危险性也高，一条rm -rf命令如果配置错了，后果非常严重。所以我在配置里加了一个确认开关，高危命令默认要求二次确认，同时在任务执行前把“目标设备列表”和“命令内容”打印出来，确认无误后再执行。
任务执行记录会保存在 Server 端，打开面板就能看到哪些任务在哪些设备上执行成功了，哪些失败了。失败的常见原因包括目标设备离线、命令写错、权限不足、执行超时。我这里设了一个默认超时时间是 30 秒，如果脚本比较复杂，你需要在任务配置里调大。我个人经验是，脚本执行时间能短尽量短，一次性任务控制在几秒内完成，长任务交给后台方式去跑，不要在交互式执行里耗着。
4. 常见问题与排查技巧实录
工具用久了，总是会遇到这样那样的问题。这里我把实际使用中踩过的坑整理成一份速查表，每个问题都附上排查思路和解决办法。你不用全部看完，遇到对应问题时再来翻这一部分就行。
4.1 Agent 显示离线，心跳数据断了
这是占比最高的一个问题。打开面板看到设备标红，第一反应是检查 Agent 进程是否还在，但很多时候问题不在进程，而在网络链路。我先在设备上 curl 一下 Server 地址，看能不能通。如果连不通，大概率是防火墙或者路由问题，放行对应端口即可。如果能通，再去看 Agent 日志，看看有没有 HTTP 401 之类的认证错误。
如果 Agent 进程已经崩溃了，或者服务被意外停止了，则需要设置自动重启机制。我的 systemd 服务文件里加了Restart=on-failure和RestartSec=5，这样即使 Agent 因为异常退出，五秒后也会自动拉起来。这个配置对于长时间运行的设备管理项目来说非常关键，否则一次进程崩溃就会导致监控长达数小时处于真空状态。
4.2 GPU 指标一直为空，温度功耗都看不到
排查 GPU 指标为空的问题，先手动执行一下nvidia-smi，看命令本身能不能正常输出。如果提示未找到命令，说明驱动没装好；如果提示 no devices 或 permission denied，说明设备权限有问题。在普通权限下，nvidia-smi的某些指标可能受到限制，这时需要给 Agent 配置相应的 sudo 权限，或者在 systemd 服务里指定正确的用户组。我自己的做法是把 Agent 服务运行用户加入video组，这样不需要给太多的系统权限就能读取 GPU 信息。
还有一个特别容易踩的坑是容器的设备映射。如果你把 Agent 跑在容器里，但容器创建时没有加--gpus all参数，那容器内部是拿不到 GPU 的。这种情况下手动执行命令能想都想不到，就得回到宿主机去检查容器参数。我在实践中确实见过把 Agent 放进容器后 GPU 数据消失的案例，最后就是改回宿主机部署解决的。
4.3 Token 认证失败，推送全部被拒绝
Token 认证失败的原因无非就几种：填错了、复制多了空格、Server 端 Token 重置过后 Agent 没更新。排查时先去 Server 端的日志里找一条明确的拒绝原因，然后再和 token 文件里的原始值做对比。这里我建议尽量不要手工去复制 Token，而是用cat token.txt | ssh这样的方式直接传输，避免因为复制操作引入错误。
如果你有很多 Agent 都要更新 Token，手工一台台改太累。更好的做法是写一个简单的循环脚本，批量把新 Token 卸载到所有设备的配置里，然后一次重启所有 Agent 服务。这需要在设备列表里维护好 SSH 信息，但相比手工操作还是省力不少。更新完成后，去面板上看设备是否重新上线，确认 Token 更新没有导致其他问题。
4.4 告警刷屏与通知策略优化
告警刷屏是非常影响使用体验的问题，而且很容易让人麻木。我碰到过一次磁盘使用率触发的告警，每 15 秒就推一条，一分钟能刷几十条，值班手机都快被打爆了。后来我调整了规则，增加了“持续 10 分钟”的确认时间，又引入了“沉默期”设置，也就是同一台设备的同一类告警在触发后 30 分钟内不重复通知。这两项改完，告警量一下降了一个数量级。
更合理的做法是在日常配置中留优先级评估。真正的故障应该走紧急通知，比如高优先级 Webhook 或短信；非紧急状态就走汇总，比如每天一封摘要邮件。我在 OpenRig 里配置了一个“每日健康巡检”任务，每天上午十点把过去 24 小时的异常记录汇总出来发到邮件列表，省去了盯着面板的精力，又不会漏掉潜在问题。
4.5 数据存储与备份恢复
SQLite 单文件存储让备份变得极其简单，我直接用 crontab 每小时压缩备份一次openrig.db，推送到内网备份服务器上。恢复的时候只要把备份文件放回原来的位置，重启 Server 进程即可。实际操作中我恢复过两次，一次是磁盘故障，一次是误删数据，恢复过程都很顺利。但要注意，SQLite 在数据量很大的情况下写入并发可能成为瓶颈，如果你管理的设备超过两百台，我建议还是把历史数据转发到时序数据库，SQLite 只保留短期的实时状态。
还有一个小建议：Server 所在机器的磁盘监控一定要比普通设备更早做好。因为所有 Agent 的数据都汇聚到 Server 上，一旦 Server 的磁盘满了，SQLite 写入失败，整个监控系统就会瘫痪。我自己就因为在 Server 上没装独立的磁盘告警，等到发现问题时数据库已经写不进去了。这个坑我希望你不要再踩。
写在最后：一点点使用心得
回头想，OpenRig 这个项目带给我的并不是某一个具体功能有多强，而是一套“把分散的东西集中起来，把重复的事情自动化”的思路。对比我之前的所有设备管理方式，单是在响应效率上的提升就非常明显，现在打开面板扫一眼就能知道几十台机器的整体状态，告警消息进来后我也能迅速定位到问题设备，不需要再像以前一样一台台切换终端。
如果你也想搭一套类似的设备管理工具，我的建议是先别急着追求功能多，把自己最常用的三个场景列出来，围绕它们搭一套最小可用的系统，然后边用边加。我在 OpenRig 上也是这样一步步迭代过来的，最初只有 CPU 和内存监控，后来才加的显卡指标、告警规则和任务下发。工具是为人服务的，好用才是硬道理。
