From 7beb3aecf0810527a510854efcccc33529e5cb04 Mon Sep 17 00:00:00 2001 From: VallierDev <24893073+VallierDev@users.noreply.github.com> Date: Thu, 15 Oct 2026 10:15:59 +0800 Subject: [PATCH] Release v0.1.6 Docs for headless mode, virtual desktop, uinput udev rule and terminal shortcuts; release tarball ships contrib/. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 1 + AGENTS.md | 10 +++++-- Cargo.lock | 2 +- Cargo.toml | 2 +- README.en.md | 52 +++++++++++++++++++++++++++++++++-- README.md | 49 +++++++++++++++++++++++++++++++-- docs/release-notes/v0.1.6.md | 28 +++++++++++++++++++ 7 files changed, 134 insertions(+), 10 deletions(-) create mode 100644 docs/release-notes/v0.1.6.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6e8419c..4a5607a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -26,6 +26,7 @@ jobs: name=uu-remote-linux-${GITHUB_REF_NAME}-x86_64-linux mkdir -p "$name" cp target/release/uuremote-server LICENSE README.md README.en.md config.example.json "$name/" + cp -r contrib "$name/" tar czf "$name.tar.gz" "$name" sha256sum "$name.tar.gz" > "$name.tar.gz.sha256" - uses: softprops/action-gh-release@v2 diff --git a/AGENTS.md b/AGENTS.md index c99273c..3c81dc9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,7 +104,10 @@ viewer does not reconnect them automatically. |---|---| | `~/.config/uuremote/config.json` | user_id, device_id, client_id, system_id, machine_guid, token, csrf; optional `sign_key`, `ffmpeg_root`. `$UU_CONFIG` overrides the path | | `~/.config/uuremote/host_settings.json` | persisted 安全 settings: auto_lock, keep_mute, mute_permanent | -| `UU_DESKTOP_BACKEND` | `auto` (default) / `x11` / `wayland` / `portal` | +| `UU_DESKTOP_BACKEND` | `auto` (default) / `x11` / `wayland` / `portal` / `none` (headless: no display; desktop offers ignored; tool peers get a nominal 1920x1080 screen + Allow permissions, which the port-mapping viewer requires) | +| `UU_INPUT_BACKEND` | `auto` (uinput on Wayland/portal when `/dev/uinput` is accessible, udev `uaccess` rule in README) / `uinput` / `native`. X11 keeps XTest (held-key autorepeat handling) | +| `UU_TERMINAL_SHORTCUTS=0` | disable Ctrl+V → Ctrl+Shift+V in focused X11 terminals (Mac Cmd and Ctrl both arrive as VK_LCONTROL) | +| `contrib/virtual-desktop/` | Xvfb + session (`UU_VIRTUAL_SESSION`, `UU_VIRTUAL_BUS=user|private`) for monitorless hosts; serve it with `DISPLAY=:99` | | `UU_VIDEO_ENCODER=cpu` | force libx264 instead of NVENC | | `UU_FFMPEG_ROOT` | FFmpeg prefix (`bin/ffmpeg`, libs in `lib/x86_64-linux-gnu`) | | `UU_AUDIO=0`, `UU_AUDIO_SOURCE` | disable sound / choose the Pulse source (default `@DEFAULT_MONITOR@`) | @@ -123,7 +126,7 @@ every 60 s. | `src/webrtc.rs` | peer connection, data channels, CONTROL dispatch, initialization messages | | `src/video.rs`, `src/capture_setting.rs` | FFmpeg H.264 pipeline; viewer quality/fps/resolution settings | | `src/audio.rs` | Pulse/PipeWire monitor → Opus audio track | -| `src/input.rs`, `src/input_mapping.rs` | input injection (X11 XTest / Wayland / portal), Windows VK → keysym | +| `src/input.rs`, `src/input_mapping.rs`, `src/uinput.rs` | input injection (X11 XTest / Wayland / portal / uinput), Windows VK → keysym → evdev | | `src/cursor.rs` | pointer shape mirroring (X11) | | `src/clipboard*.rs` | text clipboard bridge and protocol | | `src/file_trans.rs` | FileTransferFtp RPC | @@ -196,6 +199,9 @@ started a second full host server instead, so check that a subcommand exists in - Remote keys repeat at high RTT because key-up arrives after the X autorepeat delay. XTEST repeats through the master keyboard; the engine disables global autorepeat only while a remote key is held. - Interactive shells ignore SIGTERM: the server HUPs/KILLs PTY sessions on shutdown. +- An explicit `DISPLAY` that cannot be opened is an error; the X11 engine falls back to `:0`/`:1` only when DISPLAY is unset. +- systemd/D-Bus-activated apps (GNOME Terminal, portals) run with the user manager's environment, not the caller's: + a private `dbus-run-session` bus does not bring them onto a virtual display. - GTK windows stop repainting while GNOME is locked or the monitor is off; test UI on Xvfb or after unlock. - logind `unlock-session` by the session owner clears the GNOME shield in ~3 s. - GNOME closes the portal session on lock; capture/input must share one portal session and be rebuilt after diff --git a/Cargo.lock b/Cargo.lock index 9e233c2..679a807 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2649,7 +2649,7 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" [[package]] name = "uu-remote-linux" -version = "0.1.5" +version = "0.1.6" dependencies = [ "base64 0.22.1", "bytes", diff --git a/Cargo.toml b/Cargo.toml index 3e4b8b5..d13fe4b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "uu-remote-linux" -version = "0.1.5" +version = "0.1.6" edition = "2021" authors = ["uu-remote-linux contributors"] description = "Unofficial Linux host for NetEase UU Remote: control a Linux desktop from the official clients" diff --git a/README.en.md b/README.en.md index 1fba107..a92e4e7 100644 --- a/README.en.md +++ b/README.en.md @@ -33,7 +33,8 @@ |---|---| | QR login | GTK login window (or a terminal QR code with `login --no-gui`); expired codes refresh automatically; the service opens the login window by itself when credentials are missing or expired | | Remote desktop | H.264 video, NVENC hardware encoding on NVIDIA GPUs, libx264 otherwise; the viewer draws its local pointer, so there is no double cursor | -| Mouse / keyboard | Absolute and relative motion, clicks, wheel, keys; no spurious key repeat on high-latency links | +| Mouse / keyboard | Absolute and relative motion, clicks, wheel, keys; no spurious key repeat on high-latency links; optional uinput virtual devices on Wayland (layout independent, see below) | +| Terminal shortcuts | Mac viewers send both Cmd and Ctrl as Ctrl. In a focused terminal window Ctrl+V / Cmd+V become Ctrl+Shift+V (paste); Ctrl+C always interrupts, copy with Cmd+Shift+C (X11) | | Pointer shape | Remote cursor shape is mirrored to the viewer (X11) | | Clipboard | Two-way text sync | | Quality / frame rate / resolution | Auto, Original 20M, Ultra 8M, HD 2M, custom; 30/60/90/144 fps; "other resolutions" are scaled by the encoder, the host monitor is left untouched | @@ -46,6 +47,7 @@ | System actions | Lock, show desktop, task manager (system monitor), reboot, shut down | | Port mapping | The official "port mapping" tool: forwards a local port on the viewer to an address reachable from the Linux host (e.g. 127.0.0.1:22); `UU_PORT_MAPPING=0` disables it | | Reconnects | Every tool window has its own connection; they do not disturb each other | +| Headless servers | Goes online without a monitor with terminal, file transfer and port mapping; an Xvfb virtual desktop gives a full remote desktop (see below) | ## Supported Linux desktops @@ -77,7 +79,7 @@ permission; the permission is remembered once granted. | Privacy screen on the host | Not implemented | | Microphone (viewer audio played on the host) | Not implemented (needs a virtual sound card) | | Plugins such as the WoW queue notifier | Not supported; the client is told that no plugins exist | -| Access before login (greeter / no user logged in) | Not supported; only an already logged-in desktop session can be controlled | +| Access before login (greeter / no user logged in) | The greeter cannot be controlled; without a logged-in user use headless mode or a virtual desktop (see below) | | Relay connections on restrictive networks | Uses the ICE servers provided by the UU cloud; complex network setups are not thoroughly tested | | Acting as a viewer (controlling other machines from Linux) | Out of scope | @@ -149,6 +151,48 @@ journalctl --user -u uuremote-native.service -f # online once you see availabi If you have not logged in yet, the service opens the QR login window on your desktop. +### 5. uinput virtual keyboard/mouse on Wayland (recommended) + +On Wayland (especially GNOME/KDE via the portal) the default input path needs portal consent and some keyboard layouts +drop symbols such as the underscore. Once the logged-in user may access `/dev/uinput`, the host switches to kernel +virtual devices that send physical key codes: + +```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` grants access only to the user sitting at the machine. `UU_INPUT_BACKEND=uinput|native` forces a backend. +X11 keeps XTest by default because it handles held keys correctly on high-latency links. + +## Servers without a monitor + +**Headless mode** (terminal, file transfer and port mapping only): add `Environment=UU_DESKTOP_BACKEND=none` to the +service and run `loginctl enable-linger $USER`, so the systemd user manager (with `XDG_RUNTIME_DIR` and the user D-Bus) +starts at boot without a login. The viewer's remote desktop keeps showing "connecting" in this mode; that is expected. +Log in once with `uuremote-server login --no-gui` (QR in the terminal). + +**Virtual desktop**: for a full remote desktop, run a desktop session (Xfce recommended) on an Xvfb screen: + +```sh +sudo apt install xvfb dbus-x11 xfce4 # or another session, chosen with 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 +``` + +The virtual screen is `:99`, 1920x1080 by default. Xvfb has no GPU acceleration, so it is a little less smooth than a +real display; NVENC is still used for encoding when an NVIDIA GPU is present. The script exports `DISPLAY` to the +systemd user session so D-Bus-activated programs open on the virtual screen; on a machine that also runs a real desktop +session set `UU_VIRTUAL_BUS=private` so the real session is not affected. + +To make a GPU drive a real (non-Xvfb) desktop without a monitor, use a dummy HDMI plug or load an EDID file with the +kernel parameter `drm.edid_firmware=`, then install as for a normal X11 desktop. + ## Configuration Common environment variables: @@ -156,7 +200,9 @@ Common environment variables: | Variable | Purpose | |---|---| | `UU_CONFIG` | Config file path (default `~/.config/uuremote/config.json`) | -| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` | +| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `none` (headless) | +| `UU_INPUT_BACKEND` | `auto` (default: uinput on Wayland when accessible) / `uinput` / `native` | +| `UU_TERMINAL_SHORTCUTS=0` | Disable the Ctrl+V paste rewrite in terminal windows | | `UU_VIDEO_ENCODER=cpu` | Force CPU encoding | | `UU_FFMPEG_ROOT` | Use FFmpeg from this prefix | | `UU_AUDIO=0` | Disable sound; `UU_AUDIO_SOURCE` picks the PulseAudio source | diff --git a/README.md b/README.md index 9ac17de..1dfef5a 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,8 @@ |---|---| | 扫码登录 | 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 帧;「其他分辨率」由编码器缩放,不改动主机显示器 | @@ -42,6 +43,7 @@ | 系统操作 | 锁屏、显示桌面、任务管理器(系统监视器)、重启、关机 | | 端口映射 | 官方「端口映射」工具:把控制端本地端口转发到 Linux 能访问到的地址(如 127.0.0.1:22);`UU_PORT_MAPPING=0` 可关闭 | | 多次重连 | 每个工具窗口独立连接,互不影响 | +| 无头服务器 | 没有显示器也能上线,提供终端、文件传输和端口映射;也可以用 Xvfb 虚拟桌面提供完整远程桌面(见下文) | ## 支持的 Linux 桌面 @@ -71,7 +73,7 @@ Wayland 下的限制:只支持单屏、固定分辨率;portal 后端暂不 | 被控端防窥模式 | 未实现 | | 麦克风(控制端声音传到被控端) | 未实现(需要虚拟声卡) | | 魔兽世界排队提醒等插件 | 不支持,会明确告诉客户端「无插件」 | -| 登录前(登录界面 / 无人登录)访问 | 不支持,只能控制已登录的桌面会话 | +| 登录前(登录界面 / 无人登录)访问 | 不支持控制登录界面;没有人登录时可以用无头模式或虚拟桌面(见下文) | | 跨运营商 / 受限网络的中继连接 | 已接入官方下发的 ICE 服务器,但复杂网络环境未充分测试 | | 作为控制端(在 Linux 上控制别的电脑) | 不在本项目范围 | @@ -142,6 +144,45 @@ journalctl --user -u uuremote-native.service -f # 看到 availability=Some("re 如果还没有登录,服务会自动在桌面上弹出扫码窗口。 +### 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 dbus-x11 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 桌面的方式安装。 + ## 配置 常用环境变量: @@ -149,7 +190,9 @@ journalctl --user -u uuremote-native.service -f # 看到 availability=Some("re | 变量 | 作用 | |---|---| | `UU_CONFIG` | 配置文件路径(默认 `~/.config/uuremote/config.json`) | -| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` | +| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `none`(无头模式) | +| `UU_INPUT_BACKEND` | `auto`(默认,Wayland 下可用时用 uinput)/ `uinput` / `native` | +| `UU_TERMINAL_SHORTCUTS=0` | 关闭终端窗口里的 Ctrl+V 粘贴转换 | | `UU_VIDEO_ENCODER=cpu` | 强制使用 CPU 编码 | | `UU_FFMPEG_ROOT` | 使用指定目录下的 FFmpeg | | `UU_AUDIO=0` | 关闭声音转发;`UU_AUDIO_SOURCE` 指定 PulseAudio 采集源 | diff --git a/docs/release-notes/v0.1.6.md b/docs/release-notes/v0.1.6.md new file mode 100644 index 0000000..4c57765 --- /dev/null +++ b/docs/release-notes/v0.1.6.md @@ -0,0 +1,28 @@ +无头服务器、虚拟桌面、uinput 输入和终端快捷键。/ Headless servers, virtual desktop, uinput input and terminal shortcuts. + +### 新增 / Added +- **无头模式** `UU_DESKTOP_BACKEND=none`:没有显示器、没有图形会话也能上线,提供终端、文件传输和端口映射。 + 配合 `loginctl enable-linger` 可以开机自动上线。已在实机上用官方 Mac 客户端验收(端口映射传输 10 MB 校验一致)。 + Headless mode: online without a display; terminal, file transfer and port mapping verified with the official Mac viewer. +- **虚拟桌面** `contrib/virtual-desktop/`:用 Xvfb 创建虚拟屏幕并启动桌面会话,没有显示器的服务器也能使用完整的远程桌面。 + 实机验收了画面和键鼠;默认的「用户总线」模式(把 `DISPLAY` 导入 systemd 用户会话)尚未在纯无头机器上验证。 + Virtual desktop scripts (Xvfb + session). Video and input verified; the default user-bus mode is not yet verified on a + truly monitorless machine. +- **uinput 虚拟键鼠**(参考 Sunshine):Wayland/portal 下,只要当前用户能访问 `/dev/uinput`(README 里有一条 udev 规则), + 就自动改用内核级虚拟键盘和鼠标,发送物理按键码,不依赖键盘布局,也不需要 portal 输入授权。应能解决 #3(下划线被吞)。 + `UU_INPUT_BACKEND=auto|uinput|native`;X11 继续默认用 XTest。 + uinput keyboard/mouse on Wayland (layout independent, no portal input consent); should fix #3. +- **终端快捷键**:Mac 控制端的 Cmd 和 Ctrl 到被控端都是 Ctrl。焦点在终端窗口时,Ctrl+V / Cmd+V 自动转成 Ctrl+Shift+V 粘贴; + Ctrl+C 始终是中断,复制用 Cmd+Shift+C(X11,`UU_TERMINAL_SHORTCUTS=0` 关闭)。 + Terminal-aware paste: Ctrl+V/Cmd+V paste in terminal windows, Ctrl+C always interrupts. + +### 修复 / Fixed +- 没有桌面时(无头模式,或 portal 后端还没授权时)打开端口映射会被控制端立即断开:现在工具连接会收到屏幕信息和「允许」权限。 + Port mapping was aborted by the viewer when no desktop was available. +- 明确设置的 `DISPLAY` 打不开时,不再悄悄改用 `:0`/`:1`(会截到真实屏幕),而是报错。 + An explicit DISPLAY that cannot be opened no longer falls back to the physical screen. + +### 下载 / Download +`uu-remote-linux-v0.1.6-x86_64-linux.tar.gz`:X11 版可执行文件(x86_64,glibc ≥ 2.35),附带 `contrib/virtual-desktop/`。 + +**非官方项目,与网易无关。** / **Unofficial, not affiliated with NetEase.**