DOCSEARCHbyAlgolia
Submit Docs

ServerBee Documentation

website·Indexed 32 days ago

https://docs.serverbee.app

A lightweight, self-hosted VPS monitoring probe system built with a Rust backend and React frontend. ServerBee provides real-time server monitoring via WebSocket streaming, a built-in web terminal, remote file management, and a native iOS companion app. It features a flexible alerting system, synthetic service monitors, and public status pages, with a lightweight agent for collecting system metrics like CPU, memory, and disk I/O.

Tokens
60.3K
Snippets
297
Records
432
Agent score
64%

What's inside ServerBee

  1. Overview of ServerBee Service Monitors

    Service Monitors are synthetic checks executed by the central ServerBee server process. Unlike Ping monitors (which are initiated by Agents), Service Monitors are ideal for monitoring public services that may not have a ServerBee Agent installed. Results are stored in SQLite, displayed on the dashboard, and can trigger alerts via notification groups.

  2. Overview of ServerBee VPS Monitoring System

    ServerBee is a lightweight, self-hosted VPS monitoring probe system designed for resource efficiency on small VPS instances. It uses a hub-and-spoke architecture consisting of a central Server (dashboard, API, and job manager) and multiple Agents installed on target VPS instances to collect and report system metrics via WebSockets.

    Key capabilities include:

    • Real-time Monitoring: CPU, memory, disk, network, load average, temperature, GPU, and disk I/O.
    • Service Monitoring: SSL certificates, DNS, HTTP keywords, TCP, and WHOIS checks.
    • Remote Management: Browser-based PTY terminal sessions, scheduled cron tasks, and a sandboxed file manager.
    • Network Analysis: ICMP, TCP, and HTTP probes with packet loss/latency charts and traceroute.
    • Docker Management: Container stats, logs, events, and lifecycle actions.
    • Public Status Pages: Custom health pages with incidents, maintenance windows, and uptime timelines.
    • Cost Insights: Normalized price-to-resource value scoring for VPS instances.

  3. Overview of ServerBee Ping Monitoring

    ServerBee's Ping monitoring allows you to periodically probe target addresses using Agents distributed across different servers to monitor network reachability and response latency.

  4. Overview of ServerBee Alerting Workflow

    ServerBee's alerting system operates via a background task that runs every 1 minute. The workflow is as follows:

    1. Iterate through all enabled alert rules.
    2. Evaluate each server within the rule's coverage scope.
    3. If trigger conditions are met, send notifications via the assigned notification group.
    4. If the state recovers from a trigger, send a recovery notification (if configured).

  5. Overview of ServerBee VPS Monitoring System

    ServerBee is a lightweight, self-hosted VPS monitoring probe system designed for individuals and small teams. Built entirely with Rust, it focuses on high performance and minimal resource consumption. The system consists of two primary components:

    • Server: The control center deployed on a management server. It provides the Web management panel, data storage (SQLite), alert evaluation, background tasks, and API interfaces.
    • Agent: A lightweight collection program deployed on each monitored server. It collects system metrics and reports them in real-time via WebSocket. It can also perform probes, terminal commands, file operations, and Docker management based on authorization.

    Key technical advantages include a zero-dependency deployment (no external database like MySQL or Redis required) and extremely low memory footprints (Agent: 5-15 MB; Server: 50-100 MB for 1,000 nodes).

  6. Overview of ServerBee Service Monitors

    Service Monitors are synthetic checks executed by the central ServerBee server to monitor public-facing services. Unlike Ping Monitoring (which uses agents), Service Monitors run from the server process. Results are stored in SQLite, displayed in the dashboard, and can trigger notifications via notification groups.

  7. ServerBee System Architecture Overview

    ServerBee consists of three primary components: a central Server, lightweight Agents deployed on monitored servers, and a React-based Frontend.

    • Server (Rust/Axum): Acts as the hub, managing Agent connections, alert evaluations, metric aggregation, and providing a REST/WebSocket API.
    • Agent (Rust): Collects system metrics (CPU, RAM, Disk, Network), executes remote commands, performs network probes (ICMP/TCP/HTTP), and manages PTY terminal sessions.
    • Frontend (React 19): A Single Page Application (SPA) embedded into the server binary via rust-embed, utilizing TanStack Router/Query and shadcn/ui for the dashboard.
    • Common Crate: A shared Rust library defining communication protocols and data structures (e.g., AgentMessage, SystemReport) used by both the Server and Agent.

  8. Monitor Docker containers

    ServerBee provides real-time Docker monitoring if the Agent has access to the Docker daemon and the CAP_DOCKER capability is enabled. It provides a dashboard with container status, CPU/Memory/Network/Block I/O stats, and a real-time event timeline. Container logs are streamed via a dedicated WebSocket endpoint. Note that container statistics and logs are streamed in real-time and are not persisted to the database.
    WebSocket Log Endpoint: /api/ws/docker/logs/{server_id}

  9. Use Notification Template Variables

    Notification messages support the following variables to provide context about the alert:

    • {{server_name}}: Name of the server
    • {{server_id}}: ID of the server
    • {{rule_name}}: Name of the alert rule
    • {{event}}: Event type (Trigger/Recovery)
    • {{message}}: Detailed alert info
    • {{time}}: Event timestamp
    • {{cpu}}: Current CPU usage
    • {{memory}}: Current memory usage
    [ServerBee] {{server_name}} {{event}}
{{message}}
时间: {{time}}

  10. Install ServerBee Server using the automated script

    The recommended installation method is the one-click script, which automatically detects architecture, downloads binaries, generates configuration, registers and starts a systemd service, and creates a symlink for the serverbee management CLI.

    • IP-based installation (Plain HTTP): Access via http://<Server-IP>:9527.
    • Domain-based installation (Automatic Caddy + HTTPS): Access via https://your-domain.
    # Option 1: Install using IP (Plain HTTP)
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server -y

# Option 2: Install using Domain (Automatic Caddy + HTTPS)
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server \
  --domain monitor.example.com --email admin@example.com -y

  11. Install ServerBee Server using the one-click script

    ServerBee Server can be installed using a one-click script that handles architecture detection (amd64/arm64), binary downloads, and systemd service registration. It is recommended to use Docker for the Server installation for easier upgrades and isolation.

    Prerequisites:

    • Linux host (amd64/arm64) running as root (or using sudo).
    • For binary installation: systemd is required.
    • For Docker installation: Docker 20.10+ and Compose V2 are required.
    • Firewall: Port 9527 must be open for Agent and browser access.
    # Option 1: Install via IP (Plain HTTP)
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server -y

# Option 2: Install via Domain (Automatic HTTPS via Caddy)
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server \
  --domain monitor.example.com \
  --email admin@example.com \
  -y

# Option 3: Install using Docker method
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server --method docker -y

# Interactive Mode (Follow prompts for language, method, and domain)
curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash

  12. ServerBee API Endpoint Overview

    ServerBee exposes a wide range of REST API endpoints categorized by functional family. All write operations and system management follow the standard { "data": ... } response envelope.
    Server Management: /api/servers/*
Agent Enrollment: /api/agent/enrollments, /api/agent/{id}/rotate-token
Agent Recovery: /api/servers/{target_id}/recovery-candidates, /api/servers/recovery-jobs/{job_id}
Groups/Tags: /api/server-groups/*, /api/server-tags/*
Pings/Probes: /api/ping-tasks/*, /api/network-probes/*
Traceroute: /api/servers/{id}/traceroute
Files: /api/files/{server_id}/write, delete, mkdir, move, download, upload
Docker: /api/servers/{id}/docker/containers/{cid}/action
Service Monitors: /api/service-monitors/*
Dashboards: /api/dashboards
Branding: /api/settings/brand
Status Pages: /api/status-pages/*
Incidents: /api/incidents/*
Maintenance: /api/maintenances/*
Alerts/Notifications: /api/alert-rules/*, /api/notifications/*, /api/notification-groups/*
Tasks: /api/tasks
Users: /api/users/*
Audit/Settings: /api/audit-logs, /api/settings/*
GeoIP: /api/geoip/download
Mobile Push: /api/mobile/pair, /api/mobile/push/register, /api/mobile/push/unregister