# ai-remote

**Repository Path**: willionjake_admin/ai-remote

## Basic Information

- **Project Name**: ai-remote
- **Description**: 远程控制
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Remote: 远程控制演示工具

> AI-PK大赛参赛作品 — 浏览器零安装主控 + 全平台单文件轻量被控

## 项目简介

AI-Remote 是一个面向终端安全管理场景的远程控制演示工具，采用 **「浏览器零安装主控 + 全平台单文件轻量被控」** 架构。控制方无需安装任何软件，打开浏览器即可发起远程控制；被控方仅需运行一个几 MB 的轻量客户端，覆盖 Windows / macOS / Linux / 安卓四大平台。服务端为 Go 语言单二进制部署，前端资源通过 `go embed` 嵌入二进制，双击运行自动打开管理后台。

架构对标行业标杆 **Apache Guacamole**（HTML5 远控事实标准），落地参考 Go 生态成熟项目 screego、robotgo，在两天周期内实现可用版本。

## 核心获奖亮点

1. **主控零门槛** — 浏览器即开即用，零安装演示，服务端单二进制启动内置 Web 页面，一分钟完成演示环境搭建
2. **全平台覆盖** — Windows / macOS / Linux / 安卓四大平台，被控端单文件无依赖，双击运行用完即删
3. **轻量到极致** — 纯 Go 实现，空闲内存 < 20MB，CPU < 5%，无后台服务无捆绑
4. **性能不降级** — JPEG/WebP 帧编码 + 分块差分传输 + 全链路异步流水线，端到端延迟 < 200ms
5. **工业级安全** — 连接码认证 + 原生授权弹窗（显示来源 IP）+ 操作审计日志 + 危险命令拦截
6. **管理大屏** — 实时监控所有在线设备、会话状态、审计日志，独立 `/admin` 路由

## 架构概览

```
┌─────────────────────────────────────────────────────────┐
│         主控层（浏览器 / 纯前端）                        │
│  连接面板 / Canvas屏幕渲染 / 键鼠触控事件捕获            │
│  Vue3 + 原生Canvas，静态资源嵌入Go二进制                 │
└──────────────────────┬──────────────────────────────────┘
                       │ WebSocket + HTTPS
┌──────────────────────▼──────────────────────────────────┐
│         中心服务层（Go 单二进制）                        │
│  Web服务 + 信令调度 + 中继转发 + 会话管理               │
│  单文件启动，同时承担Web门户、信令、中继角色             │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│  │ Session │ │ Relay    │ │ Web      │ │ Auth        │ │
│  │ Manager │ │ Forward  │ │ Server   │ │ Manager     │ │
│  └─────────┘ └──────────┘ └──────────┘ └─────────────┘ │
└──────────────────────┬──────────────────────────────────┘
                       │ 自定义二进制协议
┌──────────────────────▼──────────────────────────────────┐
│         被控Agent层（全平台 Go 实现）                    │
│  Windows / macOS / Linux / 安卓                          │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│  │ Screen  │ │ Input    │ │ Command  │ │ File        │ │
│  │ Capture │ │ Inject   │ │ Executor │ │ Transfer    │ │
│  └─────────┘ └──────────┘ └──────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
```

## 标准演示连接流程

1. 演示方启动服务端程序，自动打开 Web 控制后台
2. 客户设备运行对应平台的轻量被控端，屏幕显示 **6 位数字连接码**
3. 演示方在浏览器输入连接码，被控端弹出 **授权确认**（弹窗显示来源 IP）
4. 客户点击「允许」，浏览器页面立即出现远程屏幕，可直接鼠标 / 键盘控制
5. 支持随时切换被控设备、多设备并排展示

## 技术栈

| 模块 | 技术选型 | 选型理由 |
|------|---------|--------|
| 中心服务端 | Go + gorilla/websocket | 高并发、易打包、单二进制部署 |
| Web 前端 | Vue3 + Canvas + WebSocket | 轻量易开发，Canvas 渲染性能最优 |
| 桌面被控端 | Go + Win32 API（Windows） | 零 CGO，纯 Go 调用系统 API |
| 安卓被控端 | Go Mobile + 安卓系统 API | 核心逻辑复用 Go 代码，APK 体积极小 |
| 编码与压缩 | JPEG（默认零 CGO）/ WebP（可选 CGO）+ 分块差分 | JPEG 用 Go 标准库零依赖；WebP 压缩率高 30%，通过 build tag 按需启用 |
| 打包部署 | Go embed + UPX 压缩（可选） | 前端嵌入二进制，压缩后单文件 < 15MB |

## 功能特性

- **远程屏幕控制** — 实时屏幕捕获 + 鼠标/键盘/触控输入注入，JPEG 编码 + 分块差分传输 + 自适应 FPS/质量
- **连接码接入** — 6 位数字连接码，被控端原生授权弹窗（Win32 自绘窗口，显示来源 IP），安全合规
- **远程命令终端** — 在线 Shell（CMD/PowerShell/Bash），实时输出回显，危险命令拦截
- **文件传输** — 远程文件浏览、上传、下载（50MB 限制）
- **系统监控** — CPU、内存、磁盘实时监控仪表盘
- **多会话管理** — 多标签页同时控制多台设备，会话列表统一管理
- **管理大屏** — 实时监控所有在线设备、会话状态、审计日志
- **全平台覆盖** — Windows / macOS / Linux / 安卓，单文件无依赖
- **安全传输** — TLS 加密 + 连接码认证 + 授权弹窗 + 操作审计日志
- **断线重连** — Agent 指数退避自动重连 + 前端 WebSocket 自动重连（最多 10 次）
- **实时 FPS 指标** — 屏幕流传输时右上角实时显示帧率

## 目录结构

```
ai-remote/
├── README.md                     # 项目总览（本文档）
├── Agent.md                      # 红线规则与最低交付标准
├── go.mod                        # Go 模块定义
├── go.sum                        # Go 依赖校验
├── Makefile                      # 跨平台构建脚本
├── build.ps1                     # Windows 一键构建脚本（PowerShell）
├── .gitignore
│
├── docs/                         # 项目文档
│   ├── SPEC.md                   # 需求规格说明书
│   ├── HLD.md                    # 概要设计文档
│   ├── DDD.md                    # 详细设计文档（工业级）
│   ├── API.md                    # 通信协议 API 文档
│   ├── TASK_PLAN.md              # AI 任务计划
│   ├── ACCEPTANCE.md             # 验收标准文档
│   ├── DESIGN.md                 # 设计概要
│   ├── AI_INTERACTION.md         # AI 交互过程记录（英文）
│   ├── 与AI交互文档.md            # AI 交互过程记录（中文，持续更新）
│   └── ui/                       # UI 设计资源
│
├── cmd/                          # 程序入口
│   ├── server/
│   │   ├── main.go               # 服务端入口（embed 前端 + SPA fallback）
│   │   └── dist/                 # 嵌入的前端构建产物（自动生成）
│   └── agent/
│       └── main.go               # 被控端入口（支持 --server / --no-reconnect）
│
├── internal/                     # 内部包
│   ├── server/                   # 服务端逻辑
│   │   ├── server.go             # HTTP/WebSocket 服务核心 + 信令处理
│   │   ├── hub.go                # 会话管理 + 连接码管理 + 上下线通知
│   │   ├── relay.go              # 中继转发管道（双向消息转发）
│   │   ├── auth.go               # 认证管理器（会话/授权/超时清理）
│   │   └── audit.go              # 审计日志（连接/授权/命令/文件操作）
│   │
│   ├── agent/                    # 被控端逻辑
│   │   ├── agent.go              # Agent 核心（连接/重连/消息处理）
│   │   ├── console.go            # 控制台 UI（彩色日志/状态显示/连接码）
│   │   ├── dialog_windows.go     # Win32 原生授权弹窗（自绘窗口+倒计时）
│   │   ├── dialog_unix.go        # macOS/Linux 授权弹窗（osascript/zenity）
│   │   ├── dll_windows.go        # Win32 DLL 懒加载（user32/gdi32）
│   │   ├── screen.go             # 屏幕采集核心（差分/自适应FPS/质量）
│   │   ├── screen_windows.go     # Windows 屏幕截图实现
│   │   ├── screen_other.go       # 非 Windows 屏幕截图占位
│   │   ├── input.go              # 输入注入调度
│   │   ├── input_windows.go      # Windows 键鼠注入（Win32 API）
│   │   ├── input_other.go        # 非 Windows 键鼠注入占位
│   │   ├── executor.go           # 命令执行 + 系统信息 + 危险命令拦截
│   │   ├── fileutil.go           # 文件操作工具
│   │   └── recovery.go           # goroutine panic 恢复
│   │
│   └── transport/                # 传输层
│       └── conn.go               # WebSocket 连接封装（写泵/心跳/超时）
│
├── pkg/                          # 公共包
│   └── proto/
│       └── proto.go              # 消息协议定义（类型常量/编解码/二进制帧）
│
└── web/                          # Web 前端（Vue3 + TypeScript）
    ├── package.json
    ├── vite.config.ts
    ├── tsconfig.json
    ├── index.html
    └── src/
        ├── main.ts               # 应用入口 + 路由配置
        ├── App.vue               # 根组件
        ├── style.css             # 全局样式
        ├── env.d.ts              # 环境类型声明
        ├── views/                # 页面视图
        │   ├── ConnectView.vue   # 连接码输入页
        │   ├── DashboardView.vue # 主控仪表盘
        │   ├── AdminView.vue     # 管理大屏（设备监控/审计日志）
        │   └── ErrorView.vue     # 错误页
        ├── components/
        │   ├── ControlBar.vue    # 屏幕控制工具栏（开始/停止/截图/质量）
        │   ├── base/             # 基础组件
        │   │   ├── BaseButton.vue
        │   │   ├── BaseEmpty.vue
        │   │   ├── BaseSpinner.vue
        │   │   ├── CodeInput.vue     # 6 位连接码输入框
        │   │   ├── StatusBar.vue     # 连接状态指示器
        │   │   └── ToastContainer.vue# Toast 通知容器
        │   ├── layout/           # 布局组件
        │   │   ├── AppHeader.vue     # 顶部导航
        │   │   ├── AppFooter.vue     # 底部状态栏
        │   │   ├── SessionSidebar.vue# 左侧会话列表
        │   │   └── TabBar.vue        # 功能标签栏
        │   └── views/            # 功能视图
        │       ├── ScreenView.vue    # Canvas 屏幕渲染 + FPS 指标
        │       ├── TerminalView.vue  # 远程终端
        │       ├── FileView.vue      # 文件管理
        │       └── SystemView.vue    # 系统监控仪表盘
        ├── composables/
        │   ├── useWebSocket.ts   # WebSocket 组合式函数（自动重连）
        │   └── useToast.ts       # Toast 通知组合式函数
        └── types/
            └── index.ts          # TypeScript 类型定义
```

## 快速开始

### 环境要求

- Go 1.22+
- Node.js 18+（仅开发/构建前端时需要）
- UPX（可选，用于压缩二进制）

### 一键构建

#### Windows（PowerShell）

```powershell
# 构建全部（前端 + 服务端 + 被控端）
.\build.ps1

# 仅构建前端
.\build.ps1 -Target web

# 仅构建服务端
.\build.ps1 -Target server

# 仅构建被控端
.\build.ps1 -Target agent

# 构建 + UPX 压缩（可能触发杀毒误报，可选）
.\build.ps1 -Compress
```

构建产物输出到 `bin/` 目录：
- `bin/server.exe` — 服务端（含嵌入前端）
- `bin/agent.exe` — 被控端

#### 跨平台（Makefile）

```bash
# 构建全部
make build

# 仅构建服务端
make server

# 仅构建被控端
make agent

# 构建前端
make web

# 交叉编译（macOS/Linux Agent）
make agent-macos
make agent-linux

# 清理构建产物
make clean
```

#### 手动构建（分步）

```powershell
# 1. 构建前端
cd web
npm install
npm run build
cd ..

# 2. 复制前端产物到服务端嵌入目录
Copy-Item -Path web\dist\* -Destination cmd\server\dist\ -Recurse -Force

# 3. 构建服务端（零 CGO）
$env:CGO_ENABLED = "0"
go build -ldflags="-s -w" -o bin\server.exe ./cmd/server

# 4. 构建被控端（零 CGO，Windows 隐藏控制台窗口）
go build -ldflags="-s -w -H windowsgui" -o bin\agent.exe ./cmd/agent
```

### 运行服务端 (Server)

```bash
# 默认端口 9418
.\bin\server.exe

# 指定端口
.\bin\server.exe --addr :9090

# 启用 TLS（生产环境推荐）
.\bin\server.exe --tls-cert cert.pem --tls-key key.pem

# 反向代理部署（Nginx/宝塔等）
.\bin\server.exe --external-url http://remote.qxue.tech
```

启动后浏览器访问 `http://localhost:9418` 即可进入连接码输入页。

### 反向代理部署（Nginx / 宝塔面板）

当 Server 运行在内网，通过 Nginx 反向代理对外暴露域名时，需要配置 WebSocket 转发。

**Nginx 配置示例：**

```nginx
server {
    listen 80;
    server_name remote.qxue.tech;

    location / {
        proxy_pass http://127.0.0.1:9418;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
    }

    location /ws/ {
        proxy_pass http://127.0.0.1:9418;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_read_timeout 86400s;
    }
}
```

**启动 Server：**
```bash
.\bin\server.exe --external-url http://remote.qxue.tech
```

**Agent 连接：**
```bash
.\bin\agent.exe --server ws://remote.qxue.tech
```

或在 Agent 设置界面中修改服务器地址为 `ws://remote.qxue.tech`。

### 运行被控端 (Agent)

```bash
# Windows（默认连接 ws://localhost:9418）
.\bin\agent.exe

# 指定服务器地址
.\bin\agent.exe --server ws://192.168.1.100:9418

# 使用 TLS
.\bin\agent.exe --server wss://remote.example.com:443

# 禁用自动重连（调试用）
.\bin\agent.exe --no-reconnect
```

Agent 启动后控制台显示：
- 彩色 Banner（Hostname / OS / PID / 启动时间）
- **6 位连接码**（青色边框 + 绿色粗体数字）
- 实时状态日志（INFO/WARN/ERROR/AUTH 带时间戳）

### 进入管理大屏

管理大屏提供设备监控、会话状态、审计日志的实时总览。

**方式一：直接访问 URL**

```
http://localhost:9418/admin
```

**方式二：从连接页进入**

在连接码输入页（`/`）底部，点击「管理大屏」按钮即可跳转。

**管理大屏功能：**
- 在线设备列表（Hostname / OS / IP / 状态）
- 实时统计（在线数 / 总会话数 / 审计日志数）
- 审计日志流（连接 / 授权 / 命令 / 文件操作 / 断开）
- 设备上下线实时 Toast 通知

### 演示流程

1. **启动 Server** — `.\bin\server.exe`，浏览器自动打开 `http://localhost:9418`
2. **启动 Agent** — 在受控设备运行 `.\bin\agent.exe`，控制台显示 6 位连接码
3. **输入连接码** — 在浏览器连接页输入连接码，点击「连接」
4. **授权确认** — 受控设备弹出 Win32 原生授权弹窗（显示来源 IP），点击「允许」
5. **开始控制** — 浏览器进入主控仪表盘，可进行屏幕控制 / 远程终端 / 文件管理 / 系统监控
6. **管理大屏** — 访问 `/admin` 查看所有设备状态和审计日志

### 连接状态说明

| 状态 | 含义 | 用户可见提示 |
|------|------|-------------|
| `idle` | 等待输入连接码 | "请输入被控端显示的 6 位连接码" |
| `connecting` | 正在连接服务器 | "正在连接服务器..." |
| `waiting_auth` | 等待被控端授权 | "等待被控端授权... (请在被控设备上确认)" |
| `connected` | 授权成功 | "授权成功，正在进入控制面板..." |
| `rejected` | 授权被拒绝 | "授权被拒绝 — 被控端用户拒绝了连接请求" |
| `error` | 连接码无效 | "连接码不存在或已过期，请检查后重试" |
| `locked` | 尝试次数过多 | "尝试次数过多，已被临时锁定，请稍后再试" |
| `disconnected` | 连接断开 | "与服务器连接已断开"（可点击"重新连接"） |

## 开发计划

| 阶段 | 内容 | 状态 |
|------|------|------|
| P1 | 核心框架搭建：Server + Web 雏形 + Windows Agent 原型 | ✅ 完成 |
| P2 | 核心功能闭环：控制指令双向传输 + JPEG/差分 + 授权弹窗 | ✅ 完成 |
| P3 | 多平台扩展：macOS/Linux + 亮点功能 | ✅ 完成 |
| P4 | 打包优化 + 演示打磨：交叉编译 + UPX + 演示脚本 | ✅ 完成 |
| P5 | 文档编写 + 最终提交 | ✅ 完成 |
| P6 | 工业级闭环补全：重连/审计/通知/管理大屏 | ✅ 完成 |
| P7 | UX 优化升级：结构化日志/来源IP/超时检测/FPS指标 | ✅ 完成 |

## 文档

- [需求规格说明书](docs/SPEC.md)
- [概要设计文档](docs/HLD.md)
- [详细设计文档](docs/DDD.md)
- [通信协议 API](docs/API.md)
- [AI 任务计划](docs/TASK_PLAN.md)
- [验收标准](docs/ACCEPTANCE.md)
- [AI 交互过程记录](docs/与AI交互文档.md)
- [UI 设计说明](docs/ui/UI_DESIGN.md)
- [红线规则](Agent.md)

## License

MIT