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/README.md b/README.md index 8cc075e..5bc4eb3 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,35 @@ HarborForge.Monitor/ 同时也兼容旧的/正确拼写的 `HF_MONITOR_*` 变量名。 +### MONITOR_PORT — 插件桥接端口 + +当 `MONITOR_PORT` (或 `monitorPort`) 设置为大于 0 的值时,Monitor 会在 `127.0.0.1:` 上启动一个本地 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` — 备选 + ## 本地开发 ```bash @@ -77,34 +109,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..9bb534d 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,43 @@ 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) + + // 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 { buf, _ := json.MarshalIndent(payload, "", " ") fmt.Println(string(buf)) diff --git a/config.example.json b/config.example.json index 49f1e22..b91ada0 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": 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..cf86c98 --- /dev/null +++ b/internal/bridge/bridge.go @@ -0,0 +1,187 @@ +// Package bridge provides a local HTTP server on MONITOR_PORT for +// communication between the HarborForge OpenClaw plugin and Monitor. +// +// 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" + "sync" + "time" + + "git.hangman-lab.top/zhi/HarborForge.Monitor/internal/config" + "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 + logger *log.Logger + srv *http.Server + + mu sync.RWMutex + lastPayload *telemetry.Payload + lastUpdated time.Time + + openclawMeta *OpenClawMeta + openclawUpdated 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"` +} + +// 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() + + // 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) + }) + + // 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 +} + +// 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 +} 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 { 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) {