A Go-managed host cannot receive the client upgrade that only the MFC master can push. Transfer moves its main link there and brings it back after N days; MFC has no reason to return it. Transfer is not share: ASSIGN writes the target and drops the current connection, so the old master sees the host go offline and the new master gets a normal main link it can remote control and upgrade. While a transfer is live the client refuses a second transfer and any share, so no host is handed to a third master that expiry would orphan. Server: admin-only `transfer_device` WS command, COMMAND_ASSIGN_MASTER + SHARE_TYPE_YAMA_FOREVER as `host:port:days::transport\0`, byte-compatible with the MFC dialog. The transport segment is always present (YAMA_TRANSFER_TRANSPORT, default 0/TCP) because clients keep their current link when it is missing: a WSS-managed host would otherwise retry WSS against the MFC master's raw TCP port and never connect. The empty shine segment keeps the host's header encryption. The button only renders when `device_list.transfer` is present, which MFC never sends, so no MFC change is needed. devicehistory keeps transfer_to/transfer_until for the card badge and drops the marker on expiry or on a fresh login here. Client: KernelManager.cpp writes the registry and disconnects; ClientDll.cpp re-reads the registry at the top of every reconnect, so a mid-session transfer lands on the next round. Expiry is checked before every connect attempt as well as inside the heartbeat loop, so an unreachable target cannot pin the host to an expired address until a restart; restoring rebuilds the link captured on entry (address, header encryption, transport). linux/main.cpp applies the transfer on the main loop and restores the captured endpoint at expiry; Android does the same; macOS has neither share nor transfer.
19 KiB
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。
使用方法
基本用法
./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 并重启即可(它会在下次升级时被覆盖)。
主机转移
服务端选中一台主机后点「转移主机」,选目标主控和有效天数,客户端会:
- 把目标写进
~/.config/ghost/config.conf的transfer键(ip:port:transport:shine:valid_to); - 立刻断开当前主控,主连接改连新主控——转移是把这条主连接搬走,不是另开一条。
老主控上这台主机随即离线,
--share那种旁路连接在这里是不对的:新主控拿到的 会是一条不能升级、也不真正属于它的连接; - 新主控从此可以像自己的主机一样操作它:远控、文件、终端、升级程序都正常;
- 过了有效天数自动回到转移前的原主控——原地址只记在内存里(启动参数或编译期默认), 不写回配置,所以重启后仍然有效;到期时按原地址重连。
转移期间(now <= valid_to)客户端会拒绝两件事:再次转移和分享。前者是为了防止
主机被 B 转到 C、到期却按 A 复原,中间那一跳成为谁也不认的孤儿;后者是因为主机此刻只
连着新主控,新主控无权再把它分出去。两条都会回一条消息进服务端消息栏,不会静默丢弃。
注意事项:
- 目标是永久转移(天数填 0)时客户端会拒绝,避免把主机改到一个不可达的地址后无法回退;
- 有效期内重复下发会被忽略(与 Windows 客户端一致);
- 转移期间切换传输方式(明文 / WS / WSS)会跟随服务端下发的
transport段; - 「取消分享」只收掉分享子进程,撤销不了转移;
- 只想把主机要回来,直接把
transfer键清空并重启客户端即可。
主机分享
服务端选中一台主机后点「分享主机」,填目标主控地址,客户端会:
- 把记录追加进
~/.config/ghost/config.conf的share_list键 (多条用|分隔,每条ip:port[:shine[:transport]],与 Windows 的settings/share_list格式一致); - 不动主连接,另起一个子进程
<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: 远程桌面功能不工作
检查项:
-
确认使用 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) |
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 自动转换
技术细节
屏幕捕获流程
- 使用
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 下工作。