Unraid管理工具

System Requirements and Dependencies

Important: The Unraid Management Agent has NO external plugin dependencies. It collects data directly from system sources.

For detailed information, see:

• System Requirements & Dependencies - Complete requirements and data collection methods
• Quick Start Guide - Get started quickly
• Diagnostic Commands - Troubleshooting guide

Quick Prerequisites

• Unraid 6.9+ (tested on Unraid 7.x)
• Port 8043 available (configurable)
• No other plugins required

Install dependencies

make deps

Install dependencies

make deps

Building from Source

```bash

Build for Unraid (Linux/amd64)

make release

Start a Docker container

curl -X POST http://localhost:8043/api/v1/docker/nginx/start

Building and Testing

```bash

Build for local development

make local

Clean build artifacts

make clean ```

Automated setup (recommended)

./scripts/setup-pre-commit.sh

Or manual setup

pip install pre-commit make pre-commit-install

Pre-commit will automatically run checks before each commit. See [docs/development/code-quality.md](docs/development/code-quality.md) for detailed documentation.

#### Available Commands

Usage

Example API Usage

```bash

API Response Examples

Tested Configuration

This plugin has been developed and tested on the following configuration:

• Unraid Version: 7.x
• Plugin Version: 2025.11.0
• Architecture: Linux/amd64
• Primary Testing: REST API endpoints, WebSocket events, Docker/VM control operations

Note: This configuration represents the primary development and testing environment. Your mileage may vary on different hardware setups.

Configuration

Settings Page

Configure the plugin through the Unraid web UI:

1. Navigate to Settings → Unraid Management Agent
2. Adjust settings as needed:

• Port: API server port (default: 8043)
• Collection Intervals: How often each data type is collected

1. Click Apply to save changes (service restarts automatically)

Advanced: Manual Configuration

For automation or headless setups, you can edit the config file directly:

/boot/config/plugins/unraid-management-agent/config.cfg

Changes require a service restart:

/usr/local/emhttp/plugins/unraid-management-agent/scripts/stop
/usr/local/emhttp/plugins/unraid-management-agent/scripts/start

Relationship to Official Unraid API

• Official Unraid API: Unraid OS 7.2+ includes an official GraphQL-based API as part of the core operating system. This is the official API provided and supported by Lime Technology (the creators of Unraid).

• This Plugin: The Unraid Management Agent is a separate, independent third-party plugin that provides a REST API and WebSocket interface for system monitoring and control. It is developed and maintained by the community, not by Lime Technology.

Coexistence with Official API

This plugin can coexist with the official Unraid API. They operate independently and do not conflict with each other. You can use both simultaneously if your use case requires it.

Official Unraid API Documentation

For information about the official Unraid GraphQL API, please refer to:

• Unraid Official Documentation
• Unraid OS 7.2+ release notes and API documentation

---

Native API Integration

For optimal performance, collectors use native Go libraries instead of shell commands:

REST API Endpoints

Base URL: http://localhost:8043/api/v1

Monitoring Endpoints

• GET /health - Health check
• GET /system - System information
• GET /array - Array status
• GET /disks - List all disks
• GET /disks/{id} - Get specific disk info
• GET /network - Network interface list
• GET /shares - List user shares
• GET /docker - List Docker containers
• GET /docker/{id} - Get container details
• GET /vm - List virtual machines
• GET /vm/{id} - Get VM details
• GET /ups - UPS status
• GET /gpu - GPU metrics
• GET /logs - List log files or get log content
• GET /logs/{filename} - Get specific log file by name

Settings & Configuration Endpoints

• GET /settings/disk-thresholds - Global disk temperature warning/critical thresholds
• GET /settings/mover - Mover schedule, thresholds, and running status
• GET /settings/services - Docker and VM Manager enabled/disabled status
• GET /settings/network-services - Network services status (SMB, NFS, FTP, SSH, VPN, etc.)
• GET /array/parity-check/schedule - Parity check schedule configuration
• GET /plugins - List installed plugins with versions and update status
• GET /updates - OS and plugin update availability
• GET /system/flash - USB flash boot drive health statistics

Control Endpoints

• POST /docker/{id}/start - Start container
• POST /docker/{id}/stop - Stop container
• POST /docker/{id}/restart - Restart container
• POST /docker/{id}/pause - Pause container
• POST /docker/{id}/unpause - Unpause container
• POST /vm/{id}/start - Start VM
• POST /vm/{id}/stop - Stop VM
• POST /vm/{id}/restart - Restart VM
• POST /vm/{id}/pause - Pause VM
• POST /vm/{id}/resume - Resume VM
• POST /vm/{id}/hibernate - Hibernate VM
• POST /vm/{id}/force-stop - Force stop VM

Get network interfaces

curl http://localhost:8043/api/v1/network

Network Interfaces

[
  {
    "name": "eth0",
    "mac_address": "00:11:22:33:44:55",
    "ip_address": "192.168.1.100",
    "speed_mbps": 1000,
    "state": "up",
    "bytes_received": 1234567890,
    "bytes_sent": 987654321,
    "packets_received": 5000000,
    "packets_sent": 4500000,
    "errors_received": 0,
    "errors_sent": 0,
    "timestamp": "2025-10-02T08:00:00Z"
  }
]

⚠️ Important: Third-Party Plugin Notice

This is a community-developed third-party plugin and is NOT an official Unraid product.

When to Use This Plugin

You might choose this plugin if you:

• ✅ Prefer REST API: You want a traditional REST API instead of GraphQL
• ✅ Need WebSocket Support: You require real-time event streaming via WebSockets
• ✅ Want Specific Features: This plugin offers specific monitoring and control features tailored to community needs
• ✅ Compatibility: You need an API solution that works alongside or independently of the official API

Components

Collectors

Data collectors run at configurable intervals (defaults shown):

• System Collector (15s): CPU, RAM, temps, uptime
• Array Collector (30s): Array state and parity info
• Disk Collector (30s): Per-disk metrics
• Network Collector (30s): Interface status and statistics
• Docker Collector (30s): Container information
• VM Collector (30s): Virtual machine data
• UPS Collector (60s): UPS status
• GPU Collector (60s): GPU metrics
• Share Collector (60s): User share information
• Hardware Collector (5m): Hardware info (rarely changes)
• Registration Collector (5m): License info (rarely changes)

API Server

• Maintains in-memory cache of latest collector data
• Serves REST endpoints for instant responses
• Broadcasts events to WebSocket clients
• Implements CORS, logging, and recovery middleware

Orchestrator

Coordinates the entire application lifecycle:

• Initializes all collectors
• Starts API server subscriptions before collectors
• Manages graceful shutdown

Create plugin package

make package ```

Dev Container (VS Code / GitHub Codespaces)

• Prereqs: Docker (or compatible), VS Code with Dev Containers extension — or just open in GitHub Codespaces.
• Open the repo in VS Code and run Dev Containers: Reopen in Container.
• Uses Dev Container Features for Go 1.26, Node.js 22, Python 3.12, and GitHub CLI.
• Ansible + ansible-lint included for deployment automation (ansible/ directory).
• Go tools auto-installed: golangci-lint, gosec, govulncheck, swag, goimports.
• VS Code extensions auto-installed: Go, Python, Ansible, Makefile Tools, Prettier, GitHub Copilot.
• Lifecycle: onCreateCommand installs tools, updateContentCommand refreshes deps, postCreateCommand sets up pre-commit hooks.
• Run make test to verify after attach.

Troubleshooting