Sunshine 安装配置实践记录（Linux 端）
实践时间：2026-06-14 系统环境：Ubuntu 24.04.2 LTS 显卡：Intel UHD Graphics 630（CometLake-S GT2） 桌面环境：GNOME + X11（Xorg） Sunshine 版本：v2026.516.143833
一、环境说明
硬件信息
GPU: Intel UHD Graphics 630 (CometLake-S GT2, rev 05)
PCI ID: 00:02.0
系统信息
$ lsb_release -a
Distributor ID: Ubuntu
Description: Ubuntu 24.04.2 LTS
Release: 24.04桌面环境确认
# X11 Socket 文件（确认 display 编号）
$ ls /tmp/.X11-unix/
X1
# Xorg 进程
$ ps aux | grep Xorg
/usr/lib/xorg/Xorg vt2 -displayfd 3 -auth /run/user/1000/gdm/Xauthority ...
# 所以正确的环境变量：
DISPLAY=:1
XAUTHORITY=/run/user/1000/gdm/Xauthority重要：display 编号是
:1而非:0，需要通过ls /tmp/.X11-unix/确认， 不同系统可能不同。
VAAPI 驱动确认
$ ls /dev/dri/
card1 renderD128 by-path/
$ dpkg -l | grep -i "intel-media\|va-driver"
ii intel-media-va-driver 24.1.0+dfsg1-1
ii i965-va-driver 2.4.1+dfsg1-1build2
ii libva2 2.20.0-2build1VAAPI 驱动已预装，无需额外安装。
二、安装 Sunshine
下载 deb 包
从 GitHub Releases 下载对应 Ubuntu 版本的包：
# 查询最新版本和下载地址
wget -q -O /tmp/sunshine_release.json "https://api.github.com/repos/LizardByte/Sunshine/releases/latest"
python3 -c "
import json
data = json.load(open('/tmp/sunshine_release.json'))
print('最新版本:', data['tag_name'])
assets = [a for a in data['assets'] if 'ubuntu-24.04-amd64' in a['name']]
for a in assets:
print(a['name'], '->', a['browser_download_url'])
"直接下载命令（Ubuntu 24.04 amd64）：
# 使用 axel 多线程下载（GitHub 直连速度较慢，axel 更稳定）
# 若 axel 未安装：sudo snap install axel 或 sudo apt install axel
axel -n 4 "https://github.com/LizardByte/Sunshine/releases/download/v2026.516.143833/sunshine-ubuntu-24.04-amd64.deb" \
-o ~/sunshine.deb下载注意事项：
- GitHub 直连在某些网络环境下速度极慢（1-4 KB/s），属正常现象
curl/wget可能因 GitHub CDN 签名链接超时而失败，axel会自动重连- 文件总大小约 10 MB，预计需要 10-60 分钟（取决于网速）
- 推荐在桌面浏览器下载后再安装，速度更快
安装
sudo apt install ~/sunshine.deb -y安装过程会自动安装依赖 miniupnpc，并执行以下操作：
Loading uhid kernel module for DS5 emulation.
Setting CAP_SYS_ADMIN, CAP_SYS_NICE capabilities on Sunshine binary.
Reloading udev rules.
安装成功验证：
$ which sunshine
/usr/bin/sunshine
$ dpkg -l sunshine
ii sunshine 2026.516.143833 amd64 Self-hosted game stream host for Moonlight三、安装后配置
3.1 添加用户到 video/render 组（VAAPI 权限）
Intel GPU 的 VAAPI 设备 /dev/dri/renderD128 权限为 render 组，默认用户不在该组：
sudo usermod -aG video,render $USER注意：此修改在当前会话不立即生效，需要重新登录。 如果使用 systemd 用户服务启动 Sunshine，会自动继承该权限。
验证：
$ groups
zbc adm cdrom sudo dip video plugdev render lpadmin lxd sambashare docker3.2 配置文件
Sunshine 安装后会自动创建配置目录：
$ ls ~/.config/sunshine/
apps.json credentials/ sunshine.conf sunshine.log编写 sunshine.conf（根据本机 Intel + X11 环境）：
cat > ~/.config/sunshine/sunshine.conf << 'EOF'
# Sunshine 配置文件
# 系统：Ubuntu 24.04, Intel UHD 630, X11
# ===== 捕屏设置 =====
capture = x11
# ===== 编码器设置 =====
# Intel GPU VAAPI 硬件编码
encoder = vaapi
# VAAPI 设备路径（Intel GPU）
adapter_name = /dev/dri/renderD128
# ===== 网络设置 =====
# Moonlight 连接的基础端口（默认 47989，Web UI 自动为此值 +1 即 47990）
port = 47989
address_family = both
# ===== 安全设置 =====
# 允许局域网访问 Web UI
origin_web_ui_allowed = lan
EOF3.3 创建 systemd 用户服务
Sunshine 官方 deb 包没有自带 systemd 服务文件，需手动创建：
mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/sunshine.service << 'EOF'
[Unit]
Description=Sunshine self-hosted game stream host
After=network.target graphical-session.target
Wants=graphical-session.target
[Service]
ExecStart=/usr/bin/sunshine
Environment=DISPLAY=:1
Environment=XAUTHORITY=/run/user/1000/gdm/Xauthority
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=graphical-session.target
EOF关键说明：
DISPLAY=:1：通过ls /tmp/.X11-unix/确认，本机为:1XAUTHORITY=/run/user/1000/gdm/Xauthority：GDM 登录会话的 X 鉴权文件1000是 UID，通过id -u确认
启用并启动服务：
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user daemon-reload
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user enable sunshine.service
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user start sunshine.service四、验证运行状态
查看服务状态
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user status sunshine.service成功输出示例：
● sunshine.service - Sunshine self-hosted game stream host
Loaded: loaded (...; enabled; ...)
Active: active (running) since Sun 2026-06-14 10:54:46 +08; 1min ago
Main PID: 1166973 (sunshine)
Jun 14 10:54:47 hostname sunshine[...]: Info: Found H.264 encoder: h264_vaapi [vaapi]
Jun 14 10:54:47 hostname sunshine[...]: Info: Configuration UI available at [https://localhost:47990]
Jun 14 10:54:48 hostname sunshine[...]: Info: Avahi service hostname successfully established.
关键日志含义：
Found H.264 encoder: h264_vaapi [vaapi]✅ VAAPI 硬件编码正常Configuration UI available at [https://localhost:47990]✅ Web UI 可访问Avahi service ... established✅ mDNS 服务正常（Moonlight 可自动发现主机）
查看监听端口
$ ss -tlnp | grep -E "479|480"
LISTEN *:47984 # HTTPS 认证端口（port - 5）
LISTEN *:47989 # HTTP 基础端口（Moonlight 连接此处）
LISTEN *:47990 # Web UI（port + 1）
LISTEN *:48010 # RTSP 串流控制查看日志
# 实时日志
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service -f
# 历史日志文件
cat ~/.config/sunshine/sunshine.log五、本机网络信息
$ ip addr show | grep "inet " | grep -v 127
inet 192.168.3.104/24 # 局域网 IP，Windows 端 Moonlight 用此地址连接六、服务管理命令速查
# 启动
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user start sunshine.service
# 停止
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user stop sunshine.service
# 重启
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart sunshine.service
# 查看状态
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user status sunshine.service
# 查看实时日志
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service -f
# 禁用开机自启
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user disable sunshine.service七、遇到的问题和解决方案
问题 1：DISPLAY 错误（Unable to initialize capture method）
现象：
Error: Unable to initialize capture method
Error: Platform failed to initialize
原因：启动 Sunshine 时没有设置正确的 DISPLAY 环境变量。
解决：
- 确认 display 编号：
ls /tmp/.X11-unix/（本机为X1，即:1） - 在 systemd 服务文件中设置
Environment=DISPLAY=:1
问题 2：VAAPI 编码失败
现象：
Encoder [vaapi] failed
Couldn't find any working encoder matching [vaapi]
原因：用户不在 render 组，无权访问 /dev/dri/renderD128。
解决：
sudo usermod -aG video,render $USER
# 然后重新登录或重启服务
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart sunshine.service问题 3：系统托盘创建失败（Warning: Failed to create system tray）
现象：
Warning: Failed to create system tray
原因：Sunshine 在无系统托盘环境（如 headless 终端启动）下运行。
影响：不影响实际投屏功能，可以忽略。使用 systemd 服务管理时此警告消失。
问题 4：corplink-mdm 安装报错
现象：安装 sunshine deb 时出现：
dpkg: 处理软件包 corplink-mdm (--configure)时出错
原因：系统中另一个包 corplink-mdm 的 postinstall 脚本有 bug，与 Sunshine 无关。
影响：Sunshine 本身安装完整，不受影响。
问题 5：Moonlight 提示”无法连接到目标计算机”
现象：在 Moonlight 中手动输入 IP 后，提示无法连接，连扫描也无法找到主机。
原因：sunshine.conf 中 port 参数的含义是 Moonlight 连接的流传输基础端口，而非 Web UI 端口。默认值应为 47989。若误设为 47990，端口整体偏移，导致 Moonlight 尝试连接 47989 时无人响应。
端口关系：
port = 47989（默认）
→ Moonlight HTTP 连接端口：47989
→ Web UI (HTTPS)：47990（port + 1）
→ HTTPS 认证端口：47984（port - 5）
→ RTSP 串流控制：48010（port + 21）
解决：确认 ~/.config/sunshine/sunshine.conf 中：
port = 47989然后重启服务：
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart sunshine.service问题 6：Moonlight 能扫到主机但显示”离线”
现象：Moonlight 中能看到主机图标（通过 mDNS 发现），但状态显示为”离线”，无法点击连接。
原因（本机遇到的情况）：Linux 主机运行了 corplink 企业 VPN（tun0 接口），Windows 客户端同时也连接了同一 VPN，导致 Moonlight 的网络流量通过 VPN 隧道路由，而非走局域网直连。VPN 不转发 Sunshine 的流传输端口，因此连接失败。
诊断方法：
# 在 Linux 查看是否有 VPN 接口
ip addr show | grep tun
# 有 tun0 说明 VPN 正在运行
# 抓包确认 Windows 的连接请求是否到达
sudo tcpdump -i wlp2s0 -n "port 47989"解决：
- 暂时关闭 Windows 端的 VPN 客户端（corplink 等），让 Windows 通过局域网直连 Linux
- 或在 VPN 客户端中配置”局域网直连”（split tunnel）模式，使 192.168.x.x 流量不走 VPN
八、配置文件完整参考
~/.config/sunshine/sunshine.conf（本机实际使用）：
# 捕屏方式：x11（X11 环境）或 kms（Wayland KMS 环境）
capture = x11
# 编码器：vaapi（Intel/AMD）、nvenc（NVIDIA）、software（纯软件）
encoder = vaapi
# GPU 设备路径（Intel 集显）
adapter_name = /dev/dri/renderD128
# Moonlight 连接基础端口（默认 47989）
# 注意：此处是流传输端口，不是 Web UI 端口
# Web UI 端口 = port + 1（即 47990）；HTTPS 认证端口 = port - 5（即 47984）
port = 47989
# 地址协议：both（IPv4+IPv6）、ipv4、ipv6
address_family = both
# Web UI 访问权限：lan（局域网）、wan（公网）、pc（仅本机）
origin_web_ui_allowed = lan~/.config/systemd/user/sunshine.service（本机实际使用）：
[Unit]
Description=Sunshine self-hosted game stream host
After=network.target graphical-session.target
Wants=graphical-session.target
[Service]
ExecStart=/usr/bin/sunshine
Environment=DISPLAY=:1
Environment=XAUTHORITY=/run/user/1000/gdm/Xauthority
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=graphical-session.target