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
12 KiB
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:
sudo apt update
sudo apt install libx11-6 libxtst6 libxss1 xclip
RHEL / CentOS / Fedora:
sudo dnf install libX11 libXtst libXScrnSaver xclip
Arch Linux:
sudo pacman -S libx11 libxtst libxss xclip
编译
编译依赖
# Debian/Ubuntu
sudo apt install build-essential cmake
# RHEL/Fedora
sudo dnf install gcc-c++ cmake make
编译步骤
cd linux
cmake .
make -j$(nproc)
编译成功后生成可执行文件 ghost。
使用方法
基本用法
./ghost [服务器IP] [端口]
守护进程模式
./ghost -d [服务器IP] [端口]
示例
# 前台运行,连接到 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),磁盘上什么都不用放 |
[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。
客户端行为
- 校验长度、ELF magic、
e_machine与本机自身 ELF 头一致、MD5 匹配; - 在自身所在目录写临时文件
.<名字>.new.<pid>(0755)并fsync; - 用
rename()原子替换正在运行的二进制(Linux 允许替换执行中的 inode), 旧版本保留为<名字>.old; fork+setsid+ 关闭继承的 fd + 等待老进程退出,再用原始命令行execv新版本; 老进程以g_bExit = S_CLIENT_UPDATE正常退出,服务端立刻看到断线重连。
前提:客户端所在目录对运行用户可写(否则报「cannot create ...: Permission denied」)。
任何一步失败都不会退出进程,原因会写进客户端日志并发到服务端消息栏
(Linux client update failed)。
回滚:把 ghost.old 拷回 ghost 并重启即可(它会在下次升级时被覆盖)。
常见问题
Q: 远程桌面功能不工作
检查项:
-
确认使用 X11 会话
echo $XDG_SESSION_TYPE # 应输出 "x11",如果是 "wayland" 则不支持 -
确认 DISPLAY 环境变量已设置
echo $DISPLAY # 应输出类似 ":0" 或 ":1" -
确认 X11 库已安装
ldconfig -p | grep libX11 # 应输出 libX11.so.6 的路径
Q: 鼠标/键盘控制不工作
安装 XTest 扩展库:
# Debian/Ubuntu
sudo apt install libxtst6
# RHEL/Fedora
sudo dnf install libXtst
Q: 警告 "MIT-SCREEN-SAVER missing"
这是一个无害警告,表示无法获取用户空闲时间。可以忽略,或安装 libXss:
# 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:
sudo nano /etc/gdm3/custom.conf
在 [daemon] 部分添加:
[daemon]
WaylandEnable=false
保存后重启系统:
sudo reboot
这样系统将始终使用 X11,无需每次手动选择。
KDE 桌面环境:
- 登录界面选择 "Plasma (X11)"
- 或编辑
/etc/sddm.conf设置默认会话
Q: 如何检查当前会话类型?
# 查看会话类型
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 工具:
# Debian/Ubuntu
sudo apt install xclip
# RHEL/Fedora
sudo dnf install xclip
技术实现
- 文本剪贴板:
xclip -selection clipboard - 文件剪贴板:
xclip -t text/uri-list读取文件路径 - 编码转换:服务端 GBK ↔ Linux UTF-8 自动转换
技术细节
屏幕捕获流程
- 使用
XCopyArea将 root window 拷贝到离屏 Pixmap - 使用
XGetImage从 Pixmap 获取图像数据 - 转换为 BGRA 格式并翻转行序 (BMP 格式要求)
- 计算帧差异,仅传输变化区域
屏幕压缩算法
| 算法 | 带宽占用 | 说明 |
|---|---|---|
| DIFF | 4 字节/像素 | 原始 BGRA,最高画质 |
| RGB565 | 2 字节/像素 | 16位色,节省 50% 带宽 |
| GRAY | 1 字节/像素 | 灰度,节省 75% 带宽 |
| H264 | - | 暂不支持,自动降级为 RGB565 |
算法由服务端根据网络状况自适应选择,或可手动指定。
输入模拟
使用 XTest 扩展 (libXtst) 实现:
XTestFakeMotionEvent- 鼠标移动XTestFakeButtonEvent- 鼠标点击XTestFakeKeyEvent- 键盘输入
为何不支持 Wayland?
Wayland 出于安全考虑,禁止应用程序:
- 捕获其他应用的屏幕内容
- 模拟全局输入事件
这些限制使得传统远程桌面方案无法在纯 Wayland 下工作。