Files
SimpleRemoter/linux/README.md
T
yuanyuanxianganddeepseek-flash 4d2abf34d0 Feature: Support the Tier 1 MCP tools on Linux clients
All of these tools already had a working wire protocol on the Linux
client (SystemManager.h, common/PTYHandler.h, ScreenHandler.h); only the
server-side client-type gates rejected LNX hosts. kill_process,
exec_command, terminal_open/exec/close and remote_open/close/mouse/
keyboard/clipboard now accept LNX and reject only MAC (plus APK where it
applied). No client change, no capability bit.

exec_command and terminal_exec needed platform-aware plumbing because a
POSIX shell understands none of the Windows constructs: the sentinel is
now "PS1=" / the command / "echo __MCP_DONE_<nonce>__$?" over the Linux
PTY, with output decoded as UTF-8. The PS1= line exists because
interactive bash prints its prompt after every line it reads, which
otherwise leaks into stdout; its echo sits ahead of the command echo and
is removed together with it. The Windows ConPTY and legacy non-PTY forms
are unchanged.

The default command whitelist is now platform-specific: identically named
POSIX commands can write files or change system state (find -exec,
sort -o, hostname), so kDefaultCmdWhitelistPosix only lists commands that
stay read-only even with arguments. env is deliberately excluded, since
"env <program>" runs arbitrary programs and would defeat the whitelist
entirely. An explicit McpCmdWhitelist still overrides both platforms. The
forbidden metacharacter set is split the same way: on Linux it covers
& | < > ; backtick and $( / ${ / !, where ! triggers history expansion in
interactive bash. ^ is not a POSIX metacharacter, so read-only commands
like "grep -v ^# /etc/hosts" are accepted on Linux while Windows keeps
rejecting them.

Input injection had to be sent one MSG64 per COMMAND_SCREEN_CONTROL
packet. The protocol allows batching and the Windows client handles it,
but linux/ScreenHandler.h only processes the first message of a packet,
so a batch left key_press stuck down (X11 autorepeat), click
half-pressed and type emitting only its first character. Splitting the
packets is equivalent for Windows, which processes one message at a time
anyway, and keeps already-deployed Linux clients working without an
upgrade.

Verified on a Debug server against a WSL Ubuntu 24.04 client and a
Windows client: exec_command returned real exit codes (0/1/2) with clean
output, -32007/-32008 negatives, and the POSIX-only ^ allowance;
persistent terminals kept cwd and environment, returned 1 for false and
the last exit code for ";" chains, and closed idempotently; kill_process
killed a test process, returned an empty remaining list and skipped
pid 1; remote_open reported 3840x1140, remote_mouse mapped (0.5,0.5) to
(1920,570), xev showed balanced press/release pairs for keys and buttons,
and a Chinese clipboard round-trip came back as UTF-8. The Windows
regression of the same tools was unchanged, including the multi-monitor
gate on remote_open.

Co-Authored-By: deepseek-flash
2026-10-27 21:15:44 +01:00

395 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SimpleRemoter Linux Client
SimpleRemoter 的 Linux 客户端,支持远程桌面、远程终端、文件管理和进程管理功能。
## 功能特性
- **远程桌面** - 实时屏幕截图传输,支持鼠标/键盘控制,支持多种压缩算法
- **远程终端** - 基于 PTY 的交互式 Shell
- **文件管理** - 远程文件浏览、上传、下载
- **进程管理** - 查看和管理远程进程
- **守护进程模式** - 支持后台运行 (`-d` 参数)
## 功能实现对比 (Linux vs Windows)
### 已实现
| 功能模块 | Linux 实现 | Windows 对应 | 状态 |
|---------|-----------|-------------|------|
| 远程桌面 | `ScreenHandler.h` | `ScreenManager.cpp` | ✅ 完整 (DIFF/RGB565/GRAY) |
| 进程管理 | `SystemManager.h` | `SystemManager.cpp` | ✅ 完整 |
| 文件管理 | `FileManager.h` | `FileManager.cpp` | ✅ 完整 |
| 远程终端 | `PTYHandler` (main.cpp) | `ConPTYManager.cpp` | ✅ 完整 |
| 心跳/RTT | main.cpp | `KernelManager.cpp` | ✅ 完整 |
| 用户活动检测 | `ActivityChecker` | `ActivityWindow` | ✅ 完整 |
| 系统信息采集 | main.cpp | `LoginServer.cpp` | ✅ 完整 |
| 守护进程 | daemonize() | Windows 服务 | ✅ 完整 |
| 剪贴板同步 | `ClipboardHandler.h` | `ScreenManager.cpp` | ✅ 服务端↔Linux |
| V2 文件传输 | `FileTransferV2.h` | `file_upload.h` | ✅ 服务端↔Linux(含 MCP `upload_file`/`download_file`:发送完成包带流式 SHA-256,路径不存在/无权限回 `TOKEN_DOWNLOAD_ERROR`) |
| C2C 文件接收 | `FileTransferV2.h` | `file_upload.h` | ✅ Windows/MCP → Linux(目标目录由服务端 `dst_dir` 指定,落盘后回执) |
| 配置持久化 | `LinuxConfig` | INI 文件 | ✅ 完整 |
| MCP 远程管理 | 复用 `SystemManager.h` / `PTYHandler.h` / `ScreenHandler.h` | 服务端 MCP | ✅ 档 1:`kill_process`、`exec_command`、`terminal_open/exec/close`、`remote_open/close/mouse/keyboard/clipboard`(服务端放开门禁,客户端协议本已实现) |
### 未实现
| 功能模块 | Windows 文件 | 命令 | 优先级 | 说明 |
|---------|-------------|------|-------|------|
| 会话管理 | `KernelManager.cpp` | `COMMAND_SESSION` | 高 | 关机/重启/注销 |
| 下载执行 | `KernelManager.cpp` | `COMMAND_DOWN_EXEC` | 高 | 下载并运行程序 |
| 服务管理 | `ServicesManager.cpp` | `COMMAND_SERVICES` | 中 | systemd 服务列表 |
| 键盘记录 | `KeyboardManager.cpp` | `COMMAND_KEYBOARD` | 中 | 需要 X11/evdev |
| 开机自启 | `auto_start.h` | - | 中 | systemd user service |
| 窗口列表 | `SystemManager.cpp` | `COMMAND_WSLIST` | 低 | X11 窗口枚举 |
| 音频监听 | `AudioManager.cpp` | `COMMAND_AUDIO` | 低 | 需要 PulseAudio/ALSA |
| 摄像头 | `VideoManager.cpp` | `COMMAND_WEBCAM` | 低 | 需要 V4L2 |
| 语音对讲 | `TalkManager.cpp` | `COMMAND_TALK` | 低 | 双向音频传输 |
| 清除日志 | `KernelManager.cpp` | `COMMAND_CLEAN_EVENT` | 低 | 清除 syslog |
| 注册表管理 | `RegisterManager.cpp` | `COMMAND_REGEDIT` | - | Linux 不适用 |
### 开发优先级说明
**高优先级** - 日常管理常用功能
- ~~剪贴板同步:跨平台复制粘贴~~ ✅ 已完成
- 会话管理:远程关机/重启
- 下载执行:远程部署程序
**中优先级** - 系统管理功能
- 服务管理:查看/控制 systemd 服务
- 键盘记录:输入监控
- 开机自启:持久化运行
**低优先级** - 硬件相关功能
- 音频/摄像头/语音:需要额外硬件库支持
## 系统要求
### 显示服务器
| 类型 | 支持状态 | 说明 |
|------|---------|------|
| X11 / Xorg | 支持 | 完全支持 |
| XWayland | 部分支持 | X11 应用可用,原生 Wayland 应用不可见 |
| Wayland (纯) | 不支持 | 无法工作 |
> **重要**: 本客户端使用 X11 API 进行屏幕捕获,**不支持纯 Wayland 环境**。
> 如果你使用 GNOME/KDE 等桌面环境,请在登录时选择 "Xorg" 或 "X11" 会话。
### 依赖库
#### 必需 (远程桌面功能)
| 库 | 包名 (Debian/Ubuntu) | 包名 (RHEL/Fedora) | 用途 |
|----|---------------------|-------------------|------|
| libX11 | `libx11-6` | `libX11` | X11 核心库,屏幕捕获 |
#### 推荐 (完整远程控制)
| 库 | 包名 (Debian/Ubuntu) | 包名 (RHEL/Fedora) | 用途 |
|----|---------------------|-------------------|------|
| libXtst | `libxtst6` | `libXtst` | XTest 扩展,模拟鼠标/键盘输入 |
#### 可选
| 库 | 包名 (Debian/Ubuntu) | 包名 (RHEL/Fedora) | 用途 |
|----|---------------------|-------------------|------|
| libXss | `libxss1` | `libXScrnSaver` | 获取用户空闲时间 |
| xclip | `xclip` | `xclip` | 剪贴板同步 (文本/文件) |
### 一键安装依赖
**Debian / Ubuntu:**
```bash
sudo apt update
sudo apt install libx11-6 libxtst6 libxss1 xclip
```
**RHEL / CentOS / Fedora:**
```bash
sudo dnf install libX11 libXtst libXScrnSaver xclip
```
**Arch Linux:**
```bash
sudo pacman -S libx11 libxtst libxss xclip
```
## 编译
### 编译依赖
```bash
# Debian/Ubuntu
sudo apt install build-essential cmake
# RHEL/Fedora
sudo dnf install gcc-c++ cmake make
```
### 编译步骤
```bash
cd linux
cmake .
make -j$(nproc)
```
编译成功后生成可执行文件 `ghost`。
## 使用方法
### 基本用法
```bash
./ghost [服务器IP] [端口]
```
### 守护进程模式
```bash
./ghost -d [服务器IP] [端口]
```
### 示例
```bash
# 前台运行,连接到 192.168.1.100:6543
./ghost 192.168.1.100 6543
# 后台守护进程模式
./ghost -d 192.168.1.100 6543
# 停止守护进程
kill $(cat ~/.config/ghost/ghost.pid)
```
## 远程升级
服务端选中一台 Linux 主机后点「升级程序」,即可把新的 `ghost` 推下去并自动重启。
### 服务端准备
按以下优先级取 ELF,前一级拿不到才看下一级:
| 顺序 | 来源 | 说明 |
|-----|------|------|
| 1 | `settings.ini` 的 `[settings] LinuxClientPath` | 显式指定。配了但读不到会直接报错,不会偷偷换成别的版本 |
| 2 | 服务端**程序目录**下的 `ghost_linux_amd64` | 换个文件即可,不必重编服务端 |
| 3 | 服务端 `res\ghost_linux` | 项目通用的外部资源目录 |
| 4 | 内嵌资源 `IDR_LINUX_GHOST` | 编译进服务端 exe(构建时取 `linux/ghost`),磁盘上什么都不用放 |
```ini
[settings]
LinuxClientPath=C:\build\ghost
```
第 4 级是编译时的快照,想换版本要么放到第 1~3 级,要么重编服务端。
只接受 64 位 x86_64 ELF(`ELFCLASS64` + `EM_X86_64`),其它文件会在下发前被拒绝并提示。
### 下发格式
```
[COMMAND_UPDATE:1][size:8 LE][ELF:size][md5:32 ASCII 小写 hex]
```
Windows 客户端的同名命令没有摘要(走内存加载器/更新器),LNX 多出 32 字节 MD5。
### 客户端行为
1. 校验长度、ELF magic、`e_machine` 与本机自身 ELF 头一致、MD5 匹配;
2. 在自身所在目录写临时文件 `.<名字>.new.<pid>`(0755)并 `fsync`;
3. 用 `rename()` 原子替换正在运行的二进制(Linux 允许替换执行中的 inode),
旧版本保留为 `<名字>.old`;
4. `fork` + `setsid` + 关闭继承的 fd + 等待老进程退出,再用**原始命令行** `execv` 新版本;
老进程以 `g_bExit = S_CLIENT_UPDATE` 正常退出,服务端立刻看到断线重连。
前提:客户端所在目录对运行用户可写(否则报「cannot create ...: Permission denied」)。
任何一步失败都不会退出进程,原因会写进客户端日志并发到服务端消息栏
(`Linux client update failed`)。
回滚:把 `ghost.old` 拷回 `ghost` 并重启即可(它会在下次升级时被覆盖)。
## 常见问题
### Q: 远程桌面功能不工作
**检查项:**
1. **确认使用 X11 会话**
```bash
echo $XDG_SESSION_TYPE
# 应输出 "x11",如果是 "wayland" 则不支持
```
2. **确认 DISPLAY 环境变量已设置**
```bash
echo $DISPLAY
# 应输出类似 ":0" 或 ":1"
```
3. **确认 X11 库已安装**
```bash
ldconfig -p | grep libX11
# 应输出 libX11.so.6 的路径
```
### Q: 鼠标/键盘控制不工作
安装 XTest 扩展库:
```bash
# Debian/Ubuntu
sudo apt install libxtst6
# RHEL/Fedora
sudo dnf install libXtst
```
### Q: 警告 "MIT-SCREEN-SAVER missing"
这是一个无害警告,表示无法获取用户空闲时间。可以忽略,或安装 libXss:
```bash
# Debian/Ubuntu
sudo apt install libxss1
# RHEL/Fedora
sudo dnf install libXScrnSaver
```
### Q: 如何在 Wayland 环境下使用?
目前不支持纯 Wayland。需要切换到 X11 会话。
**方法1:登录时选择 X11 会话**
- 在登录界面点击用户名后,右下角会出现齿轮图标 ⚙️
- 点击齿轮,选择 "Ubuntu on Xorg" 或 "GNOME on Xorg"
**方法2:强制禁用 Wayland(推荐)**
如果找不到齿轮图标,可以修改 GDM 配置强制使用 X11:
```bash
sudo nano /etc/gdm3/custom.conf
```
在 `[daemon]` 部分添加:
```ini
[daemon]
WaylandEnable=false
```
保存后重启系统:
```bash
sudo reboot
```
这样系统将始终使用 X11,无需每次手动选择。
**KDE 桌面环境:**
- 登录界面选择 "Plasma (X11)"
- 或编辑 `/etc/sddm.conf` 设置默认会话
### Q: 如何检查当前会话类型?
```bash
# 查看会话类型
echo $XDG_SESSION_TYPE
# 查看显示服务器信息
loginctl show-session $(loginctl | grep $(whoami) | awk '{print $1}') -p Type
```
## 配置文件
配置文件位于 `~/.config/ghost/config.conf`,存储以下信息:
| 配置项 | 说明 | 示例值 |
|-------|------|-------|
| `InstallTime` | 首次安装时间 | `1709856000` |
| `PublicIP` | 公网 IP 缓存 | `1.2.3.4` |
| `GeoLocation` | 地理位置缓存 | `北京市` |
| `QualityLevel` | 屏幕质量等级 | `2` (Good / H264 1080P) |
### 质量等级说明
| 值 | 等级 | FPS | 算法 |
|----|------|-----|------|
| -1 | 自适应 | 动态 | 动态 |
| 0 | Ultra | 30 | DIFF |
| 1 | High | 25 | DIFF |
| 2 | Good | 20 | RGB565 |
| 3 | Medium | 15 | RGB565 |
| 4 | Low | 10 | RGB565 |
| 5 | Minimal | 8 | GRAY |
## 剪贴板同步
### 支持的操作
| 方向 | 操作 | 状态 |
|------|------|------|
| 服务端 → Linux | 服务端 Ctrl+C,远程窗口 Ctrl+V | ✅ 支持 |
| Linux → 服务端 | 远程窗口 Ctrl+C,服务端 Ctrl+V | ✅ 支持 |
| Linux ↔ Linux (C2C) | 远程A Ctrl+C,远程B Ctrl+V | ❌ 暂不支持 |
### 支持的内容类型
| 类型 | 说明 |
|------|------|
| 文本 | 纯文本剪贴板内容 |
| 文件 | 单文件/多文件/文件夹,保留目录结构 |
### 依赖
需要安装 `xclip` 工具:
```bash
# Debian/Ubuntu
sudo apt install xclip
# RHEL/Fedora
sudo dnf install xclip
```
### 技术实现
- 文本剪贴板:`xclip -selection clipboard`
- 文件剪贴板:`xclip -t text/uri-list` 读取文件路径
- 编码转换:服务端 GBK ↔ Linux UTF-8 自动转换
## 技术细节
### 屏幕捕获流程
1. 使用 `XCopyArea` 将 root window 拷贝到离屏 Pixmap
2. 使用 `XGetImage` 从 Pixmap 获取图像数据
3. 转换为 BGRA 格式并翻转行序 (BMP 格式要求)
4. 计算帧差异,仅传输变化区域
### 屏幕压缩算法
| 算法 | 带宽占用 | 说明 |
|------|---------|------|
| DIFF | 4 字节/像素 | 原始 BGRA,最高画质 |
| RGB565 | 2 字节/像素 | 16位色,节省 50% 带宽 |
| GRAY | 1 字节/像素 | 灰度,节省 75% 带宽 |
| H264 | - | 暂不支持,自动降级为 RGB565 |
算法由服务端根据网络状况自适应选择,或可手动指定。
### 输入模拟
使用 XTest 扩展 (`libXtst`) 实现:
- `XTestFakeMotionEvent` - 鼠标移动
- `XTestFakeButtonEvent` - 鼠标点击
- `XTestFakeKeyEvent` - 键盘输入
### 为何不支持 Wayland?
Wayland 出于安全考虑,禁止应用程序:
- 捕获其他应用的屏幕内容
- 模拟全局输入事件
这些限制使得传统远程桌面方案无法在纯 Wayland 下工作。