Sunshine 自托管游戏串流：从安装部署到 Moonlight 配对、编码器与网络调优的完整实战指南

Sunshine 是一款面向 Moonlight 客户端的自托管游戏串流服务器，将你的 PC 变成低延迟的云游戏主机，支持 Windows、Linux、macOS 与 FreeBSD，并提供 NVIDIA NVENC、AMD、Intel 硬件编码与软件编码等多种编码路径。本文按照「获取代码与安装包 → 平台初始化 → Web UI 首次配置与登录 → Moonlight 客户端配对 → 应用管理」五步主线展开，并结合当前仓库的 安装文档、配置参考 与 故障排查手册 以及 src/ 目录下的源码实现，把每一步的命令、配置项与底层原理讲透。读完本文，你可以独立完成 Sunshine 的部署、完成首个客户端配对，并掌握编码器选择、网络调优与日志诊断的实操方法。

一、为什么选择自托管：Sunshine 的定位

传统云游戏服务通常意味着订阅费、受限的游戏库和存放在云端的数据。Sunshine 作为自托管方案，把串流主机跑在你自己的机器上：游戏库完全由你掌控，视频与输入流量只在局域网（或你自己控制的网络）中传输，隐私与延迟都由本地条件决定。

从 README 的功能兼容表可以看到 Sunshine 的核心能力边界：

• 编码 API：NVENC（NVIDIA，Linux + Windows）、AMF（AMD，Windows）、QuickSync（Intel，Windows）、Media Foundation（Qualcomm，Windows）与软件编码兜底；Linux 侧还支持 VAAPI 等路径；
• 手柄仿真：Linux 与 Windows 支持 General、DualShock/DualSense、Switch Pro、Xbox 360/One/Series 等完整手柄仿真（macOS 不支持手柄，FreeBSD 为受限支持）；
• Web UI：提供配置、客户端配对、日志查看与精选应用（Featured Apps）入口，可从浏览器或移动设备访问。

二、第 1 步：获取 Sunshine（源码与官方安装包）

2.1 从源码构建

最简单的方式是克隆官方仓库获取最新代码，然后按 构建文档 使用 CMake 构建：

git clone https://gitcode.com/GitHub_Trending/su/Sunshine
cd Sunshine

仓库根目录的 CMakeLists.txt 定义了完整的构建流程，跨平台依赖管理位于 cmake/ 目录（包含 Boost、FFmpeg、libevdev 等依赖的 CMake 配置）。Docker 环境构建可参考 docker/ 下的各发行版镜像文件。

注意：对于绝大多数用户，官方推荐直接使用 发布页的二进制包，而非源码构建；源码构建更适合需要定制或贡献代码的场景。

2.2 选择平台安装包

以下是 docs/getting_started.md 中各平台的官方安装方式，并附文档中明确标注的限制：

Windows

• 官方推荐 MSI 安装程序（AMD64 / ARM64），双击运行、按需勾选组件；
• 也可使用 winget install LizardByte.Sunshine；
• 文档特别提示：Windows ARM64 属实验性支持，且不支持 GPU 调度与硬件加速；lite 独立版性能有损，不建议普通用户使用。

Linux

• 发行版 .deb 包（Ubuntu 22.04/24.04、Debian trixie）：sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb；
• Fedora/OpenSUSE：直接安装 rpm，或启用 copr 源后 sudo dnf install Sunshine；
• Arch：LizardByte pacman-repo 预构建包或 AUR PKGBUILD；
• AppImage：./sunshine.AppImage --install（注意：AppImage 基于 Ubuntu 22.04 构建，要求 glibc 2.35+；不支持 KMS 采集）；
• Flatpak：flatpak install flathub dev.lizardbyte.app.Sunshine（同样不支持 KMS 采集），安装后还需运行 flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine 同步特权宿主机 udev 规则；
• CUDA 兼容：NVFBC 采集依赖 CUDA，LizardByte 官方包已内置对应版本（文档给出了 CUDA 13.1.1 / 最低驱动 590.48.01 的兼容矩阵）。

macOS

• 按架构下载 DMG（Apple Silicon arm64 / Intel x86_64），拖入 Applications；
• 或 Homebrew：brew tap LizardByte/homebrew && brew install sunshine；
• 文档明确标注：macOS 上的 Sunshine 处于实验阶段，手柄不可用。

FreeBSD

• 下载对应架构的 .pkg 包后 sudo pkg install ./Sunshine-FreeBSD-{ver}-{arch}.pkg；
• 已知限制：仅支持 X11 与 Wayland 采集；手柄走 libvirtualhid 的 uinput 后端，缺少动作、触摸板、电池状态、RGB、自适应扳机等特性。

Docker

• 官方镜像在 Docker Hub（lizardbyte/sunshine）与 GHCR 上可用，详见 DOCKER_README.md；
• 文档明确警告：Docker 镜像不推荐给大多数用户（显示采集与输入设备映射在容器内受限严重）。

三、第 2 步：平台初始化配置

安装完成后，各平台有一组「首次配置」动作，直接影响采集与输入是否正常工作：

Linux：用户级 systemd 服务

# 手动启动
systemctl --user start app-dev.lizardbyte.app.Sunshine

# 开机自启
systemctl --user --now enable app-dev.lizardbyte.app.Sunshine

服务名已从 sunshine.service 改名为 app-dev.lizardbyte.app.Sunshine（提升 XDG Desktop Portal 兼容性），旧名仍保留为别名。

Windows：Virtual HID 驱动

Windows 上的虚拟输入基于 libvirtualhid（见 third-party/libvirtualhid/ 与 src/platform/virtualhid_input.cpp）。需要单独安装 Virtual HID Driver 才能获得驱动级 Raw Input 键鼠 + 完整虚拟手柄支持；ViGEmBus 仅在不可用时作为 Xbox 360 / DualShock 4 手柄的受限回退。文档建议安装或更新驱动后重启电脑。

macOS：系统权限

首次启动会请求屏幕录制与麦克风权限。macOS 14（Sonoma）及以上可通过 Apple Audio Tap API 原生采集系统音频（将 Audio Sink 留空即可）；也可自建 BlackHole/Soundflower 环回设备并填入 audio_sink 配置项。

FreeBSD：input 用户组

pw groupmod input -m $USER

加入 input 组并重新登录后，才能创建虚拟键鼠与手柄设备。

四、第 3 步：Web UI 首次配置与登录

Sunshine 全部配置通过 Web UI 完成，默认地址为：

https://localhost:47990

可把 localhost 换成主机内网 IP。浏览器会提示「不安全网站」，这是因为使用的是自签名证书，属正常现象（配置服务实现见 src/confighttp.cpp，其中 redirect_if_username 逻辑表明：当账号尚未创建时访问根路径会重定向到欢迎页；账号创建完成后欢迎页即被重定向回主界面）。

首次登录流程（与 docs/getting_started.md 一致）：

1. 打开 https://localhost:47990，首次访问进入欢迎页；
2. 创建并牢记用户名与密码（文档用 CAUTION 级别强调：首次运行务必记下你创建的账号密码，遗忘后需用 sunshine --creds {new-username} {new-password} 重置，见 docs/troubleshooting.md）；
3. 在导航栏下拉菜单选择 Web UI 主题（主题效果见 docs/images/split-themes.png）；
4. 按需搜索并调整配置项（配置搜索界面见 docs/images/configuration-search.png）。

配置文件位置与手工编辑

配置文件默认位置（来自 docs/configuration.md）：

平台	默认配置目录
Docker	/config
FreeBSD	~/.config/sunshine
Linux	~/.config/sunshine
macOS	~/.config/sunshine
Windows	%ProgramFiles%\Sunshine\config

也可以用第一个命令行参数指定自定义配置文件（不存在时会自动创建），apps.json 默认与配置文件同目录：

sunshine ~/sunshine_config.conf

官方推荐用配置 UI，但也可以直接编辑 conf 文件。几个常用项（细节与全部选项见 docs/configuration.md）：

• sunshine_name：Moonlight 列表中显示的服务器名称，默认为 PC 主机名；
• locale：Web UI 界面语言，默认 en，支持 zh（简体中文）、zh_TW 等 20 种语言（对应 src_assets/common/assets/web/public/assets/locale/ 下的语言文件）；
• min_log_level：日志级别，默认 info，可选 verbose / debug / info / warning / error / fatal / none；文档提醒 verbose 与 debug 可能影响串流性能；
• global_prep_cmd：所有应用启动前/后执行的全局命令，任一步失败会中止启动，例如：

global_prep_cmd = [{"do":"nircmd.exe setdisplay 1280 720 32 144","elevated":true,"undo":"nircmd.exe setdisplay 2560 1440 32 144"}]

五、第 4 步：连接 Moonlight 客户端

在目标设备（Android、iOS、Windows、macOS、Linux、Apple TV、NVIDIA Shield 等）上安装 Moonlight 客户端，确保其与 Sunshine 主机在同一网络。

配对流程（按 docs/getting_started.md 的 Usage 章节）：

1. Moonlight 会自动发现局域网内的 Sunshine；发现不了时可手动添加（输入内网 IP）；
2. Moonlight 请求输入 PIN 时，登录 Sunshine Web UI → 导航栏打开「PIN」页 → 输入 PIN 并按 Enter，同时为设备起一个名字，随后出现成功提示；
3. 在 Moonlight 中选择一个应用（App）即可开始串流。

发现失败的排查方向（与 docs/troubleshooting.md 一致）：

• 首要检查防火墙规则：Sunshine 需要放行 TCP 与 UDP 入站。Windows 轻量版的防火墙脚本 src_assets/windows/misc/firewall/add-firewall-rule.bat 展示了完整规则——为 sunshine.exe 同时添加 TCP 与 UDP 的入站允许规则；
• 确认客户端与主机在同一网段；
• 重启 Sunshine 服务。

运行方式补充：若未以服务方式运行，直接执行 sunshine（AppImage 为 ./sunshine.AppImage，Flatpak 为 flatpak run dev.lizardbyte.app.Sunshine）。Linux/X11 无头主机可通过 SSH 启动：

ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'

全局快捷键（与 Moonlight 一致，均以 Ctrl+Alt+Shift 开头）：

• Ctrl+Alt+Shift+N：隐藏/显示光标（远程桌面模式很有用）；
• Ctrl+Alt+Shift+F1/F12：切换串流所用显示器。

六、第 5 步：应用管理与配置

应用管理是 Sunshine 的核心功能：串流前你要告诉它「启动什么」。官方桌面（Desktop）与 Steam 大屏模式的预置模板可直接查看 src_assets/linux/assets/apps.json 与 src_assets/windows/assets/apps.json，自定义应用则保存在用户配置目录的 apps.json 中，通常通过 Web UI 的 Applications 页面管理（界面见上文第二张截图）。

添加应用的典型步骤：

1. 点击「Add New」；
2. 选择类型：Desktop（纯桌面串流，无启动命令）、Steam 应用（detached 方式拉起 steam 指定 appid）或 Custom App；
3. 填写应用名称、图标、启动命令与工作目录；
4. 保存后在 Moonlight 中选择该应用测试启动。

命令行与启动行为的关键规则（来自 docs/getting_started.md Application List / Considerations 章节）：

• 应用配置支持环境变量：$(HOME) 会被替换为 $HOME；$$ 会被替换为字面 $（即 $$(HOME) → $(HOME)）；
• env 字段可以为被启动的进程注入/覆盖环境变量（仅能通过直接修改 apps.json 实现）；
• Windows 采集限制：Desktop Duplication API 只能采集用于显示的 GPU 的画面；若要在 eGPU 上采集+编码，需把显示器（或 HDMI 假负载）接到 eGPU 并把游戏跑在该显示输出上；
• 进程接管规则：启动新应用时，正在运行的旧应用会被终止；任何 prep-command 失败都会中止启动；应用退出后串流随即关闭——所以 steam 这类常驻进程必须用 detached 方式启动，否则串流会立刻失败；
• Flatpak 下启动宿主机命令需加前缀 flatpak-spawn --host；
• 「Desktop」应用的特殊性：它不启动任何程序，只开启串流；删除后可通过新建同名应用（图标 desktop.png）恢复。

七、硬件编码器选择策略

Sunshine 按 GPU 与平台自动选择编码后端。各编码 API 的平台支持情况（README 兼容表）：

编码 API	GPU 厂商	Linux	Windows
NVENC	NVIDIA	支持	支持
VAAPI（含 Intel/AMD）	Intel / AMD	支持	—
AMF	AMD	—	支持
QuickSync	Intel	—	支持
Media Foundation	Qualcomm	—	支持
软件编码	任意	兜底	兜底

NVIDIA 编码路径的完整实现位于 src/nvenc/ 目录：nvenc_base 封装编码器核心，nvenc_d3d11 / nvenc_d3d11_on_cuda / nvenc_dynamic_factory 分别处理 D3D11 表面输入、CUDA 表面输入与 NVENC DLL 动态加载（兼容不同版本驱动导出的 NvEncoderLib）。从源码结构看，这套动态工厂机制正是 Sunshine 能在不绑定特定 NVENC SDK 版本的情况下适配各代 NVIDIA 驱动的原因。Linux 侧的 VAAPI 实现见 src/platform/linux/vaapi.cpp，Vulkan 编码路径见 src/platform/linux/vulkan_encode.cpp，采集后端则有 KMS、wlgrab、x11grab、NVFBC 等多种（src/platform/linux/ 目录）。

编码器参数精细调整（结合 docs/performance_tuning.md 与 docs/configuration.md）：

• 最大码率：max_bitrate 配置项（src/config.cpp 中解析，0 表示不额外限制）；
• 参考经验区间（按带宽与分辨率匹配，需实测调整）：
  • 千兆有线 / 良好 5GHz WiFi：1080p60 约 15–25 Mbps，1440p120 约 25–50 Mbps，4K60 约 50–100 Mbps；
  • 弱网环境：先降分辨率再降帧率，通常比一味降码率更有效；
• 帧率策略：Moonlight 客户端请求的帧率需在主机端 framerate 列表内生效；src/config.cpp 中的注释明确指出，配置文件中只写 30 而不包含该值的默认帧率列表会导致设置不生效——建议把 30、60、90、120 等目标值都列入。

八、网络配置与性能调优

硬件与布线（最佳选择是端到端有线）

• 主机端：千兆以太网（CAT5e 及以上）；
• 路由器：开启 QoS，优先保障串流流量；
• 无线场景：使用 5GHz 频段，尽量靠近路由器，避免 2.4GHz 干扰；WiFi 6/6E 路由器可进一步改善。

网络质量诊断

docs/troubleshooting.md 给出了一个重要的判断标准：实时串流对网络路径最敏感的不是峰值带宽，而是稳定性——低且稳定的延迟、极低的抖动与丢包。官方推荐的测试工具是 iPerf3：

# 主机（Sunshine 端）以服务器模式启动
iperf3 -s

# 客户端发起 60 秒反向 UDP 测试（示例 50 Mbps）
iperf3 -c <sunshine_ip> -u -b 50M -t 60 -R

观察 60 秒内丢包率与抖动曲线：如果 UDP 测试稳定，而串流仍卡顿，问题多半在编码/显示端；反之则先解决网络。

端口与防火墙

Web UI 使用 47990（HTTPS），串流数据面为 RTSP/RTP 端口群。Windows 下可参考 add-firewall-rule.bat 的规则写法：对 sunshine.exe 程序同时放行 TCP 与 UDP 入站。Linux 上若使用 firewalld/ufw，同样需要放行 Sunshine 进程的 TCP/UDP 入站（Web UI 无法访问时，文档给出的第一条排查建议就是检查防火墙规则）。

九、实战场景配置要点

客厅大屏（电视）

1. 分辨率匹配电视原生分辨率（如 4K）；
2. 码率按第八节的区间随实测带宽调整；
3. HDR：主机端开启系统级 HDR，并在 Moonlight 客户端同时开启 HDR，否则主机为 HDR 时画面会过曝；Windows 主机支持 Intel/AMD/NVIDIA 的 HEVC Main 10 或 AV1 10-bit 编码 GPU，Linux 主机为实验性支持（需 KMS 采集 + 支持 HDR 合成的桌面环境，如 Gamescope 或 KDE Plasma 6，编码需 Intel/AMD GPU 的 HEVC Main 10 / AV1 10-bit）。

移动设备

1. 触控布局按游戏类型自定义虚拟按键；
2. 屏幕比例按设备选择；
3. 优先 5GHz WiFi 并确保信号稳定；
4. 蓝牙手柄直连客户端（Xbox、DualShock 4、DualSense、Switch Pro 及标准 XInput 设备均可），Moonlight 端即可用主机级手柄体验串流。

多用户共享

• 每台客户端设备在 Web UI 的 PIN 配对页拥有独立的设备名，配对状态可单独管理；
• 注意 Sunshine 的串流是单会话模型：同一时刻一条串流，启动新应用会终止旧应用，因此「多用户同时串流」并不成立，共享方式应是分时使用。

十、故障排查与日志诊断

Web UI 内日志：导航栏「Troubleshooting」页可以逐条浏览每条 warning/error（日志读取逻辑在 src/confighttp.cpp 中从配置目录读取 sunshine.log）。Web UI 无法访问时按 docs/troubleshooting.md 顺序排查。

日志文件位置（与配置目录一致）：

• Windows：%ProgramFiles%\Sunshine\config\sunshine.log；
• Linux / macOS：~/.config/sunshine/sunshine.log；
• Docker：容器日志 docker logs sunshine。

高频问题速查：

症状	排查方向
客户端无法发现/连接	防火墙（TCP+UDP 入站）、同网段、重启服务
忘记 Web UI 密码	sunshine --creds {new-username} {new-password} 重置
画面卡顿掉帧	降低分辨率/码率、更新显卡驱动、iPerf3 验证网络稳定性、检查 CPU/GPU 占用
鼠标行为异常	在主机上接一个物理鼠标试试
手柄在 Steam 正常但游戏内无效	Steam 手柄兼容设置只保留 Generic；断开主机上物理手柄，让 Sunshine 虚拟手柄成为「第一」设备（Linux 可写 /sys/bus/usb/devices/<dev>/authorized 为 0 禁用）
连接后键鼠/手柄无效	FreeBSD/Linux 上把运行 sunshine 的用户加入 input 组
Linux 应用启动即失败	改用 detached 方式启动常驻进程

十一、进阶主题与延伸阅读

• HDR 串流：主机 OS 需已激活 HDR（必要时接 EDID 模拟器 dongle）；客户端与主机显示器的 HDR 校准差异可能很大，建议把 Windows HDR Calibration 应用串流到客户端上做校准；部分 GPU 编码器在 HDR 下的编码质量/性能低于 SDR。
• 精选应用（Featured Apps）：Web UI 的 Featured Apps 页聚合了 Moonlight 各平台客户端与实用工具入口（界面见 docs/images/featured-apps.png）。
• 安全建议：使用强密码保护 Web UI；如需公网访问，务必先配置反向代理与认证，避免将 47990 直接暴露到互联网；定期更新 Sunshine 与显卡驱动。

十二、要点回顾

1. 安装选对包：优先发行版官方包（.deb/.rpm/AppImage/pacman-repo），AppImage 与 Flatpak 不支持 KMS 采集，Docker 不推荐普通用户使用；
2. 初始化别漏：Linux 用户服务、Windows Virtual HID 驱动、macOS 录屏/麦克风权限、FreeBSD input 组；
3. 配置走 Web UI：https://localhost:47990 创建账号、配应用、查日志，apps.json 与 conf 文件默认同目录；
4. 网络看稳定性：iPerf3 的 60 秒 UDP 测试是判断网络是否胜任的关键；
5. 编码器按硬件选：NVIDIA 走 NVENC（src/nvenc/），Linux 的 Intel/AMD 走 VAAPI，Windows 的 AMD/Intel 走 AMF/QuickSync，软件编码兜底；
6. 排查看日志：Troubleshooting 页逐条读 warning/error，配合 min_log_level 调整详细度。

仓库内的进一步阅读路径：README（功能兼容矩阵）、docs/getting_started.md（安装与使用）、docs/configuration.md（全部配置项参考）、docs/troubleshooting.md（故障排查）、docs/performance_tuning.md（性能调优）。