155 lines
3.9 KiB
Markdown
155 lines
3.9 KiB
Markdown
# HarborForge.Monitor
|
||
|
||
轻量级 Go 遥测客户端，用于把服务器硬件状态上报到 HarborForge Monitor。
|
||
|
||
它**不依赖 OpenClaw**，适合普通 Linux 主机、VPS、Nginx 机器等。
|
||
|
||
## 采集内容
|
||
|
||
- CPU 使用率
|
||
- 内存使用率
|
||
- 磁盘使用率
|
||
- Swap 使用率
|
||
- Load Average
|
||
- Uptime
|
||
- Nginx 是否安装
|
||
- `/etc/nginx/sites-enabled` 列表
|
||
|
||
## 上报接口
|
||
|
||
客户端调用：
|
||
|
||
- `POST /monitor/server/heartbeat`
|
||
- 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` 设置为大于 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
|
||
```
|