# HamRemote **Repository Path**: yzycoc/ham-remote ## Basic Information - **Project Name**: HamRemote - **Description**: 跨平台 Android 远程控制框架 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-25 - **Last Updated**: 2026-07-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# HamRemote **Control Anywhere.** — 开源免费的跨平台 Android 远程控制框架 HamRemote 是一套开源免费的跨平台 Android 远程控制框架，支持 **USB + ADB** 与 **App 被控** 两种接入方式，提供远程看屏、触控与设备管理能力。 提供 REST API、Web 管理台与 Windows / Android / iOS 客户端；[MIT](LICENSE) 协议免费开放，**可私有化部署**，支持局域网直连，亦可配合 服务器部署 / 内网穿透进行远程控制。
[![License: MIT](https://img.shields.io/badge/License-MIT-3b82f6?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/) [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Android%20%7C%20iOS-0078D4?style=for-the-badge&logo=windows&logoColor=white)](clients/) [![Gitee](https://img.shields.io/badge/Gitee-ham--remote-C71D23?style=for-the-badge&logo=gitee&logoColor=white)](https://gitee.com/yzycoc/ham-remote) [![Version](https://img.shields.io/badge/Release-0.5.0--beta-6366f1?style=for-the-badge)](https://gitee.com/yzycoc/ham-remote)
[快速开始](#-快速开始) · [功能特性](#-功能特性) · [目录结构](#-目录结构) · [客户端](#-客户端) · [安全提示](#-安全提示)
--- ## 功能特性 | | | |---|---| | **设备管理** | USB 连接、设备列表、详情、截图 | | **远程看屏** | Web SSE / 截图通道；H.264 低延迟（WebCodecs 或原生客户端） | | **自动化** | uiautomator2 签到、简单脚本、定时任务 | | **开箱即用** | Windows x64 内置 ADB + scrcpy-server；首次启动自动生成 `API_KEY` | ## 环境要求 | 组件 | 必需 | 说明 | |:--|:--:|--| | Python 3.12+ | 是 | 后端运行环境 | | USB 调试手机 | 是 | 数据线连接运行后端的电脑 | | Windows x64 内置工具 | 否 | 仓库已含 `backend/util/tools/win64/`（约 10MB） | | JDK 17 + Android SDK | 否 | 仅 `bin/build-android.bat` 打包 APK 时需要 | ## 快速开始 ### 1. 克隆与安装 ```powershell git clone https://gitee.com/yzycoc/ham-remote.git cd ham-remote python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` ### 2. 连接手机并启动 ```powershell # USB 连接手机，开启 USB 调试 bin\start.bat ``` > **首次启动** 会自动创建 `config/.env` 并在控制台打印 **API_KEY**，Web 控制台登录时填写即可。 ### 3. 访问 | 入口 | 地址 | |------|------| | 首页 | http://127.0.0.1:8790/ | | Web 控制台 | http://127.0.0.1:8790/console/ | | API 文档 | http://127.0.0.1:8790/docs | | 健康检查 | http://127.0.0.1:8790/api/health | ### 打包客户端 需安装对应工具链。编译产物输出到项目根目录 **`dist/`**（已加入 `.gitignore`）。 版本号在 [`config/client-versions.json`](config/client-versions.json) 修改，构建前会自动同步。 | 脚本 | 产物 | 额外依赖 | |------|------|----------| | `bin\build-android.bat` | `dist\ham-Pilot.apk` | JDK 17 + Android SDK | | `bin\build-android-server.bat` | `dist\ham-View.apk` | JDK 17 + Android SDK | | `bin\build-windows.bat` | `dist\HamRemote.exe` | Node.js + npm | **版本号**统一在 [`config/client-versions.json`](config/client-versions.json) 修改，构建前会自动执行 `python -m backend.util.apply_versions` 同步到各客户端。 ```powershell bin\build-android.bat bin\build-windows.bat ``` ### 路径前缀（nginx / FRP） 控制台登录页填写与地址栏一致的前缀，例如 `adb` 或 `frp/adb`。 | 访问方式 | 路径前缀 | |----------|----------| | 直连 `http://IP:8790/console/` | 留空 | | nginx `http://IP:8080/adb/console/` | `adb` | | FRP `http://域名/frp/adb/console/` | `frp/adb` | ## 客户端 Web 浏览器 H.264 受 WebCodecs / HTTPS 限制；**低延迟请用原生客户端**： | 目录 | 平台 | |------|------| | [`clients/windows/`](clients/windows/) | Electron（Windows） | | [`clients/android/`](clients/android/) | WebView + MediaCodec | | [`clients/ios/`](clients/ios/) | WKWebView（需 macOS + Xcode） | 详见 [clients/README.md](clients/README.md)。 ## 目录结构 ``` ham-remote/ ├── bin/ # 核心脚本 │ ├── start.bat # 启动后端 │ ├── build-android.bat # 打包 Android 控制端 APK → dist/ │ ├── build-android-server.bat │ └── build-windows.bat # 打包 Windows 便携版 → dist/ ├── backend/ │ ├── util/tools/win64/ # 内置 ADB / scrcpy-server │ ├── automation/complex/ # 复杂自动化 Python 脚本 │ └── web/ # 官网 + Web 控制台 ├── config/ # .env.example；运行时 .env 自动生成 ├── docs/ # 对外文档与截图（见 docs/README.md） └── clients/ # 多端客户端（ham Pilot / ham View） ``` 个人脚本、日志、FRP 配置等请放在 **`temp/`**（不入库）。AI 协作者见根目录 `AGENTS.md`（本机专用，亦不入库）。 ## API 概览 | 方法 | 路径 | 说明 | |:--:|--|--| | `GET` | `/api/health` | 健康检查 | | `GET` | `/api/devices` | 设备列表 | | `GET` | `/api/device/{serial}` | 设备详情 | | `GET` | `/api/screenshot/{serial}` | 截图 | | `POST` | `/api/checkin` | 执行签到 | 若设置了 `API_KEY`，请求需携带头：`X-API-Key: <你的密钥>`。 ## 安全提示 > 将手机控制权暴露到公网**风险极高**。若对外提供服务，请务必： > > 1. 使用强随机 `API_KEY`（首次启动已自动生成） > 2. 使用 **HTTPS** + 反向代理 > 3. **不要**将 ADB 5037 端口暴露到公网 > 4. 勿提交 `config/.env`、`temp/` 等敏感或本地文件 ---
**HamRemote** — Control Anywhere. Created by [Hamster](https://yzycoc.com) · [yzycoc@gmail.com](mailto:yzycoc@gmail.com) [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) [![Gitee Star](https://gitee.com/yzycoc/ham-remote/badge/star.svg?theme=dark)](https://gitee.com/yzycoc/ham-remote/stargazers)