zhi/HarborForge.Monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge dev-2026-03-21 into main #1

Merged
hzhang merged 3 commits from dev-2026-03-21 into main 2026-03-22 14:16:02 +00:00
Conversation 0 Commits 3 Files Changed 8 +225 -20
5 changed files with 225 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 360743ba6b - Show all commits

71
README.md
View File

@@ -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
```

20
cmd/harborforge-monitor/main.go
View File

@@ -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))

2
config.example.json
View File

@@ -5,5 +5,5 @@
"reportIntervalSec": 30,
"logLevel": "info",
"rootFs": "/host",
"monitorPort": 0
"monitorPort": 9100
}

22
docker-compose.yml Normal file
View File

@@ -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

130
internal/bridge/bridge.go Normal file
View File

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