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 +}