从 NVIDIA GameStream 迁移到 Sunshine(Apollo):GSMS 自动迁移、UPnP 互联网串流与已知限制全解析

原创2026-09-22 14:01:501,843 阅读
文章标签:音视频游戏开发

从 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 在启动前后执行分辨率切换、游戏设置命令等),可以在很大程度上弥补。

总结:一份完整的迁移检查清单

  1. 安装 Sunshine(本仓库 Apollo)并完成首次启动,确认默认 apps.json 已生成;
  2. 使用 GSMS 工具将 GameStream 中的自定义与自动检测游戏/应用迁移到 apps.json,核对 cmd、working-dir、image-path(PNG 封面图)是否正确,必要时在 Web UI 中增删改;
  3. 卸载(或升级到 v5.6+)Moonlight Internet Hosting Tool,避免与 UPnP 端口转发冲突;
  4. 需要公网串流时,在 Web UI 启用 UPnP(或配置 upnp = enabled),并确认路由器支持 UPnP;如使用 IPv6,可将 address_family 设为 both;
  5. 在 Moonlight 客户端中重新发现主机并配对,验证局域网与公网两种场景下的串流均正常。

相关文档:第三方便携包指南 | 法律声明 | 完整配置参考 | 入门指南

登录后查看全文
Apollo