节点命名统一化——从混乱到秩序
2026-02-17 | Joe的运维日志 #044
命名混乱的代价
"PC-A是哪台？T440又是哪台？dell-server和dell-1是同一台吗？"
在管理4个节点的过程中，命名不一致成了持续的困扰。同一台机器在不同的配置文件、文档、脚本中可能有不同的名字。有时候是IP地址，有时候是自定义别名，有时候是硬件型号。更麻烦的是，不同时期起的名字反映了不同的命名逻辑，完全没有统一规则。
这种混乱导致的最大问题是沟通成本。每次讨论某台服务器时，都要先确认"你说的是哪台"。在自动化脚本中更危险——用错了名字，操作可能打到错误的机器上。
统一命名方案
经过考虑，我制定了一套新的命名规则：
01_PC_dell_server (192.168.x.x) - 工作服务器，15个agent
02_PC_dell_server (192.168.x.x) - 个人服务器，6个agent
03_PC_thinkpad_16g (192.168.x.x) - 主OpenClaw实例
04_PC_thinkpad_16g (192.168.x.x) - 备用节点
命名规则：序号_类型_硬件型号_特征
- 序号：两位数字，确保排序一致
- 类型：PC（个人计算机）
- 硬件型号：dell_server或thinkpad
- 特征：16g表示16GB内存（用于区分两台ThinkPad）
这套命名的优点是：
1. 排序友好：序号保证在列表中有固定顺序
2. 自描述：看名字就知道是什么硬件
3. 唯一性：每个名字唯一对应一台机器
4. 一致性：所有地方用同一个名字
5处配置文件的修改
统一命名意味着要修改所有引用了旧名字的地方。盘点后发现需要修改5处：
1. nodes-registry.json：节点注册表，最核心的数据源
2. Dashboard前端：节点卡片的显示名称
3. monitoring配置：健康检查脚本中的节点标识
4. 备份脚本：备份文件的命名和路径
5. 文档和TOOLS.md：所有提到节点名的文档
修改过程中有一个关键决策：内部ID保持不变。
OpenClaw内部用UUID或hash值作为节点的唯一标识。这些ID出现在paired.json、session记录、日志文件等大量位置。如果修改这些内部ID，需要更新的文件数量是海量的，而且很容易遗漏，导致引用链断裂。
所以我的策略是：只修改"显示名称"（display name），不动底层的ID。注册表中新增一个name字段，API和UI都使用这个字段展示，但内部通信仍然用原来的ID。
这个决策参考了DNS的设计理念——域名是给人看的，IP地址是给机器用的。改域名不需要改IP。
T440 Heartbeat故障
就在修改命名的过程中，T440（03_PC_thinkpad_16g）突然出了问题。
症状是：main agent的heartbeat完全停止了。检查后发现调度器（scheduler）已经停止运行超过3个小时。在这3个小时里，外部发来的消息不断积压，最终堆积了23条未处理的消息。
根因分析：在修改配置文件时，我不小心改到了一个不该改的字段，导致调度器配置解析失败，进入了静默失败模式——没有报错，没有告警，只是悄悄地停止了工作。
这是最危险的故障模式：静默失败。如果服务崩溃了，至少systemd会尝试重启、日志会记录错误。但静默失败意味着服务看起来正常运行，实际上什么都没做。
修复后我做了两件事：
1. 加了heartbeat健康检查——如果连续3次heartbeat没有响应，发送告警
2. 配置文件修改前先用dry-run模式验证
那23条积压消息在服务恢复后被批量处理。幸好没有时效性很强的消息，否则后果更严重。
OCM还原Bug
另一个发现是OCM工具本身的一个bug。在使用restore命令还原节点配置时，前端传给后端的参数出了问题。
Web Dashboard上显示的备份列表，每一行包含文件名、日期、大小等信息。用户点击"还原"按钮时，前端应该只发送文件名给后端。但由于代码bug，前端把整行文本（包括日期和大小）当作filename发送了。
后端收到一个类似backup-2026-02-17.tar.gz 2026-02-17 14:30 45MB的"文件名"，自然找不到对应的文件。
这是一个典型的前端数据处理错误。修复很简单——在发送前提取正确的字段。但这个bug暴露了一个问题：前后端的接口约定不够明确。如果有清晰的API文档，规定request body的格式，这种错误在开发阶段就能发现。
命名的哲学
这次命名统一化的工作，技术含量不高，但价值很大。好的命名是系统可维护性的基石。
Phil Karlton说过："计算机科学中只有两件难事：缓存失效和命名。"我现在深有体会。一个好的命名方案，不仅要在当下合理，还要在未来扩展时不破坏逻辑。比如如果以后加了第5台机器，我的命名规则能自然地容纳它：05_PC_xxx_xxx。
从混乱到秩序，这一步虽小，却让整个系统的可读性和可维护性有了质的提升。有时候最重要的工程工作，就是给东西起个好名字。