设备管理系统项目文档

1. 项目概述

本项目是一个轻量级的远程设备管理系统，专注于Android设备的远程Shell脚本执行与状态监控。系统采用PHP + MySQL架构，提供Web管理界面，支持设备自动注册、心跳保活、命令下发及日志记录功能。

2. 项目结构

主要文件结构

e:\phpstudy_pro2\WWW\yc3\
├── common.php          # 核心配置文件与公共函数库（包含数据库配置）
├── common_scripts.php  # 公共脚本管理逻辑
├── dashboard.php       # 主管理控制台（设备列表、命令下发）
├── index.php           # 入口文件（重定向至登录页）
├── install.php         # 系统安装向导
├── login.php           # 管理员登录页面
├── logout.php          # 退出登录处理
├── logs.php            # 系统日志查看页面
├── profile.php         # 个人资料与API密钥管理
├── remote_api.php      # 设备端通信接口（心跳、注册、命令获取）
├── script_editor.php   # 在线脚本编辑器
└── scripts/            # 脚本文件存储目录

3. 系统功能

3.1 设备管理

• 自动注册：设备通过API密钥首次连接时自动注册。
• 状态监控：实时显示设备在线/离线状态（基于心跳机制，默认120秒超时）。
• 设备信息：记录设备型号、Android版本、序列号(SN)、首次/最后上线时间。
• 设备维护：支持修改设备备注、软删除设备、清理长期离线设备。

3.2 远程执行

• Shell脚本执行：支持在线编写Shell脚本并下发至设备执行。
• 命令管理：
  • run_script: 下发指定脚本。
  • stop: 停止当前任务。
• 命令历史：记录对每个设备下发的操作指令及时间。
• 公共脚本：维护常用脚本库，可快速应用至多台设备。

3.3 安全机制

• 身份验证：
  • 管理员：用户名/密码登录，含防暴力破解机制（5次失败锁定）。
  • 设备端：基于Bearer Token (API Key) 的身份验证。
• 数据安全：
  • 密码加密存储 (bcrypt)。
  • SQL注入防护 (PDO预处理)。
  • CSRF防护 (令牌验证)。
  • XSS防护 (输出转义)。

4. API接口说明

4.1 设备通信接口 (remote_api.php)

功能：设备心跳上报、注册与命令获取。

• URL: /remote_api.php
• Method: POST
• Headers:
  • Authorization: Bearer <YOUR_API_KEY>
  • Content-Type: application/json

请求参数 (JSON):

{
  "device_id": "设备唯一ID",
  "sn": "设备序列号",
  "model": "设备型号",
  "android_version": "Android系统版本",
  "timestamp": 1630000000
}

响应 (JSON):

{
  "command": "run_script:device_id.sh" // 或 "stop", 或 "" (无命令)
}

逻辑说明:

1. 验证API Key。
2. 更新/注册设备信息（最后在线时间）。
3. 检查是否有待执行命令。
4. 返回命令并清除数据库中的该命令记录（保证命令只执行一次）。

5. 数据库结构

系统主要包含以下数据表（由 install.php 自动创建）：

表名	描述	关键字段
users	管理员账户表	id, username, password_hash, api_key
devices	设备信息表	device_id, user_id, last_seen, command_status, is_deleted
device_commands	待执行命令队列	id, device_id, command, timestamp
logs	系统操作日志	id, type, message, timestamp
login_attempts	登录安全限制	ip, username, attempts, lockout_until
api_rate_limits	API限流记录	ip, request_count, window_start

6. 安装与配置

6.1 安装流程

系统内置自动化安装向导，无需手动导入SQL。

1. 访问入口：浏览器访问 install.php。
2. 环境检测：自动检测PHP版本、扩展（PDO, GD, cURL等）及目录权限。
3. 数据库配置：输入MySQL主机、库名、账号密码，系统将自动验证连接。
4. 管理员设置：创建初始管理员账号及生成系统API Key。
5. 完成安装：
   • 系统自动创建数据库表结构。
   • 自动修改 common.php 中的数据库配置信息。
   • 生成 installed.lock 锁定文件防止重复安装。

6.2 配置文件

核心配置位于 common.php 文件中：

$config = array(
    'db_host' => 'localhost',
    'db_name' => 'yckz22',
    'db_user' => '...',
    'db_pass' => '...',
    // ...
);

注意：安装完成后，如需修改数据库连接，可直接编辑此文件。

7. 使用指南

1. 登录系统：使用安装时创建的管理员账号登录。
2. 获取API Key：在仪表板 (dashboard.php) 顶部查看或复制您的API Key。
3. 配置设备：将API Key配置到您的Android设备控制端脚本中。
4. 设备上线：设备启动并请求API后，将自动出现在仪表板列表中。
5. 执行操作：
   • 点击“编辑脚本”编写Shell指令。
   • 点击“执行脚本”下发指令。
   • 在“命令历史”中确认下发记录。

8. 技术栈

• 后端：PHP 7.0+
• 数据库：MySQL / MariaDB
• 前端：HTML5, CSS3, 原生JavaScript
• 服务器要求：Nginx/Apache, PHP扩展 (pdo_mysql, curl, mbstring)

---

文档更新时间：2026-02-13