Sunshine 快速上手：跨平台安装、系统服务部署与首次配置全流程指南

2026-09-05 10:17:23作者：齐冠琰

Sunshine 是一个自托管的 Moonlight 串流主机程序，本文基于官方入门文档 docs/getting_started.md 完整梳理了在 FreeBSD、Linux、macOS、Windows 各平台上的安装包选择、安装命令、系统服务配置、Web UI 首次配置、命令行用法与快捷键、应用管理规则及 HDR 串流支持等全部内容，并结合仓库源码补充了端口布局、服务单元文件与命令行参数解析的实现依据。读完本文，你可以独立完成任意平台的 Sunshine 部署，理解其默认端口与配置文件的生成机制，并排除首次连接 Moonlight 客户端时的常见问题。

安装前的准备：选择正确的发行方式

官方推荐运行 Sunshine 的方式是使用最新正式版本发布包中附带的二进制发行版。每个 release 都会构建对应的二进制包，覆盖 FreeBSD、Linux、macOS 与 Windows 四大平台。此外还可以获取预发布（Pre-release）构建，但它们应当被视为 beta 版本——由于合并变更的节奏更快，预发布产物在个别版本中可能缺失，仅建议在明确需要尝鲜时使用。

需要注意的是，社区中也存在第三方打包的 Sunshine 包，可参见第三方包说明。官方明确声明不为第三方包提供任何形式的支持，生产环境建议一律使用官方发布产物。

分平台安装

Docker（不推荐大多数用户使用）

[!WARNING] 官方不推荐大多数用户使用 Docker 镜像。

Docker 镜像托管在 Docker Hub 与 ghcr.io 上（仓库组织 LizardByte 名下），完整说明见 DOCKER_README.md。仓库内 docker/ 目录提供了 ubuntu-22.04/24.04/26.04 与 debian-trixie 的 Dockerfile，可对照了解镜像构建方式。

FreeBSD

安装：下载与架构对应的 .pkg 包，然后执行：

sudo pkg install ./Sunshine-FreeBSD-14.4-{arch}.pkg

架构	包名
amd64/x86_64	Sunshine-FreeBSD-14.4-amd64.pkg
arm64/aarch64	Sunshine-FreeBSD-14.4-aarch64.pkg

卸载：

sudo pkg delete Sunshine

Linux

Linux 的安装方式最多，官方按发行形态分为 AppImage、Arch、Debian/Ubuntu、Fedora/OpenSUSE、Flatpak 与 Homebrew 六类。

CUDA 兼容性：CUDA 用于 NVFBC 画面捕获。官方 LizardByte 发布包已内置所需 CUDA 运行库，使用官方包无需单独安装 CUDA；如果你自行编译，则需按下表核对显卡的 Compute Capability 与驱动版本：

CUDA 版本	最低驱动	支持 Compute Capabilities	覆盖的包形态
13.1.1	590.48.01	50; 52; 60; 61; 62; 70; 72; 75; 80; 86; 87; 89; 90; 100; 101; 103; 120; 121	AppImage、Ubuntu 22.04/24.04 deb、Debian trixie deb、Flatpak、Fedora/OpenSUSE Copr、Arch PKGBUILD

AppImage

[!CAUTION] 如果系统有发行版专属包，请优先使用专属包。AppImage 不支持 KMS 捕获。

AppImage 基于 Ubuntu 22.04 构建，要求 glibc ≥ 2.35 与 libstdc++ ≥ 3.4.11。

# 安装：下载到主目录后执行
cd ~
wget <latest-release>/sunshine.AppImage
./sunshine.AppImage --install

# 运行
./sunshine.AppImage --install && ./sunshine.AppImage

# 卸载
./sunshine.AppImage --remove

Arch Linux

[!CAUTION] AUR 编译安装风险自担。

预构建包方式（先按 LizardByte pacman-repo 的说明添加仓库）：

pacman -S sunshine

PKGBUILD 归档方式：

wget <latest-release>/sunshine.pkg.tar.gz
tar -xvf sunshine.pkg.tar.gz
cd sunshine

# 安装可选依赖
pacman -S cuda  # Nvidia GPU 编码支持
pacman -S libva-mesa-driver  # AMD GPU 编码支持

makepkg -si

卸载：pacman -R sunshine。

Debian / Ubuntu

下载 sunshine-{distro}-{distro-version}-{arch}.deb（{distro-version} 是构建该包所用的发行版版本，{arch} 是系统架构）后执行：

sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb

卸载：sudo apt remove sunshine。图形环境下也可以直接双击 deb 文件查看详情并启动安装。

Fedora / OpenSUSE

[!TIP] 包名区分大小写。

下载 Sunshine-{version}.{distro+version}.{arch}.rpm 后执行：

sudo dnf install ./Sunshine-{version}.{distro}.{arch}.rpm

卸载：sudo dnf remove sunshine。

CopR 源安装：

[!IMPORTANT] 稳定版 CopR 构建仅在 Sunshine 发布时间晚于对应 Fedora 版本发布时存在，因此官方更常建议使用 beta copr（无需频繁更新，但极少数情况下可能遭遇破坏性变更）。

# 1. 启用 copr 仓库（二选一）
sudo dnf copr enable lizardbyte/stable
# 或
sudo dnf copr enable lizardbyte/beta

# 2. 安装
sudo dnf install Sunshine

卸载：sudo dnf remove Sunshine。仓库中的 copr spec 文件展示了该包的构建定义。

Flatpak

[!CAUTION] 有发行版专属包时请优先使用专属包。Flatpak 不支持 KMS 捕获。

系统级安装（Flathub 或本地 sunshine_{arch}.flatpak）：

flatpak install --system flathub dev.lizardbyte.app.Sunshine
flatpak install --system ./sunshine_{arch}.flatpak

用户级安装：

flatpak install --user flathub dev.lizardbyte.app.Sunshine
flatpak install --user ./sunshine_{arch}.flatpak

必做的额外步骤：安装或更新 Flatpak 后，必须运行特权宿主机 udev 规则同步脚本（脚本源在 additional-install.sh）：

flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine

运行与卸载：

flatpak run dev.lizardbyte.app.Sunshine        # X11 使用 NVFBC，Wayland 使用 XDG Portal 捕获
flatpak run --command=remove-additional-install.sh dev.lizardbyte.app.Sunshine
flatpak uninstall --delete-data dev.lizardbyte.app.Sunshine

Homebrew（Linux 上为实验性支持）

brew update
brew upgrade
brew tap LizardByte/homebrew
brew install sunshine
sudo "$(brew --prefix sunshine)/bin/postinst"

卸载：brew uninstall sunshine。测试版可将命令中的 sunshine 替换为 sunshine-beta。

macOS

[!IMPORTANT] Sunshine 在 macOS 上处于实验阶段，手柄不可用。

DMG 安装：按架构下载（arm64 Apple Silicon / x86_64 Intel）Sunshine-macOS-{arch}.dmg，打开后把 Sunshine.app 拖入 Applications 文件夹并弹出镜像。卸载：退出程序后从「应用程序」文件夹拖入废纸篓。

Homebrew：

brew update
brew upgrade
brew tap LizardByte/homebrew
brew install sunshine
# 卸载：brew uninstall sunshine

测试版同样可用 sunshine-beta 替代。

Windows

[!NOTE] Sunshine 支持 Windows ARM64，但属于实验性支持，该版本不能正确支持 GPU 调度与任何硬件加速。

安装包（推荐）：

架构	安装包
AMD64/x64	Sunshine-Windows-AMD64-installer.msi
ARM64	Sunshine-Windows-ARM64-installer.msi

[!CAUTION] 未来将以 msi 安装包为主。使用其他类型安装方式之前，应手动卸载此前的安装。请谨慎勾选/取消勾选安装选项，不要盲目启用功能。

安装日志位于 %%TEMP%/Sunshine/logs/install/。卸载入口在系统「设置 → 应用」中，不同 Windows 版本的卸载步骤略有差异。

独立版（lite 精简版）：

[!WARNING] 相比安装包，lite 版性能会下降，官方不推荐大多数用户使用，且不提供支持。

下载并按架构解压后，以管理员身份打开命令行，依次执行防火墙规则与服务脚本（脚本源文件见 src_assets/windows/misc/ 目录）：

:: 防火墙规则
cd /d {解压目录}
scripts\add-firewall-rule.bat      :: 安装
scripts\delete-firewall-rule.bat   :: 卸载

:: Windows 服务
cd /d {解压目录}
scripts\install-service.bat
scripts\autostart-service.bat      :: 安装
scripts\uninstall-service.bat      :: 卸载

初始配置

FreeBSD：虚拟输入设备

[!IMPORTANT] 要使用虚拟输入设备（键盘、鼠标、手柄），必须把当前用户加入 input 组。

安装过程会创建 input 组并配置 /dev/uinput 权限，执行以下命令后需重新登录生效：

pw groupmod input -m $USER

Linux：用户服务

一次性启动：

systemctl --user start app-dev.lizardbyte.app.Sunshine

开机自启：

systemctl --user --now enable app-dev.lizardbyte.app.Sunshine

[!NOTE] 服务命名为 app-dev.lizardbyte.app.Sunshine 是为了提升与 XDG Desktop Portal 的兼容性，同时保留了 sunshine.service 别名。

从源码可以印证这一点：服务单元模板 app-dev.lizardbyte.app.Sunshine.service.in 中定义了 Alias=sunshine.service，WantedBy=graphical-session.target 使其挂接图形会话，ExecStartPre=/bin/sleep 5 用于避免桌面初始化完成前抢先启动，Restart=on-failure 保证失败后 5 秒自动重启。

macOS：系统权限与音频

首次启动会请求屏幕录制与麦克风权限。macOS 14.0 (Sonoma) 及更新版本可通过 Apple Audio Tap API 原生捕获系统声音，此时只需将 Audio Sink 设置留空；若偏好自行管理回环设备（如 Soundflower、BlackHole），可将其设备名填入 audio_sink 配置项。

[!NOTE] Command 键不会被 Moonlight 转发，右 Option 键映射为 CMD 键。 [!CAUTION] 当前版本不支持手柄。

macOS 音频捕获的实现可参见 src/platform/macos/av_audio.mm 等源码文件。

Windows：虚拟输入驱动

Windows 上的虚拟输入基于 libvirtualhid：需要单独安装 Virtual HID Driver 才能启用基于驱动的 Raw Input 键盘/鼠标以及完整的虚拟手柄支持。ViGEmBus 仅作为 libvirtualhid 不可用时针对 Xbox 360 与 DualShock 4 手柄的受限回退（该回退逻辑可参见 src/platform/virtualhid_input.cpp 与 src/platform/windows/input.cpp 中对 ViGEm 的引用）。

要求 Virtual HID Driver 版本不低于 2026.829.2338.54；更早版本的 Windows 控制与 broker 协议不兼容，必须与 Sunshine 内嵌的 libvirtualhid 库同步升级。本地开发驱动的 0.0.0.* 版本仍受支持。
相比 ViGEmBus 回退，Virtual HID Driver 支持创建 Xbox One、Xbox Series、DualSense、Switch Pro、Generic 手柄，并可在支持时暴露运动、触控板、LED、自适应扳机等控制器特性。
在兼容驱动与有效许可证下，常规按键通过真实 HID 键盘暴露，Raw Input 应用可直接接收；Unicode 文本输入及超出支持 HID 键盘页的按键仍走 Windows 注入。驱动/中间层/许可证不可用时，libvirtualhid 保留 SendInput 回退。
相对鼠标移动、按键与滚轮通过真实 HID 鼠标暴露；绝对鼠标定位仍使用 Windows 输入注入。
驱动级设备（含手柄、Raw Input 键鼠）需要有效的机器许可证。Sunshine 会在 Web UI 的 Troubleshooting 页与托盘「Virtual HID Driver」子菜单中显示许可证状态；未激活机器上启动时，点击托盘通知即可在 Web UI 中打开激活与购买选项。许可操作成功后 Sunshine 会重建共享键鼠，切换 HID/SendInput 路径无需重启 Sunshine。
安装或更新虚拟输入驱动后，建议重启计算机。

启动与使用

基本用法

若未以服务方式安装/运行（Windows 安装包默认以服务模式运行，不建议运行多个 Sunshine 实例），直接执行：

sunshine

指定配置文件

sunshine <配置文件所在目录>/sunshine.conf

[!NOTE] 此步骤可省略。不指定时使用默认位置；指定的配置文件若不存在会被自动创建。

源码印证：参数解析逻辑位于 src/config.cpp——命令行中不含 = 的第一个非选项参数即被识别为配置文件路径（约 L1947-L1949），加载前会确保 appdata 目录存在并在配置文件缺失时自动创建空文件（约 L1971-L1977），默认配置路径为 appdata()/sunshine.conf（约 L877）。

通过 SSH 启动（Linux/X11）

已登录宿主机显示会话时：

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

仅有 tty 时可先用 startx 拉起 X server，必要时在两者之间加 sleep 等待显示就绪：

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

[!TIP] 也可以在 ~/.bash_profile 或 ~/.bashrc 中设置 DISPLAY 变量。

命令行参数

查看可用参数（不同运行形态的入口不同）：

sunshine --help                    # 常规安装
./sunshine.AppImage --help         # AppImage
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help  # Flatpak

从源码结构看，--help 输出由 src/logging.cpp 的 print_help 生成，参数解析与选项注册集中在 src/config.cpp，例如 port 选项的合法区间由 HTTP 与 RTSP 端口偏移共同约束（约 L1810-L1812）。

Web UI 配置流程

Sunshine 通过 Web UI 配置，默认地址为 https://localhost:47990（可用内网 IP 替换 localhost）。

[!NOTE] 浏览器提示"不安全网站"属于正常现象，原因是使用了自签名 SSL 证书。 [!CAUTION] 首次运行请记下创建的账号与密码。

端口布局的实现依据：基础端口默认值为 47989（src/config.cpp 约 L879），Web UI 运行在 port + 1 上，因此为 47990（约 L1814-L1819，代码注释明确"Web UI runs on port + 1"）；RTSP 建连监听使用偏移 21（src/rtsp.h 中 RTSP_SETUP_PORT = 21），各监听端口在 src/network.cpp 中统一按 config::sunshine.port + offset 映射。

配置步骤：

通过导航栏下拉菜单切换主题；
添加游戏与应用程序；
按需调整配置项，可搜索栏定位选项；
在 Featured Apps 标签页查找 Moonlight 客户端等工具；
Moonlight 中可能需要手动添加 PC；
Moonlight 请求输入 PIN 时：登录 Web UI → 导航栏进入 "PIN" → 输入 PIN 并按 Enter，为设备填写名称，随后应出现成功提示 → 回到 Moonlight 选择要串流的应用；
遇到问题时查看 Troubleshooting 标签页的日志，逐条浏览警告/错误信息定位问题。

快捷键

所有快捷键均以 Ctrl+Alt+Shift 起始，与 Moonlight 一致：

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

应用列表规则

应用应通过 Web UI 配置；
需要理解工作目录与命令的基本概念；
命令中可使用环境变量替代字面值：$(HOME) 会被替换为 $HOME 的值；$$ 会被替换为 $，例如 $$(HOME) 最终得到 $(HOME)；
env 字段可为 Sunshine 启动的命令/应用添加或覆盖环境变量，该字段只能直接修改 apps.json 文件（默认路径为 appdata 下的 apps.json，见 src/config.cpp 中 APPS_JSON_PATH 定义）。

行为注意事项

Windows 上 Sunshine 使用 Desktop Duplication API，仅能捕获用于显示的 GPU。若要捕获并编码 eGPU，需把显示器（或 HDMI 假负载）连接到 eGPU，并让游戏运行在该显示器上；
启动新应用时，正在运行的旧应用会被终止；
任何 prep-commands 失败都会中止应用启动；
应用退出时串流也会随之结束——例如把 steam 配成普通 cmd 而非 detached 会导致串流立即失败，因为 Steam 进程的执行方式会立刻"结束"；detached 应用不受此限制；
"Desktop" 应用与其他应用行为一致，只是没有启动命令，它直接开始串流。若误删，新建一个名为 "Desktop"、图片路径为 "desktop.png" 的应用即可恢复；
Linux Flatpak 下命令必须以 flatpak-spawn --host 前缀执行；
连接后输入（鼠标、键盘、手柄）无效时：FreeBSD/Linux 上把运行 sunshine 的用户加入 input 组；
FreeBSD 版本缺少 Linux 上的部分特性，已知限制：仅支持 X11 与 Wayland 捕获；手柄走 libvirtualhid 的 uinput 后端，运动、触控板输入、电池状态、RGB LED、自适应扳机、原始 HID 输出报告等描述符驱动特性不可用。

HDR 支持

Windows 主机上正式支持 HDR 串流，Linux 主机上为实验性支持。通用要求：

主机操作系统必须已激活 HDR，可能需要 HDR 显示器或 EDID 模拟器 dongle；
Moonlight 客户端设置中也必须开启 HDR，否则串流为 SDR（主机处于 HDR 时可能过曝）；
良好体验依赖主机与客户端两侧的正确 HDR 校准，两者可能差异显著；
可能需要在游戏内调节亮度滑杆或 HDR 校准选项以适配客户端显示器的亮度能力；
部分 GPU 视频编码器在 HDR 下的画质或编码性能可能低于 SDR。

平台细节：

Windows：支持能编码 HEVC Main 10 或 AV1 10-bit 档位的 Intel、AMD、NVIDIA GPU。建议通过串流 Windows HDR Calibration 应用到客户端完成显示器校准并保存校准配置文件；使用 NVIDIA 私有 NVAPI HDR（而非原生 Windows HDR）的旧游戏可能无法正常显示 HDR。
Linux：支持通过 VAAPI 编码 HEVC Main 10 或 AV1 10-bit 档位的 Intel 与 AMD GPU；必须使用 KMS 捕获后端（NvFBC、X11 等不支持 HDR）；需要支持 HDR 渲染的桌面合成器，如 Gamescope 或 KDE Plasma 6。