Files
SimpleRemoter/docs/Client_Capability_Matrix.md
T
yuanyuanxianganddeepseek-flash de9e9a7369 Feature(client): support host transfer in the macOS client
Mirror the Android semantics: move the main link to the assigned master
immediately, persist the record in config so it survives restarts, return
to the original master on expiry or early return, and revert after the new
master stays unreachable for 60s. Share requests are answered as
unsupported, and the capability matrix is updated accordingly.

A target counts as unusable when the connection is refused or when it is
accepted but never passes MasterSettings (a foreign service on that port,
or a master built with another key). The latter used to be retried forever,
stranding the host until expiry; both shapes now count toward the revert
gate and reset only once a connection verifies. Early return clears the
persisted record at once, so a crash before the main loop restores the
original master cannot resurrect the transfer on restart.

Endpoints from the command or the record are bounds-checked before being
written into CONNECT_ADDRESS (strcpy_s is strcpy on POSIX), config access
is serialized across the receive and main threads, the new validTo is
published before the pending target so expiry cannot undo a fresh
transfer, and a stale early-return flag is cleared when a new transfer
applies or one is reverted.

The Linux client was rebuilt with the shared header changes; the macOS
side is not compiled here and still needs a build on a Mac.

Co-Authored-By: deepseek-flash
2026-11-21 10:15:35 +01:00

14 KiB
Raw Blame History

客户端能力矩阵

以 Windows 客户端为基线,对比 Linux、macOS、Android 客户端的实现情况。表中所有主表行在 Windows 列均为 ✓;其他平台按实际代码判断,不做推测。

  • 依据:各平台客户端源码(client/、linux/、macos/、android/app/src/main/)与登录能力位(common/commands.h 的 DefaultCaps()),代码基线 main@d9fe93f(2026-11-19)。
  • linux/README.md 里的「未实现」清单部分已过时(例如开机自启已由 install.sh 实现),以本表为准。
  • 图例:✓ 已实现;△ 部分实现或依赖运行环境;— 未实现。
  • 服务端侧功能(主机列表、备注/分组、上线提醒、授权管理界面、MCP、Web 控制台等)不在本表范围。

一、连接与传输

功能 Windows Linux macOS Android
TCP 直连 ✓ ✓ ✓ ✓
WebSocket / WSS 传输(出包时选择) ✓ ✓ ✓ ✓
TLS 加密传输 ✓ ✓ ✓ ✓
子连接 ConnAuth 身份校验 ✓ ✓ ✓ ✓
断线自动重连 ✓ ✓ ✓ ✓
心跳与活动窗口上报 ✓ ✓ ✓ ✓
服务端修改分组 ✓ ✓ ✓ ✓
UDP / KCP / HTTP 伪装传输 ✓ — — —
并发上线(多实例并行) ✓ — — —
远程切换传输协议(TCP/WS/WSS) ✓ — — —
客户端 ID 重建(克隆机撞 ID) ✓ — — —
分享主机 / 取消分享 ✓ ✓ — —
转移主机(到期自动复原) ✓ ✓ ✓ ✓

说明:

  • 分享/转移:Android 实现转移、不实现分享(收到分享命令会回“不支持”);macOS 同样只实现转移(收包即迁移主连接,记录存 ~/.config/ghost/config.conf 的 transfer 键,连不上目标满 60 秒且连续失败 3 次后退回原主控),分享命令回“不支持”。
  • WebSocket/WSS 是“出包能力”,不是“运行时切换能力”:四个平台的网络层(IOCPClient + WsChannel.h)都实现了 WS/WSS,生成客户端时把「协议」选为 WebSocket 或 WS+TLS 即可,客户端启动后按烘焙的 protoType 连接(需经反向代理入口;WSS 还需内嵌或在线下发的信任锚)。但运行时的「协议切换」菜单走 COMMAND_SET_PROTO,只有 Windows 客户端处理该命令并声明 CLIENT_CAP_PROTO_SWITCH;其他平台该菜单整组置灰,菜单里勾选 TCP 只是当前实际连接的传输,不代表客户端只能走 TCP。
  • UDP/KCP/HTTP 伪装传输:只有 Windows 客户端有对应实现;Linux/macOS/Android 的网络层只处理 TCP/WS/WSS,出包时选其他协议不会生效。
  • 并发上线(RUNNING_PARALLEL)只有 Windows 客户端实现;其他平台按单实例运行。
  • 客户端 ID 重建同样仅 Windows 处理。
  • TLS:macOS 复用 client/TlsChannelLinux.cpp,实机验证仍待补;Android/Linux 已随 TLS 开关使用。

二、远程桌面

功能 Windows Linux macOS Android
实时屏幕查看 ✓ ✓ ✓ ✓
H.264 编码与关键帧请求 ✓ ✓ ✓ △
画质档位下发(自适应/固定档) ✓ ✓ ✓ ✓
帧率设置(CMD_FPS) ✓ — — ✓
远程桌面调优 / 硬编码 / SSE2 ✓ — — —
鼠标/键盘注入 ✓ ✓ ✓ △
剪贴板同步 ✓ ✓ ✓ △
剪贴板文件同步(复制文件/路径) ✓ ✓ ✓ —
锁定目标键鼠 ✓ — — ✓
隐私屏幕(独立桌面) ✓ — — —
多显示器整桌面捕获 ✓ △ — —
切换显示器 ✓ — — —
黑白屏幕(灰度传输) ✓ ✓ ✓ —
区域/窗口级截图 ✓ — — —
全屏 / 远程光标视图偏好 ✓ ✓ — —
滚动优化 / 多线程压缩 ✓ — — —
RDP 会话归位 / 虚拟桌面重置 / 窗口切换 ✓ — — —
自定义光标 ✓ — — —
屏幕缩略图预览 ✓ ✓ ✓ ✓
远程音频监听 ✓ — — ✓
远程摄像头 ✓ — — ✓
键盘记录 ✓ — — —
即时消息/远程交谈 ✓ — — ✓
远程画板 ✓ — — —

说明:

  • 剪贴板:Windows/Linux/macOS 支持读取与写入;Android 只处理服务端下发的“写入并粘贴”,不支持读取设备剪贴板。
  • 剪贴板文件同步:Windows/Linux/macOS 在剪贴板里是文件时返回文件清单/内容(COMMAND_GET_FOLDER / COMMAND_GET_FILE),Android 没有文件剪贴板协议。
  • 缩略图预览:Linux 需有可截图的 X11 会话,macOS 需已授予录屏权限,Android 需无障碍服务与 API 30+;条件不满足时客户端不声明对应能力位,服务端会提前拒绝。
  • 画质配置表(CMD_QUALITY_PROFILES)仅 Windows/Android 处理;Linux/macOS 只处理单档 CMD_QUALITY_LEVEL。
  • 关键帧请求(COMMAND_SCREEN_KEYFRAME_REQ):Windows/Linux/macOS 处理(Web 屏幕墙恢复用);Android 未处理该命令,只在注入手势后主动请求 IDR。
  • 鼠标/键盘注入:Windows/Linux/macOS 是完整键鼠注入;Android 把鼠标映射为触摸手势,只支持 Back/Home/Apps/截图/粘贴等少量按键,没有通用键盘注入。
  • 帧率设置:Android 处理 CMD_FPS;CMD_SCREEN_TUNING 在 Android 上是显式 no-op,COMMAND_ENCODE_LEVEL(硬编码选择)只有 Windows 处理。
  • 多显示器:Windows 支持整桌面捕获和按显示器切换;Linux 总是抓 X root(含所有显示器),不能按显示器选择;macOS 只抓主显示器。
  • 全屏/远程光标:Windows 与 Linux 会把主控端的视图偏好落盘并在下次打开时上报;macOS/Android 没有这两个偏好命令。
  • 黑白屏幕(灰度传输):Windows/Linux/macOS 处理 ALGORITHM_GRAY;Android 没有该算法,收到后会忽略灰度标志。
  • RDP 会话归位/虚拟桌面重置/窗口切换:均为 Windows 屏幕子连接命令,其他平台没有对应实现。
  • 键盘记录仅在 Windows 客户端实现(支持实时与离线落盘、清除);其他平台没有输入钩子。
  • 远程音频为单向麦克风监听(Windows/Android);双向语音对讲/麦克风回传未实现(评估后放弃)。Windows 的音频开关支持持久化(CMD_AUDIO_CTRL),Android 不支持。
  • 远程摄像头:Windows 支持压缩开关与分辨率调整;Android 固定 1280×720@8fps JPEG。
  • Android 的锁定键鼠、黑屏遮罩、锁屏(映射 GLOBAL_ACTION_LOCK_SCREEN)都依赖无障碍服务,客户端按运行时状态追加 PRIVACY_OVERLAY / LOCK_SCREEN 能力位;Windows 无锁屏/黑屏对应行,故未列入主表。

三、文件管理

功能 Windows Linux macOS Android
磁盘/目录浏览 ✓ ✓ ✓ ✓
上传/下载 ✓ ✓ ✓ ✓
V2 文件传输通道 ✓ ✓ ✓ ✓
断点续传 ✓ — — —
删除/重命名/新建目录 ✓ ✓ ✓ ✓
文件搜索 ✓ — — ✓
压缩/解压 ✓ — — —
客户端间 C2C 文件直传 ✓ △ △ —
客户端间 C2C 剪贴板文本 ✓ △ △ —
文件复制/粘贴 / 属性 / 最近文件 / 网上邻居 / 远程打开 / 强制删除 ✓ — — —
文件加密/解密(经典文件管理器) ✓ — — —
插件文件管理(SimplePlugins) ✓ — — —

说明:

  • 断点续传:仅 Windows 客户端处理 COMMAND_FILE_QUERY_RESUME / COMMAND_FILE_RESUME;其他平台走 V2 普通传输,不响应续传查询。
  • C2C 文件:Windows 支持发送(CLIENT_CAP_C2C_PATHS)与接收(COMMAND_C2C_PREPARE/_RESP);Linux/macOS 只做接收端并在落盘后回执(CLIENT_CAP_C2C_RECV_ACK);Android 未实现。C2C 需要收发两端能力配合,单端具备能力不等于任意两平台之间都能直传。
  • C2C 剪贴板文本(COMMAND_C2C_TEXT):Windows 能发送也能接收;Linux/macOS 只处理接收端(服务端下发文本后写入本机剪贴板,Linux 需要 xclip/xsel);Android 未实现。
  • 文件复制/粘贴、属性、最近文件、网上邻居、远程打开、强制删除:Windows 经典文件管理器的扩展命令;Linux/macOS/Android 的 V2 文件管理只提供目录浏览与增删改,没有这些入口。
  • 文件加密/解密:Windows 客户端处理 COMMAND_FILE_Encryption / COMMAND_FILE_Decrypt;其他平台没有对应实现。
  • 插件文件管理(SimplePlugins):Windows 的「实验功能 → 文件管理」走 COMMAND_FILE_MANAGER_PLUGIN;其他平台没有该插件入口。

四、系统管理

功能 Windows Linux macOS Android
进程列表 ✓ ✓ ✓ △
结束进程 ✓ ✓ ✓ △
进程冻结/解冻/删除 ✓ — — —
窗口列表 ✓ — △ —
窗口操作(激活/移动/置顶/关闭) ✓ — — —
远程终端(PTY) ✓ ✓ ✓ ✓
服务管理(启动/停止/暂停/删除) ✓ — — —
计划任务管理 ✓ — — —
注册表管理 ✓ — — —
系统信息/机器管理 ✓ — — —
已安装软件清单/卸载 ✓ — — —
电源操作(关机/重启/注销) ✓ — — —
下载执行 / 上传执行 / DLL 执行 ✓ — — —
代理映射/端口转发 ✓ — — —
提权运行(UAC) ✓ — — —
进程注入(记事本 / Shellcode) ✓ — — —
连接管理(连接列表/强制断开) ✓ — — —
远程封禁(强制终止客户端) ✓ — — —

说明:

  • Android 进程列表/结束进程依赖 root;非 root 设备登录时不声明 CLIENT_CAP_PROCESS,服务端直接返回“不支持”。
  • 窗口列表:macOS 只提供应用列表(PID 当伪句柄),不是窗口级枚举;Linux 的 COMMAND_WSLIST 只回一个空 TOKEN_WSLIST(无 GUI 窗口管理),Android 仅上报当前活动窗口标题。窗口移动/置顶/关闭只有 Windows 实现。
  • 机器管理(Windows)在同一面板下还提供网络连接、浏览器历史、收藏夹、HOSTS 文件、驱动服务等清单/编辑能力;其他平台没有对应面板。
  • 电源操作仅 Windows 实现(MCP power_action 也只放行 Windows 主机)。
  • 连接管理:Windows 客户端枚举本机 TCP 连接并通过 SetTcpEntry 强制断开;其他平台没有 COMMAND_CONNECTION / COMMAND_KILL_CONNECTION 处理。
  • 远程封禁(COMMAND_FORBIDDEN)只有 Windows 客户端处理(直接 TerminateProcess 退出);其他平台收到命令会走 default 丢弃。

五、监控与审计

功能 Windows Linux macOS Android
拉取客户端运行日志 ✓ ✓ ✓ ✓
历史活动上报 ✓ ✓ ✓ ✓

六、升级与运维

功能 Windows Linux macOS Android
远程升级 ✓ ✓ — ✓
TLS 开关下发 ✓ ✓ ✓ ✓
自启动/服务化 ✓ ✓ ✓ △
远程卸载 ✓ — — ✓
授权/许可校验(V2) ✓ — — —

说明:

  • 远程升级:Windows 替换 PE、Linux 替换 ELF、Android 下发 APK 并拉起系统安装器(尚未真机验收);macOS 客户端没有 COMMAND_UPDATE 分支,暂不支持自升级。
  • 自启动:Windows 安装为系统服务;Linux 注册 XDG autostart(install.sh,另有 -d 守护进程模式);macOS 添加登录项;Android 为前台服务,但清单里没有 BOOT_COMPLETED 接收器,重启设备后需手动启动一次。
  • 远程卸载:Linux/macOS 仅提供本地 uninstall.sh,服务端命令不会被处理。
  • 授权/许可:V2 授权校验、服务端「延长授权/撤销授权」只对 Windows 客户端生效;其他平台不参与授权校验。

七、平台前提与已知边界

  • Windows:功能最全;能力位未声明的终端、进程、聊天等功能实际已实现(服务端历史上按平台名放行)。
  • Linux:抓屏与注入依赖 X11/XTest;Wayland 会话下抓屏不可用。安装脚本要求以普通桌面用户运行,以注册 autostart。
  • macOS:屏幕录制与辅助功能需要用户在“隐私与安全性”里授权;更新二进制会导致授权失效,需要重新授权。自升级未实现。
  • Android:屏幕预览/注入依赖无障碍服务;进程管理依赖 root;文件管理依赖全盘访问权限(MANAGE_EXTERNAL_STORAGE);远程摄像头、音频、锁屏、黑屏遮罩需相应系统权限或 API 级别;APK 在线升级已编码但尚未真机验收。

八、能力位对照(登录上报)

服务端从 moduleVersion 的 -XXXX 后缀解析能力位(DefaultCaps()):

平台 默认能力位 运行时追加
Windows V2、UTF8、SCREEN_PREVIEW、C2C_PATHS、PROTO_SWITCH、VIRTUAL_DESKTOP、WINDOW_INFO、SCREEN_REGION 仅当本次连接走 TLS 且使用内嵌锚时追加 EMBEDDED_ANCHOR
Linux V2、UTF8、C2C_RECV_ACK、PROCESS SCREEN_PREVIEW(有可抓 X11 桌面时)
macOS V2、UTF8、TERMINAL、SCREEN_CLIPBOARD、PROCESS、C2C_RECV_ACK SCREEN_PREVIEW(已授录屏权限时)
Android V2、UTF8、APK_UPDATE、SCREEN_CLIPBOARD、UNINSTALL、REMOTE_CHAT、TERMINAL SCREEN_PREVIEW、LOCK_SCREEN、PRIVACY_OVERLAY、PROCESS(按无障碍/API/root 状态)

注意:Windows 的终端、进程、聊天、剪贴板、卸载等能力虽未在能力位中声明,但客户端实际实现并被服务端按平台放行;其他平台的能力位缺失会被服务端提前拒绝。