Sunshine 串流服务容器化部署实战：3 步把书房主机搬到客厅电视

Sunshine 串流服务容器化部署实战：3 步把书房主机搬到客厅电视

【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine

Sunshine 是一款开源的自托管游戏串流服务端，它的任务只有一个：把电脑上的游戏画面，实时推送给任意位置的 Moonlight 客户端。本文不谈空泛的原理，直接带你完成容器化部署——3 个步骤、几条命令，从拉取镜像到手机或电视成功串流，全程大约一刻钟。文中每一条命令都能直接复制运行，参数含义也一并讲透。

先说一个真实场景：主机在书房，快乐在客厅

周末下午，你窝在沙发上，电视开着，手柄握在手里，脑子里想的全是昨晚没打完的 Boss。

可主机在书房。你不得不爬起来，跑过去开机、进游戏，再坐回客厅——如果显示器离电视足够近，还得拖着长长的 HDMI 线，在茶几和书桌之间反复腾挪。

这就是 Sunshine 存在的意义：让游戏画面"无线搬家"。主机待在原地不动，画面通过局域网实时编码并推送到你手边的任何屏幕。而容器化，则让这个串流服务的安装从"地狱级"变成"复制粘贴级"。

我最初是手动装的：编码器库、图形栈、音频栈、权限配置，一环扣一环，系统一升级就崩。后来换成官方 Docker 镜像，五分钟跑通，再也没折腾过第二遍。

容器到底帮我们挡掉了什么麻烦

把镜像想成一张"出厂模板"，容器则是按模板拆开即用的快递盒——盒子里已经装好了 Sunshine 需要的整套运行环境，不需要你在宿主机上手动凑齐依赖。

手动部署时，你要和这些东西搏斗：

• 显卡编码库（NVENC、AMF、VAAPI 各平台不同）
• 图形与音频栈的系统依赖
• 用户权限、目录归属、开机自启
• 升级系统后某依赖版本冲突，服务直接罢工

用容器，以上全部封进镜像。换机器、重装系统、多台设备共用一套配置，都只是"拉镜像 + 跑容器"的事。数据仍然在你手里，这就是自托管的意义。

动手前的三分钟自检：显卡、端口、镜像标签

开始敲命令之前，先花三分钟确认三件事，能少走大半弯路。

第一，显卡是否有硬件编码能力。NVIDIA 走 NVENC，AMD 走 AMF/VAAPI，Intel 核显走 Quick Sync。没有独显也能跑，但 CPU 软编码延迟明显，串流体验会打折扣。

第二，端口别被占用。下面这组端口是串流协议必需的，部署前检查一下：

• 47984–47990（TCP）：网页管理界面与配对
• 48010（TCP）：RTSP 握手
• 47998–48000（UDP）：音视频与控制流

第三，会读镜像标签。从 v0.18.0 起，官方镜像不再支持latest、master、vX.X.X这种单独标签，必须用<版本>-<系统>的组合格式，例如latest-ubuntu-24.04。版本部分可以是latest、master、具体版本号或 commit hash；系统部分目前提供debian-bookworm、ubuntu-22.04、ubuntu-24.04三种后缀，均同时支持 x86_64 和 ARM64 架构。

🐳 第一步：读懂镜像标签，再把它拉下来

先用最省事的组合跑通流程：

docker pull lizardbyte/sunshine:latest-ubuntu-24.04

这条命令会拉取官方镜像。第一次使用就用latest-ubuntu-24.04验证全链路，跑通之后再换成固定版本号——比如想锁定某个正式版本，可以先到镜像仓库的 Tags 页查一下有哪些可用版本，再填入vX.X.X-ubuntu-24.04这样的标签，避免手滑写了不存在的版本号。

第二步：一条 docker run 命令跑起服务

镜像就绪后，直接执行下面的命令（按你的实际路径替换/data/sunshine和用户 ID）：

docker run -d \ --name=sunshine \ --restart=unless-stopped \ --device /dev/dri/ \ --ipc=host \ -e PUID=1000 \ -e PGID=1000 \ -e TZ=Asia/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

拆开看，每一行都不是摆设：

• --device /dev/dri/：把 GPU 图形设备直通进容器，这是后面画质优化的前提
• --ipc=host：共享宿主机内存空间，避免串流进程的内存访问异常
• -v /data/sunshine:/config：把配置和配对凭据持久化到宿主机，容器删除也不丢
• 三组-p：分别对应网页界面、RTSP 会话、音视频数据流，缺一不可
• PUID/PGID/TZ：容器内运行身份与时区，直接影响文件权限和日志时间

PUID 和 PGID 用id命令查一下自己当前的用户 ID 即可，挂载目录的属主要和它保持一致，否则容器可能没有写入权限。

第三步：打开浏览器，完成首次配对

容器运行后，在任意一台能访问到它的设备上打开浏览器，访问：

http://主机IP:47990

你会看到 Sunshine 的欢迎页，按提示设置访问密码，之后在 Moonlight 客户端里添加主机、输入屏幕上的 PIN 码，握手就完成了。手机、平板、电视盒子、另一台电脑，装好 Moonlight 都能连。

到这一步，串流链路已经打通。接下来是让它变得更好用的进阶操作。

那串参数到底在管什么：端口、目录、身份、时区

很多人部署成功后不敢动参数，其实规则很简单：冒号左边是宿主机，右边是容器内部。

• 网页端口：容器内固定 47990，宿主机一侧可以随便改，比如-p 8080:47990就能用 8080 访问管理页
• 串流端口：三组端口的内部端口都不能改，它们被 Moonlight 协议写死了
• 配置目录：/config是唯一的配置落盘点，所有密码、应用列表、画质设置都在里面，务必挂载
• 身份与时区：PUID/PGID 不设则容器以 root 运行，设了更安全；TZ 影响所有日志的时间戳

如果之后要改 PUID/PGID，需要重建容器，所以最好一开始就定好。

🎮 画质不掉帧的关键一步：把 GPU 直通给容器

这是串流体验的分水岭。CPU 软编码不是不能跑，而是高分辨率、高码率下延迟和丢帧都很难看。硬件编码才是正解。

• Intel / AMD 核显或独显：上面命令里的--device /dev/dri/已覆盖绝大多数场景，无需额外配置
• NVIDIA 独显：需要额外的驱动与容器运行时支持，步骤稍多，建议先确认宿主机驱动版本
• 验证是否生效：进入网页端的 Logs 页面，能看到编码器识别情况；如果日志里出现编码器相关的 Error，先回去检查 GPU 直通

日志页是排错的第一现场，串流黑屏、起流失败，十有八九能从这里找到答案。

更进一步：把部署固化成 compose 剧本

命令行适合验证，长期使用更推荐把配置写成docker-compose.yml。好处很实在：换机器、重装系统时，一条命令就能完整复现环境，配置还能放进版本管理。

services: sunshine: image: lizardbyte/sunshine:latest-ubuntu-24.04 container_name: sunshine restart: unless-stopped devices: - /dev/dri:/dev/dri ipc: host environment: - PUID=1000 - PGID=1000 - TZ=Asia/Shanghai volumes: - /data/sunshine:/config ports: - "47984-47990:47984-47990/tcp" - "48010:48010" - "47998-48000:47998-48000/udp"

保存后在文件所在目录执行docker compose up -d即可。如果用的是 Podman，把--userns=keep-id换成对应的 compose 配置项，其余参数几乎可以照搬。

踩坑现场：五个高频问题的抢救手册

容器起来了，网页却打不开。先查端口映射是否完整，再确认 47990 没被宿主机其他进程占用，docker logs sunshine看一眼启动日志最直接。

串流黑屏或起流失败。八成是 GPU 没直通成功。确认/dev/dri设备存在且--device参数正确，然后回 Logs 页找编码器相关的报错。

容器内写不了配置。挂载目录的属主和 PUID/PGID 对不上。把目录属主改成对应 ID，例如chown -R 1000:1000 /data/sunshine（1000 换成你自己的 ID）。

局域网能连，出门就连不上。这是网络问题，不是容器问题。需要在路由器上为 47984–48010 的 TCP 和 47998–48000 的 UDP 做端口转发，并配合公网 IP 或内网穿透使用。

升级后配置不兼容，服务起不来。很可能是用了latest标签，镜像更新把配置格式带偏了。这就是为什么我建议生产环境锁定具体版本号，升级前先备份/config。

出门前 10 分钟：锁版本、做备份、管好安全

• 版本锁定：把latest换成明确的版本号，可预期、可回滚
• 定期备份：/config目录里是全部家当，密码、应用列表都在，备份它等于备份整个服务
• 开机自启：--restart=unless-stopped已包含在示例中，断电重启后服务会自动恢复
• 安全边界：网页管理界面别直接暴露到公网，建议用反向代理加 HTTPS；管理密码设强一些
• 资源限制：机器上还有其他服务的话，可以用--cpus和--memory给容器划定上限，避免串流吃满整机资源

到这里，你的 Sunshine 已经跑在容器里，可以随时用手机、平板或电视串流玩 3A 大作了。下一步值得折腾的方向很多：Steam 大屏模式配合手柄直连、多客户端同时接入、把整套 compose 配置写进自己的部署脚本。

最后想问问你：你手上的显卡是 NVIDIA 还是 AMD？GPU 直通这一步，有没有踩过什么神奇的坑？欢迎对照这篇文章里的日志排查思路，说说你的串流配置和实际延迟表现。

【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine