Sunshine 远程串流容器化部署避坑指南从镜像选择到故障排查【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的开源游戏串流服务端与 Moonlight 客户端配合就能把电脑上的游戏画面远程串流到手机、平板或另一台主机。用 Docker 容器化部署它环境依赖、多架构兼容与配置持久化可以一次打包从拉取镜像到客户端配对通常只需几分钟。不过它的镜像有一套特殊的标签规则和使用前提沿用普通软件的 Docker 习惯很容易翻车。这篇文章带你走完选镜像、跑容器、查故障的完整闭环。先从一个真实翻车现场说起你花了一晚上手动编译安装好 Sunshine浏览器里管理页也正常打开了。可坐到沙发上拿起手机Moonlight 客户端却怎么都连不上好不容易连上第二天重启宿主机登录凭证和画质设置又全部归零——这类配置好了却连不上重启后全丢的问题绝大多数都能用容器化避免。容器化把 Sunshine 的运行环境冻结成一份镜像换机器、换系统、迁移部署拉起同一份镜像即可复现/config目录外置后配置、配对记录、日志全部落在宿主机磁盘上容器删了重建也不丢。前提是镜像选对、参数挂对、设备传对。下面逐步说。动手前先定两件事镜像标签与部署形态如何选择适合你的镜像标签镜像标签是区分版本与基础系统的命名规则。自 v0.18.0 起Sunshine 不再允许单独使用latest、master、vX.X.X这样的简单标签必须组合成版本-操作系统的完整格式。例如latest-ubuntu-24.04、v0.18.0-debian-bookworm想精确复现某个构建还可以用 commit hash 作为版本部分。版本部分适用场景latest快速试用跟随稳定版更新vX.X.X生产环境固定版本master尝鲜开发分支谨慎使用commit hash精确锁定某次构建系统后缀决定基础系统也决定架构支持面系统后缀amd64/x86_64arm64/aarch64debian-bookworm支持支持ubuntu-22.04支持支持ubuntu-24.04支持支持一个容易被忽略的事实官方将 Docker 镜像定位为基础镜像并明确标注为实验性官方文档并不推荐大多数用户直接用它跑生产。因此先想清楚场景再动手——容器化适合三类人需要把 Sunshine 与 Steam、Games on Whales 等容器栈集成的想在无桌面受限环境快速试用的以及需要跨机器快速迁移部署的。追求极致稳定与性能时官方二进制仍是首选。三种部署形态怎么选裸容器docker run适合快速验证一条命令跑通Docker Compose适合固定复现配置、端口、卷全部落盘为文件Podman 无根模式适合不允许 root 的共享主机用--usernskeep-id规避用户命名空间问题。三个典型场景三套可直接用的命令场景一局域网内 5 分钟跑起第一条串流这是最常见的使用方式在 Linux 主机上直接拉起容器然后用手机或笔记本上的 Moonlight 配对串流。docker run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --ipchost \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v /data/sunshine:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:latest-ubuntu-24.04启动后打开http://主机IP:47990完成首次账号与密码设置即可在 Moonlight 中按提示配对。TCP 段覆盖 Web 管理、HTTPS 与配对通道UDP 段承载视频、音频与控制流三类端口一个都不能少。场景二ARM 小主机上的跨架构部署如果你用的是树莓派、NAS 这类 ARM 设备不需要手动指定平台——debian-bookworm与两个 Ubuntu 后缀都同时提供 amd64 和 arm64 镜像Docker 会按宿主机架构自动拉取对应版本。唯一要留意的是权限宿主机上挂载目录的属主必须与容器内的 PUID/PGID 一致否则容器内写配置会直接失败。id youruser # 输出形如 uid1000(youruser) gid1000(yourgroup)把输出的两个数字填入-e PUID1000 -e PGID1000并确保/data/sunshine归属于该用户。场景三把 Sunshine 嵌进自己的串流容器栈官方镜像的原始定位就是积木以它为底座在 Dockerfile 里叠加自己需要的组件。典型如配合 Steam 的容器栈ARG SUNSHINE_VERSIONlatest ARG SUNSHINE_OSubuntu-24.04 FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS} RUN apt-get update apt-get install -y \ steam \ wayland-protocols \ weston ENTRYPOINT steam sunshine构建定义可对照仓库docker/目录下的ubuntu-22.04.dockerfile、ubuntu-24.04.dockerfile理解镜像的多阶段构建与用户初始化逻辑。四个高频故障的逆向排查遇到问题先别急着改配置按现象 → 原因 → 解法自查多数坑都能定位。现象一浏览器打不开管理页先确认容器在运行docker ps看sunshine是否 Up再确认端口映射完整特别是47990。外部端口可以改例如-p 8080:47990后用http://主机IP:8080访问但内部端口必须保持47990。最后检查宿主机防火墙是否放行了映射后的端口。现象二客户端能连上但串流黑屏日志提示编码器缺失原因通常是 GPU 设备没有传进容器或宿主驱动/编码器不完整。排查日志里是否出现Encoder not found之类的记录确认命令中包含--device /dev/dri/并确认宿主机上vainfo等工具能正常枚举编码器。现象三重启容器后配置全部丢失这是典型的卷没挂对。确认启动命令里带了-v 宿主机目录:/config而不是依赖容器内临时目录同时核对目录属主与 PUID/PGID 一致否则容器内进程写不进配置表现同样像是配置全丢。修复命令chown -R 1000:1000 /data/sunshine现象四Podman 无根模式启动即失败无根容器默认的用户命名空间映射会导致权限错乱启动时加上--usernskeep-id让容器内 UID 与宿主用户保持一致同时挂载目录属主对齐 PUID/PGID问题即可消除。收束部署前检查清单与延伸阅读动手部署前花两分钟过一遍这份清单能挡掉八成问题标签格式已写为版本-系统生产环境固定到具体版本而非latestTCP47984-47990、48010与 UDP47998-48000端口全部映射/config已挂载宿主机目录属主与 PUID/PGID 一致已通过--device /dev/dri/传入 GPU 设备宿主驱动可用已设置TZ时区与--ipchost防火墙已放行对应端口。想深入仓库内这几份文件足够你读完DOCKER_README.md是镜像标签、端口与参数的权威说明docs/getting_started.md覆盖安装与首次配置docs/configuration.md提供全部配置项解析docs/troubleshooting.md收录更多已知问题。需要自己构建或定制镜像可以拉取源码git clone https://gitcode.com/GitHub_Trending/su/Sunshine。容器化不是终点它只是把环境不可复现变成一条命令可复现。镜像选对、端口挂全、设备传好剩下的就交给 Sunshine 本身了。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Sunshine 远程串流容器化部署避坑指南：从镜像选择到故障排查
Sunshine 远程串流容器化部署避坑指南从镜像选择到故障排查【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的开源游戏串流服务端与 Moonlight 客户端配合就能把电脑上的游戏画面远程串流到手机、平板或另一台主机。用 Docker 容器化部署它环境依赖、多架构兼容与配置持久化可以一次打包从拉取镜像到客户端配对通常只需几分钟。不过它的镜像有一套特殊的标签规则和使用前提沿用普通软件的 Docker 习惯很容易翻车。这篇文章带你走完选镜像、跑容器、查故障的完整闭环。先从一个真实翻车现场说起你花了一晚上手动编译安装好 Sunshine浏览器里管理页也正常打开了。可坐到沙发上拿起手机Moonlight 客户端却怎么都连不上好不容易连上第二天重启宿主机登录凭证和画质设置又全部归零——这类配置好了却连不上重启后全丢的问题绝大多数都能用容器化避免。容器化把 Sunshine 的运行环境冻结成一份镜像换机器、换系统、迁移部署拉起同一份镜像即可复现/config目录外置后配置、配对记录、日志全部落在宿主机磁盘上容器删了重建也不丢。前提是镜像选对、参数挂对、设备传对。下面逐步说。动手前先定两件事镜像标签与部署形态如何选择适合你的镜像标签镜像标签是区分版本与基础系统的命名规则。自 v0.18.0 起Sunshine 不再允许单独使用latest、master、vX.X.X这样的简单标签必须组合成版本-操作系统的完整格式。例如latest-ubuntu-24.04、v0.18.0-debian-bookworm想精确复现某个构建还可以用 commit hash 作为版本部分。版本部分适用场景latest快速试用跟随稳定版更新vX.X.X生产环境固定版本master尝鲜开发分支谨慎使用commit hash精确锁定某次构建系统后缀决定基础系统也决定架构支持面系统后缀amd64/x86_64arm64/aarch64debian-bookworm支持支持ubuntu-22.04支持支持ubuntu-24.04支持支持一个容易被忽略的事实官方将 Docker 镜像定位为基础镜像并明确标注为实验性官方文档并不推荐大多数用户直接用它跑生产。因此先想清楚场景再动手——容器化适合三类人需要把 Sunshine 与 Steam、Games on Whales 等容器栈集成的想在无桌面受限环境快速试用的以及需要跨机器快速迁移部署的。追求极致稳定与性能时官方二进制仍是首选。三种部署形态怎么选裸容器docker run适合快速验证一条命令跑通Docker Compose适合固定复现配置、端口、卷全部落盘为文件Podman 无根模式适合不允许 root 的共享主机用--usernskeep-id规避用户命名空间问题。三个典型场景三套可直接用的命令场景一局域网内 5 分钟跑起第一条串流这是最常见的使用方式在 Linux 主机上直接拉起容器然后用手机或笔记本上的 Moonlight 配对串流。docker run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --ipchost \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v /data/sunshine:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:latest-ubuntu-24.04启动后打开http://主机IP:47990完成首次账号与密码设置即可在 Moonlight 中按提示配对。TCP 段覆盖 Web 管理、HTTPS 与配对通道UDP 段承载视频、音频与控制流三类端口一个都不能少。场景二ARM 小主机上的跨架构部署如果你用的是树莓派、NAS 这类 ARM 设备不需要手动指定平台——debian-bookworm与两个 Ubuntu 后缀都同时提供 amd64 和 arm64 镜像Docker 会按宿主机架构自动拉取对应版本。唯一要留意的是权限宿主机上挂载目录的属主必须与容器内的 PUID/PGID 一致否则容器内写配置会直接失败。id youruser # 输出形如 uid1000(youruser) gid1000(yourgroup)把输出的两个数字填入-e PUID1000 -e PGID1000并确保/data/sunshine归属于该用户。场景三把 Sunshine 嵌进自己的串流容器栈官方镜像的原始定位就是积木以它为底座在 Dockerfile 里叠加自己需要的组件。典型如配合 Steam 的容器栈ARG SUNSHINE_VERSIONlatest ARG SUNSHINE_OSubuntu-24.04 FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS} RUN apt-get update apt-get install -y \ steam \ wayland-protocols \ weston ENTRYPOINT steam sunshine构建定义可对照仓库docker/目录下的ubuntu-22.04.dockerfile、ubuntu-24.04.dockerfile理解镜像的多阶段构建与用户初始化逻辑。四个高频故障的逆向排查遇到问题先别急着改配置按现象 → 原因 → 解法自查多数坑都能定位。现象一浏览器打不开管理页先确认容器在运行docker ps看sunshine是否 Up再确认端口映射完整特别是47990。外部端口可以改例如-p 8080:47990后用http://主机IP:8080访问但内部端口必须保持47990。最后检查宿主机防火墙是否放行了映射后的端口。现象二客户端能连上但串流黑屏日志提示编码器缺失原因通常是 GPU 设备没有传进容器或宿主驱动/编码器不完整。排查日志里是否出现Encoder not found之类的记录确认命令中包含--device /dev/dri/并确认宿主机上vainfo等工具能正常枚举编码器。现象三重启容器后配置全部丢失这是典型的卷没挂对。确认启动命令里带了-v 宿主机目录:/config而不是依赖容器内临时目录同时核对目录属主与 PUID/PGID 一致否则容器内进程写不进配置表现同样像是配置全丢。修复命令chown -R 1000:1000 /data/sunshine现象四Podman 无根模式启动即失败无根容器默认的用户命名空间映射会导致权限错乱启动时加上--usernskeep-id让容器内 UID 与宿主用户保持一致同时挂载目录属主对齐 PUID/PGID问题即可消除。收束部署前检查清单与延伸阅读动手部署前花两分钟过一遍这份清单能挡掉八成问题标签格式已写为版本-系统生产环境固定到具体版本而非latestTCP47984-47990、48010与 UDP47998-48000端口全部映射/config已挂载宿主机目录属主与 PUID/PGID 一致已通过--device /dev/dri/传入 GPU 设备宿主驱动可用已设置TZ时区与--ipchost防火墙已放行对应端口。想深入仓库内这几份文件足够你读完DOCKER_README.md是镜像标签、端口与参数的权威说明docs/getting_started.md覆盖安装与首次配置docs/configuration.md提供全部配置项解析docs/troubleshooting.md收录更多已知问题。需要自己构建或定制镜像可以拉取源码git clone https://gitcode.com/GitHub_Trending/su/Sunshine。容器化不是终点它只是把环境不可复现变成一条命令可复现。镜像选对、端口挂全、设备传好剩下的就交给 Sunshine 本身了。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
