lachlanchen/uu-remote-ubuntu-bridge

这是一个实验性的兼容性桥接工具，它在一个隔离的 Wine prefix 中运行官方 Windows UU 客户端，通过本地 RDP 中继呈现真实的 GNOME 桌面，并使鼠标和键盘控制能够正常工作。 | 功能 | 验证结果 | | --- | --- | | 桌面视频 | `1920x1080` 分辨率下的 GNOME 实时会话 | | 鼠标 | 通过 UU 进行移动、按键、滚轮、焦点和点击操作 | | 键盘 | 物理按键、快捷键以及标准化的手机输入法文本 | | 恢复 | 用户 systemd 重启、开机自启动以及 DLL 重新注入 | | 稳定性 | 一个 UU 服务端 PID 超越了之前的四分钟故障窗口期 | | 认证 | 正常的 UU 登录和独立的 GNOME RDP 凭据 | 支持的主机环境为 x86-64 Ubuntu 24.04，且带有已登录的 GNOME 46 桌面（物理显示、Wayland、Xorg 或 XRDP）。安装程序会检查此边界，如果在不受支持的操作系统或架构上运行，会在进行部分更改之前失败。 ## 快速开始 在已登录的 Ubuntu GNOME 桌面会话中运行： ``` ./install.sh ``` 这个一键安装程序会： 1. 安装 Ubuntu、WineHQ、构建工具、X11、RDP 和 keyring 依赖项 2. 在需要时下载并验证已批准的 UU 安装程序 3. 构建所有原始的兼容性 DLL 和辅助工具 4. 构建 SDL FreeRDP 所使用的固定版本 Windows WinPR runtime 5. 备份并仅应用已批准的二进制签名 6. 使用固定的 TLS 证书配置 GNOME Remote Desktop 7. 将中继密码存储在 GNOME Keyring 中，绝不存储在脚本中 8. 安装并启动受监管的用户服务 9. 立即运行端到端验证 首次运行时会提示输入本地中继密码（输入不回显），并在启动私有中继之前，在已登录的桌面上打开官方 UU 窗口。完成账户登录并关闭该窗口。重新运行相同的命令是幂等的；未更改的 FreeRDP 构建输出会通过校验和验证并被重复使用。 端口、分辨率和私有 display 的选择是持久的，可以在不编辑服务的情况下进行设置： ``` ./install.sh --rdp-port 3391 --resolution 2560x1440 --display auto ``` 它们会被验证并存储在 `~/.config/uu-remote-bridge/environment` 中。`auto` 会安全地从 `:20` 到 `:99` 中选择第一个空闲的私有 X display，从而避免与现有的 VNC/Xvfb 会话冲突。之后直接运行普通的 `./install.sh` 会保留这些选择。 请求的端口和固定的 display 在使用前会进行检查。冲突的非 GNOME 监听器将直接报错关闭，而安装程序出错则会重启在尝试升级之前处于活动状态的桥接。 ### 更新现有安装 使用最新支持的 tag，无需删除 UU 账户状态或更改已保存的中继设置： ``` cd ~/Projects/uu-remote-ubuntu-bridge git status --short git fetch --tags origin git checkout v0.1.0 ./install.sh --skip-packages --skip-account-login ./scripts/verify.sh --quick ``` 如果 status 命令报告了本地更改，请停止操作。安装过程会短暂重启中继。阅读 [v0.1.0 发布说明](docs/releases/v0.1.0.md)，使用 [公开的 GitHub 发布版本](https://github.com/lachlanchen/uu-remote-ubuntu-bridge/releases/tag/v0.1.0)，并在更新另一台授权的机器时发送[可直接复制的运维人员交接文档](docs/update-handoff.md)。 使用已下载的安装程序或未来已批准的发布清单： ``` ./install.sh \ --uu-installer ~/Downloads/UU-Remote/uuyc_4.33.0.exe \ --release-manifest patches/uu-remote-4.33.0.8907.json ``` ### 无人值守重启启动 为了在重启后无需先在本地或通过 RDP 登录即可使用 UU，请启用基于 TPM 的可选启动路径： ``` ./install.sh --unattended ``` 对于现有安装，请运行 `./scripts/configure-unattended.sh enable`。这将启用 GDM 自动登录，因此任何具有物理访问权限的人都可以在开机后使用桌面。Keyring 密码仍然针对此机器的 TPM 进行加密，绝不会存储在脚本或进程参数中。 [阅读设置、验证、密码更改和回滚的详细信息](docs/unattended-startup.md)。 ## 架构 ``` Phone / Windows / macOS UU controller | | UU signaling, video, and input v GameViewerServer.exe in Wine | | captures window SendInput IAT hook | | v v Ubuntu-Desktop-Relay bounded named-pipe broker SDL FreeRDP | | | +------------------+ Wine/X11 input | RDP on 127.0.0.1 | v GNOME Remote Desktop | v logged-in GNOME desktop (Wayland or Xorg/XRDP) ``` UU 看到的是一个普通的 Windows 桌面窗口。SDL FreeRDP 将该窗口中继到 GNOME Remote Desktop，后者负责处理受支持的 GNOME 捕获和输入。启动器会发现当前活跃的 GNOME Shell 的 D-Bus，包括使用私有会话 bus 的 XRDP 会话，并将 RDP 跳跃限制在主机本地。当 Wine 拒绝来自 UU 服务 token 的 `SendInput` 请求时，一个受限的 broker 会从一个普通用户的 Wine 进程中重复相同的输入请求。 [阅读完整的架构说明](docs/architecture.md)。 ## 日常命令 ``` uu-remote status uu-remote restart uu-remote stop uu-remote logs uu-remote login # one-time sign-in or account recovery on this desktop scripts/verify.sh --quick scripts/verify.sh ``` 完整的验证程序会等待 270 秒，并证明同一个服务端 PID 能够跨过 UU 之前四分钟的故障间隔期。 ## 针对新 UU 版本的更新 未知的二进制文件绝不会自动修补。维护工具包将更新转化为可复现的审查流程： ``` # 暂存 installer 而不影响现有的 Wine prefix。 scripts/stage-uu-release.sh \ --installer ~/Downloads/UU-Remote/uuyc_NEW.exe \ --sandbox-install # 生成 PE maps、semantic landmarks、candidate signatures、 # targeted disassembly，以及一个刻意无法运行的 draft manifest。 scripts/audit-gameviewer.py inspect \ --server build/upstream/NEW/GameViewerServer.exe \ --healthd build/upstream/NEW/GameViewerHealthd.exe \ --installer ~/Downloads/UU-Remote/uuyc_NEW.exe \ --baseline patches/uu-remote-4.33.0.8907.json \ --version NEW_VERSION ``` 经过手动语义审查后，`audit-gameviewer.py finalize` 会推导出完整的修补后哈希值并创建一个已批准的清单。然后，通用的补丁引擎无需更改源代码即可处理补丁、验证和字节级一致的恢复操作。 [了解完整的上游工作流](docs/upstream-maintenance.md)。 ## 二进制安全模型 补丁引擎会验证： - 已批准的清单状态 - 完整的原始 SHA-256 和文件大小 - 每个精确文件偏移量处的一个长原始签名 - 等长且不重叠的替换内容 - 完整的修补后 SHA-256 - 恢复前已验证且匹配的审计备份 如果更新中哪怕有一个字节超出了已批准的范围，都会直接报错并停止执行。草案清单不能被安装程序或修补程序使用。 该桥接工具不会编辑 OS 账户数据库、绕过登录、安装内核输入驱动程序、通过 TCP 暴露 X11，也不会添加新的远程控制协议。RDP 跳跃仅针对 loopback，并固定了 GNOME 的证书指纹。 [审查所有的信任边界和剩余风险](docs/security.md)。 ## 仓库结构 | 路径 | 用途 | | --- | --- | | `patches/` | 已版本化的获批 UU 标识和补丁签名 | | `CHANGELOG.md` | 标记过的桥接版本历史和升级入口点 | | `src/` | 输入 hook、broker、injector、服务辅助程序和 SSPI shim | | `scripts/gameviewer_patchlib.py` | 通用的发布清单引擎 | | `scripts/patch-gameviewer.py` | 用于修补、验证、查看状态、查询和恢复的 CLI | | `scripts/stage-uu-release.sh` | 私有安装程序暂存沙盒 | | `scripts/audit-gameviewer.py` | 新版本证据和审批工作流 | | `scripts/uu-remote-bridge` | 受监管的 UU/Xvfb/FreeRDP 编排脚本 | | `scripts/configure-unattended.sh` | 基于 TPM 的 GDM 自动登录设置和回滚 | | `scripts/uu-keyring-unlock.py` | 在 GNOME RDP 之前的 Secret Service 解锁脚本 | | `install.sh` / `uninstall.sh` | 幂等设置和可逆卸载 | | `tests/` | 无专有二进制文件的清单单元测试 | 我们不提交任何网易可执行文件、FreeRDP 构建产物、Wine prefix、密码、token、设备 ID、原始生产日志、截图或私有桌面内容。 ## 文档 - [架构](docs/architecture.md) - [更新日志](CHANGELOG.md) - [v0.1.0 发布说明](docs/releases/v0.1.0.md) - [针对其他运维人员的更新交接文档](docs/update-handoff.md) - [重启后的无人值守启动](docs/unattended-startup.md) - [方法论和工具清单](docs/methodology-and-toolkit.md) - [带有精确 `xxd` 和 `objdump` 证据的逆向工程记录](docs/reverse-engineering.md) - [在上游更新中维护桥接工具](docs/upstream-maintenance.md) - [Windows 参考比较](docs/windows-reference.md) - [故障排除](docs/troubleshooting.md) - [安全性](docs/security.md) - [贡献指南](CONTRIBUTING.md) ## 卸载 恢复经过审计的原始文件并移除桥接组件，同时保留专用 UU 账户的状态： ``` ./uninstall.sh --dry-run ./uninstall.sh ``` 试运行会验证两个回滚备份，而不会更改服务或任何文件。`./uninstall.sh --purge` 还会删除专用的 Wine prefix、桥接凭据和 GNOME RDP 启用状态。 ## 项目 本项目作为 [The Art of Lazying](https://lazying.art) 的一部分创建：将繁琐的部分自动化，保留推理过程，并使结果可复用。 原始源代码采用 MIT 许证。UU Remote、Wine、FreeRDP、GNOME、OpenSSL 及其他第三方组件保留其各自的许可证和商标。

标签：Cutter, RDP, Wine, 桌面环境, 系统桥接, 网易UU远程, 远程控制, 逆向工具