我最近一直在折腾家里的设备管理，手头攒了树莓派、两台迷你主机、一块硬盘阵列，还有家里几个智能家居网关。东西一多，问题就来了：哪台设备 CPU 温度异常、哪个挂载点离线、哪块盘快要塞满，全靠手动登录去查，完全管不过来。直到我搭了一套 OpenRig，把设备挂载、状态采集、告警通知全部收拢到一个面板里，才算真正从"用插线板堆设备"升级成了"有体系的设备管理"。这篇文章就把我一个月来的部署过程、踩坑经验、以及 OpenRig 的核心设计思路完整讲一遍，给同样在折腾家庭服务器或小型工作站的你做个参考。

OpenRig 本质上是一个开源的设备挂载与管理框架。它解决了这样一个问题：当你的设备从一两台增加到十几台时，你需要知道"哪台设备还活着""它的温度、负载、磁盘状态是否正常""哪个文件系统挂载到哪里去了""启动之后设备节点顺序有没有变"。这些事靠 SSH 逐台登录当然也能做，但效率太低，且状态不可追溯。OpenRig 用"Agent 上报 + Server 聚合 + Web 面板展示"的思路，把所有硬件资产变成一份随时可查的清单，同时提供 API 和告警机制，让设备管理从"被动救火"变为"主动预防"。

后面我会按它的核心设计、部署步骤、挂载识别机制、自动化联动和实战中踩过的坑依次展开，内容尽量写得能直接抄作业。

1. 从一堆插线板到 OpenRig：我为什么需要一套设备管理框架

先说一个真实场景。上个月我给家里的网络加了一台软路由，又为了跑内网服务塞了一台 NUC。算上原有的树莓派 4B、一台老笔记本改的备份服务器、两块移动硬盘、一个 3D 打印机控制板，整个书桌后面已经乱成了蜘蛛网。更让人头疼的是，有一次树莓派因 SD 卡 IO 错误挂掉了，但我是三天后才发现——因为只有等我需要登录它的时候，才会意识到它已经失联。

这就是典型的"设备多了但管理方式没跟上"。

1.1 小型设备集群的三大痛点

归纳一下我当时遇到的问题，基本可以分成三类：

• 设备状态不可见：每台设备的 CPU 温度、内存占用、磁盘剩余、网络连通性都是独立的，没有一个统一的视图。想看整体运行状况，只能一台一台 SSH 进去敲命令。
• 设备挂载混乱：多块硬盘在不同机器间挪来挪去，插到哪台机器、以什么路径挂载，全靠记忆。一旦某次开机顺序不同，/dev/sda变成了/dev/sdb，挂载就可能出错，甚至导致数据读不出来。
• 故障发现滞后：没有主动告警机制，设备过热、掉盘、服务异常，都是等到用户真正要用时才发现。最典型的就是我那块 SD 卡——因为频繁读写提前老化，系统直接只读挂载，但外表看起来一切正常。

1.2 为什么不能直接用现成的监控工具

有人可能会说：用 Prometheus 加 Grafana 不就行了？我确实试过。Prometheus 在指标采集和可视化上很强，但它定位是"监控系统"，解决的是"指标趋势"问题。OpenRig 的切入点不一样，它把重点放在了设备语义上：不只知道某个数字是 62 度，还知道这个温度属于哪一台物理设备，这台设备放在哪个位置、运行着什么任务、有哪些挂载点、上次重启是什么时候。

这两者最大的区别在于：Prometheus 告诉你"CPU 高了"，OpenRig 告诉你"书房那台跑批处理的 NUC 温度高了，建议去检查风扇"。前者是数据维度，后者是管理维度。实际用下来，我是两个都在跑，Prometheus 看趋势和告警曲线，OpenRig 管设备台账和日常运维操作入口。

我也看了像 Cockpit 这类单机管理工具，但它们强在单机管理，不适合做成多设备统一入口。OpenRig 的 Agent 设计让我可以把所有机器纳入同一个管理平面，这才是它对我最大的价值。

2. OpenRig 的核心设计：它在管什么、组件如何分工

既然要用 OpenRig，就要先搞清楚它内部的几个关键概念。否则你部署完了只会看个温度，很多能力都浪费了。

2.1 OpenRig 的四大管理对象

从我实际使用的经验看，OpenRig 把需要管理的内容抽象成了四类对象：

设备台账（Asset Inventory）

每台设备不再是一串 IP，而是一个有身份的实体。你可以给设备填上别名、位置、硬件型号、序列号、负责的任务、购买日期、保修信息。这一点在最开始觉得没什么用，等设备超过十台之后就非常有用了——你不需要回忆"这台机器当初是拿来干嘛的"，面板上写得清清楚楚。

硬件状态（Health Status）

Agent 周期性采集 CPU 温度、负载、内存、磁盘空间、网络吞吐、电源状态等指标。采集间隔可以配置，默认是 30 秒一次。我调成了 10 秒，因为我想对温度变化更敏感一些，代价是数据库写入量会大一些。

挂载管理（Mount Management）

这是 OpenRig 区别于一般监控工具的重要功能。它记录每台设备上所有的文件系统挂载点、设备节点、文件系统类型、挂载选项。如果有两台设备抢同一个网络存储挂载点，或者某块盘挂载失败，OpenRig 会直接标记异常，而不是等你去df -h才发现。

任务与操作（Operation & Tasks）

OpenRig 允许在 Web 面板上对设备下发一些标准操作，比如重启、关机、执行指定脚本等。它默认比较保守，不会让你随意在设备上跑任意命令，得先定义好"可执行任务模板"。这个设计我很喜欢——把容易出错的操作限制在一个白名单里，既方便日常使用，又不会手滑酿成事故。

2.2 Server、Agent、 Web 面板的三角结构

整个 OpenRig 运行时由三部分组成：

Server 和 Agent 之间的通信基于 HTTP 协议。Agent 启动后先注册到 Server，之后周期性地把自己采集到的数据 POST 到 Server 的接口上。也就是说，被管设备只需要能访问 Server 的某一个端口就行，不需要 Server 主动去连被管设备。这一点在实际部署中非常有用——即使设备在 NAT 后面，只要它发起出站请求，依然可以被管理到。

2.3 数据存储与通信设计

Server 端的数据存储默认使用 SQLite，数据量大了以后可以切换到 PostgreSQL。按我的使用量——12 台设备、每台一次上报约 40 个指标点——30 秒上报一次，SQLite 完全没有压力。只有当我调成 10 秒周期并开启长时间趋势查询时，SQLite 的写入锁竞争才变得明显，所以后来我换成了 PostgreSQL。对于大多数场景，SQLite 足够。

通信安全方面，Agent 到 Server 可以使用 Token 认证。每个 Agent 注册时生成一个独立的 Token，Server 只接受携带有效 Token 的上报请求。推荐在 Server 前面再挂一层 HTTPS，这样即使在公网上跑，数据也是加密的。我自己的环境在内网，只做了 Token 认证，没有上 HTTPS，但如果你有多地组网的需求，HTTPS 还是建议加上。

3. 从零部署一套 OpenRig：安装、配置与接入设备的完整过程

下面进入实操部分。我在一台树莓派 4B（4GB 版本）上部署了 Server，另有两台 Ubuntu 主机和一台 Debian 主机作为 Agent 端接入。

3.1 第一步：以 Docker 方式安装 Server

OpenRig 官方提供了 Docker 镜像，这是最省事的部署方式。我的树莓派原来已经装好了 Docker 和 Docker Compose，所以直接写一个 compose 文件：

version: "3.8" services: openrig-server: image: openrig/server:latest container_name: openrig-server restart: unless-stopped ports: - "8080:8080" environment: - OR_DB_TYPE=sqlite - OR_DB_PATH=/data/openrig.db - OR_TOKEN_EXPIRE=720h - OR_ENABLE_TASK=true volumes: - ./data:/data - ./config:/etc/openrig

在docker compose up -d之前，建议先创建一个config目录，并在里面放一个server.yaml配置文件。我的初始配置是这样：

server: listen: 0.0.0.0:8080 db_type: sqlite db_path: /data/openrig.db auth: token_enabled: true token_expire_hours: 720 agents: allow_register: true checkin_interval: 30 task: enabled: true allowed_scripts: - /usr/local/bin/check-cache.sh - /usr/local/bin/restart-service.sh

这里的allow_register: true表示允许新 Agent 主动注册。等设备都接入完之后，建议把它改为false，避免局域网里其他设备意外接入你的管理面。

3.2 第二步：在设备端部署 Agent

Agent 的部署取决于被管设备的系统。对 Linux 设备，OpenRig 提供了安装脚本：

curl -fsSL https://get.openrig.io/install.sh | sudo bash

安装完成后编辑/etc/openrig/agent.yaml：

agent: server_url: http://192.168.1.100:8080 device_name: home-nuc location: 书房 tags: - compute - medi-server interval: 30 monitor_cpu: true monitor_mem: true monitor_disk: true monitor_mount: true monitor_network: true

这里最关键的三个字段是server_url（Server 地址）、device_name（设备名，建议设置成有语义的名字，别用默认的主机名）和tags（标签）。标签是 OpenRig 做分组管理的重要维度，比如你可以把home-nuc和home-rpi4都打上compute标签，Web 面板里就能按标签一眼看到所有算力设备。

配置完成后启动服务：

sudo systemctl enable openrig-agent sudo systemctl start openrig-agent

启动后观察日志，如果出现类似registered successfully, token=xxx的输出，就说明 Agent 已经成功注册到 Server。

3.3 第三步：在面板上完成设备分类与基础配置

等所有 Agent 都注册进来后，打开 Web 面板就能看到设备列表。我建议花十分钟做三件事：

• 给每台设备补充硬件信息：CPU 型号、内存大小、磁盘容量、操作系统版本。这些信息虽然日常看仪表盘用不上，但在排查故障、考虑升级时非常有用。
• 把设备按房间和用途打标签：比如书房/客厅/机房、下载机/备份机/登录跳板。标签可以多打几个，后续做告警分组和视图筛选会方便很多。
• 设置所属组：如果设备分布在不同地方，组可以用来区分管理域。比如home-main和remote-office。

到这里，OpenRig 的运行框架就算搭起来了。Web 面板上应该能看到每台设备的实时状态、历史温度曲线和挂载列表。我第一次把所有设备接入完后，最大的感受是：终于不用再记一堆 IP 和路径了。

4. 挂载识别与冲突处理：udev 规则和稳定标签的实战配置

这部分是我个人觉得 OpenRig 最值钱的地方——挂载管理。如果你只有一块硬盘插在一台机器上，可能体会不深；但当你有好几块硬盘、在不同设备间轮换使用，挂载混乱是必然会遇到的问题。

4.1 为什么不能直接用 /dev/sda 这种设备名

Linux 的设备节点名是内核按发现顺序动态分配的。开机时如果 U 盘先于内置盘被识别，原本的/dev/sda可能变成/dev/sdb。如果你在 fstab 里写的是/dev/sda1，下一次开机可能就挂载失败，或者更糟——挂到了错误的设备上。

这个问题的真正解法是用稳定的设备标识。Linux 下有几个选择：

• /dev/disk/by-uuid/：按文件系统 UUID 区分，稳定可靠，适合已经格式化好的分区
• /dev/disk/by-id/：按硬件序列号区分，适合整块设备级别
• /dev/disk/by-path/：按物理接口路径区分，适合磁盘位置固定的场景

OpenRig 在挂载管理里也正是利用这些稳定标识来做设备节点的识别。你可以把报告上来的设备节点理解为"经过归一化之后的稳定路径"，而不是一次性的内核节点名。

4.2 用 udev 规则生成固定的设备别名

为了让系统层直接把设备变成固定路径，我在每台设备上添加了 udev 规则。新建文件/etc/udev/rules.d/99-openrig.rules：

# 根据 USB 设备序列号创建稳定软链接 SUBSYSTEM=="block", ATTRS{serial}=="ABC123456789", SYMLINK+="openrig/backup-disk", ACTION=="add", RUN+="/usr/bin/systemctl restart openrig-agent" # 根据硬盘 wwid 创建稳定软链接 SUBSYSTEM=="block", ATTRS{wwid}=="naa.5000c500abcd1234", SYMLINK+="openrig/media-disk1", ACTION=="add", RUN+="/usr/bin/systemctl restart openrig-agent"

写完规则后执行sudo udevadm control --reload-rules && sudo udevadm trigger，然后检查/dev/openrig/目录下是否生成了对应的软链接。

这样一来，在 fstab 或挂载脚本中就可以使用/dev/openrig/backup-disk这样的路径，无论内核把设备识别成 sda 还是 sdb，都能正确找到它。

4.3 OpenRig 的挂载冲突检测逻辑

设备接入 OpenRig 后，Agent 会周期性扫描所有挂载点并上报。Server 端会做一个简单但实用的检测：如果两个 Agent 上报了同一个挂载点路径（比如两个设备的 Agent 都上报了/mnt/media），或者同一块磁盘被两个 Agent 同时挂载，就会生成一条警告记录。

我最开始认为这个功能没什么用，因为我的每台设备挂载路径都不同。后来我加了一台网络存储设备，通过 NFS 同时挂载到了 NUC 和树莓派上，OpenRig 就把这两个挂载点标记成了"共享挂载"。这种场景下它不会报冲突，但会在该挂载点上标记多个持有者，方便你排查"这个目录到底被多少台机器占用了"。

还有一次，我手动在另一台机器上挂载了某块移动硬盘，忘记先卸载原来的挂载。OpenRig 检测到同一块磁盘出现两个挂载点后，立刻在告警里标了出来——虽然系统层面不会强制卸载，但它能提醒我，这块盘可能已被双写，存在数据一致性风险。

4.4 实测中容易忽略的两个细节

USB 设备序列号可能为空。某些廉价 U 盘和硬盘盒的序列号字段是空的，udev 规则用ATTRS{serial}根本匹配不上。这种情况建议改用ATTRS{idVendor}和ATTRS{idProduct}组合匹配，或者直接使用/dev/disk/by-uuid/来挂载分区。

移动硬盘盒断电后重新变只读。OpenRig 上报的是内核看到的挂载状态。有的硬盘盒电源管理不佳，在树莓派 USB 口供电不足时，磁盘会突然变成只读挂载。Agent 把这个状态上报后，OpenRig 能看到挂载属性里出现了ro，但不会自动帮你改回读写。你需要检查 dmesg，必要时重新拔插或给硬盘盒换独立供电。我在树莓派上就遇到过两次，后来直接给硬盘盒加了独立电源，问题就消失了。

5. 告警、仪表盘与自动化联动：让 OpenRig 成为管理中枢

设备全部接入之后，OpenRig 的身份就不只是"状态查看器"了。配合它的告警规则和 API，可以做到很多自动化的事情。

5.1 设计一套实用的告警规则

进入面板的告警规则配置页，我按实际需求配了下面几条：

告警里有几个参数需要说明。持续时间这个参数很关键。如果不加持续时间，有些机器偶尔瞬时温度冲到 80 度就会误报。我设置了 5 分钟持续判断，稳定性好了很多。离线判定阈值则要根据你的 Agent 上报周期来定。如果上报间隔是 30 秒，3 分钟未上报基本可以确定设备掉线；如果间隔是 5 分钟，那就要调整到 15 分钟以上。

5.2 通过 Webhook 把告警送给其他系统

OpenRig 支持 Webhook 通知，也就是把告警信息以 JSON 格式 POST 到你指定的 URL。我家里有一台 Home Assistant，所以我把 OpenRig 的告警接到了 Home Assistant 的自动化里，实现了这样几个场景：

• 当书房 NUC 温度超过阈值时，自动打开书房风扇
• 当备份服务器磁盘快满时，推送一条消息到手机，提醒我清理过期备份
• 当软路由的 WAN 口流量异常突增时，给我发一个提醒

具体配置方法是在 OpenRig 的server.yaml里加上：

webhook: enabled: true url: http://192.168.1.50:8123/api/webhook/openrig-alert secret: my-secret-token

在 Home Assistant 端添加一个 Webhook 自动化，就可以接收并解析告警了。这块联动的体验很顺，OpenRig 的告警结构很清晰，直接把device_name、alert_type、message字段取出来做条件判断就行。

5.3 用 API 做自己的小脚本

OpenRig 提供了完整的 REST API。我最常用的是这两个端点：

# 获取所有设备实时状态 curl -H "Authorization: Bearer ${TOKEN}" http://192.168.1.100:8080/api/devices # 获取某台设备的历史温度 curl -H "Authorization: Bearer ${TOKEN}" http://192.168.1.100:8080/api/devices/home-nuc/metrics/temperature?hours=24

基于这个 API，我写了一个很实用的小脚本：每天早上 8 点，检查所有设备的磁盘剩余空间，如果某个分区剩余空间低于 15%，就在钉钉群里发一条提醒。类似这样的脚本，其实才是 OpenRig 发挥价值的最高形态——它不再是"一个监控页面"，而是变成了一个可以编程调用、可以嵌入到任意业务逻辑里的设备数据底座。

关于 API Token 有一点想提醒：OpenRig 的 Token 默认有效期是 720 小时（30 天），过期之后脚本就会 401。我当时排查了半天，才发现是这个原因。解决办法是在 Server 端提前创建一个长期 Token 供脚本使用，或者把OR_TOKEN_EXPIRE调大。

5.4 自愈操作：把 Task 用起来

OpenRig 的 Task 机制允许管理员在面板上对设备执行预定义脚本。我在两台设备上配置了这样一个自愈流程：当 Agent 上报某个服务的进程数低于阈值时，OpenRig 调用预定义任务/usr/local/bin/restart-service.sh来自动重启这个服务。

这个流程能够成立的前提，是 OpenRig 的 Agent 具备执行任务的能力，且任务脚本在白名单中。我的做法是在每台设备的 Agent 配置里声明允许执行哪些脚本，并且脚本本身也做了防护——比如重启服务前先检查日志，确认不是更严重的故障导致进程消失，再执行重启。这样既实现了一定程度的自愈，又不会在设备真正出问题时反复重启造成二次损伤。

6. 跑了整整一个季度之后：几个必须说的坑和我的最终配置

OpenRig 从部署到现在已经稳定运行了一个季度。这期间踩了不少坑，有些是 OpenRig 本身的问题，有些是它暴露出来的底层系统问题。下面挑几个影响最大的说说。

6.1 树莓派 SD 卡寿命是最大短板

OpenRig Server 跑在树莓派上，数据库频繁写入，对 SD 卡的磨损很明显。我第一张 32G 卡大概撑了两个月就开始出现只读错误。后来我换了 MLC 颗粒的工业级 SD 卡，同时给系统做了只读化改造，把大部分可写目录放到 tmpfs 里。如果你也打算用树莓派长期跑 Server，建议要么用 SSD 通过 USB 启动，要么至少做 OverlayFS 只读方案，否则重启时发现数据库文件损坏是迟早的事。

6.2 Agent 数据上报频率与数据库膨胀的取舍

我一开始把 Agent 的上报间隔调成 10 秒，一个季度下来 SQLite 数据库涨到了快 1.5GB。虽然有保留策略在自动清理，但大数据库让仪表盘的查询变慢了不少。后来我调整成"日常 30 秒、需要排查时临时改为 10 秒"，数据库增长明显放缓，查询速度也恢复了。

如果你也想精确控制数据保留周期，可以在 Server 配置里加：

metrics: retention_days: 30 aggregation: hourly

这个配置可以按天清理 30 天前的原始数据，只保留小时级聚合值。对于查看趋势图来说完全够用，存储压力少一个数量级。

6.3 远程执行任务必须做防呆设计

OpenRig 的 Task 功能虽然方便，但我在一次操作中深刻体会到防呆设计的重要性。当时我在面板上点了一下重启存储服务器，结果脚本执行后，那台服务器因为某个服务没有正确关闭，导致文件系统没有干净卸载，自动开机后修复磁盘花了很久。从那以后我为自己立了一条规则：凡是可能影响数据可用性的操作，都写进脚本里做前置检查，比如检查是否有进程还在使用挂载目录、是否有未完成的任务等。OpenRig 允许在任务模板里写判断逻辑，这不只是方便，更是安全保障。

6.4 我在生产环境里的最终配置参考

如果你打算照着搭一套，这是我目前仍在用的最终配置：

这个配置跑下来的整体稳定性很好，设备管理效率也提升了一大截。以前我每天早上第一件事是逐台检查设备，现在只需要看一眼 OpenRig 仪表盘，或者等告警通知推过来就行。

最后再分享一个让我受益很大的使用习惯：不要只把 OpenRig 当成监控工具。它的价值在于把设备身份、状态、挂载、任务都抽象成了统一的接口和数据。这意味着你可以基于它做更多自动化——无论是联动 Home Assistant，还是自己写脚本处理告警，甚至未来接入更大的运维体系，它都能成为一个扎实的底座。你只要记住一点：规则和任务模板一定要保守、防呆、可审计，设备管理这事，安全永远排在便利前面。