feat: README + one-click install scripts for server and agent

2026-02-22 19:45:49 +08:00
parent b6ed6f8bba
commit a8c604f215
3 changed files with 214 additions and 30 deletions
--- a/README.md
+++ b/README.md
@@ -1,45 +1,100 @@
-# OpenClaw Monitor
+# 🐾 OC Monitor — OpenClaw Mission Control

-Multi-node monitoring dashboard for OpenClaw instances.
+Real-time monitoring dashboard for [OpenClaw](https://github.com/openclaw/openclaw) multi-node deployments.

-## Architecture
+![Dashboard](https://img.shields.io/badge/status-active-brightgreen) ![License](https://img.shields.io/badge/license-MIT-blue)

- **Server**: Node.js + SQLite + WebSocket (central dashboard)
- **Agent**: Bash script on each OpenClaw machine, reports heartbeat + metrics
+## ✨ Features

-## Quick Start
+- **Real-time metrics** — CPU / Memory / Disk / Swap with live jitter animation (10s refresh)
+- **Provider health checks** — Auto-detect all configured AI providers, latency monitoring
+- **Default model detection** — Auto-identifies most-used provider per node (green dot indicator)
+- **Request logging** — Track API calls across all nodes with filtering by node / provider / result
+- **Multi-node support** — Lightweight bash+python agent, works on macOS & Linux
+- **Dark / Light theme** — Toggle with localStorage persistence
+- **WebSocket push** — Instant updates, no polling
+- **Admin panel** — Node management, token display, one-click agent install command generator
+- **Docker deployment** — Single container, SQLite storage
+
+## 🚀 Quick Start
+
+### 1. Deploy Server (Docker)

-### Server (Docker)
 ```bash
-docker run -d --name oc-monitor -p 3800:3800 -v oc-monitor-data:/app/data ghcr.io/mango082888-bit/oc-monitor
-# Get auth token
-docker logs oc-monitor 2>&1 | grep "Auth token"
+curl -fsSL https://raw.githubusercontent.com/mango082888-bit/oc-monitor/main/install.sh | bash
 ```

-### Agent
+This will:
+- Pull the repo and build the Docker image
+- Generate a random auth token
+- Start the container on port **3800**
+- Print the dashboard URL and token
+
+### 2. Install Agent on Each Node
+
+After server is running, install the agent on each OpenClaw node:
+
 ```bash
-curl -sL https://raw.githubusercontent.com/mango082888-bit/oc-monitor/main/agent/agent.sh -o agent.sh
-chmod +x agent.sh
-./agent.sh -s http://YOUR_SERVER:3800 -t YOUR_TOKEN -n "My Node" -r master
+curl -fsSL https://raw.githubusercontent.com/mango082888-bit/oc-monitor/main/install-agent.sh | bash -s -- \
+  -s http://YOUR_SERVER_IP:3800 \
+  -t YOUR_AUTH_TOKEN \
+  -n "Node Name"
 ```

-## Features
+The agent auto-detects:
+- OpenClaw config, providers, and models
+- System metrics (CPU, memory, disk, swap)
+- Gateway & daemon status
+- Session count and token usage
+- Default/most-used provider

- Real-time node status (CPU/mem/disk/swap)
- Provider health matrix across all nodes
- API request logging with TTFT/latency tracking
- Auto-detect OpenClaw config changes
- WebSocket live updates
- Dark theme UI
+### 3. Open Dashboard

-## API
+Visit `http://YOUR_SERVER_IP:3800` in your browser.

-| Endpoint | Method | Auth | Description |
-|---|---|---|---|
-| `/api/dashboard` | GET | No | Full dashboard data |
-| `/api/heartbeat` | POST | Yes | Agent heartbeat report |
-| `/api/request` | POST | Yes | Log API request |
-| `/api/node/rename` | POST | Yes | Rename a node |
-| `/api/node/:id` | DELETE | Yes | Remove a node |
+## 📐 Architecture

-Auth: `Authorization: Bearer <token>`
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Node Agent  │     │  Node Agent  │     │  Node Agent  │
+│  (bash+py)   │     │  (bash+py)   │     │  (bash+py)   │
+└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
+       │ HTTP POST          │                     │
+       └────────────────────┼─────────────────────┘
+                            ▼
+                   ┌─────────────────┐
+                   │  OC Monitor     │
+                   │  Server         │
+                   │  (Node.js+SQLite│
+                   │   +WebSocket)   │
+                   └────────┬────────┘
+                            │ WS push
+                            ▼
+                   ┌─────────────────┐
+                   │  Browser        │
+                   │  Dashboard      │
+                   └─────────────────┘
+```
+
+## 🔧 Configuration
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3800` | Server listen port |
+| `AUTH_TOKEN` | (required) | Bearer token for API auth |
+
+## 📋 API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/dashboard` | Full dashboard data |
+| POST | `/api/heartbeat` | Agent heartbeat report |
+| POST | `/api/request` | API request log (single or batch) |
+| POST | `/api/rename` | Rename a node |
+| DELETE | `/api/node/:id` | Remove a node |
+
+All POST/DELETE endpoints require `Authorization: Bearer <token>` header.
+
+## License
+
+MIT
--- a/install-agent.sh
+++ b/install-agent.sh
@@ -0,0 +1,80 @@
+#!/bin/bash
+# OC Monitor - One-click agent install
+set -e
+
+SERVER="" TOKEN="" NAME="" ROLE="worker"
+while getopts "s:t:n:r:" opt; do
+  case $opt in s)SERVER="$OPTARG";;t)TOKEN="$OPTARG";;n)NAME="$OPTARG";;r)ROLE="$OPTARG";;esac
+done
+
+if [ -z "$SERVER" ] || [ -z "$TOKEN" ]; then
+  echo "Usage: $0 -s SERVER_URL -t AUTH_TOKEN [-n NAME] [-r ROLE]"
+  echo "  -s  Server URL (e.g. http://1.2.3.4:3800)"
+  echo "  -t  Auth token"
+  echo "  -n  Node name (default: hostname)"
+  echo "  -r  Role: master|worker (default: worker)"
+  exit 1
+fi
+
+[ -z "$NAME" ] && NAME=$(hostname)
+AGENT="/usr/local/bin/oc-monitor-agent.sh"
+
+echo "🐾 OC Monitor Agent Installer"
+echo "=============================="
+
+# Check deps
+for cmd in python3 curl; do
+  command -v $cmd &>/dev/null || { echo "❌ $cmd not found"; exit 1; }
+done
+
+# Download agent
+echo "📦 Downloading agent..."
+curl -fsSL https://raw.githubusercontent.com/mango082888-bit/oc-monitor/main/agent/agent.sh -o "$AGENT"
+chmod +x "$AGENT"
+
+# Detect init system
+if [ "$(uname)" = "Darwin" ]; then
+  PLIST="$HOME/Library/LaunchAgents/com.oc-monitor.agent.plist"
+  echo "🍎 Setting up launchd service..."
+  cat > "$PLIST" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>com.oc-monitor.agent</string>
+<key>ProgramArguments</key><array>
+<string>/bin/bash</string><string>$AGENT</string>
+<string>-s</string><string>$SERVER</string>
+<string>-t</string><string>$TOKEN</string>
+<string>-n</string><string>$NAME</string>
+<string>-r</string><string>$ROLE</string>
+</array>
+<key>RunAtLoad</key><true/>
+<key>KeepAlive</key><true/>
+<key>StandardOutPath</key><string>/tmp/oc-monitor-agent.log</string>
+<key>StandardErrorPath</key><string>/tmp/oc-monitor-agent.log</string>
+</dict></plist>
+EOF
+  launchctl unload "$PLIST" 2>/dev/null || true
+  launchctl load "$PLIST"
+  echo "✅ Agent running (launchd)"
+else
+  echo "🐧 Setting up systemd service..."
+  cat > /etc/systemd/system/oc-monitor-agent.service <<EOF
+[Unit]
+Description=OC Monitor Agent
+After=network.target
+[Service]
+ExecStart=/bin/bash $AGENT -s $SERVER -t $TOKEN -n $NAME -r $ROLE
+Restart=always
+RestartSec=5
+[Install]
+WantedBy=multi-user.target
+EOF
+  systemctl daemon-reload
+  systemctl enable --now oc-monitor-agent
+  echo "✅ Agent running (systemd)"
+fi
+
+echo ""
+echo "📡 Node '$NAME' reporting to $SERVER"
+echo "📋 Logs: journalctl -u oc-monitor-agent -f"
--- a/install.sh
+++ b/install.sh
@@ -0,0 +1,49 @@
+#!/bin/bash
+# OC Monitor - One-click server install
+set -e
+
+PORT=${PORT:-3800}
+TOKEN=${TOKEN:-$(head -c 16 /dev/urandom | xxd -p | tr '[:lower:]' '[:upper:]')}
+DIR="/opt/oc-monitor"
+
+echo "🐾 OC Monitor Installer"
+echo "========================"
+
+# Check docker
+if ! command -v docker &>/dev/null; then
+  echo "❌ Docker not found. Install docker first."
+  exit 1
+fi
+
+# Clone or update
+if [ -d "$DIR" ]; then
+  echo "📦 Updating existing installation..."
+  cd "$DIR" && git pull
+else
+  echo "📦 Cloning repository..."
+  git clone https://github.com/mango082888-bit/oc-monitor.git "$DIR"
+  cd "$DIR"
+fi
+
+# Build and run
+echo "🔨 Building Docker image..."
+docker build -t oc-monitor .
+
+docker rm -f oc-monitor 2>/dev/null || true
+echo "🚀 Starting container..."
+docker run -d --name oc-monitor --restart always \
+  -p "$PORT:3800" \
+  -v oc-monitor-data:/app/data \
+  -e "AUTH_TOKEN=$TOKEN" \
+  oc-monitor
+
+IP=$(hostname -I 2>/dev/null | awk '{print $1}' || curl -s ifconfig.me)
+
+echo ""
+echo "✅ OC Monitor is running!"
+echo "========================"
+echo "🌐 Dashboard: http://$IP:$PORT"
+echo "🔑 Auth Token: $TOKEN"
+echo ""
+echo "📡 Install agent on each node:"
+echo "  curl -fsSL https://raw.githubusercontent.com/mango082888-bit/oc-monitor/main/install-agent.sh | bash -s -- -s http://$IP:$PORT -t $TOKEN -n \"NodeName\""