From ccfa49bc7daff0242f328af2e52495d6abd98b4b Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 15:25:02 +0000 Subject: [PATCH 1/3] feat: add MONITOR_PORT env var and monitorPort config field - Added MonitorPort field to Config struct (TODO 5.1) - Config loads from MONITOR_PORT or HF_MONITOR_PORT env vars - Added to Dockerfile env defaults - Updated config.example.json - Merge function handles monitorPort from file config Prepares Monitor for local plugin communication bridge (TODO 5.1, 5.2) --- Dockerfile | 3 ++- config.example.json | 3 ++- internal/config/config.go | 5 +++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 6184884..a841207 100644 --- a/Dockerfile +++ b/Dockerfile @@ -15,6 +15,7 @@ ENV HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \ HF_MONITER_API_KEY= \ HF_MONITER_REPORT_INTERVAL=30 \ HF_MONITER_LOG_LEVEL=info \ - HF_MONITER_ROOTFS=/host + HF_MONITER_ROOTFS=/host \ + MONITOR_PORT=0 ENTRYPOINT ["/usr/local/bin/harborforge-monitor"] diff --git a/config.example.json b/config.example.json index 49f1e22..9f32745 100644 --- a/config.example.json +++ b/config.example.json @@ -4,5 +4,6 @@ "apiKey": "replace-with-server-api-key", "reportIntervalSec": 30, "logLevel": "info", - "rootFs": "/host" + "rootFs": "/host", + "monitorPort": 0 } diff --git a/internal/config/config.go b/internal/config/config.go index ee3471c..d4e83f0 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -14,6 +14,7 @@ type Config struct { ReportIntervalSec int `json:"reportIntervalSec"` LogLevel string `json:"logLevel"` RootFS string `json:"rootFs"` + MonitorPort int `json:"monitorPort"` } func Load(path string) (Config, error) { @@ -43,6 +44,7 @@ func Load(path string) (Config, error) { cfg.ReportIntervalSec = getenvIntAny([]string{"HF_MONITER_REPORT_INTERVAL", "HF_MONITOR_REPORT_INTERVAL"}, cfg.ReportIntervalSec) cfg.LogLevel = getenvAny([]string{"HF_MONITER_LOG_LEVEL", "HF_MONITOR_LOG_LEVEL"}, cfg.LogLevel) cfg.RootFS = getenvAny([]string{"HF_MONITER_ROOTFS", "HF_MONITOR_ROOTFS"}, cfg.RootFS) + cfg.MonitorPort = getenvIntAny([]string{"MONITOR_PORT", "HF_MONITOR_PORT"}, cfg.MonitorPort) if cfg.BackendURL == "" { return cfg, fmt.Errorf("backendUrl is required") @@ -88,6 +90,9 @@ func merge(dst *Config, src Config) { if src.RootFS != "" { dst.RootFS = src.RootFS } + if src.MonitorPort > 0 { + dst.MonitorPort = src.MonitorPort + } } func getenvAny(keys []string, fallback string) string { From 360743ba6bcbef6cfb7a70d1b4aab8b7c107ebe8 Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 16:06:42 +0000 Subject: [PATCH 2/3] Add local monitor bridge service --- README.md | 71 ++++++++++++----- cmd/harborforge-monitor/main.go | 20 +++++ config.example.json | 2 +- docker-compose.yml | 22 ++++++ internal/bridge/bridge.go | 130 ++++++++++++++++++++++++++++++++ 5 files changed, 225 insertions(+), 20 deletions(-) create mode 100644 docker-compose.yml create mode 100644 internal/bridge/bridge.go diff --git a/README.md b/README.md index 8cc075e..cc9b218 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,9 @@ HarborForge.Monitor/ ├── cmd/harborforge-monitor/ # 程序入口 ├── internal/config/ # 配置加载 ├── internal/telemetry/ # 指标采集与上报 +├── internal/bridge/ # MONITOR_PORT 本地桥接服务 ├── Dockerfile # 容器化运行 +├── docker-compose.yml # Docker Compose 配置 ├── config.example.json └── README.md ``` @@ -46,7 +48,8 @@ HarborForge.Monitor/ "identifier": "vps-nginx-01", "apiKey": "your-api-key", "reportIntervalSec": 30, - "logLevel": "info" + "logLevel": "info", + "monitorPort": 9100 } ``` @@ -61,6 +64,24 @@ HarborForge.Monitor/ 同时也兼容旧的/正确拼写的 `HF_MONITOR_*` 变量名。 +### MONITOR_PORT — 插件桥接端口 + +当 `MONITOR_PORT` (或 `monitorPort`) 设置为大于 0 的值时，Monitor 会在 `127.0.0.1:` 上启动一个本地 HTTP 服务，供 HarborForge OpenClaw 插件查询遥测数据。 + +支持的端点： + +| 端点 | 说明 | +|------|------| +| `GET /health` | 健康检查，返回 Monitor 版本和标识符 | +| `GET /telemetry` | 返回最新的遥测数据快照 | + +**重要**：桥接端口是可选的。如果 `MONITOR_PORT` 为 0 或未设置，桥接服务不会启动，Monitor 的心跳上报功能完全不受影响。即使桥接服务启动失败，心跳上报也会继续正常工作。 + +环境变量： + +- `MONITOR_PORT` — 首选 +- `HF_MONITOR_PORT` — 备选 + ## 本地开发 ```bash @@ -77,34 +98,46 @@ go build ./cmd/harborforge-monitor docker build -t harborforge-monitor . ``` +### 使用 Docker Compose + +```bash +# 设置环境变量 +export HF_IDENTIFIER=my-server +export HF_API_KEY=your-api-key +export MONITOR_PORT=9100 + +# 启动 +docker compose up -d +``` + +### 手动 Docker 运行 + 推荐以**宿主机 rootfs 只读挂载**方式运行，这样容器里采集到的是宿主机信息而不是容器自身： ```bash docker run -d \ --name harborforge-monitor \ --restart unless-stopped \ - -e HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \ - -e HF_MONITER_IDENTIFIER=vps-nginx-01 \ - -e HF_MONITER_API_KEY=your-api-key \ - -e HF_MONITER_REPORT_INTERVAL=30 \ - -e HF_MONITER_ROOTFS=/host \ + --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 ``` -`Dockerfile` 里已经预置了这些环境变量： +## systemd -- `HF_MONITER_BACKEND_URL` -- `HF_MONITER_IDENTIFIER` -- `HF_MONITER_API_KEY` -- `HF_MONITER_REPORT_INTERVAL` -- `HF_MONITER_LOG_LEVEL` -- `HF_MONITER_ROOTFS` +也可以直接用 systemd 运行编译好的二进制： -## 注意 +```bash +# 编译 +go build -o /usr/local/bin/harborforge-monitor ./cmd/harborforge-monitor -- Docker 模式下，建议挂载 `-v /:/host:ro` 并设置 `HF_MONITER_ROOTFS=/host` -- 这样 CPU/MEM/LOAD/UPTIME 会通过 host proc/sys 视角采集，磁盘和 nginx 配置也会走宿主机路径 -- 当前 Nginx site 列表读取的是 `${ROOTFS}/etc/nginx/sites-enabled` -- 如果机器没有安装 Nginx，会回报 `nginx_installed = false` -- 该客户端不会尝试读取 OpenClaw 信息，`agents` 默认为空，`openclaw_version` 不上报 +# 复制 systemd unit (见 systemd/ 目录) +cp systemd/harborforge-monitor.service /etc/systemd/system/ +systemctl daemon-reload +systemctl enable --now harborforge-monitor +``` diff --git a/cmd/harborforge-monitor/main.go b/cmd/harborforge-monitor/main.go index 90d5259..422168f 100644 --- a/cmd/harborforge-monitor/main.go +++ b/cmd/harborforge-monitor/main.go @@ -12,6 +12,7 @@ import ( "syscall" "time" + "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/bridge" "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/config" "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/telemetry" ) @@ -50,11 +51,30 @@ func main() { ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) defer stop() + // Start the bridge server if MONITOR_PORT is configured. + // The bridge is independent of heartbeat — if it fails to start, + // heartbeat continues normally. + var bridgeSrv *bridge.Server + if cfg.MonitorPort > 0 { + bridgeSrv = bridge.New(cfg, logger) + go func() { + if err := bridgeSrv.Start(ctx); err != nil { + logger.Printf("bridge error (non-fatal): %v", err) + } + }() + } + sendOnce := func() error { payload, err := telemetry.BuildPayload(ctx, cfg) if err != nil { return err } + + // Update bridge with latest telemetry + if bridgeSrv != nil { + bridgeSrv.UpdatePayload(payload) + } + if printPayload || dryRun { buf, _ := json.MarshalIndent(payload, "", " ") fmt.Println(string(buf)) diff --git a/config.example.json b/config.example.json index 9f32745..b91ada0 100644 --- a/config.example.json +++ b/config.example.json @@ -5,5 +5,5 @@ "reportIntervalSec": 30, "logLevel": "info", "rootFs": "/host", - "monitorPort": 0 + "monitorPort": 9100 } diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..b20e900 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,22 @@ +version: "3.8" + +services: + harborforge-monitor: + build: . + container_name: harborforge-monitor + restart: unless-stopped + environment: + - HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top + - HF_MONITER_IDENTIFIER=${HF_IDENTIFIER:-} + - HF_MONITER_API_KEY=${HF_API_KEY:-} + - HF_MONITER_REPORT_INTERVAL=${HF_REPORT_INTERVAL:-30} + - HF_MONITER_LOG_LEVEL=${HF_LOG_LEVEL:-info} + - HF_MONITER_ROOTFS=/host + - MONITOR_PORT=${MONITOR_PORT:-0} + volumes: + - /:/host:ro + ports: + # Expose MONITOR_PORT on 127.0.0.1 only for plugin communication. + # Only active when MONITOR_PORT > 0. + - "127.0.0.1:${MONITOR_PORT:-9100}:${MONITOR_PORT:-9100}" + network_mode: host diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go new file mode 100644 index 0000000..67ca7a6 --- /dev/null +++ b/internal/bridge/bridge.go @@ -0,0 +1,130 @@ +// Package bridge provides a local HTTP server on MONITOR_PORT for +// communication between the HarborForge OpenClaw plugin and Monitor. +// +// The plugin queries this endpoint to enrich its telemetry with +// host/hardware data. The bridge is optional: if monitorPort is 0 +// or not set, the bridge is not started and Monitor operates normally. +package bridge + +import ( + "context" + "encoding/json" + "fmt" + "log" + "net" + "net/http" + "sync" + "time" + + "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/config" + "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/telemetry" +) + +// Server is the local bridge HTTP server. +type Server struct { + cfg config.Config + logger *log.Logger + srv *http.Server + + mu sync.RWMutex + lastPayload *telemetry.Payload + lastUpdated time.Time +} + +// New creates a bridge server. It does not start listening. +func New(cfg config.Config, logger *log.Logger) *Server { + return &Server{ + cfg: cfg, + logger: logger, + } +} + +// UpdatePayload stores the latest telemetry payload so the bridge can +// serve it to plugin queries without re-collecting. +func (s *Server) UpdatePayload(p telemetry.Payload) { + s.mu.Lock() + defer s.mu.Unlock() + s.lastPayload = &p + s.lastUpdated = time.Now() +} + +// bridgeResponse is the JSON structure served to the plugin. +type bridgeResponse struct { + Status string `json:"status"` + MonitorVer string `json:"monitor_version"` + Identifier string `json:"identifier"` + Telemetry *telemetry.Payload `json:"telemetry,omitempty"` + LastUpdated *time.Time `json:"last_updated,omitempty"` +} + +func (s *Server) handler() http.Handler { + mux := http.NewServeMux() + + // Health / discovery endpoint + mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(map[string]string{ + "status": "ok", + "monitor_version": telemetry.Version, + "identifier": s.cfg.Identifier, + }) + }) + + // Telemetry endpoint — returns the latest cached payload + mux.HandleFunc("/telemetry", func(w http.ResponseWriter, r *http.Request) { + s.mu.RLock() + payload := s.lastPayload + updated := s.lastUpdated + s.mu.RUnlock() + + resp := bridgeResponse{ + Status: "ok", + MonitorVer: telemetry.Version, + Identifier: s.cfg.Identifier, + } + if payload != nil { + resp.Telemetry = payload + resp.LastUpdated = &updated + } + + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(resp) + }) + + return mux +} + +// Start begins listening on 127.0.0.1:. It blocks until +// the context is cancelled or an error occurs. +func (s *Server) Start(ctx context.Context) error { + if s.cfg.MonitorPort <= 0 { + return nil // bridge disabled + } + + addr := fmt.Sprintf("127.0.0.1:%d", s.cfg.MonitorPort) + listener, err := net.Listen("tcp", addr) + if err != nil { + return fmt.Errorf("bridge listen on %s: %w", addr, err) + } + + s.srv = &http.Server{ + Handler: s.handler(), + ReadTimeout: 5 * time.Second, + WriteTimeout: 5 * time.Second, + IdleTimeout: 30 * time.Second, + } + + s.logger.Printf("bridge listening on %s", addr) + + go func() { + <-ctx.Done() + shutCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + s.srv.Shutdown(shutCtx) + }() + + if err := s.srv.Serve(listener); err != nil && err != http.ErrServerClosed { + return fmt.Errorf("bridge serve: %w", err) + } + return nil +} From dc05fa01d11a9b13d537bf0361dac1e56b6b7f87 Mon Sep 17 00:00:00 2001 From: zhi Date: Sun, 22 Mar 2026 01:37:15 +0000 Subject: [PATCH 3/3] feat: add POST /openclaw endpoint and enrich heartbeats with OpenClaw metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Bridge server now accepts POST /openclaw from OpenClaw plugin - OpenClawMeta struct stores version, plugin_version, and agents - Heartbeat sendOnce() enriches payload with plugin metadata when available - Telemetry Payload adds optional openclaw_version field - README updated to document /openclaw endpoint and metadata enrichment - All communication remains optional — Monitor functions without plugin data --- README.md | 11 ++++++ cmd/harborforge-monitor/main.go | 13 +++++++ internal/bridge/bridge.go | 63 +++++++++++++++++++++++++++++++-- internal/telemetry/telemetry.go | 4 +++ 4 files changed, 88 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cc9b218..5bc4eb3 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,17 @@ HarborForge.Monitor/ |------|------| | `GET /health` | 健康检查，返回 Monitor 版本和标识符 | | `GET /telemetry` | 返回最新的遥测数据快照 | +| `POST /openclaw` | 接收 OpenClaw 插件推送的元数据（版本、代理等） | + +### OpenClaw 元数据 enrichment + +当 OpenClaw 插件通过 `POST /openclaw` 推送元数据后，Monitor 会在后续的心跳上报中自动将这些信息附加到遥测数据中： + +- `openclaw_version` — OpenClaw 运行时版本 +- `plugin_version` — 插件版本 +- `agents` — 代理列表 + +如果插件从未推送过元数据，这些字段会被省略，心跳上报完全不受影响。 **重要**：桥接端口是可选的。如果 `MONITOR_PORT` 为 0 或未设置，桥接服务不会启动，Monitor 的心跳上报功能完全不受影响。即使桥接服务启动失败，心跳上报也会继续正常工作。 diff --git a/cmd/harborforge-monitor/main.go b/cmd/harborforge-monitor/main.go index 422168f..9bb534d 100644 --- a/cmd/harborforge-monitor/main.go +++ b/cmd/harborforge-monitor/main.go @@ -73,6 +73,19 @@ func main() { // Update bridge with latest telemetry if bridgeSrv != nil { bridgeSrv.UpdatePayload(payload) + + // Enrich payload with OpenClaw metadata if available + if meta := bridgeSrv.GetOpenClawMeta(); meta != nil { + if meta.Version != "" { + payload.OpenClawVersion = meta.Version + } + if meta.PluginVersion != "" { + payload.PluginVersion = meta.PluginVersion + } + if len(meta.Agents) > 0 { + payload.Agents = meta.Agents + } + } } if printPayload || dryRun { diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go index 67ca7a6..cf86c98 100644 --- a/internal/bridge/bridge.go +++ b/internal/bridge/bridge.go @@ -1,15 +1,19 @@ // Package bridge provides a local HTTP server on MONITOR_PORT for // communication between the HarborForge OpenClaw plugin and Monitor. // -// The plugin queries this endpoint to enrich its telemetry with -// host/hardware data. The bridge is optional: if monitorPort is 0 -// or not set, the bridge is not started and Monitor operates normally. +// The bridge serves two purposes: +// 1. Expose hardware telemetry to the plugin via GET /telemetry +// 2. Receive OpenClaw metadata from the plugin via POST /openclaw +// +// The bridge is optional: if monitorPort is 0 or not set, the bridge +// is not started and Monitor operates normally. package bridge import ( "context" "encoding/json" "fmt" + "io" "log" "net" "net/http" @@ -20,6 +24,14 @@ import ( "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/telemetry" ) +// OpenClawMeta holds metadata received from the OpenClaw plugin. +// This data is optional enrichment for heartbeat uploads. +type OpenClawMeta struct { + Version string `json:"version"` + PluginVersion string `json:"plugin_version"` + Agents []any `json:"agents,omitempty"` +} + // Server is the local bridge HTTP server. type Server struct { cfg config.Config @@ -29,6 +41,9 @@ type Server struct { mu sync.RWMutex lastPayload *telemetry.Payload lastUpdated time.Time + + openclawMeta *OpenClawMeta + openclawUpdated time.Time } // New creates a bridge server. It does not start listening. @@ -57,6 +72,14 @@ type bridgeResponse struct { LastUpdated *time.Time `json:"last_updated,omitempty"` } +// GetOpenClawMeta returns the latest OpenClaw metadata received from +// the plugin, or nil if no metadata has been received. +func (s *Server) GetOpenClawMeta() *OpenClawMeta { + s.mu.RLock() + defer s.mu.RUnlock() + return s.openclawMeta +} + func (s *Server) handler() http.Handler { mux := http.NewServeMux() @@ -91,6 +114,40 @@ func (s *Server) handler() http.Handler { json.NewEncoder(w).Encode(resp) }) + // OpenClaw metadata endpoint — plugin POSTs its metadata here + mux.HandleFunc("/openclaw", func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost { + http.Error(w, "method not allowed", http.StatusMethodNotAllowed) + return + } + + body, err := io.ReadAll(io.LimitReader(r.Body, 64*1024)) + if err != nil { + http.Error(w, "read error", http.StatusBadRequest) + return + } + defer r.Body.Close() + + var meta OpenClawMeta + if err := json.Unmarshal(body, &meta); err != nil { + http.Error(w, "invalid json", http.StatusBadRequest) + return + } + + s.mu.Lock() + s.openclawMeta = &meta + s.openclawUpdated = time.Now() + s.mu.Unlock() + + s.logger.Printf("received OpenClaw metadata: version=%s plugin=%s agents=%d", + meta.Version, meta.PluginVersion, len(meta.Agents)) + + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(map[string]string{ + "status": "ok", + }) + }) + return mux } diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.go index f9c2a87..6c906b9 100644 --- a/internal/telemetry/telemetry.go +++ b/internal/telemetry/telemetry.go @@ -35,6 +35,10 @@ type Payload struct { SwapPct float64 `json:"swap_pct,omitempty"` LoadAvg []float64 `json:"load_avg,omitempty"` UptimeSeconds uint64 `json:"uptime_seconds,omitempty"` + + // Optional OpenClaw metadata, enriched from plugin bridge. + // These fields are omitted if no plugin data is available. + OpenClawVersion string `json:"openclaw_version,omitempty"` } func BuildPayload(ctx context.Context, cfg config.Config) (Payload, error) {