从 NVIDIA GameStream 迁移到 Sunshine(Apollo):GSMS 自动迁移、UPnP 互联网串流与已知限制全解析
从 NVIDIA GameStream 迁移到 Sunshine(Apollo):GSMS 自动迁移、UPnP 互联网串流与已知限制全解析
NVIDIA 已于 2023 年 2 月正式终止面向 NVIDIA Games 客户端的 GameStream 服务。本文基于仓库文档 docs/gamestream_migration.md,系统讲解如何借助 GSMS 迁移工具将原有 GameStream 游戏与应用平滑迁移到 Sunshine(本仓库即 Apollo,一个以客户端设备原生分辨率串流为目标的 Sunshine fork),并深入源码解析互联网串流所需的 UPnP 端口映射机制、迁移后的必要清理工作,以及相对 GameStream 仍存在的功能限制。读完本文,你将掌握一套可复现的 GameStream→Sunshine 迁移流程,并能独立排查 UPnP 相关的串流问题。
迁移背景:为什么需要迁移
NVIDIA 官方宣布,面向 NVIDIA Games 客户端的 GameStream 服务将于 2023 年 2 月停止运营。这意味着继续依赖该服务的用户需要寻找替代方案。Sunshine 作为开源的串流服务端,其串流性能目前已达到与 NVIDIA GameStream 相当甚至更好的水平,且通过 Moonlight 客户端即可无缝接入——客户端无需更换,只需将服务端从 NVIDIA 软件切换到 Sunshine。
本仓库(Apollo)正是基于这一生态的 Sunshine 分支,项目描述明确其目标是"以客户端设备的原生分辨率进行串流"(The easiest way to stream with the native resolution of your client device),因此它是 GameStream 迁移的自然目的地。
第一步:使用 GSMS 工具自动迁移游戏与应用
手工重建数十个游戏条目既繁琐又易错,为此官方开发了独立的迁移工具 GSMS(GameStream Migration Service),专门用于将 GameStream 中已有的游戏和应用自动迁移到 Sunshine。
GSMS 能迁移什么
根据 docs/gamestream_migration.md 的说明,GSMS 具备以下能力:
- 迁移自定义游戏和应用以及自动检测到的游戏和应用(auto-detected games and apps);
- 将每个条目的**工作目录(working directory)、启动命令(command)和封面图(image)**写入 Sunshine 的应用清单文件
apps.json; - 将 box-art 封面图复制到你指定的目录中。
也就是说,迁移完成后,你在 Moonlight 客户端中看到的游戏列表、图标与启动行为都尽量与原来保持一致,无需逐个手动录入。
迁移结果落点:apps.json 的结构
所有迁移结果最终都写入 apps.json。该文件默认与配置文件放在同一目录(Linux/macOS 为 ~/.config/sunshine,Windows 为 %ProgramFiles%\Sunshine\config,Docker 为 /config),也可通过配置文件中的 file_apps 项指定自定义路径(见 docs/configuration.md 中 file_apps 的说明)。
仓库内置了一份默认的 apps.json(src_assets/linux/assets/apps.json),它在 Sunshine 首次启动时被复制到用户数据目录(见 src/config.cpp)。其内容展示了应用条目的典型形态:
{
"env": {
"PATH": "$(PATH):$(HOME)/.local/bin"
},
"apps": [
{
"name": "Desktop",
"image-path": "desktop.png",
"allow-client-commands": false
},
{
"name": "Low Res Desktop",
"image-path": "desktop.png",
"allow-client-commands": false,
"prep-cmd": [
{
"do": "xrandr --output HDMI-1 --mode 1920x1080",
"undo": "xrandr --output HDMI-1 --mode 1920x1200"
}
]
},
{
"name": "Steam Big Picture",
"prep-cmd": [
{
"do": "",
"undo": "setsid steam steam://close/bigpicture"
}
],
"detached": [
"setsid steam steam://open/bigpicture"
],
"image-path": "steam.png"
}
]
}
顶层 env 对象定义所有应用共享的环境变量(如 $(PATH)、$(HOME) 这类占位符会在运行时展开),apps 数组则列出每个可启动的应用。
应用条目的完整字段说明
从源码解析逻辑(src/process.cpp)和 Web 管理端 API 文档(src/confighttp.cpp)可以确认,每个应用条目支持以下字段:
| 字段 | 类型 | 含义 |
|---|---|---|
name |
string | 应用名称,会显示在 Moonlight 客户端中 |
cmd |
string | 启动应用的命令 |
working-dir |
string | 工作目录(Windows 上解析时会去除引号并追加反斜杠) |
image-path |
string | 封面图路径,必须是 PNG 文件 |
output |
string | 日志输出路径 |
elevated |
bool | 是否以提升权限运行,默认 false |
auto-detach |
bool | 自动分离进程,默认 true |
wait-all |
bool | 是否等待所有子进程退出,默认 true |
exit-timeout |
int | 退出超时(秒),默认 5 |
prep-cmd |
array | 应用启动前/退出后执行的准备命令列表,每项含 do、undo、elevated |
state-cmd |
array | 暂停/恢复流媒体时执行的状态命令 |
detached |
array | 独立于主进程启动的附加命令 |
exclude-global-prep-cmd |
bool | 是否排除全局准备命令,默认 false |
exclude-global-state-cmd |
bool | 是否排除全局状态命令,默认 false |
allow-client-commands |
bool | 是否允许客户端命令(如 Alt+Tab),默认 true |
virtual-display |
bool | 是否使用虚拟显示器,默认 false |
use-app-identity / per-client-app-identity |
bool | Windows 进程身份相关选项 |
uuid |
string | 应用唯一标识,用于 Web UI 中的新增/编辑 |
除应用级 prep-cmd 外,配置文件还支持全局准备命令 global_prep_cmd,它在所有应用启动前执行,任一条失败都会中止应用启动(见 docs/configuration.md 及解析代码 src/config.cpp)。
通过 Web UI 查看与管理应用
Sunshine 的 Web 管理端(默认 https://localhost:47990)通过 REST API 提供应用管理能力:
GET /api/apps:读取apps.json并返回完整应用列表,同时附带current_app、host_uuid、host_name等字段(src/confighttp.cpp);POST /api/apps:接收 JSON 格式的应用定义,合并写回apps.json并热刷新(proc::refresh),因此新增/编辑应用无需重启 Sunshine(src/confighttp.cpp)。
迁移完成后,建议在 Web UI 的"应用"页面逐条核对 GSMS 生成的条目,重点检查 cmd、working-dir 与 image-path 是否指向正确路径。
第二步:互联网串流——移除旧工具并启用 UPnP
如果你此前使用 Moonlight Internet Hosting Tool 来实现公网串流,迁移到 Sunshine 后可以将其从系统中完全移除,因为 Sunshine 内置了 UPnP 端口映射能力,不再需要额外的打洞工具。
在 Web UI 中启用 UPnP
要借助支持 UPnP 的路由器实现互联网串流,只需在 Sunshine Web UI 中启用 UPnP 选项即可。该选项同样可以通过配置文件设置(docs/configuration.md):
# 默认 disabled
upnp = enabled
配置解析逻辑在 src/config.cpp:读取 upnp 布尔值后翻转 config::flag::UPNP 标志位,后续由 UPnP 模块据此决定是否启动端口映射线程(src/upnp.cpp)。
重要警告:如果 Sunshine 与 v5.6 之前版本的 Moonlight Internet Hosting Tool 同时运行,会导致 UPnP 端口转发变得不可靠。因此迁移时应彻底卸载该工具,或至少将其升级到 v5.6 及以上版本(见 docs/gamestream_migration.md 的注意条款)。
UPnP 模块的源码级原理
启用后,Sunshine 的 UPnP 实现(src/upnp.h、src/upnp.cpp)会完成以下工作:
1. 维护一组端口映射清单
deinit_t 构造函数中按需组装映射列表(src/upnp.cpp),涵盖串流所需的全部端口:
- RTSP(TCP),描述为 "Sunshine - RTSP"
- 视频流(UDP),"Sunshine - Video"
- 音频流(UDP),"Sunshine - Audio"
- 控制通道(UDP),"Sunshine - Control"
- 客户端 HTTP(TCP),"Sunshine - Client HTTP"
- 客户端 HTTPS(TCP),"Sunshine - Client HTTPS"
此外,只有当 Web 管理端配置为允许来自 WAN 的访问时(origin_web_ui_allowed 取值为 wan,即大于 LAN 级别,参见 src/config.cpp),才会额外映射 "Sunshine - Web UI" 端口——这是出于安全考虑,默认 lan 值不会对外开放管理端口。
2. 发现 IGD 并维持映射
UPnP 线程以 120 秒的刷新间隔循环执行(REFRESH_INTERVAL,见 src/upnp.h):
- 通过
upnpDiscover发现 IPv4 UPnP 设备,再用UPNP_GetValidIGD校验是否为有效的 IGD(Internet Gateway Device,即路由器); - 对清单中的每个端口调用
UPNP_GetSpecificPortMappingEntry检查是否已映射:已存在且目标一致则跳过;存在冲突则尝试删除后重建; - 映射租约周期为 3600 秒(
PORT_MAPPING_LIFETIME);如果路由器是老旧/有问题的 IGDv1 设备(返回 606 Unauthorized 之外的异常错误),会退化为使用永久(0 秒租约)映射以兼容; - 每轮循环都会重新发现并校验映射——文档注释明确指出:路由器重启、WAN IP 变化等各种情况都可能导致映射丢失,因此必须周期性刷新(src/upnp.cpp);
- 如果
address_family = both(docs/configuration.md 中可选ipv4或both),且 IGD 支持 IPv6 防火墙控制,还会尝试为 IPv6 打开防火墙 pinhole(src/upnp.cpp),IPv6 下没有 WAN→LAN 端口映射概念,直接对 LAN 端口开洞; - Sunshine 退出时会调用
unmap_all_upnp_ports清理所有映射(src/upnp.cpp)。
3. 相关网络配置项
| 配置项 | 默认值 | 说明 |
|---|---|---|
upnp |
disabled | 是否启用 UPnP 端口映射 |
port |
47989 | 端口族基址,修改后会整体偏移其他端口(范围 1029–65514) |
address_family |
ipv4 | ipv4 仅 IPv4;both 为 IPv4+IPv6 |
origin_web_ui_allowed |
lan | pc 仅本机、lan 仅局域网、wan 任何人可访问 Web UI |
external_ip |
自动 | 手动指定公网 IP,留空则自动检测 |
迁移后的已知限制
相比 NVIDIA GameStream,Sunshine 目前仍存在以下两点功能差异(见 docs/gamestream_migration.md 的 Limitations 一节),迁移前需要知晓:
- 无自动游戏/应用列表:GameStream 能够自动扫描并列出已安装的游戏,而 Sunshine 依赖
apps.json中的手动条目或 GSMS 迁移结果,新安装的游戏不会自动出现在串流列表中,需要自行添加。 - 不会自动修改游戏设置来优化串流:GameStream 在串流时可能自动调整游戏的图形设置以适配串流场景,Sunshine 不会干预游戏内部设置;分辨率、帧率等优化需要依靠串流端的虚拟显示器/分辨率策略或手动配置来完成。
这两项限制本质上都是"自动化程度"的差异,并不会影响串流质量本身——通过合理的 apps.json 条目编排(如利用 prep-cmd 在启动前后执行分辨率切换、游戏设置命令等),可以在很大程度上弥补。
总结:一份完整的迁移检查清单
- 安装 Sunshine(本仓库 Apollo)并完成首次启动,确认默认
apps.json已生成; - 使用 GSMS 工具将 GameStream 中的自定义与自动检测游戏/应用迁移到
apps.json,核对cmd、working-dir、image-path(PNG 封面图)是否正确,必要时在 Web UI 中增删改; - 卸载(或升级到 v5.6+)Moonlight Internet Hosting Tool,避免与 UPnP 端口转发冲突;
- 需要公网串流时,在 Web UI 启用 UPnP(或配置
upnp = enabled),并确认路由器支持 UPnP;如使用 IPv6,可将address_family设为both; - 在 Moonlight 客户端中重新发现主机并配对,验证局域网与公网两种场景下的串流均正常。