如何用Docker 5分钟部署Sunshine游戏串流服务器：零基础避坑指南

如何用Docker 5分钟部署Sunshine游戏串流服务器：零基础避坑指南

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

Sunshine 是一款开源、自托管的游戏串流服务端，专门配合 Moonlight 客户端使用，能把你的电脑变成随时随地可访问的游戏主机。本文用 Docker 带你 5 分钟完成部署，从镜像标签、端口映射、GPU 直通到各种权限坑位，一步步照抄就能跑通，全程零基础友好。

一、痛点开篇：装个串流服务，怎么这么折腾？

先讲个真实场景。上周朋友跟我抱怨，他照着仓库里的说明手动编译 Sunshine，折腾了一整晚还是没起来：一会儿缺依赖库，一会儿编译报错，好不容易装好了，系统一更新又打回原形。换台机器？不好意思，全部从头再来。

这其实是自托管串流服务的老大难。Sunshine 要做的事很多——采集画面、硬件编码、处理输入、转发网络流，背后牵扯一堆图形、编码、虚拟输入相关的系统库，而每个发行版的环境又不太一样。手动部署的每一步，都可能成为劝退你的理由。

Docker 就是冲着这个痛点来的。它把 Sunshine 以及它需要的所有环境打包成一个镜像，你拉下来就能跑；换机器只是重新拉一次的事；想回滚版本，切换镜像标签就行。说白了，容器帮你把"环境地狱"彻底隔离在了一层壳里。

二、快速认知：四个概念，一次讲透

动手之前，先花三分钟把几个高频词搞清楚。看不懂概念，后面命令里的每个参数都会让你发怵；搞懂了，一切就顺理成章。

• 镜像和容器：镜像相当于安装包，容器是跑起来的程序。你拉取的是镜像，启动的是容器，删掉容器不影响镜像，随时能再起一个。
• 端口映射：Sunshine 在容器内部监听 47990 等端口，宿主机必须把对应端口映射出来，Moonlight 客户端才能找到它。映射是单向门——你指定的宿主机端口指向容器端口。
• 设备直通（--device /dev/dri）：串流最吃硬件编码。只有把显卡设备"借"进容器，编码才能走 GPU；否则退化成软件编码，画质和延迟都会很难看。
• 数据卷（-v /config）：Sunshine 的配置默认存在容器里的 /config 目录。不挂载出来的话，容器一删，配置、配对信息全部归零，所以这步一定不能省。

是不是比想象中简单？下面进入正题，跟着做就行。

三、手把手实战：五步跑通你的第一个串流容器

这一节是全篇重点，我会放慢速度，每一条命令都带上注释。建议你开个终端，边看边敲。

第1步 先做环境自检

确认两件事：Docker 装好了、显卡驱动正常。以 Linux 为例：

docker --version # 确认 Docker 可用 ls /dev/dri # 能看到 renderD128 等节点，说明显卡可直通

如果你的机器上/dev/dri不存在，先去装好显卡驱动再继续，这一步没做好，后面串流会卡成 PPT。

第2步 拉取正确标签的镜像（这一步最容易翻车）

重点来了，从 v0.18.0 版本起，Sunshine 官方镜像的标签规则变了：

• 不再支持latest、master、vX.X.X这种单独标签；
• 必须使用组合格式：版本-操作系统，例如latest-ubuntu-22.04；
• 版本部分也可以填具体的 commit hash。

# 正确姿势 docker pull lizardbyte/sunshine:latest-ubuntu-22.04 docker pull lizardbyte/sunshine:v0.18.0-ubuntu-22.04 # 错误示范（v0.18.0 之后这样拉会报错） docker pull lizardbyte/sunshine:latest

版本部分支持四类写法：具体版本号（如 v0.18.0）、latest（最新稳定版）、master（开发分支）、某次提交的 hash。操作系统部分目前可选：archlinux、debian-bookworm、ubuntu-22.04、ubuntu-24.04。

第3步 初始化配置目录

在宿主机上建一个目录存放配置，并提前把权限交给容器内用户，免得启动后写不进去：

mkdir -p /path/to/config sudo chown -R 1000:1000 /path/to/config

第4步 一条命令把容器拉起来

下面是完整版 docker run，参数都标了注释，照着抄就行：

docker run -d \ --device /dev/dri/ \ # 显卡直通，硬件编码必需 --name=sunshine-container \ # 自定义容器名 --restart=unless-stopped \ # 开机自启，异常退出自动拉起 --ipc=host \ # 共享宿主机内存，传帧数据很吃内存 -e PUID=1000 \ # 容器内用户 ID -e PGID=1000 \ # 容器内用户组 ID -e TZ=Asia/Shanghai \ # 时区，决定日志时间 -v /path/to/config:/config \ # 配置持久化 -p 47984-47990:47984-47990/tcp \ # 控制通道 + Web 管理界面(47990) -p 48010:48010 \ # 媒体流通道 -p 47998-48000:47998-48000/udp \ # 视频/音频流 lizardbyte/sunshine:latest-ubuntu-22.04

如果你习惯用 docker compose，把下面这段存成 docker-compose.yml，再执行docker compose up -d效果一样：

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

第5步 验证成果：登录 Web 界面并完成配对

浏览器打开http://你的主机IP:47990，会进入 Sunshine 的 Web 管理登录页，按提示创建账号登录即可：

登录后进入 Applications 页面，默认已经有 Desktop、Steam 这些应用卡片，点右上角的 Add New 可以继续添加你想串流的游戏或程序：

到这里容器就算正式跑起来了。最后一步，在手机或平板装好 Moonlight 客户端，添加主机时填电脑的 IP，用 Web 界面里显示的 PIN 码完成配对，就能开始你的第一次串流了。

四、进阶与自定义：从"能跑"到"跑得顺手"

基础部署没问题后，这几个问题你迟早会遇到：版本选哪个、ARM 设备能不能用、参数怎么按需调、能不能和 Steam 生态组队。

版本与架构怎么选

镜像的架构支持并不统一，动手前先对号入座：

我的建议很直白：Intel/AMD 台式机，ubuntu-22.04 或 debian-bookworm 随便选，稳；ARM 设备（软路由、开发板这类），优先 debian-bookworm 和 ubuntu-24.04；用 Arch 的玩家就别惦记 ARM64 镜像了。

参数速查与按需调整

如果默认的 Web 端口 47990 被别的服务占了，把映射改成-p 8080:47990，然后访问http://IP:8080就行，其他端口照旧。PUID/PGID 建议改成你宿主机实际用户的 ID，避免文件归属混乱。

想在 Web 界面里快速定位某个配置项，可以用顶部搜索框，比如搜 "Upnp" 就能直接找到网络端口转发相关的开关：

Podman 用户的平替方案

不用 Docker 也可以玩。Podman 的启动命令几乎一样，唯一要记得的是把用户映射参数换成--userns=keep-id，其余照抄：

podman run -d \ --device /dev/dri/ \ --name=sunshine-container \ --restart=unless-stopped \ --userns=keep-id \ -e PUID=1000 \ -e PGID=1000 \ -e TZ=Asia/Shanghai \ -v /path/to/config:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:latest-ubuntu-22.04

把它当积木：集成进自己的镜像

官方镜像本身就是按"基础镜像"设计的，方便你往上叠加依赖。比如想让容器里直接带上 Steam，可以这么写 Dockerfile：

ARG SUNSHINE_VERSION=latest ARG SUNSHINE_OS=ubuntu-22.04 FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS} # 在基础镜像上补齐 Steam 和 Wayland 相关依赖 RUN apt-get update && apt-get install -y \ steam \ wayland-protocols \ weston ENTRYPOINT ["steam", "&&", "sunshine"]

构建时通过 ARG 传不同的版本和系统，同一套 Dockerfile 就能随意切换，灵活度很高。

五、避坑手册：四个高频翻车现场

最后分享四个我见过最多的问题，都按"现象 → 原因 → 解决"来整理，遇到直接对号入座。

坑1：容器反复重启，日志全是 Permission denied

• 现象：容器起不来，挂载目录里写不进任何文件。
• 原因：宿主机目录的属主和容器内 PUID/PGID 对不上。
• 解决：把目录权限交给容器内用户：

  sudo chown -R 1000:1000 /path/to/config

坑2：串流画面卡成幻灯片，GPU 完全不干活

• 现象：能连上，但帧率极低，CPU 占用爆表。
• 原因：显卡设备没直通进容器，或宿主机驱动本身没装好。
• 解决：确认ls /dev/dri有输出，且启动命令里保留了--device /dev/dri/。还不生效的话，去 Web 界面的 Logs 页看有没有 "Encoder not found" 之类的报错，日志里通常直接写明问题：

坑3：Web 界面打不开，或打开的是别的程序

• 现象：访问 47990 端口没反应，或者跳到了完全无关的页面。
• 原因：端口被其他服务占用了。
• 解决：改宿主机的端口映射，比如-p 8080:47990，之后用http://IP:8080访问。

坑4：容器日志时间总是差好几个小时

• 现象：日志时间戳全是 UTC，和本地时间对不上。
• 原因：没设置时区。
• 解决：启动时加一行-e TZ=Asia/Shanghai，其他地区按需替换即可。

六、收尾：从"跑起来"到"玩明白"

还记得开头那个折腾一整晚的朋友吗？现在他只需要复制一条 docker run，5 分钟服务就能恢复如初，换机器也只是重新拉一次镜像的事。手动部署时代最折磨人的环境问题，被容器干净利落地挡在了门外。

给你几条收尾建议：

• 求稳：日常使用锁定具体版本（比如 v0.18.0-ubuntu-22.04），别追 latest，升级更可控；
• 求新：想尝鲜新功能，随时切到 master 分支标签体验；
• 勤备份：/config 目录定期备份——容器丢了能重建，配置和配对记录丢了才是真麻烦；
• 控资源：串流很吃资源，给容器加上 CPU/内存限额，别让它拖垮整台机器。

想继续深入，仓库的 docs 目录就是最好的向导：部署全流程看 docs/getting_started.md，画质与延迟调优看 docs/performance_tuning.md，遇到问题先去 docs/troubleshooting.md 翻一翻。想从源码开始折腾，也可以 clone 下来自己编译：

git clone https://gitcode.com/GitHub_Trending/su/Sunshine

一句话收束：Sunshine 负责把游戏画面送出去，Docker 负责把 Sunshine 养在"无菌室"里。跑通部署之后你会发现，真正值得花时间的不是环境配置，而是串流画质、延迟和输入体验的调优——那才是这份乐趣真正开始的地方。

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