sunshine - ubuntu 22.04, moonlight - mac OS26 远程桌面-平芜编程栈

1. 安装

https://github.com/LizardByte/Sunshine/releases

下载最新版，

wgethttps://github.com/LizardByte/Sunshine/releases/download/v2026.817.185037/sunshine-ubuntu-22.04-amd64.debsudoaptinstallsunshine-ubuntu-22.04-amd64.deb

以下是Ubuntu 22.04（远程主机，Sunshine 服务端）+ macOS 26（本地主机，Moonlight 客户端）的完整安装与配置步骤。核心思路：Ubuntu 侧 Sunshine 不使用 systemd，而是随 GNOME 桌面会话自动启动，彻底避免 Wayland 下托盘崩溃、环境变量缺失等问题。

一、Ubuntu 22.04 侧 — 安装并配置 Sunshine

1. 下载并安装 Sunshine

Sunshine 官方提供 Ubuntu 22.04 的.deb包，直接从 GitHub Releases 下载安装：

cd~wgethttps://github.com/LizardByte/Sunshine/releases/latest/download/sunshine-ubuntu-22.04-amd64.debsudoaptupdatesudoaptinstall-y./sunshine-ubuntu-22.04-amd64.deb

安装完成后，Sunshine 会默认注册一个 systemd 用户服务，但我们不启用它，下一步将其停用。

2. 停用 systemd 用户服务

systemd 用户服务在 GNOME Wayland 下启动时缺少图形环境变量，Qt 托盘会崩溃，且与桌面自启动冲突。

systemctl--userstop sunshine systemctl--userdisable sunshine

3. 创建配置文件（禁用 system_tray）

Sunshine Linux 版读取的是sunshine.conf，配置项叫system_tray，值是字符串disabled。

mkdir-p~/.config/sunshinecat>~/.config/sunshine/sunshine.conf<<'EOF' system_tray = disabled EOF

注意：不是tray = false，也不是config.json。这是 GNOME Wayland 下避免托盘崩溃的关键。

4. 创建桌面自启动文件

让 Sunshine 随 GNOME 图形会话一起启动，自动继承DISPLAY、WAYLAND_DISPLAY、XDG_SESSION_TYPE等所有环境变量。

mkdir-p~/.config/autostartcat>~/.config/autostart/sunshine.desktop<<'EOF' [Desktop Entry] Name=Sunshine Comment=Self-hosted game stream host for Moonlight Exec=/usr/bin/sunshine Type=Application Terminal=false Icon=sunshine Categories=Game;Network; X-GNOME-Autostart-enabled=true EOFchmod+x ~/.config/autostart/sunshine.desktop

5. 配置防火墙（UFW）

Sunshine 需要开放以下端口才能正常通信：

sudoufw allow47984:47990/tcpsudoufw allow48010/tcpsudoufw allow47998:48000/udpsudoufw allow48002/udpsudoufw reload

验证：

sudoufw status|grep-E'4798|4801|4800|4802'

6. 创建 udev 规则（允许 Sunshine 创建虚拟输入设备）

Sunshine 通过uinput模拟游戏手柄和键盘鼠标，需要 udev 权限：

echo'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"'|\sudotee/etc/udev/rules.d/85-sunshine.rulessudoudevadm control --reload-rulessudoudevadm trigger

7. 注销并重新登录 GNOME

完成上述配置后，注销当前用户并重新登录（或重启）。GNOME 登录后 Sunshine 会自动在后台启动。

8. 验证 Sunshine 是否正常运行

ss-tlnp|grep-E'47989|47990'

看到端口监听即成功。浏览器访问 Web UI：

https://localhost:47990

首次访问需要设置管理员用户名和密码。

如果你不在 Ubuntu 机器旁边，可以通过 SSH 端口转发远程配置：
ssh-L47990:localhost:47990 username@ubuntu_ip
然后在本地浏览器打开https://localhost:47990进行初始化设置。

二、macOS 26 侧 — 安装并配置 Moonlight

1. 下载并安装 Moonlight

Moonlight 是 Sunshine 的客户端，macOS 版本支持 Intel 和 Apple Silicon：

安装方式（任选其一）：

方式 A：官网下载 DMG
1. 打开 https://moonlight-stream.org/
2. 点击macOS下载Moonlight-*.dmg
3. 双击挂载 DMG，将Moonlight.app拖入应用程序文件夹
方式 B：App Store
在 Mac App Store 搜索“Moonlight Game Streaming”并安装（注意认准官方开发者）。

2. 首次启动与配对

打开Moonlight应用。
如果 Ubuntu 主机与 Mac 在同一局域网，Moonlight 应能自动发现 Sunshine 主机；如果没有自动发现，点击“Add Host Manually”，输入 Ubuntu 的IP 地址。
点击主机图标，Moonlight 会显示一个4 位 PIN 码。
在 Ubuntu 侧打开 Sunshine Web UI（https://localhost:47990），进入“PIN”页面，输入该 PIN 码并给设备命名。
配对成功后，Moonlight 会显示“Pairing successful!”。

3. 连接并串流

配对完成后，Moonlight 主界面会列出 Sunshine 主机上的可用应用（默认至少有一个Desktop）。

点击Desktop即可串流整个 Ubuntu 桌面。
首次连接时可根据网络情况调整分辨率、帧率、码率（建议 LAN 环境下使用1080p@60fps / 50Mbps或更高）。

三、核心要点总结

坑	正确做法
systemd 用户服务启动 Sunshine	改用`~/.config/autostart/sunshine.desktop`桌面自启动
配置项叫`tray`	实际叫`system_tray`
值写`false`	实际写`disabled`
用`config.json`	Linux 版读`sunshine.conf`
GNOME Wayland 托盘崩溃	禁用`system_tray`彻底解决
防火墙未开放端口	按上文开放 TCP/UDP 端口
无虚拟输入设备权限	创建`/etc/udev/rules.d/85-sunshine.rules`

四、可选优化

1. 固定 Ubuntu IP（局域网内）

在路由器中为 Ubuntu 主机设置静态 DHCP 绑定，或配置 Netplan 固定 IP，避免 Moonlight 每次都要重新查找主机。

2. 远程访问（不在同一局域网）

如果需要在公网访问，推荐：

Tailscale / WireGuard：在 Ubuntu 和 macOS 上都安装 Tailscale，组成虚拟局域网，Moonlight 中直接输入 Tailscale 分配的 IP。
SSH 隧道：仅用于临时管理 Web UI，不适合游戏串流（延迟高）。

3. 编码器调优

在 Sunshine Web UI →Configuration中检查自动识别的编码器：

NVIDIA GPU→ NVENC
AMD GPU→ AMF
Intel iGPU→ QuickSync (VAAPI)
无独显 → Software fallback（CPU 编码，延迟较高）

至此，两侧配置完成。重新登录 Ubuntu 后 Sunshine 会自动启动，Mac 上打开 Moonlight 即可随时串流。

2. 配置自动登录

不需要在 Ubuntu 上"复刻"一个和 Mac 相同的登录，但有一个关键前提：Ubuntu 主机必须先有一个用户登录到 GNOME 桌面，Sunshine 才能工作。

为什么必须先登录？

Sunshine 在GNOME Wayland下需要依赖活跃的图形会话来捕获屏幕。它不能自己创建或唤醒一个图形会话——这和 Windows 版 Sunshine（可以虚拟显示器、锁屏连接）不同。

所以流程必须是：

Ubuntu 开机 → 用户登录 GNOME 桌面 → Sunshine 随桌面自启动 → Moonlight 连接

Moonlight 只管连接，不管替你在 Ubuntu 上登录桌面。

如果你希望完全无人值守

如果你不想每次 Ubuntu 重启后都手动去登录一次，可以配置GDM 自动登录：

sudonano/etc/gdm3/custom.conf

找到并修改为（将your_username换成你的实际用户名）：

[daemon] AutomaticLoginEnable=true AutomaticLogin=your_username

保存后重启，Ubuntu 开机后会自动进入桌面，Sunshine 随之自动启动，之后 Mac 上的 Moonlight 随时可连。

总结

问题	答案
Ubuntu 需要和 Mac 相同的用户名/密码吗？	不需要，两边完全独立
Ubuntu 需要先有人登录桌面吗？	需要，Sunshine 依赖活跃图形会话
能做到开机后无人值守直接连吗？	可以，配置 GDM 自动登录即可

3. 配置分辨率

(实践用了方案二）

配置输出分辨率涉及两端：Moonlight 客户端请求什么分辨率，以及Sunshine 服务端是否动态调整物理显示器的分辨率来匹配。以下是针对你场景（Ubuntu 22.04 GNOME Wayland + 桌面自启动）的完整配置方法。

方案一：动态分辨率匹配（推荐）

让 Ubuntu 桌面在串流时临时切换分辨率到 Moonlight 客户端请求的分辨率，串流结束后恢复。这是体验最好的方案。

1. 找到你的显示器输出名

在 Ubuntu 上执行：

kscreen-doctor-o

输出示例：

Output: 1 DP-1 ... Output: 2 HDMI-1 ...

记下你的主显示器名称（如DP-1或HDMI-1）。

2. 在 Sunshine Web UI 中配置 Command Preparations

打开https://localhost:47990→Configuration→Applications→ 编辑你要串流的应用（或Desktop）→Command Preparations→ 点击Add：

字段	值
Do Command	`sh -c "kscreen-doctor output.DP-1.mode.${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}"`
Undo Command	`sh -c "kscreen-doctor output.DP-1.mode.1920x1080@60"`

将DP-1替换为你实际的显示器名称，1920x1080@60替换为你平时使用的分辨率和刷新率。

环境变量说明：Sunshine 在串流启动时会自动注入以下变量，可直接在命令中使用：

变量	含义
`SUNSHINE_CLIENT_WIDTH`	Moonlight 请求的分辨率宽度
`SUNSHINE_CLIENT_HEIGHT`	Moonlight 请求的分辨率高度
`SUNSHINE_CLIENT_FPS`	Moonlight 请求的帧率

3. 为什么桌面自启动对此方案更有利

如果你之前用 systemd 启动 Sunshine，这些kscreen-doctor命令会因为没有DISPLAY/WAYLAND_DISPLAY环境变量而失败：

而你的桌面自启动方式（~/.config/autostart/sunshine.desktop）自动继承了完整的图形会话环境，所以kscreen-doctor可以正常工作。

方案二：Moonlight 客户端直接设置（最简单）

如果你不想折腾服务端分辨率切换，直接在macOS 上的 Moonlight中设置：

打开 Moonlight → 点击右上角 ⚙️设置
设置分辨率、帧率、码率：

场景	分辨率	帧率	码率
MacBook Air / 一般 WiFi	1920×1080	60 fps	20–30 Mbps
MacBook Pro / 有线网络	2560×1440	60 fps	40–60 Mbps
4K 显示器 / 优质网络	3840×2160	60 fps	80–120 Mbps

Moonlight 会将画面缩放到你设置的尺寸，但Ubuntu 物理显示器分辨率不变。如果客户端分辨率与显示器原生比例不一致，会出现黑边或拉伸。

方案三：指定 Sunshine 捕获特定显示器（多屏场景）

如果你有多个显示器，可以在~/.config/sunshine/sunshine.conf中指定捕获哪一个：

# 先查看 Sunshine 启动日志中的显示器列表journalctl--user|grep"Detected display"

然后在sunshine.conf中添加：

system_tray = disabled output_name = HDMI-1

将HDMI-1替换为日志中显示的连接器名称。

方案四：虚拟显示器（Headless / 无物理显示器）

如果你的 Ubuntu 主机不接物理显示器，可以配置虚拟显示器。这个比较复杂，取决于你的显卡：

NVIDIA 显卡（推荐）

参考社区方案，通过内核参数强制启用虚拟显示器：

核心步骤：

生成自定义 EDID（包含你想要的分辨率，如 4K@120Hz）
配置 GRUB 内核参数强制启用连接器
Sunshine 配置capture = kms，自动捕获虚拟显示器

通用方案（xrandr + 虚拟输出）

如果你使用 Intel/AMD 显卡，可以尝试：

# 创建虚拟输出（需安装 xserver-xorg-video-dummy 或类似驱动）xrandr--addmodeVIRTUAL1 1920x1080

然后在 Sunshine 中指定output_name = VIRTUAL1。

总结：按场景选择

场景	推荐方案
Ubuntu 接了物理显示器，想完美匹配 Mac 分辨率	方案一（Command Preparations + kscreen-doctor）
懒得配置，能接受黑边或缩放	方案二（只在 Moonlight 客户端设置）
Ubuntu 多显示器，只想串流其中一块	方案三（`output_name`指定）
Ubuntu 不接显示器（headless）	方案四（虚拟显示器）

最推荐的是方案一 + 方案二结合：服务端用 Command Preparations 动态切分辨率，客户端 Moonlight 按需设置合适的码率。