🖥️ Server Monitor

A lightweight, high-performance Node.js server monitoring API service

Real-time system performance metrics monitoring with clean RESTful API interface

🇺🇸 English Documentation (Current) · 📖 中文文档

Quick Start · API Documentation · Service Management · Report Issues

---

✨ Features

🚀 Real-time Monitoring - Monitor CPU, memory, disk usage and system load in real-time
📊 RESTful API - Clean HTTP API interface, easy to integrate
🌐 CORS Support - Built-in CORS support, frontend friendly
⚙️ systemd Integration - Support both system-level and user-level service installation
🔄 Auto Restart - Automatic restart on service failure, ensuring high availability
📝 Logging - Integrated with systemd logging system for easy debugging
🐳 Lightweight - Minimal resource footprint, suitable for all environments

🚀 Quick Start

System Requirements

• Node.js v14.0.0 or higher
• npm package manager
• Linux system (with systemd support)

📦 Installation Methods

Method 1: Clone Repository (Recommended)

# Clone the project
git clone https://github.com/superboyyy/server-monitor.git
cd server-monitor

# Install dependencies
npm install

# User-level service installation (recommended, no sudo required)
./install-service.sh --user

💡 Recommended to use installation script: The installation script will automatically:

• Check system dependencies
• Install npm dependencies
• Auto-configure username and path in service files
• Enable and start the service

Method 2: System-level Service Installation

# System-level service installation (requires sudo)
sudo ./install-service.sh

Method 3: Direct Run (Development Mode)

# Install dependencies
npm install

# Start service
npm start
# or
node server.js

🎯 One-Click Experience

curl -s http://localhost:3001/api/system/metrics | jq .

📊 API Interface

Get System Metrics

Endpoint: GET /api/system/metrics

Request	Response
curl http://localhost:3001/api/system/metrics	{ "cpu": 15, "memory": 68, "disk": 45, "load": "0.8", "timestamp": "2025-09-10T12:30:42.123Z" }

📋 Response Field Descriptions

Field	Type	Description	Range
cpu	number	CPU usage percentage	0-100
memory	number	Memory usage percentage	0-100
disk	number	Disk usage percentage	0-100
load	string	System load average (1 minute)	≥ 0.0
timestamp	string	Data collection timestamp (ISO 8601)	-

💡 Usage Examples

JavaScript / Node.js

const response = await fetch('http://localhost:3001/api/system/metrics');
const metrics = await response.json();

console.log(`CPU: ${metrics.cpu}%`);
console.log(`Memory: ${metrics.memory}%`);
console.log(`Disk: ${metrics.disk}%`);
console.log(`Load: ${metrics.load}`);

Python

import requests

response = requests.get('http://localhost:3001/api/system/metrics')
metrics = response.json()

print(f"CPU: {metrics['cpu']}%")
print(f"Memory: {metrics['memory']}%") 
print(f"Disk: {metrics['disk']}%")
print(f"Load: {metrics['load']}")

Shell / Bash

#!/bin/bash
metrics=$(curl -s http://localhost:3001/api/system/metrics)

cpu=$(echo $metrics | jq -r '.cpu')
memory=$(echo $metrics | jq -r '.memory') 
disk=$(echo $metrics | jq -r '.disk')
load=$(echo $metrics | jq -r '.load')

echo "CPU: ${cpu}%"
echo "Memory: ${memory}%"
echo "Disk: ${disk}%"
echo "Load: ${load}"

⚙️ Service Management

User Service Management

Operation	Command	Description
📊 Check Status	systemctl --user status server-monitor	View service running status
▶️ Start Service	systemctl --user start server-monitor	Start monitoring service
⏹️ Stop Service	systemctl --user stop server-monitor	Stop monitoring service
🔄 Restart Service	systemctl --user restart server-monitor	Restart monitoring service
📝 View Logs	journalctl --user -u server-monitor -f	View service logs in real-time
❌ Disable Auto-start	systemctl --user disable server-monitor	Disable auto-start on boot

System Service Management

Operation	Command	Description
📊 Check Status	sudo systemctl status server-monitor	View service running status
▶️ Start Service	sudo systemctl start server-monitor	Start monitoring service
⏹️ Stop Service	sudo systemctl stop server-monitor	Stop monitoring service
🔄 Restart Service	sudo systemctl restart server-monitor	Restart monitoring service
📝 View Logs	sudo journalctl -u server-monitor -f	View service logs in real-time
❌ Disable Auto-start	sudo systemctl disable server-monitor	Disable auto-start on boot

🛠️ Installation Script Usage

Basic Usage

# Show help information
./install-service.sh --help

# Install as user service (recommended)
./install-service.sh --user

# Install as system service
./install-service.sh --system

# Check service status
./install-service.sh --status

# View service logs
./install-service.sh --logs

# Uninstall service
./install-service.sh --uninstall

🔧 Script Features

Feature	Description
🔍 Auto Dependency Check	Automatically check Node.js, npm and required files
🤖 Smart Installation	Auto-create package.json and install dependencies
⚙️ Auto Configuration	Auto-replace placeholders in service files for username and path
🎯 Dual Support	Support both system-level and user-level service installation
📦 Complete Management	Provide installation, uninstallation, status viewing, log viewing functions
⚠️ Error Handling	Comprehensive error messages and exception handling
🎨 Colored Output	Clear information categorization display

🚀 One-Click Installation: The installation script automatically handles all configurations, no need to manually modify any files!

🔧 Configuration

Environment Variables

Variable	Default	Description
PORT	3001	Service listening port
NODE_ENV	production	Runtime environment

Service Configuration

Service configuration file server-monitor.service supports customization:

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/server_monitor
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3001

⚠️ Important Note: You need to replace placeholders in the configuration file before use:

• Replace YOUR_USERNAME with your actual username
• Replace /path/to/server_monitor with the actual project path

Or just use the installation script, it will handle these configurations automatically!

🚨 Troubleshooting

🔧 Port Already in Use

# Check port usage
sudo netstat -tlnp | grep :3001
# or use ss command
sudo ss -tlnp | grep :3001

# Kill the process using the port
sudo kill -9 <PID>

🚨 Service Start Failed

# View detailed error logs
journalctl --user -u server-monitor -n 50
# or view system service logs
sudo journalctl -u server-monitor -n 50

# Check service status
systemctl --user status server-monitor

📦 Dependency Installation Failed

# Clean npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

🔐 Permission Issues

• User service: Ensure current user has execution permissions
• System service: Ensure running installation script with sudo privileges
• File permissions: Ensure script has executable permissions chmod +x install-service.sh

🔄 Reinstallation

# 1. Uninstall existing service
./install-service.sh --uninstall

# 2. Clean dependencies (optional)
rm -rf node_modules package-lock.json

# 3. Reinstall
./install-service.sh --user

📁 Project Structure

server-monitor/
├── 📄 server.js                 # Main service file
├── ⚙️ server-monitor.service    # systemd service configuration
├── 🚀 install-service.sh        # Installation script
├── 📦 package.json              # Project configuration file  
├── 🔒 package-lock.json         # Dependency lock file
├── 📖 README.md                 # Project documentation (Chinese)
├── 📖 README_EN.md              # Project documentation (English)
└── 🙈 .gitignore                # Git ignore file

🛠️ Tech Stack

Technology	Version	Purpose
Node.js	≥14.0.0	Runtime environment
Express.js	^5.1.0	Web framework
systemd	-	Service management
Shell Script	-	Automated installation

🤝 Contributing

We welcome all forms of contributions! Please follow these steps:

1. Fork this project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Add appropriate comments
• Test your changes
• Update relevant documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details

⭐ Star History

If this project helps you, please give it a ⭐ Star!

---

🌐 Access URL: http://localhost:3001/api/system/metrics

📧 Report Issues: GitHub Issues

🔗 More Projects: GitHub Profile

Made with ❤️ by Aiden