Files
SimpleRemoter/linux/README.md
T
yuanyuanxianganddeepseek-flash 913b74097b Improve: ship release builds without debug info and symbols
linux/CMakeLists.txt forced -g into the global flags regardless of build
type, so even a Release build carried full DWARF: 7.7MB of the 10.3MB
binary was .debug_* material the client never uses at runtime.

Drop the forced -g and default CMAKE_BUILD_TYPE to Release, stripping the
symbol table at link time (-s) so only Debug builds keep symbols. Do the
same for macOS with ld64's -Wl,-x on Release, which drops the 8.3k local
symbols while keeping external ones and the signature ld appends.

linux/ghost drops from 10.3MB to 2.5MB (UPX on top: 0.87MB). Rebuilt
under WSL and verified with readelf: no .debug_*/.symtab/.strtab, BuildID
kept. The macOS change is not verified here; it needs a build on the Mac.

Co-Authored-By: deepseek-flash
2026-11-20 17:40:00 +01:00

19 KiB
Raw Blame History

SimpleRemoter Linux Client

SimpleRemoter 的 Linux 客户端,支持远程桌面、远程终端、文件管理和进程管理功能。

功能特性

  • 远程桌面 - 实时屏幕截图传输,支持鼠标/键盘控制,支持多种压缩算法
  • 屏幕预览 - 服务端双击主机弹缩略图、在线列表缩略图、MCP get_screenshot
  • 远程终端 - 基于 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 ✅ 完整
历史活动 LinuxActivityHistory.h ActivityHistory.cpp ✅ 双后端(有桌面:X11 前台窗口驻留,格式与 Windows 一致;无桌面:last 登录记录 + bash/zsh 命令历史,activity_commands=0 可关闭命令采集)
系统信息采集 main.cpp LoginServer.cpp ✅ 完整
守护进程 daemonize() Windows 服务 ✅ 完整
剪贴板同步 ClipboardHandler.h ScreenManager.cpp ✅ 服务端↔Linux
屏幕预览(缩略图) ScreenPreview.cpp client/ScreenPreview.cpp ✅ 完整(X11 抓屏 → 缩放 → 原始 BGRA 上报,由服务端统一编码 JPEG;双击预览、列表缩略图、MCP get_screenshot 均可用。无 DISPLAY 时不声明能力位,服务端不会发请求)
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 指定,落盘后回执)
主机转移 common/host_transfer.h + main.cpp KernelManager.cpp ✅ 完整(COMMAND_ASSIGN_MASTER,真的转移:收包后立刻断开原主控、主连接连到新主控,旧主控上这台主机随即离线;新主控可正常远控/升级,但不能再转移或分享它;到期自动回原主控)
主机分享 common/host_share.h + main.cpp KernelManager.cpp / ClientDll.cpp ✅ 完整(每条分享记录 fork 一个 --share 子进程,主连接不受影响;取消分享立即断开,重启自动恢复)
配置持久化 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。

默认按 Release 构建(-O3,链接时 -s 剥离符号表,产物约 2.5MB,不含调试信息)。 需要 gdb 调试或保留 DWARF 时改用:

cmake -DCMAKE_BUILD_TYPE=Debug .            # -g(未优化)
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .   # -O2 -g -DNDEBUG

使用方法

基本用法

./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。

客户端行为

  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 并重启即可(它会在下次升级时被覆盖)。

主机转移

服务端选中一台主机后点「转移主机」,选目标主控和有效天数,客户端会:

  1. 把目标写进 ~/.config/ghost/config.conf 的 transfer 键(ip:port:transport:shine:valid_to);
  2. 立刻断开当前主控,主连接改连新主控——转移是把这条主连接搬走,不是另开一条。 老主控上这台主机随即离线,--share 那种旁路连接在这里是不对的:新主控拿到的 会是一条不能升级、也不真正属于它的连接;
  3. 新主控从此可以像自己的主机一样操作它:远控、文件、终端、升级程序都正常;
  4. 过了有效天数自动回到转移前的原主控——原地址只记在内存里(启动参数或编译期默认), 不写回配置,所以重启后仍然有效;到期时按原地址重连。

转移期间(now <= valid_to)客户端会拒绝两件事:再次转移和分享。前者是为了防止 主机被 B 转到 C、到期却按 A 复原,中间那一跳成为谁也不认的孤儿;后者是因为主机此刻只 连着新主控,新主控无权再把它分出去。两条都会回一条消息进服务端消息栏,不会静默丢弃。

注意事项:

  • 目标是永久转移(天数填 0)时客户端会拒绝,避免把主机改到一个不可达的地址后无法回退;
  • 有效期内重复下发会被忽略(与 Windows 客户端一致);
  • 转移期间切换传输方式(明文 / WS / WSS)会跟随服务端下发的 transport 段;
  • 「取消分享」只收掉分享子进程,撤销不了转移;
  • 只想把主机要回来,直接把 transfer 键清空并重启客户端即可。

主机分享

服务端选中一台主机后点「分享主机」,填目标主控地址,客户端会:

  1. 把记录追加进 ~/.config/ghost/config.conf 的 share_list 键 (多条用 | 分隔,每条 ip:port[:shine[:transport]],与 Windows 的 settings/share_list 格式一致);
  2. 不动主连接,另起一个子进程 <exe> --share <记录> 连到目标主控。 子进程复用同一份登录/心跳/命令处理代码,有自己的日志文件 (log_<月份>_<pid>.txt)和自己的重连循环。

跨平台部分在 common/host_share.h(命令解析、记录编解码、按 ip:port 去重), macOS 可直接复用。

注意事项:

  • 同一个 ip:port 只保留一条记录,换了传输方式会替换旧记录并重启对应的子进程; 完全相同的记录重复下发会被忽略,不会断开已有分享连接;
  • 分享实例不再响应「分享主机」「转移主机」「升级程序」——分享链不能一层套一层, 二进制也不能几个进程同时替换;
  • 「取消分享」在 Linux 上立即生效(Windows 是清空配置、下次启动才生效), 会杀掉所有分享子进程并清空 share_list;「转移主机」建立的那条连接不属于分享, 不受影响;
  • 主实例退出(含被 kill -9)时子进程跟着退出(PR_SET_PDEATHSIG);
  • 分享链路的传输方式在分享那一刻固定,之后主连接切 TCP/WS/WSS 不会影响它;
  • TLS 信任锚是整机一份(TlsEnabledFor 只看进程,不看目标主控),而 COMMAND_TLS_ENABLE / COMMAND_TLS_DISABLE 只作用于主连接、分享实例不处理。 所以分享到一台不在当前信任锚覆盖范围内的主控时,子进程会按 fail-closed 直接 握手失败、反复重连;要么先给这台主机装好包含该主控 CA 的信任锚,要么用明文分享。

历史活动

服务端「客户管理 → 历史活动」与 MCP get_activity_history 取的是同一次上报 (COMMAND_QUERY_ACTIVITY → TOKEN_REPORT_ACTIVITY)。客户端在启动时按有没有 桌面挑一个后端,之后不再切换:

后端 触发条件 内容
窗口 DISPLAY 可用且能连上 X 服务器 后台每秒采样前台窗口,格式与 Windows 客户端一致:[YYYY-MM-DD HH:MM:SS] [窗口标题] 时长。驻留不足 5 秒不记录,空闲 5 分钟算打断,内存保留最近 500 条,最新在前;重启客户端后重新累计
无头 没有 DISPLAY / 连不上 X(服务器、容器、systemd 服务) 查询时现算:登录记录来自 last -n 100 -F,命令历史来自 root 和 /home/* 下的 .bash_history、.zsh_history,每行带 [登录] / [命令] 标签,首行 [来源] 说明

无头后端把额度按 6:4 分给登录记录和命令历史(登录至少 10 行),并且 reboot 记录最多保留 10 条——WSL/容器每启动一次就写一条 reboot,不设上限会把真正的 登录和命令全挤掉。

无头后端的登录记录和命令历史合并后按时间戳统一排序(新的在前,时间未知的排最后), 所以服务端/MCP 按 offset 分页时「offset=0」真的是最近的那些。

窗口后端有两个已知边界:

  • X 起来了但没有 EWMH 窗口管理器(Xvfb、裸 X):_NET_ACTIVE_WINDOW 永远读不到。 启动时用根窗口上的 _NET_SUPPORTING_WM_CHECK 判一下,没有就直接按无头后端走。
  • 没装 libXss(很少见):拿不到空闲时间,一直按「在用」算,同一窗口会一路累加 时长,锁屏也不会打断。装了 libxss1 就正常。

命令历史的时间戳取决于 shell 配置:bash 需要 HISTTIMEFORMAT,zsh 需要 EXTENDED_HISTORY,否则只能拿到命令本身,显示为 [时间未知]。

隐私开关:在 ~/.config/ghost/config.conf 里写 activity_commands=0,无头后端就只上报 登录记录、不读任何 shell 历史。每次查询都重新读配置,改完不用重启。

常见问题

Q: 远程桌面功能不工作

检查项:

  1. 确认使用 X11 会话

    echo $XDG_SESSION_TYPE
    # 应输出 "x11",如果是 "wayland" 则不支持
    
  2. 确认 DISPLAY 环境变量已设置

    echo $DISPLAY
    # 应输出类似 ":0" 或 ":1"
    
  3. 确认 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)
transfer 主机转移记录(空 = 未转移),见「主机转移」 1.2.3.4:443:6:0:1790000000
share_list 主机分享记录(空 = 未分享),竖线分隔,见「主机分享」 1.2.3.4:443:0:6
activity_commands 无头后端是否采集 shell 命令历史(1 = 采集,0 = 只报登录记录),见「历史活动」 1

质量等级说明

值 等级 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 自动转换

技术细节

屏幕捕获流程

  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 下工作。