# RemotePad

**Repository Path**: annanxue/remote-pad

## Basic Information

- **Project Name**: RemotePad
- **Description**: 远程触摸板+鼠标+键盘
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Remote Touchpad

一个跨平台的远程触摸板应用程序，允许您通过手机或平板电脑控制计算机的鼠标和键盘。

## 功能特性

- 🖱️ **远程鼠标控制** - 通过触摸屏控制鼠标移动、点击和滚动
- ⌨️ **虚拟键盘** - 支持文本输入和媒体控制键
- 📱 **多平台支持** - 支持 Windows、Linux (X11/Wayland) 和 Flatpak
- 🔒 **安全连接** - 基于 HMAC-SHA256 的身份验证机制
- 🖼️ **实时屏幕截图** - 自动推送屏幕截图到客户端
- 🌐 **Ngrok 集成** - 支持通过 Ngrok 隧道实现外网访问
- 📐 **响应式设计** - 适配桌面、平板和手机屏幕

## 项目结构

```
RemotePad/
├── main.go                    # 应用程序入口和 WebSocket 服务器
├── webdata.go                 # 静态资源嵌入
├── webdata/                   # 前端资源
│   ├── index.html             # 主页面
│   ├── main.css               # 样式文件
│   ├── icon.woff              # 图标字体
│   └── app/                   # JavaScript 模块
│       ├── main.mjs           # 主入口
│       ├── ui.mjs             # UI 控制器
│       ├── touchpad.mjs       # 触摸板逻辑
│       ├── mouse.mjs          # 鼠标控制
│       ├── keyboard.mjs       # 键盘控制
│       ├── socket.mjs         # WebSocket 连接
│       └── inputcontroller.mjs # 输入控制接口
├── inputcontrol/              # 输入控制实现
│   ├── controller.go          # 控制器接口定义
│   ├── windows_controller.go  # Windows 实现
│   ├── x11_controller.go      # Linux X11 实现
│   ├── portal_controller.go   # Linux Wayland (xdg-desktop-portal)
│   ├── uinput_controller.go   # Linux uinput 实现
│   └── null_controller.go     # 空实现
├── screenshot/                # 屏幕截图功能
│   └── screenshot.go          # 截图实现（支持光标检测）
├── host/                      # 主机信息
│   └── host.go                # 主机名/IP 获取
├── terminal/                  # 终端工具
│   ├── terminal.go            # 终端控制
│   ├── qr.go                  # 二维码生成
│   └── terminal_*.go          # 平台特定实现
├── utils/                     # 工具函数
│   └── logger.go              # 日志系统
├── ngrok/                     # Ngrok 集成测试
├── web_e2e_test.go            # Playwright E2E 测试
├── go.mod                     # Go 模块定义
└── .env.example               # 环境变量示例
```

## 技术栈

### 后端
- **Go 1.25** - 主要编程语言
- **WebSocket** - 实时双向通信 (golang.org/x/net/websocket)
- **嵌入式静态资源** - 使用 `//go:embed` 嵌入前端文件
- **HMAC-SHA256** - 客户端身份验证

### 前端
- **原生 JavaScript (ES Modules)** - 无框架依赖
- **Touch Events** - 触摸板手势支持
- **Pointer Lock API** - 鼠标捕获
- **Fullscreen API** - 全屏支持

### 输入控制
- **Windows** - SendInput API
- **Linux X11** - XTest 扩展
- **Linux Wayland** - xdg-desktop-portal
- **Linux** - uinput 内核接口

## 快速开始

### 安装依赖

```bash
# 克隆仓库
git clone <repository-url>
cd RemotePad

# 安装 Go 依赖
go mod download

# 安装 Playwright 浏览器（用于 E2E 测试）
go run github.com/playwright-community/playwright-go/cmd/playwright install chromium
```

### 运行应用

```bash
# 基本运行
go run .

# 指定绑定地址
go run . -bind :8080

# 指定密钥
go run . -secret mysecret

# 启用 TLS
go run . -cert server.crt -key server.key

# 启用 Ngrok（需要设置 NGROK_AUTH_TOKEN 环境变量）
go run . -ngrok

# 查看所有选项
go run . -help
```

### 环境变量

创建 `.env` 文件：

```env
NGROK_AUTH_TOKEN=your_ngrok_token
```

## 命令行参数

| 参数 | 默认值 | 描述 |
|------|--------|------|
| `-bind` | `:0` | 服务器绑定地址 `[HOSTNAME]:PORT` |
| `-secret` | 随机生成 | 客户端认证密钥 |
| `-cert` | - | TLS 证书文件 |
| `-key` | - | TLS 私钥文件 |
| `-update-rate` | 30 | 每秒更新次数 |
| `-move-speed` | 1.0 | 触摸板移动速度倍数 |
| `-scroll-speed` | 1.0 | 触摸板滚动速度倍数 |
| `-mouse-move-speed` | 1.0 | 鼠标移动速度倍数 |
| `-mouse-scroll-speed` | 1.0 | 鼠标滚动速度倍数 |
| `-log-level` | 1 | 日志级别: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR |
| `-log-dir` | `logs` | 日志目录 |
| `-ngrok` | true | 启用 Ngrok 隧道 |
| `-ngrok-token` | - | Ngrok 认证令牌 |
| `-version` | - | 显示版本号 |

## WebSocket 协议

### 认证流程

1. 服务器发送随机挑战消息
2. 客户端使用 HMAC-SHA256(secret, message) 计算响应
3. 服务器验证响应，通过后发送配置信息

### 消息格式

```json
// 配置消息（服务器 → 客户端）
{
  "type": "config",
  "payload": {
    "updateRate": 30,
    "moveSpeed": 1.0,
    "scrollSpeed": 1.0,
    "mouseMoveSpeed": 1.0,
    "mouseScrollSpeed": 1.0
  }
}

// 截图消息（服务器 → 客户端）
{
  "type": "screenshot",
  "payload": {
    "image": "base64_encoded_webp_image",
    "cursorType": "arrow"
  }
}

// 命令消息（客户端 → 服务器）
{
  "type": "command",
  "payload": {
    "action": "m",
    "data": "10;20"
  }
}
```

### 命令类型

| 命令 | 格式 | 描述 |
|------|------|------|
| `m` | `m<deltaX>;<deltaY>` | 相对鼠标移动 |
| `a` | `a<x>;<y>` | 绝对鼠标移动 |
| `b` | `b<button>;<0\|1>` | 鼠标按钮按下/释放 |
| `s` | `s<deltaH>;<deltaV>` | 滚动（像素） |
| `S` | `S<deltaH>;<deltaV>` | 滚动（行） |
| `k` | `k<key>` | 按下特殊键 |
| `t` | `t<text>` | 输入文本 |

## 测试

### 单元测试

```bash
go test ./...
```

### E2E 测试

```bash
# 确保服务器已启动
go run .

# 运行 Playwright E2E 测试
go test -v -run TestAllButtons -timeout 120s .

# 运行所有 E2E 测试
go test -v -timeout 300s .
```

### 测试覆盖

- `TestPageLoad` - 页面加载测试
- `TestTouchpadScene` - 触摸板场景测试
- `TestMenuButton` - 菜单按钮测试
- `TestKeyboardButton` - 键盘按钮测试
- `TestFullscreenButton` - 全屏按钮测试
- `TestRefreshScreenshotButton` - 刷新截图按钮测试
- `TestKeysSceneButtons` - 按键场景测试
- `TestTextInputFunctionality` - 文本输入测试
- `TestResponsiveLayout` - 响应式布局测试
- `TestWebSocketConnection` - WebSocket 连接测试

## 构建

### 本地构建

```bash
# 构建当前平台
go build -o remote-touchpad .

# Windows
go build -o remote-touchpad.exe .

# Linux
GOOS=linux GOARCH=amd64 go build -o remote-touchpad-linux .

# macOS
GOOS=darwin GOARCH=amd64 go build -o remote-touchpad-darwin .
```

### 交叉编译

```bash
# Windows x64
GOOS=windows GOARCH=amd64 go build -o bin/remote-touchpad-windows-amd64.exe

# Windows x86
GOOS=windows GOARCH=386 go build -o bin/remote-touchpad-windows-386.exe

# Linux x64
GOOS=linux GOARCH=amd64 go build -o bin/remote-touchpad-linux-amd64

# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o bin/remote-touchpad-linux-arm64
```

## Linux/WSL2 支持

### 输入控制器

Linux 版本支持多种输入控制器，默认使用 **uinput**：

| 控制器 | 构建标签 | 说明 |
|--------|----------|------|
| uinput | 默认 | 内核级输入设备模拟，不依赖 X11/Wayland |
| X11 | `-tags x11` | 使用 XTest 扩展，需要 X Server |
| Wayland | `-tags portal` | 使用 xdg-desktop-portal |
| null | `-tags null` | 空实现，仅用于测试 |

### WSL2 配置

WSL2 默认未启用 uinput 支持，需要手动配置：

#### 1. 启用 uinput 模块

```bash
# 加载 uinput 内核模块
sudo modprobe uinput

# 验证模块已加载
lsmod | grep uinput
```

#### 2. 设置设备权限

```bash
# 创建 udev 规则（永久生效）
echo 'KERNEL=="uinput", MODE="0666", GROUP="input"' | sudo tee /etc/udev/rules.d/99-uinput.rules

# 重新加载规则
sudo udevadm control --reload-rules
sudo udevadm trigger

# 临时设置权限（立即生效，重启后失效）
sudo chmod 666 /dev/uinput
```

#### 3. 添加用户到 input 组

```bash
# 将当前用户加入 input 组
sudo usermod -a -G input $USER

# 重新登录使权限生效
```

#### 4. 运行程序

```bash
# 编译
go build .

# 使用 sudo 运行（如果需要）
sudo ./RemotePad

# 或普通用户运行（已配置权限后）
./RemotePad
```

### 常见问题

#### 错误："could not open device file"

**原因**：无法访问 `/dev/uinput` 设备

**解决**：
```bash
# 检查设备是否存在
ls -la /dev/uinput

# 临时解决方案
sudo chmod 666 /dev/uinput

# 或使用 sudo 运行
sudo ./RemotePad
```

#### 错误："compiled without controller"

**原因**：没有启用任何输入控制器

**解决**：确保使用默认构建（不带标签）或正确的构建标签：
```bash
# 默认构建（启用 uinput）
go build .

# 显式启用 X11
go build -tags x11 .

# 测试模式
go build -tags null .
```

#### WSL2 图形应用支持

如果在 WSL2 中运行图形应用，需要安装 X Server（如 VcXsrv）并设置 DISPLAY：

```bash
# 安装依赖
sudo apt-get install x11-apps

# 设置 DISPLAY（根据你的 X Server 配置）
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

# 验证
xclock
```

### 截图工具支持

Linux 版本支持多种截图工具，按优先级尝试：

| 工具 | 安装命令 | 说明 |
|------|----------|------|
| scrot | `sudo apt-get install scrot` | 轻量级，推荐 |
| gnome-screenshot | `sudo apt-get install gnome-screenshot` | GNOME 桌面环境 |
| ImageMagick | `sudo apt-get install imagemagick` | 功能强大 |
| xwd + convert | `sudo apt-get install x11-apps imagemagick` | X11 工具 |

**WSL2 安装示例：**

```bash
# 安装 scrot（推荐）
sudo apt-get update
sudo apt-get install -y scrot

# 或安装 imagemagick
sudo apt-get install -y imagemagick
```

## 平台支持

| 平台 | 控制器 | 状态 |
|------|--------|------|
| Windows | SendInput | ✅ 完整支持 |
| Linux X11 | XTest | ✅ 完整支持 |
| Linux Wayland | xdg-desktop-portal | ✅ 完整支持 |
| Linux/WSL2 | uinput | ✅ 完整支持（需配置）|

## 安全注意事项

⚠️ **警告**: 默认情况下 TLS 未启用，请勿在不受信任的网络中使用！

建议：
- 使用 `-cert` 和 `-key` 参数启用 TLS
- 使用强密钥 (`-secret`)
- 在受信任的网络中运行
- 使用 Ngrok 提供的 HTTPS 隧道

## 许可证

[LICENSE](LICENSE)

## 贡献

欢迎提交 Issue 和 Pull Request！

## 致谢

- 感谢 [kbinani/screenshot](https://github.com/kbinani/screenshot) 提供跨平台截图功能
- 感谢 [skip2/go-qrcode](https://github.com/skip2/go-qrcode) 提供二维码生成
- 感谢 [playwright-go](https://github.com/playwright-community/playwright-go) 提供 E2E 测试支持