# VPS Hub - 多平台VPS监控与管理系统

<div align="center">

![License](https://img.shields.io/badge/license-MIT-red)

**一个强大的多平台VPS监控、管理和自动重启系统**

[功能特性](#-功能特性) • [快速开始](#-快速开始) • [架构设计](#-架构设计) • [API文档](#-api文档) • [常见问题](#-常见问题)

</div>

---

## 📋 目录

- [功能特性](#-功能特性)
- [系统架构](#-系统架构)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [配置说明](#-配置说明)
- [使用指南](#-使用指南)
- [数据库设计](#-数据库设计)
- [API文档](#-api文档)
- [监控服务](#-监控服务)
- [安全说明](#-安全说明)
- [常见问题](#-常见问题)
- [许可证](#-许可证)

---

## ✨ 功能特性

### 🎯 核心功能

- **多平台支持**：支持魔方平台（智简魔方）、阿里云、腾讯云等主流VPS平台
- **实时监控**：每5分钟自动Ping检测所有VPS的可用性
- **自动开机**：检测到VPS关机时自动执行开机操作
- **状态管理**：实时显示VPS的运行状态（开机/关机/未知）
- **详细信息**：展示CPU、内存、磁盘、带宽、操作系统等配置信息

### 🔧 管理功能

- **Web管理面板**：美观的响应式Web界面
- **手动刷新**：一键刷新VPS列表和详细信息
- **远程控制**：支持开机、关机、硬重启操作
- **配置管理**：轻松添加和管理多个VPS平台配置
- **统计信息**：实时统计VPS总数、运行中数量、已关机数量

### 📊 监控功能

- **Ping检测**：定期检测VPS网络可达性
- **延迟记录**：记录每次Ping的延迟时间
- **状态持久化**：将VPS状态保存到SQLite数据库
- **历史数据**：保留30天的Ping历史记录
- **每日摘要**：每天0点生成前一天的可用性统计报告

### 🚀 智能优化

- **API调用优化**：Ping成功时不调用API，减少不必要的请求
- **Token缓存**：JWT Token缓存2小时，避免频繁登录
- **动态更新**：只更新实际变化的字段，避免数据覆盖
- **防重复机制**：使用唯一约束防止重复数据
- **错误重试**：开机失败后自动重试并记录真实状态

---

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────┐
│                  Web前端 (index.php)                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ VPS列表  │  │ 操作控制 │  │  统计信息展示    │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP POST/GET
┌──────────────────────▼──────────────────────────────┐
│              PHP后端 (mofangidc.php)                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ API封装  │  │Token管理 │  │  数据库操作      │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │ SQLite
┌──────────────────────▼──────────────────────────────┐
│              数据库层 (SQLite)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ vps.db   │  │vpslist.db│  │   status.db      │  │
│  │(配置)    │  │ (VPS列表)│  │  (监控记录)      │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│          Python监控服务 (monitor.py)                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ Ping检测 │  │ API调用  │  │  定时任务        │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────┘
```

### 架构特点

1. **前后端分离**：PHP负责Web界面和API调用，Python负责后台监控
2. **多数据库设计**：三个独立的SQLite数据库，职责清晰
3. **混合架构**：PHP处理用户交互，Python处理定时任务
4. **适配器模式**：支持多平台扩展，易于添加新平台

---

## 💻 技术栈

### 后端
- **PHP 7.4+**：Web服务器端逻辑
- **Python 3.6+**：后台监控服务
- **SQLite 3**：轻量级数据库

### 前端
- **HTML5/CSS3**：页面结构和样式
- **JavaScript**：交互逻辑
- **响应式设计**：支持移动端访问

### 依赖库
- **PHP**: cURL, PDO-SQLite
- **Python**: requests, schedule, sqlite3

---

## 🚀 快速开始

### 环境要求

- PHP 7.4 或更高版本
- Python 3.6 或更高版本
- SQLite 3
- Linux/Windows/macOS

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://git.masonliu.com/MasonLiu/VPSHUB.git
cd VPSHUB
```

#### 2. 配置Web

直接将VPSHUB文件夹下的所有文件放置于网站路径下即可

**温馨提示**：

请将app路径设置为禁止外网访问（或添加Basic认证）。

#### 3. 一键快速启动

```bash
chmod 755 app/install.sh
./app/install.sh
```

#### 4. 访问Web界面

浏览器访问：`http://your-domain.com/`

首次访问会自动跳转到配置页面，添加第一个VPS平台配置。

---

## ⚙️ 配置说明

### 添加VPS平台配置

1. 访问 `config_add.php?pass=YOUR_API_PASS`
2. 填写配置信息：
   - **API标识**：自定义名称（唯一）
   - **网站类型**：选择平台（目前支持魔方平台）
   - **网站链接**：API根域名（不要包含路径）
   - **账户**：登录账号
   - **API密钥**：登录密码或API Key
   - **自动监控**：是否启用自动监控

3. 点击"保存配置"

### 配置示例

**魔方平台配置**：
```
API标识: 核云IDC
网站类型: 魔方平台
网站链接: https://www.heyunidc.cn
账户: 邮箱或电话号码
API密钥: your_api_key
自动监控: ✓
```

![API_KEY](./src/api.png)

⚠️ **重要提示**：
- 网站链接只填写根域名，不要包含 `/v1` 或 `/api` 等路径
- API标识必须唯一，不能重复
- 确保账户和密码正确

---

## 📖 使用指南

### Web管理面板

#### 查看VPS列表

访问 `index.php?pass=YOUR_API_PASS`，可以看到：
- 按配置分组的VPS列表
- 每个VPS的状态、IP、配置信息
- 实时统计数据

#### 操作VPS

每个VPS卡片提供三个操作按钮：
- **⚡ 开机**：启动VPS
- **🔴 关机**：关闭VPS
- **🔄 硬重启**：强制重启VPS

操作后会显示成功/失败提示，5秒后自动消失。

#### 刷新VPS列表

点击顶部工具栏的 "🔄 手动刷新VPS列表" 按钮：
1. 从API获取最新的VPS列表
2. 更新数据库中的VPS信息
3. 获取每个VPS的详细配置（CPU、内存、磁盘、带宽、系统）

### 监控服务

#### 启动监控

```bash
sudo systemctl start idc_monitor
```

#### 查看状态

```bash
sudo systemctl status idc_monitor
```


#### 停止监控

```bash
sudo systemctl stop idc_monitor
```

#### 重启监控

```bash
sudo systemctl restart idc_monitor
```

### 监控流程

```
每5分钟执行一次监控循环
  ↓
1. Ping所有VPS
  ├─ Ping成功 → 标记status='on'，不调用API
  └─ Ping失败 → 标记为abnormal，等待下一步
  ↓
2. 检查Ping失败的VPS
  ├─ 全部正常 → 跳过
  └─ 有失败的 → 调用API查询真实状态
      ├─ 状态为'on' → 可能是禁Ping，更新数据库
      └─ 状态为'off' → 执行开机操作
          ├─ 等待60秒
          └─ 验证开机结果（最多重试2次）
  ↓
3. 清理30天前的旧数据
  ↓
等待5分钟后下一次循环
```

---

## 🗄️ 数据库设计

### 数据库文件

| 文件名 | 用途 | 主要表 |
|--------|------|--------|
| `vps.db` | 存储平台配置 | `configs` |
| `vpslist.db` | 存储VPS列表 | `vps_list` |
| `status.db` | 存储监控记录 | `ping_status`, `vps_summary` |

### 表结构

#### configs 表 (vps.db)

```sql
CREATE TABLE configs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    api_label TEXT NOT NULL UNIQUE,  -- API标识
    site_type TEXT NOT NULL,         -- 平台类型
    site_url TEXT,                   -- API地址
    account TEXT NOT NULL,           -- 账户
    api_key TEXT NOT NULL,           -- API密钥
    auto_monitor BOOLEAN DEFAULT 1,  -- 是否自动监控
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### vps_list 表 (vpslist.db)

```sql
CREATE TABLE vps_list (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    config_id INTEGER NOT NULL,      -- 配置ID
    vps_id INTEGER NOT NULL,         -- VPS平台ID
    domain TEXT,                     -- 域名
    ip_address TEXT,                 -- IP地址
    product_name TEXT,               -- 产品名称
    cpu_cores INTEGER,               -- CPU核数
    memory_size TEXT,                -- 内存大小
    disk_size TEXT,                  -- 磁盘大小
    bandwidth TEXT,                  -- 带宽
    os_type TEXT,                    -- 操作系统
    status TEXT,                     -- 状态(on/off/unknown)
    section BOOLEAN DEFAULT 0,       -- 是否监控
    last_check TIMESTAMP,            -- 最后检查时间
    FOREIGN KEY (config_id) REFERENCES configs(id),
    UNIQUE(config_id, vps_id)
);
```

#### ping_status 表 (status.db)

```sql
CREATE TABLE ping_status (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    vps_id INTEGER NOT NULL,         -- VPS ID
    target TEXT NOT NULL,            -- 目标(IP或域名)
    status TEXT NOT NULL,            -- 状态(normal/abnormal)
    latency_ms REAL,                 -- 延迟(ms)
    check_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### vps_summary 表 (status.db)

```sql
CREATE TABLE vps_summary (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    vps_id INTEGER NOT NULL,         -- VPS ID
    date DATE NOT NULL,              -- 日期
    avg_latency_ms REAL,             -- 平均延迟
    max_latency_ms REAL,             -- 最大延迟
    min_latency_ms REAL,             -- 最小延迟
    count_under_100 INTEGER,         -- <100ms次数
    count_100_to_300 INTEGER,        -- 100-300ms次数
    count_300_to_500 INTEGER,        -- 300-500ms次数
    count_abnormal INTEGER,          -- 异常次数
    availability TEXT,               -- 可用性评分
    UNIQUE(vps_id, date)
);
```

---

## 📡 API文档

### 魔方平台API

- `POST /login_api?account={acc}&password={api key}` - 登录获取JWT Token

以下接口通过请求头进行认证
Authorization: JWT {token}

- `GET /hosts?page=&limit=` - 获取VPS列表
- `GET /hosts/{id}` - 获取VPS详情
- `GET /hosts/{id}/module/status?type=host` - 获取VPS状态
- `PUT /hosts/{id}/module/on` - 开机
- `PUT /hosts/{id}/module/off` - 关机
- `PUT /hosts/{id}/module/hard_reboot` - 硬重启

## 🔍 监控服务

### 配置文件

监控服务配置文件位于：`/etc/systemd/system/idc_monitor.service`

```ini
[Unit]
Description=VPS Hub Monitor Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/VPSHUB/app
ExecStart=/usr/bin/python3 monitor.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### 日志文件

- **正常日志**：`app/logs/monitor.log`
- **错误日志**：`app/logs/error.log`

### 定时任务

- **监控循环**：每5分钟执行一次
- **每日摘要**：每天00:00生成前一天的统计报告
- **数据清理**：每次循环清理30天前的Ping记录

---

## 🔒 安全说明

### 访问控制

- **API密码保护**：所有页面都需要通过 `?pass=API_PASS` 验证
- **密码文件**：存储在 `app/pass.php`，权限设置为 600
- **数据库保护**：Nginx配置禁止直接访问 `.db` 文件，或者限制访问app路径需要basic认证

### Token安全

- **Token缓存**：JWT Token缓存2小时，减少登录次数
- **自动刷新**：Token失效时自动重新登录
- **缓存文件**：`app/token.php`，权限设置为 600

### 最佳实践

1. **修改默认密码**：首次使用后立即修改API密码
2. **HTTPS**：生产环境务必使用HTTPS
3. **防火墙**：限制访问IP范围
4. **定期备份**：定期备份数据库文件
5. **日志审计**：定期检查日志文件

---

## ❓ 常见问题

### Q1: 页面显示"0台VPS"怎么办？

**A**: 
1. 点击"手动刷新VPS列表"按钮
2. 检查配置是否正确（特别是site_url不要包含路径）
3. 查看PHP错误日志：`tail -f /var/log/php/error.log`

---

### Q2: 监控服务无法启动？

**A**:
```bash
# 检查服务状态
sudo systemctl status idc_monitor

# 查看详细日志
journalctl -u idc_monitor -n 50

# 常见原因：
# 1. Python依赖未安装：pip install -r requirements.txt
# 2. 数据库文件权限问题：chown www-data:www-data app/db/*.db
# 3. 配置文件路径错误：检查service文件中的WorkingDirectory
```

---

### Q3: exec函数被禁用怎么办？

**A**: 
系统已经做了兼容处理：
- 如果exec被禁用，会显示友好提示
- 需要手动执行安装脚本：`sudo bash app/install.sh`
- 监控服务仍然可以正常运行

---

### Q4: VPS状态显示"未知"？

**A**:
可能原因：
1. 数据库中还没有该VPS的记录
2. 多次调用导致状态被覆盖（已修复）
3. API返回异常

解决方法：
- 手动刷新VPS列表
- 检查日志确认API调用是否正常
- 等待下一次监控循环

---

### Q5: 如何添加新的VPS平台？

**A**:
1. 在 `app/monitor.py` 中创建新的适配器类
2. 继承 `PlatformAdapter` 基类
3. 实现必要的方法（login, get_vps_list, get_vps_status等）
4. 在 `load_configs_and_create_adapters()` 中添加判断逻辑

示例：
```python
class AliyunAdapter(PlatformAdapter):
    def login(self):
        # 实现阿里云登录逻辑
        pass
    
    def get_vps_list(self):
        # 实现获取VPS列表逻辑
        pass
```

---

### Q6: 数据库文件在哪里？

**A**:
- `app/db/vps.db` - 配置数据库
- `app/db/vpslist.db` - VPS列表数据库
- `app/db/status.db` - 监控状态数据库

可以使用SQLite工具查看：
```bash
sqlite3 app/db/vpslist.db
.tables
SELECT * FROM vps_list;
```

---

### Q7: 如何备份数据？

**A**:
```bash
# 备份所有数据库
cp app/db/*.db backup/$(date +%Y%m%d)/

# 或使用sqlite3导出
sqlite3 app/db/vpslist.db ".dump" > backup/vpslist.sql
```

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---


## 📧 联系方式

- **项目地址**: [https://git.masonliu.com/MasonLiu/VPSHUB](https://git.masonliu.com/MasonLiu/VPSHUB)
- **作者**: MasonLiu
- **邮箱**: admin@masonliu.com

---

## 🙏 致谢

感谢以下开源项目：
- [PHP](https://www.php.net/)
- [Python](https://www.python.org/)
- [SQLite](https://www.sqlite.org/)
- [智简魔方财务系统](https://www.idcsmart.com/)

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给个Star！**

Made with ❤️ by MasonLiu

</div>