Add local monitor bridge service

2026-03-21 16:07:00 +00:00
5 changed files with 225 additions and 20 deletions
--- 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:<MONITOR_PORT>` 上启动一个本地 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
+```
--- 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))
--- a/config.example.json
+++ b/config.example.json
@@ -5,5 +5,5 @@
  "reportIntervalSec": 30,
  "logLevel": "info",
  "rootFs": "/host",
-  "monitorPort": 0
+  "monitorPort": 9100
 }
--- a/docker-compose.yml
+++ 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
--- a/internal/bridge/bridge.go
+++ 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:<monitorPort>. 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
+}