# 冬浩中控系统

**Repository Path**: blackqing/donghao-central-control-system

## Basic Information

- **Project Name**: 冬浩中控系统
- **Description**: 基于 HotGo 2.0 框架构建的 Android 设备中控管理系统，集成 scrcpy 实现 Android 设备的远程投屏与控制。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 						冬浩中控系统

<div align="center">
    <p align="center">
        <a href="https://goframe.org/pages/viewpage.action?pageId=1114119" target="_blank">
            <img src="https://img.shields.io/badge/goframe-2.10.2-green" alt="goframe">
        </a>
        <a href="https://v3.vuejs.org/" target="_blank">
            <img src="https://img.shields.io/badge/vue.js-vue3.4-green" alt="vue">
        </a>
        <a href="https://www.naiveui.com" target="_blank">
            <img src="https://img.shields.io/badge/naiveui-%3E2.44.1-blue" alt="naiveui">
        </a>
        <a href="https://www.tslang.cn/" target="_blank">
            <img src="https://img.shields.io/badge/typescript-%3E4.0.0-blue" alt="typescript">
        </a>
        <a href="https://vitejs.dev/" target="_blank">
            <img src="https://img.shields.io/badge/vite-%3E5.4.2-yellow" alt="vite">
        </a>
        <a href="https://github.com/bufanyun/hotgo/blob/v2.0/LICENSE" target="_blank">
            <img src="https://img.shields.io/badge/license-MIT-success" alt="license">
        </a>
    </p>
    <p>基于 HotGo 2.0 + scrcpy 的 Android 设备远程中控管理平台</p>
</div>

## 项目简介

冬浩中控系统是一个基于 **HotGo 2.0**（GoFrame 2.10）框架构建的 Web 端 Android 设备集中管理平台。通过集成 **scrcpy** 与 **Go-scrcpy** 实现 Android 设备的实时投屏、反向控制、文件管理、应用管理、进程管理、脚本执行等功能，并通过 WebSocket + WebCodecs 在浏览器中低延迟渲染 H.264 视频流。

默认使用 **SQLite** 数据库，开箱即用，无需额外安装 MySQL 或 PostgreSQL。适合以下场景：

- **Android 设备运维** — 批量管理测试机、广告机、自助终端
- **远程控制中心** — 集中监控和控制分散的 Android 设备
- **自动化测试平台** — 配合 ADB 执行自动化脚本
- **设备资产盘点** — 统一管理设备信息、状态、分组

## 功能特性

### 设备管理

| 功能 | 说明 |
|------|------|
| 设备列表 | 展示所有设备，支持状态筛选、关键字搜索、分页 |
| 设备详情 | 查看设备型号、Android 版本、IP、硬件信息等 |
| 状态监控 | 实时显示设备在线/离线状态，心跳检测 |
| 设备编辑 | 修改设备名称、备注、分组等信息 |
| 批量操作 | 批量连接、断开、重启、移动分组、执行脚本等 |
| 连接管理 | 支持 USB 连接、WiFi 调试连接、一键开启 WiFi 调试 |
| 自动发现 | 扫描已连接的 ADB 设备并自动入库 |

### 远程投屏 & 控制

| 功能 | 说明 |
|------|------|
| 实时投屏 | 基于 scrcpy + WebCodecs 实现设备屏幕实时投射到浏览器 |
| 屏幕墙 | 同时监控多台设备画面（Grid 布局，卡片宽度随视口自适应，竖屏 9:16 比例） |
| 多设备订阅 | 单个 WebSocket 连接支持订阅多台设备，屏幕墙所有窗口同步刷新 |
| 反向控制 | 在浏览器中直接操作设备（点击、滑动、输入），使用通用手指 pointerID |
| 独立窗口 | 单设备独立投屏窗口，支持高码率 |
| 双击放大 | 屏幕墙中双击小窗口自动切换到大窗口投屏 |
| 离线检测 | 15 秒无新帧自动广播 `device:offline` / `screen:stop`，前端更新 UI 并释放解码器 |

### 分组管理

- 支持树形分组结构，可嵌套子分组
- 自定义分组图标、排序
- 设备批量移动分组
- **分组设备管理弹窗**：可视化维护分组成员，支持从其他分组/未分组设备中搜索筛选并批量加入，支持一键移除

### 脚本管理

- 内置常见 ADB 脚本模板（获取设备信息、清理缓存、重启等）
- 支持自定义脚本，在线编辑
- 脚本执行记录，可查看输入/输出/错误信息
- 批量设备执行
- **设备下拉选择**：执行脚本时从设备列表下拉选择目标设备（支持搜索过滤），未选设备时执行按钮禁用
- **执行结果回显**：脚本执行完成后弹出结果 Modal，展示设备、状态、耗时、错误信息、完整输出（支持一键复制）

### 文件管理

- 浏览设备文件系统（目录树 + 文件列表）
- 上传文件到设备
- 下载设备文件
- 创建/删除目录
- 文件信息展示（权限、大小、修改时间）
- **设备下拉选择**：从设备列表下拉选择目标设备（支持搜索过滤），未选设备时查询按钮禁用

### 应用管理

- 查看设备已安装应用列表
- 搜索和过滤应用
- 查看应用详细信息（包名、版本号、apk 路径等）
- 卸载应用
- **设备下拉选择**：从设备列表下拉选择目标设备（支持搜索过滤），未选设备时查询按钮禁用

### 进程管理

- 查看设备运行进程列表
- 查看进程 CPU、内存占用
- 强制停止进程
- **设备下拉选择**：从设备列表下拉选择目标设备（支持搜索过滤），未选设备时查询按钮禁用
- **兼容老版本 Android**：自动回退 `ps -A` → `ps`，动态解析表头列下标（兼容 8 列/9 列两种输出格式）

### 系统配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| ADB 路径 | `adb` | ADB 可执行文件路径，从数据库配置读取 |
| 默认 ADB 端口 | 5555 | 设备连接端口 |
| scrcpy-server 路径 | `./data/scrcpy-server.jar` | scrcpy 服务端 jar 包，从数据库配置读取 |
| 默认投屏码率 | 500000 bps | 普通投屏码率 |
| 屏幕墙码率 | 500000 bps | 多设备屏幕墙码率 |
| 独立窗口码率 | 4000000 bps | 单设备投屏码率 |
| 日志保留天数 | 30 天 | 自动清理历史日志 |
| 自动刷新间隔 | 30 秒 | 设备列表刷新间隔 |
| 登录验证码 | 关闭 | 后台登录验证码开关，可在系统设置中修改 |

### 日志 & 审计

- 完整操作日志记录（模块、操作、操作人、IP、耗时）
- 登录日志
- 定时清理过期日志
- 日志导出

### 用户 & 权限

- 基于 RBAC 的权限管理体系
- 支持多角色（超管、管理员、租户、财务、技术等）
- 菜单权限、按钮权限、数据权限
- 部门管理、岗位管理

## 技术栈

| 层次 | 技术 |
|------|------|
| 后端框架 | GoFrame 2.10（Go 1.25） |
| 前端框架 | Vue 3.4 + Naive UI |
| 前端构建 | Vite 5 + TypeScript 4 |
| 数据库 | SQLite（默认）/ MySQL / PostgreSQL |
| 缓存 | 文件缓存 / Redis / Memory |
| 设备通信 | scrcpy + Go-scrcpy + ADB (Android Debug Bridge) |
| 视频解码 | WebCodecs API（浏览器端硬解 H.264） |
| 实时通信 | WebSocket |
| 包管理 | pnpm |
| 认证 | JWT (GoFrame Token) |

## 环境要求

- **Go** 1.25+
- **Node.js** 18+
- **pnpm** 8+（`npm install -g pnpm`）
- **ADB**（Android Debug Bridge），需加入系统 PATH
- **scrcpy-server** jar 包（用于投屏功能）
- **现代浏览器**：Chrome 94+ / Edge 94+（需支持 WebCodecs API）

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/yuan71058/donghao-central-control-system.git
cd donghao-central-control-system
```

### 2. 启动服务端

```bash
cd server
go run main.go
```

服务端默认监听 `:9000` 端口，使用 SQLite 数据库，数据文件自动生成在 `server/hotgo.db`。访问 `http://localhost:9000` 即可进入系统。

### 3. 启动前端（开发模式）

如果需要同时开发前端，可单独启动 Vite 开发服务器：

```bash
cd web
pnpm install
pnpm run dev
```

前端开发服务器默认监听 `:8001` 端口，API 通过代理转发到后端 `:9000`。

### 4. 一键启动（开发模式）

项目根目录提供了 `dev.bat` 脚本，可同时启动前后端：

```bash
.\dev.bat
```

### 默认账号

| 角色 | 账号 | 密码 |
|------|------|------|
| 超管 | admin | 123456 |
| 管理员 | test | 123456 |
| 租户 | ameng | 123456 |

## 生产部署

### 编译

```bash
.\build_all.bat
```

此脚本会编译 Go 后端和构建 Vue 前端，产物输出到 `release/` 目录，并自动拷贝 `scrcpy-server.jar` 到 `release/data/`。

### 启动

```bash
.\start.bat
```

生产模式下，Go 服务端直接托管前端静态文件，统一通过 `http://localhost:9000` 访问。

## 项目结构

```
├── server/                       # 后端服务 (GoFrame)
│   ├── addons/                   # 插件模块
│   │   └── androidmanager/       #   └─ Android 设备管理插件
│   │       ├── api/              #        API 请求/响应定义
│   │       ├── controller/       #        控制器层
│   │       ├── logic/            #        业务逻辑层
│   │       ├── model/            #        数据模型
│   │       ├── router/           #        路由注册（含 websocket.go）
│   │       ├── consts/           #        常量定义
│   │       ├── crons/            #        定时任务
│   │       ├── queues/           #        消息队列
│   │       ├── resource/         #        插件资源（SQL 脚本等）
│   │       ├── library/          #        插件库
│   │       └── service/          #        服务接口
│   ├── config/                   # 配置文件
│   ├── internal/                 # 核心业务逻辑
│   │   ├── cmd/                  # 命令行入口
│   │   ├── controller/           # 控制器层
│   │   ├── logic/                # 业务逻辑层
│   │   ├── model/                # 数据模型
│   │   ├── service/              # 服务接口定义
│   │   ├── library/              # 公共库
│   │   ├── consts/               # 常量
│   │   └── dao/                  # 数据访问层
│   ├── resource/                 # 静态资源与 SQL 脚本
│   ├── storage/                  # 数据文件、缓存
│   └── utility/                  # 工具函数
├── web/                          # 前端项目 (Vue 3)
│   ├── src/
│   │   ├── views/                # 页面组件
│   │   │   └── addons/
│   │   │       └── androidManager/ # 设备管理前端页面
│   │   │           ├── device/     #   设备管理
│   │   │           ├── group/      #   分组管理（含 devices.vue 分组设备维护）
│   │   │           ├── screen/     #   屏幕墙投屏
│   │   │           ├── script/     #   脚本管理
│   │   │           ├── file/       #   文件管理
│   │   │           ├── app/        #   应用管理
│   │   │           └── process/    #   进程管理
│   │   ├── api/                  # API 接口封装
│   │   ├── router/               # 路由配置
│   │   ├── store/                # 状态管理
│   │   └── components/           # 公共组件
│   └── .env                      # 环境变量（端口等）
├── release/                      # 构建产物
├── docs/                         # 文档
└── hotgo.db                      # SQLite 数据库文件（根目录，备用）
```

## 数据库配置

默认使用 SQLite，无需额外配置。如需切换数据库，修改 `server/config/config.yaml`：

```yaml
database:
  default:
    type: "sqlite"                # 可选: sqlite / mysql / pgsql
    link: "sqlite:./hotgo.db"
    debug: true                   # 开发时开启可查看 SQL 日志
```

### MySQL 示例

```yaml
database:
  default:
    type: "mysql"
    link: "mysql:root:password@tcp(127.0.0.1:3306)/hotgo?charset=utf8mb4"
```

## 投屏架构说明

系统采用 **scrcpy + WebSocket + WebCodecs** 的三层架构实现低延迟投屏：

1. **后端推流**：Go-scrcpy 启动 scrcpy-server，接收 H.264 视频流，解析 SPS/PPS 后通过 WebSocket 以二进制帧推送给前端
2. **前端解码**：浏览器使用 WebCodecs API（`VideoDecoder`）硬解 H.264，渲染到 `<canvas>`
3. **多设备订阅**：单个 WebSocket 连接可订阅多台设备，后端 `WsHub` 维护 serial → client 集合映射，按 serial 广播视频帧
4. **离线检测**：帧推送 goroutine 内置 15 秒心跳检测，超时无新帧则广播 `device:offline` / `screen:stop`
5. **反向控制**：前端通过 WebSocket 发送触控事件，后端转发给 Go-scrcpy 控制通道（pointerID 使用 `0xFFFFFFFFFFFFFFFE` 通用手指）

## 常见问题

### 1. 登录后只有系统默认菜单，看不到设备管理

**原因**：Android 设备管理插件的菜单未注册到数据库（`hg_admin_menu` 表 permissions 字段为空或缺少 type=3 按钮记录）。

**解决**：运行插件安装 SQL 脚本，确保菜单与按钮权限点完整注册（模块 type=2，按钮 type=3），重启服务端并重新登录。

### 2. 设备管理页面接口 404

**原因**：路由配置中 `router/admin.go` 和 API 的 `Meta` 路径存在重复前缀，导致实际路由路径与前端请求不匹配。

**解决**：已修复 `router/admin.go` 去掉重复的 Group 嵌套，并将所有 API 的 `Meta` 路径从 `/android-manager/xxx` 改为 `/xxx`。重新编译后端即可。

### 3. ADB 连接失败

- 确认设备已开启 USB 调试
- 确认 `adb` 命令已加入系统 PATH
- 检查 ADB 路径配置（系统设置 → 系统配置）
- WiFi 连接需确保设备与服务器在同一网络

### 4. 投屏黑屏或无法显示

**基础排查：**
- 确认已安装 `scrcpy-server.jar` 并配置正确路径（`release/data/scrcpy-server.jar`）
- 确认设备已正确连接（`adb devices` 可识别）
- 检查投屏码率设置，过高可能导致画面卡顿
- 浏览器需支持 WebCodecs API（Chrome 94+ / Edge 94+）

**后端启动成功但前端黑屏：**
- 查看后端日志是否有 `收到第N帧` 记录，若有说明 scrcpy 视频流正常
- 查看前端控制台是否有 `[投屏] 收到第N帧` 日志：
  - 若前端无日志 → WebSocket 客户端未正确绑定 serial，需确保 `screen:start` 消息处理时先 `Unsubscribe` 再 `Subscribe`
  - 若前端有日志但无画面 → 检查 VideoDecoder 配置是否成功（SPS/PPS 是否正确解析）
- 检查 `scrcpy-server` 端日志：`adb -s <serial> shell cat /data/local/tmp/scrcpy-server.log`

**已知依赖库 bug：**
- Go-scrcpy 的 `formatFloat` 函数会错误地将 `max_fps=30` 转换为 `max_fps=3`（`strings.TrimRight("30", "0")` 导致），需修复 `pkg/server/options.go` 中的 `formatFloat` 函数

### 5. 屏幕墙只有最后一个窗口刷新

**原因**：早期版本 `WsClient.Serial` 为单值字段，多设备投屏时会覆盖之前的绑定，导致 `BroadcastToSerial` 找不到客户端。

**解决**：已重构为多设备订阅模式，`WsClient.Serials` 改为 map，`WsHub.clients` 维护 serial → client 集合映射，通过 `Subscribe` / `Unsubscribe` 管理订阅关系。

### 6. 投屏窗口一直显示「投屏中」，设备掉线后不更新

**原因**：scrcpy 的 `FrameCh` 通道在设备掉线后不会立即关闭，导致后端 goroutine 阻塞、前端 UI 状态无法更新。

**解决**：后端帧推送 goroutine 已加入 15 秒心跳检测，超时无新帧自动广播 `device:offline` 和 `screen:stop`，前端收到事件后更新 UI 状态、关闭 VideoDecoder 并提示用户。

### 7. 投屏触控失效

**原因**：触控消息 pointerID 为 0 时会被 scrcpy 服务端视为无效指针。

**解决**：触控消息统一使用 `pointerID=0xFFFFFFFFFFFFFFFE`（通用手指）。

### 8. 服务端启动报端口冲突

修改 `server/config/config.yaml` 中的 `server.address` 端口：

```yaml
server:
  address: ":9000"                # 改为其他端口如 :9001
```

### 9. 路由重复注册错误

```
The duplicated route registry [...]
```

**原因**：`router/admin.go` 和 `router/genrouter/` 中重复绑定了同一个控制器。

**解决**：确保 `admin.go` 不重复绑定已在 `genrouter` 中注册的控制器。

### 10. 接口返回 `unknown status:51`

**原因**：后端分页参数 `pageSize` 校验规则为 `min:1|max:200`（见 `internal/model/input/form/page.go`），前端传 `perPage: 1000` 会触发校验失败。

**解决**：前端调用设备/列表类接口时，`pageSize` 不要超过 200。

### 11. 进程管理报「获取进程列表失败」

**原因**：老版本 Android（如 API < 26）的 `ps` 命令不支持 `-A` 参数，会返回 `bad pid '-A'`。

**解决**：后端 `logic/sys/process.go` 已实现自动回退：先尝试 `ps -A`，检测到 `bad pid '-A'` 错误后回退到 `ps`；同时动态解析表头列下标，兼容 8 列（老版）和 9 列（新版）两种输出格式。

### 12. 脚本/文件/应用/进程管理页面无法选择设备

**原因**：早期版本设备序列号字段为 `n-input` 手动输入框，易输错且体验差。

**解决**：已统一改为 `n-select` 下拉选择，自动从设备列表加载选项（显示「设备名 (序列号)」，值为序列号），支持搜索过滤，未选设备时查询按钮禁用，页面 `onMounted` 时自动加载设备列表。

## 开发指南

### 添加新功能

1. 在 `api/` 目录定义 API 请求/响应结构体
2. 在 `controller/` 目录实现控制器
3. 在 `logic/` 目录实现业务逻辑
4. 在 `router/` 目录注册路由
5. 在前端 `views/` 目录添加页面组件

### 代码生成

HotGo 框架内置代码生成工具，可快速生成 CRUD 相关代码：

```bash
go run main.go tools gen
```

### 定时任务

在 `crons/` 目录下添加定时任务：

```go
func init() {
    crons.Register("my_task", "*/5 * * * *", func(ctx context.Context) {
        // 每 5 分钟执行一次
    })
}
```

## 免责声明

- 本系统为开源学习项目，一切商业行为与本项目无关。
- 用户不得利用本系统从事非法行为，应当合法合规使用。
- 用户因使用本系统造成的任何法律责任由用户自行承担。

## License

[MIT](./LICENSE)