Merge docs/readme-refresh into main

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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:<MONITOR_PORT>` (default port `9100`) for the HarborForge OpenClaw plugin.
 
-- CPU 使用率
+## Collected Metrics
-- 内存使用率
-- 磁盘使用率
-- Swap 使用率
-- Load Average
-- Uptime
-- Nginx 是否安装
-- `/etc/nginx/sites-enabled` 列表
 
-## 上报接口
+- 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`
+## Reporting Endpoint
-- Header: `X-API-Key`
 
-## 项目结构
+The client sends:
+
+- `POST <backendUrl>/monitor/server/heartbeat`
+- Header: `X-API-Key: <apiKey>`
+- JSON body: the telemetry payload described above
+
+## Project Structure
 
 ```text
 HarborForge.Monitor/
-├── cmd/harborforge-monitor/      # 程序入口
+├── cmd/harborforge-monitor/      # Program entry point (main.go)
-├── internal/config/              # 配置加载
+├── internal/config/              # Config loading (file + env + flags)
-├── internal/telemetry/           # 指标采集与上报
+├── internal/telemetry/           # Metric collection and reporting
-├── internal/bridge/              # MONITOR_PORT 本地桥接服务
+├── internal/bridge/              # Local MONITOR_PORT bridge server
-├── Dockerfile                    # 容器化运行
+├── systemd/                      # systemd unit file
-├── docker-compose.yml            # Docker Compose 配置
+├── 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`
+### Environment Variables
-- `HF_MONITER_IDENTIFIER`
-- `HF_MONITER_API_KEY`
-- `HF_MONITER_REPORT_INTERVAL`
-- `HF_MONITER_LOG_LEVEL`
-- `HF_MONITER_ROOTFS`
 
-同时也兼容旧的/正确拼写的 `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:<MONITOR_PORT>` 上启动一个本地 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
 
-| 端点 | 说明 |
+```text
-|------|------|
+-config string          Path to config file (default "/etc/harborforge-monitor/config.json")
-| `GET /health` | 健康检查，返回 Monitor 版本和标识符 |
+-once                   Collect and send telemetry once, then exit
-| `GET /telemetry` | 返回最新的遥测数据快照 |
+-print-payload          Print the payload JSON before sending
-| `POST /openclaw` | 接收 OpenClaw 插件推送的元数据（版本、代理等） |
+-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:<MONITOR_PORT>` for the HarborForge OpenClaw plugin to query telemetry.
 
-- `openclaw_version` — OpenClaw 运行时版本
+| Endpoint | Method | Description |
-- `plugin_version` — 插件版本
+|----------|--------|-------------|
-- `agents` — 代理列表
+| `/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).
 
-环境变量：
+## Local Development
-
-- `MONITOR_PORT` — 首选
-- `HF_MONITOR_PORT` — 备选
-
-## 本地开发
 
 ```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`.