From e5df1eba0d2b809cf6f4a787189f6b7781d3d494 Mon Sep 17 00:00:00 2001 From: hzhang Date: Sat, 16 May 2026 17:50:01 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20refresh=20README=20=E2=80=94=20accuracy?= =?UTF-8?q?=20pass=20+=20HarborForge=20platform=20context?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against current code; fixed stale/inaccurate sections and documented previously-undocumented features/flags/endpoints. Added a "Part of the HarborForge platform" reference and role/port. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 146 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 82 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 7e9e9d7..b48178d 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,54 @@ # HarborForge.Monitor -轻量级 Go 遥测客户端，用于把服务器硬件状态上报到 HarborForge Monitor。 +Lightweight Go telemetry client that reports server hardware status to the HarborForge backend. -它**不依赖 OpenClaw**，适合普通 Linux 主机、VPS、Nginx 机器等。 +Part of the [HarborForge](../README.md) platform. -## 采集内容 +- Role: standalone telemetry agent; **does not depend on OpenClaw**, suitable for plain Linux hosts, VPS, Nginx boxes, etc. +- Reports to the HarborForge backend (`POST /monitor/server/heartbeat`). +- Optional local bridge HTTP server on `127.0.0.1:` (default port `9100`) for the HarborForge OpenClaw plugin. -- CPU 使用率 -- 内存使用率 -- 磁盘使用率 -- Swap 使用率 -- Load Average -- Uptime -- Nginx 是否安装 -- `/etc/nginx/sites-enabled` 列表 +## Collected Metrics -## 上报接口 +- CPU usage (`cpu_pct`) +- Memory usage (`mem_pct`) +- Disk usage (`disk_pct`, for the root / `rootFs` filesystem) +- Swap usage (`swap_pct`) +- Load average (`load_avg` — 1/5/15 min) +- Uptime (`uptime_seconds`) +- Nginx installed (`nginx_installed`) +- `/etc/nginx/sites-enabled` listing (`nginx_sites`) -客户端调用： +When OpenClaw metadata has been pushed to the bridge, heartbeats are additionally enriched with `openclaw_version`, `plugin_version`, and `agents`. -- `POST /monitor/server/heartbeat` -- Header: `X-API-Key` +## Reporting Endpoint -## 项目结构 +The client sends: + +- `POST /monitor/server/heartbeat` +- Header: `X-API-Key: ` +- JSON body: the telemetry payload described above + +## Project Structure ```text HarborForge.Monitor/ -├── cmd/harborforge-monitor/ # 程序入口 -├── internal/config/ # 配置加载 -├── internal/telemetry/ # 指标采集与上报 -├── internal/bridge/ # MONITOR_PORT 本地桥接服务 -├── Dockerfile # 容器化运行 -├── docker-compose.yml # Docker Compose 配置 +├── cmd/harborforge-monitor/ # Program entry point (main.go) +├── internal/config/ # Config loading (file + env + flags) +├── internal/telemetry/ # Metric collection and reporting +├── internal/bridge/ # Local MONITOR_PORT bridge server +├── systemd/ # systemd unit file +├── Dockerfile # Container build +├── docker-compose.yml # Docker Compose configuration ├── config.example.json └── README.md ``` -## 配置 +## Configuration -先在 HarborForge Monitor 中注册服务器并生成 API Key。 +First register the server in the HarborForge backend and generate an API Key. -然后准备配置文件，例如 `/etc/harborforge-monitor/config.json`: +Then prepare a config file, e.g. `/etc/harborforge-monitor/config.json`: ```json { @@ -49,51 +57,61 @@ HarborForge.Monitor/ "apiKey": "your-api-key", "reportIntervalSec": 30, "logLevel": "info", + "rootFs": "/host", "monitorPort": 9100 } ``` -也支持环境变量覆盖。为了兼容你的命名，这里优先支持： +Resolution order is: defaults → config file → environment variables → command-line flags (later wins). `apiKey` is required; the process exits if it is empty. -- `HF_MONITER_BACKEND_URL` -- `HF_MONITER_IDENTIFIER` -- `HF_MONITER_API_KEY` -- `HF_MONITER_REPORT_INTERVAL` -- `HF_MONITER_LOG_LEVEL` -- `HF_MONITER_ROOTFS` +### Environment Variables -同时也兼容旧的/正确拼写的 `HF_MONITOR_*` 变量名。 +Both the (intentionally compatible) `HF_MONITER_*` spelling and the `HF_MONITOR_*` spelling are accepted; `HF_MONITER_*` is checked first. -### MONITOR_PORT — 插件桥接端口 +| Variable | Purpose | Default | +|----------|---------|---------| +| `HF_MONITER_BACKEND_URL` / `HF_MONITOR_BACKEND_URL` | Backend base URL | `https://monitor.hangman-lab.top` | +| `HF_MONITER_IDENTIFIER` / `HF_MONITOR_IDENTIFIER` | Server identifier | hostname | +| `HF_MONITER_API_KEY` / `HF_MONITOR_API_KEY` | Server API key | (required) | +| `HF_MONITER_REPORT_INTERVAL` / `HF_MONITOR_REPORT_INTERVAL` | Report interval (seconds) | `30` | +| `HF_MONITER_LOG_LEVEL` / `HF_MONITOR_LOG_LEVEL` | Log level | `info` | +| `HF_MONITER_ROOTFS` / `HF_MONITOR_ROOTFS` | Host root filesystem mount (for container use) | (empty) | +| `MONITOR_PORT` / `HF_MONITOR_PORT` | Local bridge port (`0` = disabled) | `0` | -当 `MONITOR_PORT` 设置为大于 0 的值时，Monitor 会在 `127.0.0.1:` 上启动一个本地 HTTP 服务，供 HarborForge OpenClaw 插件查询遥测数据。 +When `rootFs` is set, `HOST_PROC` / `HOST_SYS` / `HOST_ETC` / `HOST_VAR` / `HOST_RUN` are derived from it (if not already set) so that gopsutil reads host metrics instead of the container's. -支持的端点： +### Command-line Flags -| 端点 | 说明 | -|------|------| -| `GET /health` | 健康检查，返回 Monitor 版本和标识符 | -| `GET /telemetry` | 返回最新的遥测数据快照 | -| `POST /openclaw` | 接收 OpenClaw 插件推送的元数据（版本、代理等） | +```text +-config string Path to config file (default "/etc/harborforge-monitor/config.json") +-once Collect and send telemetry once, then exit +-print-payload Print the payload JSON before sending +-dry-run Collect telemetry but do not send it +-version Print version and exit +-backend-url string Override backend URL +-identifier string Override identifier +-api-key string Override API key +-report-interval int Override report interval in seconds +-log-level string Override log level +-rootfs string Override root filesystem path +-monitor-port int Override monitor bridge port +``` -### OpenClaw 元数据 enrichment +### MONITOR_PORT — Plugin Bridge -当 OpenClaw 插件通过 `POST /openclaw` 推送元数据后，Monitor 会在后续的心跳上报中自动将这些信息附加到遥测数据中： +When `MONITOR_PORT` (or `monitorPort`) is greater than 0, Monitor starts a local HTTP server on `127.0.0.1:` for the HarborForge OpenClaw plugin to query telemetry. -- `openclaw_version` — OpenClaw 运行时版本 -- `plugin_version` — 插件版本 -- `agents` — 代理列表 +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/health` | `GET` | Health check; returns status, `monitor_version`, and `identifier` | +| `/telemetry` | `GET` | Returns the latest cached telemetry snapshot | +| `/openclaw` | `POST` | Receives OpenClaw metadata (version, plugin version, agents) from the plugin | -如果插件从未推送过元数据，这些字段会被省略，心跳上报完全不受影响。 +After the plugin pushes metadata via `POST /openclaw`, Monitor attaches `openclaw_version`, `plugin_version`, and `agents` to subsequent heartbeats. If the plugin never pushes metadata, these fields are omitted and heartbeats are unaffected. -**重要**：桥接端口是可选的。如果 `MONITOR_PORT` 为 0 或未设置，桥接服务不会启动，Monitor 的心跳上报功能完全不受影响。即使桥接服务启动失败，心跳上报也会继续正常工作。 +**Important:** the bridge is optional. If `MONITOR_PORT` is 0 or unset, the bridge does not start. Even if the bridge fails to start, heartbeat reporting continues normally (bridge errors are logged as non-fatal). -环境变量： - -- `MONITOR_PORT` — 首选 -- `HF_MONITOR_PORT` — 备选 - -## 本地开发 +## Local Development ```bash go mod tidy @@ -101,29 +119,29 @@ go build ./cmd/harborforge-monitor ./harborforge-monitor -config ./config.example.json -dry-run -once ``` -## Docker 运行 +## Docker -构建镜像： +Build the image: ```bash docker build -t harborforge-monitor . ``` -### 使用 Docker Compose +### Docker Compose ```bash -# 设置环境变量 export HF_IDENTIFIER=my-server export HF_API_KEY=your-api-key export MONITOR_PORT=9100 -# 启动 docker compose up -d ``` -### 手动 Docker 运行 +The compose file runs with `network_mode: host` and mounts the host root filesystem read-only at `/host` (the image defaults `HF_MONITER_ROOTFS=/host`). -推荐以**宿主机 rootfs 只读挂载**方式运行，这样容器里采集到的是宿主机信息而不是容器自身： +### Manual Docker Run + +Run with the **host rootfs mounted read-only** so the container collects host metrics instead of its own: ```bash docker run -d \ @@ -141,14 +159,14 @@ docker run -d \ ## systemd -也可以直接用 systemd 运行编译好的二进制： +You can also run the compiled binary via systemd: ```bash -# 编译 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 ``` + +The provided unit runs `harborforge-monitor -config /etc/harborforge-monitor/config.json` as `root` with `Restart=always`.