# uu-remote-linux · UU 远程 Linux 被控端(非官方) **简体中文** | [English](README.en.md) > **写在前面** > > 网易 UU 远程非常好用,但官网一直没有 Linux 版本。于是我借助 Claude 和 Codex,写了这个开源的 Linux 被控端: > 装上之后,就能用官方的 Mac / Windows / 手机客户端远程控制你的 Linux 电脑。 > > 这是个人兴趣项目,**与网易无关,也不是官方客户端**。如果网易认为本项目侵权或有不妥, > 请在推特私信我 **[@ai_fengshou](https://x.com/ai_fengshou)**,我会第一时间自行下架。

Linux 主机扫码登录窗口

首次运行时弹出的扫码登录窗口(二维码已打码)

## 它是什么 - 一个纯 Rust 写的 Linux 原生程序(不需要 Wine,也不需要任何 Windows/macOS 组件)。 - 用你自己的 UU 远程账号扫码登录后,这台 Linux 会出现在官方客户端的设备列表里,用法和 Windows 被控端一样。 - 只做**被控端**:用来控制别人的客户端,仍然是官方的 Mac / Windows / 手机 App。 ## 已实现的功能 | 功能 | 说明 | |---|---| | 扫码登录 | GTK 登录窗口(或 `login --no-gui` 终端二维码);二维码过期自动刷新;登录凭证失效时服务会自动弹出登录窗口 | | 远程桌面 | H.264 视频,NVIDIA 显卡用 NVENC 硬件编码,否则用 libx264;查看端绘制本地鼠标,不会出现双光标 | | 鼠标 / 键盘 | 绝对/相对移动、点击、滚轮、按键;修复了网络延迟导致的按键连发;Wayland 下可用 uinput 虚拟键鼠(不依赖键盘布局,见下文) | | 终端快捷键 | Mac 控制端的 Cmd 和 Ctrl 到被控端都是 Ctrl。焦点在终端窗口时,Ctrl+V / Cmd+V 自动转成 Ctrl+Shift+V 粘贴;Ctrl+C 始终是中断,复制请用 Cmd+Shift+C(X11) | | 鼠标指针样式 | 远端指针形状实时同步(X11) | | 剪贴板 | 双向文本同步 | | 画质 / 帧率 / 分辨率 | 自动、原画 20M、超清 8M、高清 2M、自定义;30/60/90/144 帧;「其他分辨率」由编码器缩放,不改动主机显示器 | | 声音 | 采集系统声音(PulseAudio / PipeWire),Opus 编码传到控制端 | | 文件传输 | 上传、下载(含文件夹)、新建文件夹、重命名、删除 | | 终端 | 官方「终端」工具,PTY 会话,支持多会话和重命名 | | 锁屏与自动解锁 | 向控制端上报锁屏状态;开启「自动解锁被控端」后,通过 PAM 校验密码并解锁当前会话 | | 远程结束后自动锁屏 | 设置保存在本机,重连后依然生效 | | 被控端静音运行 | 主机扬声器静音,控制端照常能听到声音;结束后恢复原来的音量设置 | | 系统操作 | 锁屏、显示桌面、任务管理器(系统监视器)、重启、关机 | | 端口映射 | 官方「端口映射」工具:把控制端本地端口转发到 Linux 能访问到的地址(如 127.0.0.1:22);`UU_PORT_MAPPING=0` 可关闭 | | 多次重连 | 每个工具窗口独立连接,互不影响 | | 无头服务器 | 没有显示器也能上线,提供终端、文件传输和端口映射;也可以用 Xvfb 虚拟桌面提供完整远程桌面(见下文) | ## 支持的 Linux 桌面 | 桌面环境 | 显示协议 | 状态 | 编译方式 | |---|---|---|---| | GNOME(Ubuntu 24.04) | X11 / Xorg | ✅ 实机长期使用,以上功能全部验收 | 默认 | | KDE Plasma | X11 | ✅ 虚拟机测试通过 | 默认 | | Xfce | X11 | ✅ 虚拟机测试通过 | 默认 | | Cinnamon / MATE | X11 | ✅ 虚拟机测试通过 | 默认 | | Hyprland | Wayland(wlroots 原生协议) | 🧪 实验性,虚拟机测试(部分功能受限,见下) | `--features wayland` | | GNOME / KDE Plasma | Wayland(xdg-desktop-portal) | 🧪 实验性,虚拟机测试(部分功能受限,见下) | `--features wayland,portal` | 除 GNOME(X11)外,其余桌面目前都是在虚拟机里测试的。如果你在真机上遇到问题,欢迎[提交 issue](../../issues), 请附上发行版、桌面环境、显卡型号和 `journalctl --user -u uuremote-native.service` 里的相关日志。 Wayland 下的限制:只支持单屏、固定分辨率;Hyprland 原生后端通过 shm screencopy 截屏,帧率受合成器限制(2560x1600 实测约 16~22 帧),控制端的帧率选项不生效;portal 后端暂不支持唤醒屏幕和动态分辨率;剪贴板只在控制端的远控窗口处于前台时同步。 首次连接时,桌面会弹窗请求「远程桌面 / 屏幕共享」授权,同意后会记住授权。 ## 尚未实现 / 不支持 | 功能 | 状态 | |---|---| | 多显示器切换 | 开发中 | | 真彩(4:4:4) | 未实现,握手时不声明,客户端不会启用 | | HDR | 未实现 | | 超级屏 / 虚拟显示器 | 未实现 | | 被控端防窥模式 | 未实现 | | 麦克风(控制端声音传到被控端) | 未实现(需要虚拟声卡) | | 魔兽世界排队提醒等插件 | 不支持,会明确告诉客户端「无插件」 | | 登录前(登录界面 / 无人登录)访问 | 不支持控制登录界面;没有人登录时可以用无头模式或虚拟桌面(见下文) | | 跨运营商 / 受限网络的中继连接 | 已接入官方下发的 ICE 服务器,但复杂网络环境未充分测试 | | 作为控制端(在 Linux 上控制别的电脑) | 不在本项目范围 | ## 安装 ### 1. 依赖(Ubuntu / Debian) ```sh sudo apt install build-essential pkg-config \ libx11-dev libxext-dev libxtst-dev libxfixes-dev \ libgtk-3-dev ffmpeg # 可选:Wayland 后端 sudo apt install libwayland-dev libxkbcommon-dev wl-clipboard # 可选:GNOME/KDE portal 后端 sudo apt install libglib2.0-dev libpipewire-0.3-dev ``` - 需要 Rust 工具链()。 - `libgtk-3-dev` 是可选的:没有 GTK 时只能在终端里扫码登录(也可以设置 `UU_NO_GTK=1` 主动关闭登录窗口)。 - NVIDIA 显卡用户需要使用带 `h264_nvenc` 的 FFmpeg,否则自动回落到 CPU 编码(libx264)。 ### 2. 编译 ```sh cargo build --release # X11 cargo build --release --features wayland # + Hyprland cargo build --release --features wayland,portal # + GNOME/KDE Wayland ``` ### 3. 登录 在图形桌面里运行: ```sh ./target/release/uuremote-server login ``` 用手机上的 **网易 UU 远程 App** 扫码并确认即可。登录信息只保存在本机的 `~/.config/uuremote/config.json`(权限 0600)里。 ### 4. 作为用户服务常驻 `~/.config/systemd/user/uuremote-native.service`: ```ini [Unit] Description=UU Remote Linux host (unofficial) After=graphical-session.target [Service] Environment=RUST_LOG=info # X11 桌面需要指明显示器;GNOME 的 XAUTHORITY 一般在 /run/user//gdm/Xauthority Environment=DISPLAY=:0 ExecStart=%h/.local/bin/uuremote-server Restart=always RestartSec=5 [Install] WantedBy=default.target ``` ```sh install -Dm755 target/release/uuremote-server ~/.local/bin/uuremote-server systemctl --user daemon-reload systemctl --user enable --now uuremote-native.service journalctl --user -u uuremote-native.service -f # 看到 availability=Some("ready") 即上线 ``` 如果还没有登录,服务会自动在桌面上弹出扫码窗口。 ### 5. Wayland 下使用 uinput 虚拟键鼠(推荐) Wayland(尤其是 GNOME/KDE portal)下,默认的键鼠注入要经过 portal 授权,部分键盘布局下还会丢符号(比如下划线)。 允许当前登录用户访问 `/dev/uinput` 后,服务会自动改用内核级虚拟键盘和鼠标,发送物理按键码: ```sh echo 'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"' | \ sudo tee /etc/udev/rules.d/60-uu-remote-linux-uinput.rules sudo udevadm control --reload && sudo udevadm trigger --name-match=uinput ``` `uaccess` 只把权限给当前坐在这台机器前的登录用户。`UU_INPUT_BACKEND=uinput|native` 可以强制指定后端。 X11 默认继续用 XTest,因为它能正确处理网络延迟下按住不放的按键。 ## 没有显示器的服务器 **无头模式**:只要终端、文件传输和端口映射,不需要图形界面。在服务里加 `Environment=UU_DESKTOP_BACKEND=none`, 再执行 `loginctl enable-linger $USER`,这样开机后不用登录,systemd 用户服务(以及 `XDG_RUNTIME_DIR`、用户 D-Bus)也会自动启动。 无头模式下控制端点「远程桌面」会一直显示正在连接,这是正常的。首次登录用 `uuremote-server login --no-gui` 在终端里扫码。 **虚拟桌面**:需要完整的远程桌面时,用 Xvfb 创建一块虚拟屏幕,再在上面跑一个桌面环境(推荐 Xfce): ```sh sudo apt install xvfb xauth x11-utils dbus-x11 dbus-user-session xfce4 # 或其他桌面环境,用 UU_VIRTUAL_SESSION 指定 install -Dm755 contrib/virtual-desktop/uu-virtual-desktop ~/.local/bin/uu-virtual-desktop install -Dm644 contrib/virtual-desktop/uu-virtual-desktop.service ~/.config/systemd/user/uu-virtual-desktop.service install -Dm644 contrib/virtual-desktop/virtual-display.conf ~/.config/systemd/user/uuremote-native.service.d/virtual-display.conf loginctl enable-linger $USER systemctl --user daemon-reload && systemctl --user enable --now uu-virtual-desktop.service systemctl --user restart uuremote-native.service ``` 虚拟屏幕默认是 `:99`、1920x1080。Xvfb 没有 GPU 加速,流畅度比真实显示器略差;有 NVIDIA 显卡时视频仍然用 NVENC 编码。 脚本会把 `DISPLAY` 导入 systemd 用户会话,这样通过 D-Bus 启动的程序也会显示在虚拟屏幕上; 如果这台机器同时还有真实的桌面会话,请设 `UU_VIRTUAL_BUS=private`,避免影响真实桌面。 想让 NVIDIA/AMD 显卡在不接显示器时也正常输出画面(而不是用 Xvfb),可以用假显示器插头(HDMI 诱骗器), 或者用内核参数 `drm.edid_firmware=` 加载 EDID 文件,再按普通 X11 桌面的方式安装。 ## 配置 常用环境变量: | 变量 | 作用 | |---|---| | `UU_CONFIG` | 配置文件路径(默认 `~/.config/uuremote/config.json`) | | `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `kms`(实验性特性) / `none`(无头模式) | | `UU_INPUT_BACKEND` | `auto`(默认,Wayland 下可用时用 uinput)/ `uinput` / `native` | | `UU_TERMINAL_SHORTCUTS=0` | 关闭终端窗口里的 Ctrl+V 粘贴转换 | | `UU_VIDEO_ENCODER` | `cpu` 强制 CPU;`vaapi` 显式启用 Intel/AMD 硬编;`nvenc` 强制 NVENC;未设置时检测到 NVIDIA 驱动才用 NVENC,否则用 CPU | | `UU_FFMPEG_ROOT` | 使用指定目录下的 FFmpeg | | `UU_AUDIO=0` | 关闭声音转发;`UU_AUDIO_SOURCE` 指定 PulseAudio 采集源 | | `UU_LOGIN_WINDOW=0` | 凭证缺失时不自动弹出登录窗口 | | `UU_PORT_MAPPING=0` | 关闭端口映射(对应官方被控端的开关) | 「远程结束后自动锁屏」「静音运行」等设置保存在 `~/.config/uuremote/host_settings.json`。 ## 让 AI 帮你安装或开发 如果你用 Claude Code、Codex、Cursor 等 AI 编程工具,让它先阅读 [AGENTS.md](AGENTS.md)。 这份文档写给大模型看,里面有编译安装步骤、代码地图、协议要点和开发规范,读完就能接手编译安装或继续开发。 ## 工作原理 ```mermaid flowchart LR App["官方客户端
Mac / Windows / 手机"] <-- "WebRTC:视频 · 音频 · 数据通道" --> Host["uuremote-server
(Linux)"] App <-- 信令 --> Cloud["UU 远程云服务"] Host <-- "Socket.IO 信令 · 设备登录" --> Cloud Host --> X11["X11 / Wayland
采集与输入"] Host --> FF["FFmpeg
H.264 / Opus"] Host --> Sys["PAM · logind · PipeWire"] ``` - 主机以「Windows PC」类型注册到 UU 远程,官方客户端因此能直接识别它。 - 画面经 FFmpeg 编码成 H.264,声音编码成 Opus,都通过 WebRTC 发送;键鼠、剪贴板、文件和终端走 WebRTC 数据通道。 - 协议细节通过观察官方客户端的通信,以及分析其公开发布的程序得到,仅用于实现互通。 本仓库**不包含**任何网易的程序、图标或素材。 ## 安全与隐私 - 日志不记录键盘输入、终端内容、剪贴板内容、文件内容、密码和令牌。 - 自动解锁的密码保存在**控制端**(官方客户端)里,被控端只拿来做一次 PAM 校验,不落盘、不写日志。 - 能连上这台机器的,只有登录了同一个 UU 账号的设备。请保管好你的 UU 账号。 ## 许可证 本项目以 [GPL-3.0](LICENSE) 许可证发布:可以自由使用、修改和再发布,但再发布(包括修改后的版本)必须同样以 GPL-3.0 开源。 ## 免责声明 - 「网易」「UU 远程」等名称和商标归网易公司所有。本项目与网易公司没有任何关联,未获其授权或认可。 - 本项目基于互操作目的开发,请在遵守 UU 远程用户协议和当地法律的前提下使用,风险自负。 - 网易或权利人如有异议,请通过推特 [@ai_fengshou](https://x.com/ai_fengshou) 联系,我会配合处理或下架。 ## 致谢 - 网易 UU 远程团队:做了一个好用的远程工具。 - [webrtc-rs](https://github.com/webrtc-rs/webrtc)、FFmpeg、GTK 等开源项目。 - 本项目的大部分代码在 Claude 和 Codex 的协助下完成。 ### VAAPI 硬件编码(显式启用) 设置 `UU_VIDEO_ENCODER=vaapi` 使用 Intel/AMD H.264 VAAPI;`UU_VAAPI_DEVICE` 默认 `/dev/dri/renderD128`,运行用户需要 render 节点权限。不会自动选择 VAAPI;设备或驱动初始化 失败会明确警告并回退 libx264。外部 FFmpeg 和 `--features inproc-av` 均先转 NV12 再上传硬件帧。 VBR 使用控制端码率预设及 CQ 对应的最小 QP,无 B 帧、async depth=1,并保留现有 GOP/VFR 规则。 Intel 核显(UHD 770,iHD 驱动)已实机验收:默认的外部 FFmpeg 管线用官方 Mac 控制端测试了各档画质、帧率、缩放和重连,全程硬件编码、无回退,CPU 占用比 libx264 低约 40%。**AMD 显卡和 `--features inproc-av` 管线的 VAAPI 尚未实机验证。** ### 静音运行与虚拟声卡 控制端开启「静音运行」后,程序创建虚拟输出 `uu-remote-sink`,保存原默认输出, 迁移其播放流并采集 `uu-remote-sink.monitor`。新播放也走虚拟输出;其他输出上的流不迁移。 最后一个桌面连接结束后恢复原默认输出并卸载模块;`mute_permanent` 仍保留原物理静音策略。 恢复记录保存在配置旁,权限 0600;进程锁避免重复实例抢占,异常退出后下次启动会恢复遗留路由。 有 `pactl` 时用它(PulseAudio / PipeWire-pulse);没有 `pactl` 的纯 PipeWire 系统(如默认的 Ubuntu 桌面) 自动改用 `pw-cli`/`wpctl` 创建同名虚拟输出,正在播放的声音由 WirePlumber 自动迁移。已在 Ubuntu 24.04 实机上用官方 Mac 控制端验收。 路由失败时保留原静音/monitor 方案。开关变化仅重启当前音频编码器,未开启时采集方式保持不变。 本地诊断命令 `virtual-audio-probe` 会临时切换输出五秒并恢复。 ### 虚拟桌面的用户总线 默认 `UU_VIRTUAL_BUS=user`:监督脚本将 DISPLAY/XAUTHORITY 导入 linger 用户总线,等待经过认证的 X11 就绪后通知 systemd;退出时清理 Xvfb。示例主机 drop-in 使用 `%t/uu-virtual-99.Xauthority`。 请使用没有真实图形会话的专用账号;参见[设置与官方 Mac 验收清单](contrib/virtual-desktop/ACCEPTANCE.md)。 ### Arch Linux / Omarchy ```sh sudo pacman -S --needed base-devel rust pkgconf clang ffmpeg libx11 libxext libxtst libxfixes gtk3 \ wayland libxkbcommon wl-clipboard libpipewire glib2 libpulse cargo test --locked --features wayland cargo build --release --features wayland ``` Omarchy 使用 Hyprland:在其用户会话中运行,设置 `UU_DESKTOP_BACKEND=wayland`,保留 `WAYLAND_DISPLAY` 和 `XDG_RUNTIME_DIR`。其他合成器可能需要 `--features wayland,portal`。 uinput 需加载内核模块并应用上文 uaccess 规则;无人登录账号需要专用组的受限授权。 该权限能向整个 seat(包括锁屏/登录界面)注入输入。设置 `UU_INPUT_BACKEND=uinput` 后, 仍须确认启动日志实际选择了 uinput。 VAAPI 可选包:Intel 新显卡用 `intel-media-driver`,AMD 用 `libva-mesa-driver`,`libva-utils` 提供 `vainfo`。KMS 依赖 `libdrm`。虚拟 Xfce 依赖 `xorg-server-xvfb xorg-xauth xorg-xdpyinfo xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`。 滚动 Arch 的 FFmpeg 可能超出 `inproc-av` 支持的 6.x;请使用默认进程方案或独立的 FFmpeg 6 前缀, 不要降级系统 FFmpeg。当前 Arch/Hyprland VM 验证结果见[开发验证记录](docs/validation/v017-results.md)。 ### 实验性 KMS 截屏 编译 `--features kms` 后显式设置 `UU_DESKTOP_BACKEND=kms`;`UU_KMS_DEVICE` 默认 `/dev/dri/card0`。需要 libdrm、card 节点访问权及主动授予的 `cap_sys_admin+ep`。 程序不会自动启用或授权;此 capability 权限很大,先阅读[限制、安全风险及撤销步骤](docs/validation/kms.md)。 当前仅为线性帧缓冲原型:VM 的 GDM 截图仍是黑屏,**没有通过登录界面视觉验收**,不承诺锁屏可用。 键鼠需 uinput;没有桌面会话时不提供剪贴板。 无头桌面错误码的[官方证据仍不足](docs/validation/headless-error-evidence.md),因此保持原有 offer 行为。