English | 简体中文

ServerPulse

Lightweight multi-server monitoring. Pure Python, real-time WebSocket.

Features

• Frontend dashboard: CPU, memory, disk, network, processes. No login required.
• Admin panel: manage machines, alerts, users via web UI.
• Independent port per machine: one machine down doesn't affect others.
• Uptime Kuma style overview: heartbeat bar + uptime % + 24h stats.
• Machine detail page: OS version, hardware info, CPU model, uptime.
• Alerts: email + DingTalk, test send, alert ignore.
• Network history: 24h traffic chart, 1 sample per minute.
• Custom appearance: background image/video, glass blur, custom icon, dark mode.
• Persistence: config in data.json, heartbeat history 7 days.
• Security: bcrypt password hash, token auth, input validation.
• Agent: cross-platform (Windows/Linux/macOS), local SQLite 35 days, auto-reconnect.

Requirements

• Python 3.9+
• Windows / Linux / macOS

Quick Start

Server

unzip monitor-server.zip
cd monitor-server
pip install -r requirements.txt
python main.py

Open http://localhost:8000, default login admin / admin.

Agent

unzip monitor-agent.zip
cd monitor-agent
pip install -r requirements.txt
python agent.py --init
# Edit agent_config.yaml, fill in machine_name / server_host / server_port / token
python agent.py

Add First Machine

1. Open http://server-ip:8000 → click "Admin" tab
2. Login (default admin / admin, change password immediately)
3. "Machines" → "Add Machine"
4. Fill name, IP, WS port, token (click "generate" for random token)
5. Copy token to agent's agent_config.yaml
6. Start agent, machine shows "online" in seconds

Deployment

Windows Service (NSSM)

nssm install ServerPulse-Server "C:\Python39\python.exe" "C:\monitor-server\main.py"
nssm set ServerPulse-Server AppDirectory "C:\monitor-server"
nssm set ServerPulse-Server Start SERVICE_AUTO_START
nssm start ServerPulse-Server

Linux systemd

sudo tee /etc/systemd/system/serverpulse.service <<EOF
[Unit]
Description=ServerPulse Server
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/python3 /opt/serverpulse/main.py
WorkingDirectory=/opt/serverpulse
Restart=always
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now serverpulse

Nginx Reverse Proxy + HTTPS

server {
    listen 443 ssl;
    server_name monitor.yourdomain.com;
    ssl_certificate     /etc/letsencrypt/live/yourdomain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
    }
    location /ws/public {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Resource Usage

Component	Memory	CPU	Disk
Server (50 machines)	~120 MB	<5%	~50 MB (7d heartbeat)
Agent	~30 MB	<1%	~15 MB/month (SQLite)
Dashboard	-	-	loads in <1s

Benchmark: 50 machines, 5s collect interval, 7-day heartbeat retention.

Config

Server

All config via web admin panel, stored in data.json.

Key	Description	Default
dashboard_port	Dashboard port	8000
alert_cooldown_seconds	Alert cooldown	300
offline_threshold_seconds	Offline threshold	30
card_opacity	Card opacity 0-1	0.78
card_blur	Glass blur px (0=off)	20

Agent

Edit agent_config.yaml:

machine_name: "web-01"          # must match server-side
server_host: "192.168.1.100"
server_port: 8001
token: "32-char-random-string"  # must match server-side
collect_interval: 5
retention_days: 35

Architecture

Agents x N                Server
┌──────────┐              ┌─────────────────────┐
│  Agent   │── WS :8001 ─→│  FastAPI            │
│  psutil  │              │  ├── Dashboard:8000 │
│  SQLite  │              │  ├── REST API       │
│ reconnect│              │  ├── WS push        │
└──────────┘              │  ├── Alert engine   │
                          │  └── data.json      │
                          └─────────────────────┘

Troubleshooting

Agent cannot connect

• Check network: ping server_ip
• Check port: telnet server_ip 8001
• Verify token matches server-side

Dashboard not updating

• Check WebSocket in F12 → Network → WS
• If behind Nginx, verify /ws/public config

Port in use

• Windows: netstat -ano | findstr :8000 → taskkill /PID <pid> /F
• Linux: lsof -i:8000 → kill -9 <pid>

Email alert failed?

• QQ Mail uses auth code, not login password
• Test: python -c "import smtplib; s=smtplib.SMTP_SSL('smtp.qq.com',465); s.login('your@qq.com','auth_code'); print('OK')"

FAQ

Q: How many machines can it monitor? A: Tested 50+ without issue. Each machine uses one port (1-65535).

Q: Will data be lost on restart? A: No. Config in data.json, heartbeat history retained 7 days, auto-restored on startup.

Q: Can it monitor Linux? A: Yes. Agent is pure Python, cross-platform. See systemd config above.

Q: How to upgrade? A: Stop service → replace source files → keep data.json and agent_config.yaml → start service.

License

MIT

Acknowledgments

• FastAPI
• psutil
• ECharts
• Uptime Kuma - Reference some UI elements
• Developed with assistance from GLM-5.2

---

If you find this useful, please consider giving it a Star. Thanks.