Sunshine 进阶配置与性能优化

实践时间：2026-06-14 系统环境：Ubuntu 24.04.2 LTS GPU：Intel UHD Graphics 630（CometLake-S GT2）桌面环境：GNOME + X11（Xorg） Sunshine 版本：v2026.516.143833

一、Web UI 配置详解

1.1 首次访问流程

Sunshine Web UI 运行在 https://localhost:47990（注意：HTTPS，非 HTTP）。

第一次访问步骤：

在 Linux 本机浏览器打开 https://localhost:47990
浏览器提示 SSL 证书不安全（Sunshine 使用自签名证书）：
- Chrome/Chromium：点击 Advanced → Proceed to localhost (unsafe)
- Firefox：点击 Advanced → Accept the Risk and Continue
首次访问会提示创建管理员账号，设置用户名和密码
以后所有登录均使用此凭据

重要：Sunshine 没有默认密码。如果忘记密码：

rm ~/.config/sunshine/credentials/
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart sunshine.service
# 重启后重新访问 Web UI 设置新密码

1.2 Web UI 各页面说明

页面	功能
Home	版本信息、快速链接
Applications	管理可被 Moonlight 启动的应用（包括”桌面”）
Configuration	所有编码、网络、音频、安全参数
PIN	输入 Moonlight 显示的 4 位配对码
Troubleshooting	查看日志、管理已配对设备
Change Password	修改 Web UI 登录密码

1.3 Configuration → Video 选项

分辨率（Resolutions）

这里配置的是 Sunshine 向 Moonlight 提供的分辨率候选列表，Moonlight 连接时可以从中选择，并非强制锁定。

推荐配置（本机 DP-1，2560×1440）：

2560x1440
1920x1080
1280x720

帧率（FPS）

同样是提供给 Moonlight 的帧率候选列表。推荐：

30, 60

桌面办公选 30fps 节省带宽；需要流畅操作感时选 60fps。

Bitrate（码率）

设为 0 时，Sunshine 完全跟随 Moonlight 客户端请求的码率
推荐：此处设为 0，然后在 Moonlight 客户端设置码率滑块

1.4 Configuration → Network 选项

选项	建议值	说明
`upnp`	`disabled`	关闭 UPnP 自动端口映射（局域网不需要）
`origin_web_ui_allowed`	`lan`	仅允许局域网访问 Web UI
`lan_encryption_mode`	`disabled`	局域网关闭加密，可降低延迟和 CPU 占用
`address_family`	`both`	同时支持 IPv4 和 IPv6

1.5 端口说明

Sunshine 使用一组固定端口，不建议修改：

端口	协议	用途
47984	TCP	HTTPS 客户端认证
47989	TCP	HTTP 基准端口
47990	TCP	Web UI 管理界面
48010	TCP	RTSP 串流协商
47998	UDP	视频流
47999	UDP	控制输入（键盘/鼠标/手柄）
48000	UDP	音频流
48002	UDP	麦克风回传

本机防火墙状态：未启用（inactive），无需配置。如果启用了 UFW，参见 02 文档附录。

二、VAAPI 编码器优化

2.1 验证 VAAPI 是否正常工作

在依赖 VAAPI 之前，先确认环境：

# 确认 VAAPI 设备存在
ls /dev/dri/render*
# 期望输出：/dev/dri/renderD128
 
# 确认 intel-media-va-driver 已安装
dpkg -l | grep -E "intel-media|va-driver"
 
# 查看 VAAPI 支持的编解码能力
LIBVA_DRIVER_NAME=iHD vainfo --display drm --device /dev/dri/renderD128 | grep -E "VAProfile|Driver"

Intel UHD 630 预期输出中应包含：

Driver version: Intel iHD driver for Intel(R) Gen Graphics - 24.x.x
VAProfileH264Main    : VAEntrypointEncSlice    ← H.264 编码（基本配置）
VAProfileH264High    : VAEntrypointEncSlice    ← H.264 编码（高质量）
VAProfileHEVCMain    : VAEntrypointEncSlice    ← H.265 8-bit 编码

VAProfileH264High : VAEntrypointEncSlice 是使用 VAAPI 的最低要求。

2.2 驱动选择：iHD vs i965

Ubuntu 24.04 上 Intel UHD 630 有两套 VAAPI 驱动：

驱动	包名	适用场景
`iHD`（intel-media-driver）	`intel-media-va-driver-non-free`	第 6 代及以上 Intel GPU，推荐
`i965`（libva-intel-driver）	`i965-va-driver`	旧驱动，不推荐用于 UHD 630

确保安装并使用 iHD：

sudo apt install intel-media-va-driver-non-free
 
# 验证（应看到 iHD 而非 i965）
LIBVA_DRIVER_NAME=iHD vainfo 2>&1 | head -3

在 systemd 服务文件的 [Service] 段追加此环境变量可显式指定驱动：

Environment=LIBVA_DRIVER_NAME=iHD

2.3 H.264 vs H.265 选择

针对 Intel UHD 630 + 局域网桌面投屏，强烈推荐 H.264：

编解码器	优点	缺点
H.264（h264_vaapi）	成熟稳定，兼容性最好	同等质量码率略高
H.265（hevc_vaapi）	同等质量码率更低	UHD 630 上有已知 segfault 问题
AV1	质量最优	UHD 630 不支持 AV1 硬件编码

已知问题：Sunshine 在 Intel UHD 630（Linux）上使用 H.265 编码时存在偶发崩溃（GitHub Issue #4749）。如果必须尝试 H.265，在 sunshine.conf 中加入：
hevc_mode = 1

2.4 实际编码性能测试（可选）

在配置 Sunshine 之前，可用 FFmpeg 测试 VAAPI 硬件编码是否正常：

ffmpeg -vaapi_device /dev/dri/renderD128 \
  -f lavfi -i testsrc=size=1920x1080:rate=30 \
  -vf 'format=nv12,hwupload' \
  -c:v h264_vaapi -qp 25 -t 5 \
  /tmp/test_vaapi.mp4 && echo "VAAPI H264 编码正常"

如果输出 VAAPI H264 编码正常 且生成了有效的视频文件，则 VAAPI 工作正常。

2.5 码率建议

场景	分辨率	推荐码率
局域网千兆，日常桌面操作	1440p（本机）	40–60 Mbps
局域网千兆，视频/图像处理	1440p	60–80 Mbps
局域网千兆，日常桌面操作	1080p	20–40 Mbps
局域网千兆，视频/图像处理	1080p	30–50 Mbps
局域网百兆，日常桌面	1080p	10–20 Mbps
追求最低延迟	720p	10–15 Mbps

调整方式（Moonlight 客户端）：

Settings → Bitrate 滑块，拖到对应值后重新连接生效。

注意事项：

不要超过 100 Mbps，部分用户反馈 100 Mbps 以上会出现延迟峰值
静态内容（文字、IDE）下 H.264 VAAPI 的 CBR 码率控制精度有限，码率可能波动，属正常现象
LP 编码模式（Low Power）：Intel VAAPI 在某些情况下会自动切换到低功耗编码模式（日志显示 Using LP encoding mode），搭配 CQP 码率控制（Using CQP with single frame VBV size），导致实际码率远低于客户端请求值（例如 1440p 只给 ~15 Mbps）。这是 Intel UHD 630 VAAPI 的已知行为，提高 Moonlight 码率滑块值可以缓解，但不能完全消除

三、桌面投屏专项配置

3.1 添加”桌面”到应用列表

Sunshine 默认会有一个 Desktop 条目。如果没有，需要手动添加：

进入 Web UI → Applications → Add New
按如下填写：

字段	值
Application Name	`Desktop`
Command	留空（关键！）
Working Directory	留空

Command 留空 意味着 Sunshine 不启动新程序，直接捕获当前桌面并串流。

在 Moonlight 客户端中点击 Desktop 即可开始整屏投屏。

3.2 关于可变帧率（VFR）

Sunshine 使用可变帧率编码。当屏幕静止时（如看文档、等待输入），实际帧率会自动降低到接近 0；当有内容变化（滚动页面、播放视频）时，帧率恢复到设定值。

这对桌面投屏是正常行为，不是卡顿或故障。

3.3 改善文字清晰度

桌面投屏最常见的抱怨是”文字模糊”。原因是 H.264 对高对比度边缘（黑色文字/白色背景）编码效率不如视频内容。

有效解决方法（优先级从高到低）：

提高码率：在 Moonlight 客户端 Settings → Bitrate 滑块调高；1440p 建议 40–60 Mbps，1080p 建议 20–40 Mbps，文字清晰度显著提升
保持分辨率一致：Moonlight 请求分辨率 = 目标屏幕原生分辨率，避免缩放
关闭客户端图像处理：确保 Moonlight 的锐化/平滑滤镜处于关闭状态
帧率：静态文字场景 30fps 和 60fps 视觉质量无差异，只有滚动时 60fps 才有优势

3.4 分辨率和帧率推荐

场景	推荐配置	说明
日常办公、看文档	1440p 30fps，码率 40 Mbps	本机实际分辨率，文字清晰
视频/图像处理	1440p 60fps，码率 60 Mbps	流畅操作感
追求最低延迟	1080p 60fps，码率 20 Mbps	降低分辨率减少编码负担
极限低延迟	720p 60fps，码率 15 Mbps	牺牲清晰度换延迟

四、安全设置

4.1 局域网场景安全建议

# 在 ~/.config/sunshine/sunshine.conf 中配置
upnp = disabled                  # 关闭 UPnP，防止自动开放公网端口
origin_web_ui_allowed = lan      # 仅局域网可访问 Web UI
lan_encryption_mode = disabled   # 局域网关闭加密，降低延迟和 CPU 占用

如需从外网访问，应启用 VPN，而不是直接暴露 Sunshine 端口。

4.2 PIN 配对机制

首次连接时必须进行 PIN 配对，配对成功后设备被记为受信任，后续连接无需再次 PIN。

配对流程（快速参考）：

Moonlight（Windows）         Sunshine（Linux）
     |                              |
     | 点击主机图标                  |
     | ← 显示 4 位 PIN 码            |
     |                              |
     |         （同时）              |
     |                    打开 https://localhost:47990
     |                    → PIN 页面
     |                    → 输入 4 位码
     |                    → 点击 Send
     |                              |
     | 锁形图标消失 = 配对成功 ←    |

PIN 有时效性（约 30 秒），建议提前打开 Web UI PIN 页面，再在 Moonlight 发起配对。

4.3 管理已配对设备

查看已配对设备：

进入 Web UI → Troubleshooting 选项卡，可看到所有已配对设备名称。

撤销配对（取消某设备的连接权限）：

在 Troubleshooting 中点击对应设备的 Unpair 按钮
必须重启 Sunshine 才能生效：

XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user restart sunshine.service

重要安全提醒：已确认的安全漏洞（GHSA-v8gw-jw28-v55m）显示，如果撤销配对后不重启 Sunshine，被撤销的设备仍可重新连接（无需 PIN）。重启后才真正生效。

五、日志查看与问题排查

5.1 日志位置

方式一：systemd 日志（推荐）

# 实时追踪
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service -f
 
# 查看最近 100 行
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service -n 100
 
# 查看特定时间段
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service --since "1 hour ago"

方式二：日志文件

tail -f ~/.config/sunshine/sunshine.log

方式三：Web UI

进入 Troubleshooting → Log 区域查看。

5.2 关键日志含义

启动成功的标志：

Info: Found H.264 encoder: h264_vaapi [vaapi]          ← VAAPI 正常
Info: Configuration UI available at [https://localhost:47990]  ← Web UI 可访问
Info: Avahi service hostname successfully established.  ← mDNS 自动发现正常

常见错误信息：

错误信息	原因	解决方案
`Unable to initialize capture method`	DISPLAY 环境变量错误	确认 `DISPLAY=:1`（通过 `ls /tmp/.X11-unix/` 检查）
`Platform failed to initialize`	同上	同上
`Encoder [vaapi] failed`	用户不在 render 组，或驱动问题	`sudo usermod -aG video,render $USER` 并重新登录
`Couldn't find any working encoder`	所有编码器均失败	检查 `vainfo` 输出；临时用 `encoder = software` 回退
`Failed to create system tray`	无系统托盘环境	可忽略，不影响实际功能
`Error: Could not open codec [h264_vaapi]: Invalid argument`	VAAPI 设备权限问题	检查 `/dev/dri/renderD128` 权限和用户组

5.3 Intel UHD 630 VAAPI 问题排查流程

# Step 1：确认用户组
groups $USER
# 应包含 video 和 render
 
# Step 2：确认设备可访问
ls -la /dev/dri/renderD128
# 应为 crw-rw---- ... render ...
 
# Step 3：验证 VAAPI
LIBVA_DRIVER_NAME=iHD vainfo --display drm --device /dev/dri/renderD128
 
# Step 4：搜索 Sunshine 日志中的编码器信息
XDG_RUNTIME_DIR=/run/user/$(id -u) journalctl --user -u sunshine.service | grep -i "encoder\|vaapi\|codec"
 
# Step 5（最终回退）：临时切换到软件编码排查问题
# 在 sunshine.conf 中临时改为：
# encoder = software

5.4 性能问题排查

在 Moonlight 客户端按 Ctrl + Alt + Shift + S 查看实时性能数据：

Render Latency   : Linux 渲染耗时（ms）
Encoder Latency  : Sunshine 编码耗时（ms）
Network Latency  : 网络传输耗时（ms）
Decoder Latency  : Moonlight 解码耗时（ms）
Total Latency    : 全链路总延迟

根据哪个指标偏高来定位瓶颈：

指标偏高	排查方向
Network Latency 高	优先改用有线网络；检查路由器/交换机负载
Encoder Latency 高	降低码率或分辨率；检查 VAAPI 是否生效
Decoder Latency 高	检查 Moonlight 客户端是否开启了硬件解码
Render Latency 高	Linux GPU 负载过高，降低分辨率或帧率

六、完整推荐配置参考

sunshine.conf

路径： ~/.config/sunshine/sunshine.conf

# Sunshine 配置文件
# 系统：Ubuntu 24.04, Intel UHD 630, X11（局域网桌面投屏）
 
# ===== 捕屏 =====
capture = x11
 
# ===== 编码器 =====
encoder = vaapi
adapter_name = /dev/dri/renderD128
 
# ===== 网络 =====
# 流传输基础端口（默认 47989）；Web UI = port+1（47990）；HTTPS认证 = port-5（47984）
port = 47989
address_family = both
upnp = disabled
origin_web_ui_allowed = lan
lan_encryption_mode = disabled
 
# ===== 性能 =====
# 局域网前向纠错比例（降低到 15% 节省带宽）
fec_percentage = 15
 
# ===== 如果遇到 H.265 崩溃，取消注释 =====
# hevc_mode = 1

sunshine.service

路径： ~/.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
Environment=LIBVA_DRIVER_NAME=iHD
Restart=on-failure
RestartSec=5s
 
[Install]
WantedBy=graphical-session.target

本机实际验证的关键环境变量：

DISPLAY=:1：通过 ls /tmp/.X11-unix/ 确认为 X1

XAUTHORITY=/run/user/1000/gdm/Xauthority：GDM 登录会话的 X 鉴权文件

LIBVA_DRIVER_NAME=iHD：显式指定 Intel 新驱动，避免退回到 i965

快速检查清单

vainfo 输出中包含 VAProfileH264High : VAEntrypointEncSlice
用户已加入 video 和 render 组
sunshine.conf 设置了 encoder = vaapi 和正确的 adapter_name
systemd 服务中设置了 DISPLAY=:1 和正确的 XAUTHORITY
Web UI 在 https://localhost:47990 可正常访问
Applications 中有 Command 为空 的 Desktop 条目
systemctl --user enable sunshine.service 已设置开机自启
Moonlight 客户端已完成 PIN 配对

Quartz 4

Explorer

Sunshine 进阶配置与性能优化

Sunshine 进阶配置与性能优化

目录

一、Web UI 配置详解

1.1 首次访问流程

1.2 Web UI 各页面说明

1.3 Configuration → Video 选项

1.4 Configuration → Network 选项

1.5 端口说明

二、VAAPI 编码器优化

2.1 验证 VAAPI 是否正常工作

2.2 驱动选择：iHD vs i965

2.3 H.264 vs H.265 选择

2.4 实际编码性能测试（可选）

2.5 码率建议

三、桌面投屏专项配置

3.1 添加”桌面”到应用列表

3.2 关于可变帧率（VFR）

3.3 改善文字清晰度

3.4 分辨率和帧率推荐

四、安全设置

4.1 局域网场景安全建议

4.2 PIN 配对机制

4.3 管理已配对设备

五、日志查看与问题排查

5.1 日志位置

5.2 关键日志含义

5.3 Intel UHD 630 VAAPI 问题排查流程

5.4 性能问题排查

六、完整推荐配置参考

sunshine.conf

sunshine.service

快速检查清单

参考资料

Graph View

Table of Contents

Backlinks