# HarborForge.Monitor

轻量级 Go 遥测客户端，用于把服务器硬件状态上报到 HarborForge Monitor。

它**不依赖 OpenClaw**，适合普通 Linux 主机、VPS、Nginx 机器等。

## 采集内容

- CPU 使用率
- 内存使用率
- 磁盘使用率
- Swap 使用率
- Load Average
- Uptime
- Nginx 是否安装
- `/etc/nginx/sites-enabled` 列表

## 上报接口

客户端调用：

- `POST /monitor/server/heartbeat-v2`
- Header: `X-API-Key`

## 项目结构

```text
HarborForge.Monitor/
├── cmd/harborforge-monitor/      # 程序入口
├── internal/config/              # 配置加载
├── internal/telemetry/           # 指标采集与上报
├── internal/bridge/              # MONITOR_PORT 本地桥接服务
├── Dockerfile                    # 容器化运行
├── docker-compose.yml            # Docker Compose 配置
├── config.example.json
└── README.md
```

## 配置

先在 HarborForge Monitor 中注册服务器并生成 API Key。

然后准备配置文件，例如 `/etc/harborforge-monitor/config.json`:

```json
{
  "backendUrl": "https://monitor.hangman-lab.top",
  "identifier": "vps-nginx-01",
  "apiKey": "your-api-key",
  "reportIntervalSec": 30,
  "logLevel": "info",
  "monitorPort": 9100
}
```

也支持环境变量覆盖。为了兼容你的命名，这里优先支持：

- `HF_MONITER_BACKEND_URL`
- `HF_MONITER_IDENTIFIER`
- `HF_MONITER_API_KEY`
- `HF_MONITER_REPORT_INTERVAL`
- `HF_MONITER_LOG_LEVEL`
- `HF_MONITER_ROOTFS`

同时也兼容旧的/正确拼写的 `HF_MONITOR_*` 变量名。

### MONITOR_PORT — 插件桥接端口

当 `MONITOR_PORT` (或 `monitorPort`) 设置为大于 0 的值时，Monitor 会在 `127.0.0.1:<MONITOR_PORT>` 上启动一个本地 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
go mod tidy
go build ./cmd/harborforge-monitor
./harborforge-monitor -config ./config.example.json -dry-run -once
```

## Docker 运行

构建镜像：

```bash
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 \
  --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
```

## systemd

也可以直接用 systemd 运行编译好的二进制：

```bash
# 编译
go build -o /usr/local/bin/harborforge-monitor ./cmd/harborforge-monitor

# 复制 systemd unit (见 systemd/ 目录)
cp systemd/harborforge-monitor.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now harborforge-monitor
```