KDE Kwin Wayland Sunshine

无人值守 Wayland 桌面与 Sunshine：配置经验.md

无人值守 Wayland 桌面与 Sunshine：配置经验

本文供后续代理在本机维护或在其他机器部署时参考。 更新：2026-09-08。内容来自 KDE Plasma/KWin 和 LXQt/Labwc 两种部署经验。 这是部署指南，不是 Sunshine 源码仓库说明。

目标与优先原则

建立一个完整、正常、可运行日常应用、测试工具和游戏的 Wayland 桌面； 不连接显示器时可经 Moonlight 访问，开机可自动恢复。

1. 使用发行版显示管理器，通过正常 PAM/logind 流程登录图形桌面。
2. 同一用户只运行一个图形桌面。虚拟屏和物理屏属于同一个会话。
3. 在正常 GPU/DRM 合成器里添加虚拟输出，保留正常输入设备与 GPU 访问。
4. 保留标准用户 D-Bus、PipeWire、Portal、Polkit、密钥环及应用启动入口。
5. Sunshine 随图形会话启动、退出；虚拟屏应先就绪，再启动 Sunshine。
6. 虚拟屏常驻，客户端断开不销毁输出，不影响应用、游戏和窗口布局。
7. 配置成功、服务启动、会话恢复、整机重启、客户端体验必须分别验证和记录。

正常桌面权限来自登录会话及其集成，不能用加几个用户组代替。 不要为解决应用故障引入第二套 D-Bus、独立 XDG 配置目录、root 桌面、 免密 Polkit/sudoers、关闭 AppArmor/Snap 沙箱、--no-sandbox 或应用包装入口。 管理员操作应按普通桌面方式弹出认证窗口。

开始前：先探测，后修改

• 阅读已有本地说明和实际配置；保留用户后来新增的设置、账户、配对和应用。
• 检查发行版、内核、GPU/驱动、Sunshine 版本/路径/安装形式及 capabilities。
• 检查显示管理器、已安装 Wayland 会话、当前 logind 会话、图形进程和用户服务。
• 检查物理显示器连接状态、Wayland 输出、设备 ACL、PipeWire 默认音频。
• 不照搬其他机器的用户名、UID、IP、显卡编号、输出编号或显示偏好。
• 对将修改的配置建立备份；备份如包含凭据应限制权限，不提交到公开仓库。

常用只读检查：

cat /etc/os-release
sunshine --version
loginctl list-sessions
systemctl --user show-environment
systemctl --user --failed
lspci -nn
ls -l /dev/dri /dev/uinput
getcap /usr/bin/sunshine
pactl info

读取图形环境和设备标识后，再运行相应的 kscreen-doctor、wlr-randr、 vainfo --display drm --device <实际 render 节点> 等工具。 日志可能包含地址、用户名和设备信息，公开前审查。

选择适合当前桌面的实现

桌面	正常登录	虚拟输出	Sunshine 捕获
KDE Plasma/KWin	发行版 SDDM + Plasma Wayland	正常 KWin DRM 后端中的虚拟输出	capture = kwin，需版本支持
LXQt/Labwc	发行版显示管理器 + LXQt Wayland	同时启用 DRM、libinput、headless，创建固定名称输出	capture = wlr，需协议支持

优先保留目标机已有的完整桌面。不要无条件迁移桌面或复制旧方案的版本补丁。 独立 kwin --virtual、Xvfb、容器内桌面或从 SSH 临时拼装桌面，不能直接视为 与正常本地登录等价的实现。强制 HDMI/假 EDID、VKMS、硬件假显示器属于备用 路线，使用前重新评估 GPU 加速、物理接口及热插拔行为。

正常登录与无人值守

配置显示管理器自动登录发行版自带的 Wayland 会话；会话文件名必须实查。 KDE 示例是 SDDM 的 [Autologin]，设置 User 和实际 Session。 若需要注销后也自动恢复，可配置 Relogin=true，但必须说明注销会关闭应用。

验收真实图形会话：

Seat=seat0（或实际本地 seat）
Active=yes
Remote=no
Type=wayland
Service=显示管理器的正常 PAM 登录服务

允许 SSH 会话同时存在，但不要再建一套该用户的图形桌面。 关闭不符合无人值守目标的闲置自动挂起/关闭显示策略，保留正常锁屏、手动 电源操作和管理员认证。自动登录不会自动解锁加密钱包/密钥环；需单独验证。 Sunshine 随桌面退出，不保证能操作显示管理器的登录界面。

KDE/KWin 虚拟输出实现

本次核对并验证了 KWin 6.6.6：正常 DRM 后端支持创建虚拟输出， zkde_screencast_unstable_v1 的虚拟输出请求可在同一桌面中创建显示器。 该接口是 KDE 内部协议，不保证未来版本兼容，升级时必须重新验证。

本机使用一个小型 C/Wayland 辅助程序：

• 连接正常桌面的 Wayland socket，不启动第二个合成器。
• 使用 stream_virtual_output_with_description（接口版本至少为 4）。
• 使用固定名称，实际输出名为 Virtual- 加请求名称；通过枚举确认。
• 保持协议连接和 stream 对象存活以维持输出。
• 不连接 PipeWire 帧消费者，不建立 VNC 或其他网络监听。
• 收到 created 后向 systemd 发送 READY=1。
• stream 关闭、连接错误应退出并允许服务重试。
• SIGTERM/SIGINT 应退出事件循环、关闭 stream 和连接；不要阻塞在 wl_display_dispatch() 导致每次退出等待 SIGKILL。
• 若使用 prepare_read/poll/read_events，要处理 EINTR、断连、错误和 cancel_read 配对；测试正常停止、重启和合成器退出。

通过 .desktop 为辅助程序声明：

X-KDE-Wayland-Interfaces=zkde_screencast_unstable_v1

Exec 必须匹配实际二进制路径；不要全局设置 KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 来消除授权问题。 发行版 Sunshine 可能已提供对应权限文件，先检查再补充。

krfb-virtualmonitor 可用于验证，但先核对对应版本的参数和实现。 本机仓库版本 25.12.3 会启动 VNC，未提供纯虚拟屏命令行开关； 不能假定它只是显示器助手，也不能假定 --port 0 表示关闭监听。

服务顺序与恢复

虚拟屏服务使用 Type=notify，并随 graphical-session.target 回收。 在实际 KWin、PipeWire 就绪后启动。必要时排在 Plasma shell/splash 之前， 避免应用先启动时没有任何输出；检查完整依赖图，避免循环排序。 设置合理的失败重试；不能只依赖固定 sleep 认定显示器已经就绪。

Sunshine 在虚拟输出服务就绪后启动，随图形会话退出，异常退出可自动重启。 检查厂商单元的 After/Wants，以及登录时导入用户管理器的图形环境。

本机曾遇到厂商 Sunshine 单元 After=xdg-desktop-portal.service， Portal 在重登录时仍在启动，导致 Sunshine start job 长时间等待。 KWin 直接捕获并不需要等待共享授权 Portal；本机通过用户级服务覆盖调整排序。 普通应用所需 Portal 继续保留。此修复只适用于确认了依赖问题的目标机器， 不要在其他捕获方式下无条件移除依赖，也不要修改 /usr/lib 的软件包文件。 用户级完整单元覆盖可能遮蔽未来软件包更新，应在维护记录中标明并定期复核。

“服务 inactive”不一定是启动失败：先看 systemctl --user list-jobs、 status 和日志，可能仍在等待依赖。修改后需要完整重登录验证。

捕获、编码、输入与音频

• KDE 优先验证 capture=kwin；Labwc 验证 capture=wlr。 合成器虚拟输出通常不是物理 KMS 扫描输出，不应沿用临时的 capture=kms。
• 本机 Intel 使用 VAAPI；其他 GPU 必须重新探测编码器。
• 使用实际枚举出的固定输出名称，避免物理屏热插拔改变序号。
• 分别确认桌面/游戏 GPU 渲染器和 Sunshine 编码器；排除 llvmpipe 软件渲染。
• DMA-BUF 或硬件编码日志不能证明整条流水线零拷贝，也不能替代游戏测试。
• Sunshine 直接使用 KWin 捕获可避开共享授权 Portal；普通应用的文件选择、 屏幕共享等 Portal 功能仍应正常保留。
• 优先使用厂商 udev 规则、logind 活动 seat 和 uaccess ACL 分配输入权限。 不默认长期加入 input/video/render 组；临时授权应在正常会话建立后复核回收。
• 先保留正常默认音频。无声卡时 PipeWire 的 auto_null 可提供默认回环， 不必立即创建私有声卡或固定 audio_sink。
• 音频验证用实时播放，再从实际默认 monitor 录音；生成音频瞬时灌入后立即 退出可能造成错误的静音结论。检查 mute、volume、路由及录制波形。

显示设置与应用兼容性

先建立 1080p/60 SDR 基线，再测试更高分辨率、刷新率与缩放。 主机输出分辨率、桌面逻辑尺寸和 Moonlight 请求尺寸是不同设置。 不照搬另一台机器的缩放，也不承诺自动匹配客户端尺寸。

KDE 使用正常 KScreen 设置；Labwc 使用支持 wlr-output-management 的工具。 GUI 能调整不代表能保存，必须测试退出/重新登录后的恢复。需要辅助保存时， 采用确认、超时回滚、原子保存和已知可用的回退，避免把唯一远程输出关闭。

从真实桌面菜单或终端启动原版应用检查。SSH 的 DISPLAY 为空、SSH 身份 触发的 Polkit challenge，不能用于判定正常桌面权限失败。 必要时用 systemd-run --user 继承用户管理器已导入的图形环境；不要新建 D-Bus。 也不要让所有应用都通过 Sunshine 子进程启动，以免把其特殊运行环境带入应用。

配对与管理 API

Sunshine 管理账户与 Linux 账户独立。不要记录或公开密码、PIN、配对私钥。 Web 管理使用 HTTPS；未认证访问返回 401 是正常结果。 保留认证和 CSRF，不通过关闭保护修补 API 请求。

接口随版本变化，应优先查看当前安装的 Web 前端或对应版本源码。 本次 Sunshine 2026.906.222525 的流程是：

1. 认证 GET /api/pin，读取待配对客户端及其 ID。
2. 核对请求地址/名称，只选择用户指定的请求。
3. POST /api/pin，提交 pairing_id、pin、name。
4. pairing_id 是请求中的 32 位十六进制 ID，不是四位 PIN。
5. 旧版只提交 pin/name 的示例在本版返回 400。

有多个待配对请求时不要将一个 PIN 批量提交给所有设备。 配对成功仍需客户端选择 Desktop 才会开始实际串流。

验收清单与证据标准

• 正常、唯一、活动的本地图形会话，虚拟输出与 GPU 渲染器正确。
• 图形会话退出后相关服务回收，再登录自动恢复且无重复实例。
• 虚拟屏助手崩溃/重启后的输出恢复，Sunshine 可再次捕获。
• 原版 Snap/Flatpak/发行版应用入口、文件选择器、托盘、浏览器打开链接。
• 从真实桌面执行 pkexec，显示认证窗口，输入密码后确实执行成功。
• 使用真实桌面进程身份检查电源策略；策略检查不等于实际点按钮验证。
• 锁屏、正常密码解锁；服务 LockedHint 不替代实际界面/交互检查。
• 音频回环、远程键鼠和手柄、实际游戏 GPU 与客户端帧率/延迟。
• 客户端实际画面、听感、断开重连，物理显示器热插拔。
• 分辨率/缩放修改与持久化，升级/重启后的恢复。
• 最后进行实际整机重启；这会关闭工作，应在用户授权范围内、保存工作后执行。

不要把编码器自检的 PipeWire streaming 日志误判为 Moonlight 已连接。 “SDDM 重启成功”不能写成“整机重启成功”。未验证项目明确保留为待验收， 不为消除日志警告而关闭系统安全机制。

本次机器的参考资料与验证范围

本机为 Ubuntu 26.04.1、KWin 6.6.6、Intel Lunar Lake、Sunshine 2026.906.222525。这些版本只描述本次验证，不作为所有机器的硬性依赖。

详细部署记录：/home/kevinzhow/sunshine-setup/README.md。 可参考的虚拟输出源码和构建文件： /home/kevinzhow/sunshine-setup/virtual-output/。 迁移前修改源码/Makefile 中的安装路径，并复核协议及服务环境。

已验证正常 SDDM 自动登录、虚拟输出、Intel 渲染、三种 VAAPI 编码器探测、 Firefox 原版菜单入口、KDE 文件选择器、Polkit 认证、虚拟键盘锁屏解锁、 音频回环、完整图形会话恢复和 Moonlight 配对。当前用户服务无失败项。 尚未记录实际整机重启、客户端完整画面/声音体验、游戏性能、HDMI 热插拔和 显示设置持久化验收，不将这些项目视为已通过。

其他环境的经验来源： LXQt/Labwc 部署记录。 迁移时保留其正常会话原则，不直接复制版本补丁或机器参数。

官方参考： systemd 桌面集成、 KWin 6.6.6 DRM 后端、 本次 Sunshine KWin 捕获实现。