Sunshine 用 Docker 容器化部署从镜像拉取失败到流畅串流绕开这 5 个坑【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的游戏串流服务端专门配合 Moonlight 客户端使用支持 AMD、Intel、Nvidia 显卡的硬件编码也保留软件编码兜底。把它装进 Docker 容器升级、迁移、换机器都变成拷贝一份配置文件那么简单这正是容器化部署比裸机安装更受欢迎的原因。这篇指南从一次真实的镜像拉取失败讲起把容器化部署的每个关键环节拆开帮你在半小时内把服务跑起来。一次镜像拉取失败暴露了标签命名的变化先讲一个新手几乎都会遇到的翻车现场照着老教程执行docker pull lizardbyte/sunshine:latest结果镜像 404 或行为异常。原因在于v0.18.0 起Sunshine 的镜像标签规则彻底改了——latest、master、vX.X.X这类简单标签不再单独提供。现在正确的写法是版本 操作系统组合格式固定为版本-操作系统组成允许取值作用版本部分latest、master、vX.X.X、commit hash选择稳定版、开发分支或精确快照系统部分debian-bookworm、ubuntu-22.04、ubuntu-24.04决定底层基础系统经验之谈即便版本部分支持latest生产环境也建议锁定到具体版本号。镜像名会随新版滚动变化今天能拉到的最新下个月可能就换了个行为。动手之前30 秒确认这台机器能不能跑容器镜像本身是自包含的Sunshine 运行所需的依赖都已打进镜像宿主机不需要手动装一堆库。你真正要确认的是两件事CPU 架构和显卡设备节点。镜像后缀x86_64 / amd64ARM64 / aarch64debian-bookworm✅✅ubuntu-22.04✅✅ubuntu-24.04✅✅查架构用uname -m查显卡用ls -l /dev/dri——能看到renderD128之类的节点说明 GPU 已暴露给用户态后面用--device挂进容器即可。如果宿主机连/dev/dri都没有也别慌软件编码仍能工作只是延迟和画质会打折扣。5 分钟内跑起来一条 docker run 直达 Web 管理页先给最快的路径用单条docker run把容器跑起来细节之后再拆# --device: 把 GPU 直通给容器硬件编码必需 # --ipchost: 复用宿主机共享内存降低串流延迟 # -e PUID/PGID: 指定容器内进程的用户/组避免权限混乱 # -v /home/yourname/sunshine:/config: 配置落盘升级不丢配置 docker run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --ipchost \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v /home/yourname/sunshine:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:v0.18.0-ubuntu-24.04容器起来后浏览器打开http://宿主机IP:47990看到上图这个页面就说明服务已正常。首次进入要设置登录凭证这个用户名密码请务必记牢——后面配对 Moonlight 客户端、改串流参数都靠它。端口、目录、权限把每个参数拆开看参数实际含义示例值是否必需-p 47990:47990Web 管理界面外部端口可改如8080:4799047990必需-v 目录:/config配置持久化目录/home/yourname/sunshine必需-e PUID容器内进程的用户 ID1000可选-e PGID容器内进程的组 ID1000可选-e TZ时区影响日志时间戳Asia/Shanghai可选这里有个容易看反的坑映射参数是左边宿主机右边容器。比如-p 47990:47990右边必须是 47990Web UI 端口在容器内是写死的左边可以自由改成 8080。官方示例里列举的端口全部必需一个都不能省——47984-47990 TCP 覆盖配对握手、RTSP 会话与 Web 管理47998-48000 UDP 是音视频数据通道48010 按示例原样映射即可。PUID/PGID 解决的是挂载目录的权限问题。在宿主机执行id 用户名查出你的 uid 和 gid把/config目录属主改成同一个再以相同数值启动容器就不会出现容器能写、宿主机读不了的尴尬。想让服务长期稳定跑这三个小调整值得做docker run适合验证长期运行建议固化成 compose 文件services: sunshine: image: lizardbyte/sunshine:v0.18.0-ubuntu-24.04 # 固定版本避免无声更新 container_name: sunshine restart: unless-stopped # 开机自启 崩溃自动拉起 devices: - /dev/dri:/dev/dri volumes: - /home/yourname/sunshine:/config environment: - PUID1000 - PGID1000 - TZAsia/Shanghai ipc: host ports: - 47984-47990:47984-47990/tcp - 48010:48010 - 47998-48000:47998-48000/udp三点提醒一是restart: unless-stopped让容器开机自启并自动拉起省去手动管理二是把镜像标签固定到具体版本升级时确认过新版本号再docker compose pull docker compose up -d三是/config目录定期备份串流配置、配对密钥都在里面丢了等于全部重来。连不上、画面卡顿按这个顺序排查端口先于一切容器内先ss -tlnp | grep 47990确认监听正常再在客户端机器执行nc -vz 宿主机IP 47990验证防火墙放行了 47984-47990 与 47998-48000。GPU 是否真的透传docker exec sunshine ls /dev/dri容器里看不到renderD128就别谈硬件编码回头检查--device参数和宿主机驱动。权限是否一致容器日志出现 Permission denied多半是/config属主和 PUID 对不上改目录属主比改参数快。共享内存省略了--ipchost时小内存容器可能出现画面撕裂补上即可。串流对象在 Web UI 的 Applications 页配置默认已带 Desktop 和 Steam Big Picture 两个应用可以直接编辑启动参数指向容器内装好的游戏。进阶玩法把它当底座叠出自己的串流容器官方镜像的定位其实是基础镜像在它之上叠加 Steam、Wayland 等组件构建一套属于你的完整串流环境。典型写法如下ARG SUNSHINE_VERSIONv0.18.0 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]这套容器里跑完整云游戏机的思路也是 Games on Whales 等开源项目在用的方案。不过它对显卡直通、权限、IPC 的要求高出一截建议先从上面的单容器方案跑通再往这个方向演进。落地节奏从今天开始做的三件事如果你刚接触 Sunshine按这个节奏推进最省事先把/config目录建好并把属主设成你的 uid再用固定版本号的镜像把容器跑起来确认 47990 的 Web 界面能打开设置好登录凭证后把 compose 文件收进 git 仓库作为部署基线。等这套环境稳定运行一周再去折腾叠加 Steam 的进阶玩法。收尾提醒一句每次升级镜像前先备份/config并在测试环境验证新版本——串流服务最怕的不是故障而是升级一时爽回滚火葬场。想进一步研究参数细节可对照容器官方说明 DOCKER_README.md排错清单见 docs/troubleshooting.md。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/19 10:09:39 · 阅读 1.2k Sunshine 用 Docker 容器化部署：从镜像拉取失败到流畅串流，绕开这 5 个坑
Sunshine 用 Docker 容器化部署从镜像拉取失败到流畅串流绕开这 5 个坑【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的游戏串流服务端专门配合 Moonlight 客户端使用支持 AMD、Intel、Nvidia 显卡的硬件编码也保留软件编码兜底。把它装进 Docker 容器升级、迁移、换机器都变成拷贝一份配置文件那么简单这正是容器化部署比裸机安装更受欢迎的原因。这篇指南从一次真实的镜像拉取失败讲起把容器化部署的每个关键环节拆开帮你在半小时内把服务跑起来。一次镜像拉取失败暴露了标签命名的变化先讲一个新手几乎都会遇到的翻车现场照着老教程执行docker pull lizardbyte/sunshine:latest结果镜像 404 或行为异常。原因在于v0.18.0 起Sunshine 的镜像标签规则彻底改了——latest、master、vX.X.X这类简单标签不再单独提供。现在正确的写法是版本 操作系统组合格式固定为版本-操作系统组成允许取值作用版本部分latest、master、vX.X.X、commit hash选择稳定版、开发分支或精确快照系统部分debian-bookworm、ubuntu-22.04、ubuntu-24.04决定底层基础系统经验之谈即便版本部分支持latest生产环境也建议锁定到具体版本号。镜像名会随新版滚动变化今天能拉到的最新下个月可能就换了个行为。动手之前30 秒确认这台机器能不能跑容器镜像本身是自包含的Sunshine 运行所需的依赖都已打进镜像宿主机不需要手动装一堆库。你真正要确认的是两件事CPU 架构和显卡设备节点。镜像后缀x86_64 / amd64ARM64 / aarch64debian-bookworm✅✅ubuntu-22.04✅✅ubuntu-24.04✅✅查架构用uname -m查显卡用ls -l /dev/dri——能看到renderD128之类的节点说明 GPU 已暴露给用户态后面用--device挂进容器即可。如果宿主机连/dev/dri都没有也别慌软件编码仍能工作只是延迟和画质会打折扣。5 分钟内跑起来一条 docker run 直达 Web 管理页先给最快的路径用单条docker run把容器跑起来细节之后再拆# --device: 把 GPU 直通给容器硬件编码必需 # --ipchost: 复用宿主机共享内存降低串流延迟 # -e PUID/PGID: 指定容器内进程的用户/组避免权限混乱 # -v /home/yourname/sunshine:/config: 配置落盘升级不丢配置 docker run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --ipchost \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v /home/yourname/sunshine:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:v0.18.0-ubuntu-24.04容器起来后浏览器打开http://宿主机IP:47990看到上图这个页面就说明服务已正常。首次进入要设置登录凭证这个用户名密码请务必记牢——后面配对 Moonlight 客户端、改串流参数都靠它。端口、目录、权限把每个参数拆开看参数实际含义示例值是否必需-p 47990:47990Web 管理界面外部端口可改如8080:4799047990必需-v 目录:/config配置持久化目录/home/yourname/sunshine必需-e PUID容器内进程的用户 ID1000可选-e PGID容器内进程的组 ID1000可选-e TZ时区影响日志时间戳Asia/Shanghai可选这里有个容易看反的坑映射参数是左边宿主机右边容器。比如-p 47990:47990右边必须是 47990Web UI 端口在容器内是写死的左边可以自由改成 8080。官方示例里列举的端口全部必需一个都不能省——47984-47990 TCP 覆盖配对握手、RTSP 会话与 Web 管理47998-48000 UDP 是音视频数据通道48010 按示例原样映射即可。PUID/PGID 解决的是挂载目录的权限问题。在宿主机执行id 用户名查出你的 uid 和 gid把/config目录属主改成同一个再以相同数值启动容器就不会出现容器能写、宿主机读不了的尴尬。想让服务长期稳定跑这三个小调整值得做docker run适合验证长期运行建议固化成 compose 文件services: sunshine: image: lizardbyte/sunshine:v0.18.0-ubuntu-24.04 # 固定版本避免无声更新 container_name: sunshine restart: unless-stopped # 开机自启 崩溃自动拉起 devices: - /dev/dri:/dev/dri volumes: - /home/yourname/sunshine:/config environment: - PUID1000 - PGID1000 - TZAsia/Shanghai ipc: host ports: - 47984-47990:47984-47990/tcp - 48010:48010 - 47998-48000:47998-48000/udp三点提醒一是restart: unless-stopped让容器开机自启并自动拉起省去手动管理二是把镜像标签固定到具体版本升级时确认过新版本号再docker compose pull docker compose up -d三是/config目录定期备份串流配置、配对密钥都在里面丢了等于全部重来。连不上、画面卡顿按这个顺序排查端口先于一切容器内先ss -tlnp | grep 47990确认监听正常再在客户端机器执行nc -vz 宿主机IP 47990验证防火墙放行了 47984-47990 与 47998-48000。GPU 是否真的透传docker exec sunshine ls /dev/dri容器里看不到renderD128就别谈硬件编码回头检查--device参数和宿主机驱动。权限是否一致容器日志出现 Permission denied多半是/config属主和 PUID 对不上改目录属主比改参数快。共享内存省略了--ipchost时小内存容器可能出现画面撕裂补上即可。串流对象在 Web UI 的 Applications 页配置默认已带 Desktop 和 Steam Big Picture 两个应用可以直接编辑启动参数指向容器内装好的游戏。进阶玩法把它当底座叠出自己的串流容器官方镜像的定位其实是基础镜像在它之上叠加 Steam、Wayland 等组件构建一套属于你的完整串流环境。典型写法如下ARG SUNSHINE_VERSIONv0.18.0 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]这套容器里跑完整云游戏机的思路也是 Games on Whales 等开源项目在用的方案。不过它对显卡直通、权限、IPC 的要求高出一截建议先从上面的单容器方案跑通再往这个方向演进。落地节奏从今天开始做的三件事如果你刚接触 Sunshine按这个节奏推进最省事先把/config目录建好并把属主设成你的 uid再用固定版本号的镜像把容器跑起来确认 47990 的 Web 界面能打开设置好登录凭证后把 compose 文件收进 git 仓库作为部署基线。等这套环境稳定运行一周再去折腾叠加 Steam 的进阶玩法。收尾提醒一句每次升级镜像前先备份/config并在测试环境验证新版本——串流服务最怕的不是故障而是升级一时爽回滚火葬场。想进一步研究参数细节可对照容器官方说明 DOCKER_README.md排错清单见 docs/troubleshooting.md。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考