HarborForge.Monitor

轻量级 Go 遥测客户端，用于把服务器硬件状态上报到 HarborForge Monitor。

它不依赖 OpenClaw，适合普通 Linux 主机、VPS、Nginx 机器等。

采集内容

• CPU 使用率
• 内存使用率
• 磁盘使用率
• Swap 使用率
• Load Average
• Uptime
• Nginx 是否安装
• /etc/nginx/sites-enabled 列表

上报接口

客户端调用：

• POST /monitor/server/heartbeat-v2
• Header: X-API-Key

项目结构

HarborForge.Monitor/
├── cmd/harborforge-monitor/      # 程序入口
├── internal/config/              # 配置加载
├── internal/telemetry/           # 指标采集与上报
├── internal/bridge/              # MONITOR_PORT 本地桥接服务
├── Dockerfile                    # 容器化运行
├── docker-compose.yml            # Docker Compose 配置
├── config.example.json
└── README.md

配置

先在 HarborForge Monitor 中注册服务器并生成 API Key。

然后准备配置文件，例如 /etc/harborforge-monitor/config.json:

{
  "backendUrl": "https://monitor.hangman-lab.top",
  "identifier": "vps-nginx-01",
  "apiKey": "your-api-key",
  "reportIntervalSec": 30,
  "logLevel": "info",
  "monitorPort": 9100
}

也支持环境变量覆盖。为了兼容你的命名，这里优先支持：

• HF_MONITER_BACKEND_URL
• HF_MONITER_IDENTIFIER
• HF_MONITER_API_KEY
• HF_MONITER_REPORT_INTERVAL
• HF_MONITER_LOG_LEVEL
• HF_MONITER_ROOTFS

同时也兼容旧的/正确拼写的 HF_MONITOR_* 变量名。

MONITOR_PORT — 插件桥接端口

当 MONITOR_PORT (或 monitorPort) 设置为大于 0 的值时，Monitor 会在 127.0.0.1:<MONITOR_PORT> 上启动一个本地 HTTP 服务，供 HarborForge OpenClaw 插件查询遥测数据。

支持的端点：

端点	说明
GET /health	健康检查，返回 Monitor 版本和标识符
GET /telemetry	返回最新的遥测数据快照
POST /openclaw	接收 OpenClaw 插件推送的元数据（版本、代理等）

OpenClaw 元数据 enrichment

当 OpenClaw 插件通过 POST /openclaw 推送元数据后，Monitor 会在后续的心跳上报中自动将这些信息附加到遥测数据中：

• openclaw_version — OpenClaw 运行时版本
• plugin_version — 插件版本
• agents — 代理列表

如果插件从未推送过元数据，这些字段会被省略，心跳上报完全不受影响。

重要：桥接端口是可选的。如果 MONITOR_PORT 为 0 或未设置，桥接服务不会启动，Monitor 的心跳上报功能完全不受影响。即使桥接服务启动失败，心跳上报也会继续正常工作。

环境变量：

• MONITOR_PORT — 首选
• HF_MONITOR_PORT — 备选

本地开发

go mod tidy
go build ./cmd/harborforge-monitor
./harborforge-monitor -config ./config.example.json -dry-run -once

Docker 运行

构建镜像：

docker build -t harborforge-monitor .

使用 Docker Compose

# 设置环境变量
export HF_IDENTIFIER=my-server
export HF_API_KEY=your-api-key
export MONITOR_PORT=9100

# 启动
docker compose up -d

手动 Docker 运行

推荐以宿主机 rootfs 只读挂载方式运行，这样容器里采集到的是宿主机信息而不是容器自身：

docker run -d \
  --name harborforge-monitor \
  --restart unless-stopped \
  --network host \
  -v /:/host:ro \
  -e HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \
  -e HF_MONITER_IDENTIFIER=my-server \
  -e HF_MONITER_API_KEY=your-api-key \
  -e HF_MONITER_ROOTFS=/host \
  -e MONITOR_PORT=9100 \
  harborforge-monitor

systemd

也可以直接用 systemd 运行编译好的二进制：

# 编译
go build -o /usr/local/bin/harborforge-monitor ./cmd/harborforge-monitor

# 复制 systemd unit (见 systemd/ 目录)
cp systemd/harborforge-monitor.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now harborforge-monitor