从 Nvidia GameStream 迁移到 Sunshine:游戏库迁移与互联网串流配置完全指南
从 Nvidia GameStream 迁移到 Sunshine:游戏库迁移与互联网串流配置完全指南
本文是 Sunshine(foundation-sunshine,一个自托管的 Moonlight 游戏串流服务端)的 GameStream 迁移实战指南。Nvidia 已于 2023 年 2 月正式停止 GameStream 服务,本文将以仓库内的 docs/gamestream_migration.md 为主线,完整讲解如何借助 GSMS 自动化迁移工具把 Nvidia Games 客户端的游戏与应用迁移到 Sunshine 的 apps.json,如何用 UPnP 替代 Moonlight Internet Hosting Tool 实现互联网串流,并逐一说明与 GameStream 相比的功能限制。读完本文,你将掌握从旧方案平滑迁移、正确编写应用配置、以及在 UPnP 路由器上开放串流端口的完整实操能力。
Nvidia GameStream 停服背景与迁移契机
Nvidia 宣布,面向 Nvidia Games 客户端的 GameStream 服务已于 2023 年 2 月停止运营。对于长期依赖 GameStream 在局域网内串流 PC 游戏的用户来说,这意味着需要寻找替代方案,而 Moonlight 客户端生态对应的服务端正是 Sunshine。
仓库文档对此给出的判断是:Sunshine 的串流性能目前已与 Nvidia GameStream 持平甚至更优。因此迁移不仅是被迫的替代,也是一种性能与自主可控上的升级——Sunshine 是自托管方案,服务端完全运行在你自己的机器上,不依赖任何云端服务。
迁移工作主要分两部分:
- 游戏与应用清单迁移:把 GameStream 里已配置好的游戏、应用及其启动命令、封面图等搬到 Sunshine。
- 互联网串流通道迁移:用 Sunshine 内置的 UPnP 端口映射替代 Moonlight Internet Hosting Tool 的手动端口转发。
自动化迁移工具 GSMS
原文档明确推荐使用社区开发的迁移工具 GSMS(GameStream Migration Suite,由 LizardByte 组织维护)来完成自动化迁移。
GSMS 的能力范围:
- 迁移自定义添加的游戏和应用(用户在 GameStream 客户端中手工配置的条目);
- 迁移自动检测的游戏和应用(GameStream 自动扫描识别的条目)。
迁移过程中,GSMS 会把以下关键信息完整写入 Sunshine 的 apps.json:
- working directory(工作目录)
- command(启动命令)
- image(应用封面/图标图片)
同时,GSMS 还会把 GameStream 的 box-art 封面图复制到指定的目录,供 Sunshine 应用条目引用。这意味着迁移完成后,Moonlight 客户端中看到的应用列表、图标和启动行为都与原来高度一致。
说明:GSMS 是一个独立于本仓库的迁移工具项目。如果你倾向手工迁移,也可以跳过该工具,直接按下文「深入理解 Sunshine 的应用配置 apps.json」一节手动编写
apps.json,效果相同。
深入理解 Sunshine 的应用配置 apps.json
Sunshine 通过一个 JSON 文件描述所有可供 Moonlight 启动的应用,默认文件名为 apps.json,默认存放位置与 Sunshine 配置文件相同(对应配置项 file_apps,见 docs/configuration.md 中的 file_apps 一节)。GSMS 迁移的落点也正是这个文件。
仓库中的默认 apps.json 示例
Windows 平台的默认配置见 src_assets/windows/assets/apps.json,Linux 平台的见 src_assets/linux/assets/apps.json。以下是 Windows 默认配置的节选:
{
"env": {},
"apps": [
{
"name": "Desktop",
"image-path": "desktop",
"exclude-global-prep-cmd": "false",
"elevated": "",
"auto-detach": "true",
"wait-all": "true",
"exit-timeout": "5",
"menu-cmd": [
{
"id": "kcENAT5r9P",
"name": "触摸键盘",
"cmd": ".\\tools\\qiin-tabtip.exe",
"elevated": "false"
}
]
},
{
"name": "Steam Big Picture",
"cmd": "steam://open/bigpicture",
"auto-detach": "true",
"wait-all": "true",
"image-path": "steam.png"
},
{
"name": "Xbox Game",
"cmd": "cmd \/c \"start xbox:\"",
"auto-detach": "true",
"wait-all": "true",
"image-path": "box.png"
}
]
}
Linux 默认配置则展示了 env 与 prep-cmd 的用法:
{
"env": {
"PATH": "$(PATH):$(HOME)/.local/bin"
},
"apps": [
{
"name": "Desktop",
"image-path": "desktop.png"
},
{
"name": "Low Res Desktop",
"image-path": "desktop.png",
"prep-cmd": [
{
"do": "xrandr --output HDMI-1 --mode 1920x1080",
"undo": "xrandr --output HDMI-1 --mode 1920x1200"
}
]
},
{
"name": "Steam Big Picture",
"detached": [
"setsid steam steam://open/bigpicture"
],
"image-path": "steam.png"
}
]
}
应用条目字段详解
apps.json 的顶层包含 env(全局环境变量)与 apps(应用数组)。每个应用条目支持的字段,可以从 src/process.cpp 的解析代码中确认,结合 docs/app_examples.md 的说明整理如下:
| 字段 | 类型 | 含义 |
|---|---|---|
name |
string | 应用名称,显示在 Moonlight 客户端中(必填) |
cmd |
string | 主启动命令;不填则视为桌面/无主命令类型条目 |
image-path |
string | 封面图片路径;可用 desktop.png、steam.png 等内置资源,也可指向任意图片文件 |
working-dir |
string | 工作目录;未指定时默认使用目标应用程序所在目录 |
output |
string | 应用日志输出文件路径,便于排障 |
elevated |
bool | 是否以管理员权限启动(Windows 服务方式安装时有效),可免 UAC 弹窗 |
auto-detach |
bool | 自动脱离进程组(适用于会自我更新并杀掉原进程的应用,如 Steam、UWP 应用) |
detached |
string[] | 以脱离方式启动的命令列表 |
wait-all |
bool | 等待所有子进程结束后才结束会话 |
exit-timeout |
int | 退出超时(秒) |
prep-cmd |
array | 启动前准备命令,每项含 do、undo、elevated,用于临时调整系统状态(如切换分辨率)并在结束后还原 |
menu-cmd |
array | 客户端菜单项(每项含 id、name、cmd、elevated),如「触摸键盘」等辅助入口 |
exclude-global-prep-cmd |
bool | 是否排除全局 global_prep_cmd 的影响(默认 false,即继承全局准备命令) |
mouse-mode |
int | 该应用的鼠标模式覆盖 |
gamepad |
string | 该应用的虚拟手柄类型覆盖(auto/x360/ds4/ds5,见 src/confighttp.cpp 的校验逻辑) |
rtx-hdr |
object | 该应用的 RTX HDR 相关配置 |
从 src/process.cpp 可以看到,每个应用的 prep-cmd 会与全局 global_prep_cmd 合并执行,除非该条目显式设置了 exclude-global-prep-cmd: true。此外应用与命令中的环境变量支持形如 $(VAR) 的展开(env 段与 parse_env_val 处理,见 src/process.cpp)。
封面图片与 box-art
image-path 字段就是 GSMS 迁移时写入的「image」落点。GSMS 会把 GameStream 的 box-art 封面复制到你指定的目录,然后在这个字段中引用。仓库自带的封面资源包括 desktop.png、steam.png、box.png 等(见 src_assets/common/assets)。图片文件可以放在 Sunshine 配置目录或安装目录下,使用相对路径引用即可。
互联网串流配置:从 Moonlight Internet Hosting Tool 迁移到 UPnP
如果你此前使用 Moonlight Internet Hosting Tool(Moonlight 官方提供的互联网串流托管工具,负责维护端口转发规则)进行公网串流,迁移到 Sunshine 后应当将其从系统中移除——因为 Sunshine 已经内置了完整的 UPnP 互联网串流支持。
重要兼容性警告
原文档特别强调:如果让 Sunshine 与 v5.6 之前的 Moonlight Internet Hosting Tool 版本同时运行,会导致 UPnP 端口转发变得不可靠。两者的端口映射逻辑可能互相干扰(例如都尝试通过 UPnP 管理同一批端口)。因此迁移时必须二选一:
- 彻底卸载 Moonlight Internet Hosting Tool,完全交给 Sunshine 的 UPnP 处理;或
- 至少将其更新到 v5.6 或更高版本。
启用 UPnP 的方法
在 Sunshine Web UI(默认 https://localhost:47990)中启用 UPnP 选项即可,前提是你的路由器支持 UPnP(Internet Gateway Device)。对应配置文件中的设置项为 upnp,见 docs/configuration.md:
upnp = enabled
该配置项默认值为 disabled(不开启)。开启后,Sunshine 启动时会自动在路由器上建立并维护端口映射,无需手动登录路由器管理页面。
Sunshine UPnP 端口映射明细
Sunshine 需要映射的端口由 src/upnp.cpp 定义。实际端口 = 配置项 port(默认 47989,范围 1029–65514,见 docs/configuration.md)+ 各服务偏移量(net::map_port 的实现见 src/network.cpp):
| 映射描述 | 协议 | 偏移量 | 默认端口 |
|---|---|---|---|
| Sunshine - RTSP | TCP | +21 | 48010 |
| Sunshine - Video | UDP | +9 | 47998 |
| Sunshine - Control | UDP | +10 | 47999 |
| Sunshine - Audio | UDP | +11 | 48000 |
| Sunshine - Microphone | UDP | +12 | 48001 |
| Sunshine - Client HTTP | TCP | +0 | 47989 |
| Sunshine - Client HTTPS | TCP | −5 | 47984 |
| Sunshine - Web UI | TCP | +1 | 47990 |
其中 Web UI 端口只在 origin_web_ui_allowed 允许 WAN 访问时才会被映射(见 src/upnp.cpp),该配置项默认 lan,可选 pc/lan/wan(见 docs/configuration.md)。出于安全考虑,除非确需从公网管理 Web UI,否则保持默认的 lan 即可,此时 Web UI 不会被暴露到公网。
UPnP 实现原理与维护行为
从 src/upnp.cpp 的源码可以看到 Sunshine 的 UPnP 并非「开机映射一次」那么简单,而是运行一个独立的维护线程(upnp_thread_proc,见 src/upnp.cpp):
- 周期性刷新:每 120 秒(
REFRESH_INTERVAL,定义于 src/upnp.h)重新检查一次映射状态。因为路由器重启、WAN IP 变化等事件都会导致映射丢失,持续刷新可以自动恢复。 - 租约续期:端口映射的租约时长默认 3600 秒(
PORT_MAPPING_LIFETIME,见 src/upnp.h),每次刷新都会续期;遇到旧的/异常 IGDv1 设备时退化为永久(lease 0)映射。 - 冲突处理:先查询目标端口是否已有映射(
UPNP_GetSpecificPortMappingEntry),若映射指向其他内网地址则视为冲突,尝试删除后重建(见 src/upnp.cpp)。 - 退出清理:Sunshine 正常退出时会删除所有已建立的映射(
unmap_all_upnp_ports,见 src/upnp.cpp)。 - 状态日志:启动阶段会输出 IGD 发现状态(如
No IGD device found、Valid connected IGD device found),便于排查路由器兼容性问题(见 src/upnp.cpp)。
IPv6 防火墙 pinhole
如果配置项 address_family = both(IPv4+IPv6,见 docs/configuration.md),Sunshine 还会尝试在支持 IPv6 Firewall Control 的 IGD 上为每个端口创建 IPv6 pinhole(防火墙洞,见 src/upnp.cpp)。由于 IPv6 不存在传统意义的「端口映射到内网地址」,pinhole 直接放行发往本机 LAN 地址的流量。多数家用路由器不支持该特性,失败时仅记录 debug 日志,不影响 IPv4 映射。
与 Nvidia GameStream 相比的限制
原文档明确列出了 Sunshine 相对 GameStream 仍存在的两项限制,迁移后需要了解并自行弥补:
-
自动游戏/应用列表(Automatic game/application list) GameStream 会自动扫描并列出已安装的受支持游戏;Sunshine 不具备这种自动发现能力,所有条目都需要在
apps.json中显式配置(这正是 GSMS 迁移工具存在的意义——把 GameStream 已有的清单原样搬运过来)。 -
自动更改游戏设置以优化串流(Changing game settings automatically to optimize streaming) GameStream 会在启动串流时自动调整部分游戏画质设置;Sunshine 不做这种自动化干预,而是通过
prep-cmd/global_prep_cmd机制提供等效手段——例如用nircmd、xrandr或qres在串流前后切换分辨率(可参考 docs/configuration.md 中的global_prep_cmd示例,以及 docs/app_examples.md 中带prep-cmd的完整示例)。
global_prep_cmd = [{"do":"nircmd.exe setdisplay 1280 720 32 144","undo":"nircmd.exe setdisplay 2560 1440 32 144"}]
需要注意的是,写入这些准备命令时,"true"/"false" 需按 JSON 字符串形式书写(见 docs/app_examples.md 的提示)。
迁移后的验证与排障建议
完成迁移并启用 UPnP 后,建议按以下顺序验证:
- 局域网验证:用 Moonlight 客户端连接 Sunshine,确认迁移过来的每个应用都能正常启动、封面图正确显示。
- 日志确认:查看 Sunshine 日志(
log_path,默认sunshine.log),应能看到Completed UPnP port mappings to <内网IP> via <IGD描述URL>一类信息(见 src/upnp.cpp);若提示No IGD device found,说明路由器未开启 UPnP 或设备不支持。 - 公网验证:关闭 Wi-Fi、用移动网络连接,输入主机公网地址(若不确定可配置
external_ip,见 docs/configuration.md)进行串流测试。 - 冲突排查:如果公网连接失败且此前安装过 Moonlight Internet Hosting Tool,请先确认已卸载或升级至 v5.6 以上,再重启 Sunshine 让映射线程重新建立规则。
延伸阅读
- 应用配置完整参考:docs/configuration.md(含
file_apps、upnp、port、address_family、origin_web_ui_allowed、external_ip、global_prep_cmd等全部相关配置项) - 应用条目实战示例:docs/app_examples.md
- 第三方打包与安装方式:docs/third_party_packages.md
- 许可与合规说明:docs/legal.md
- UPnP 端口映射与维护实现:src/upnp.cpp、src/upnp.h
- 应用配置解析实现:src/process.cpp、src/network.cpp
- 默认应用清单:src_assets/windows/assets/apps.json、src_assets/linux/assets/apps.json