Sunshine Docker 部署避坑实战三十分钟从零跑通游戏串流服务【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的游戏串流服务端Self-hosted game stream host for Moonlight它把宿主机上的桌面与游戏画面以低延迟串流出去配合任意 Moonlight 客户端即可在手机、平板、电视上畅玩。本文不打算复述官方文档而是聚焦用 Docker 把服务跑起来这条最短路径帮你一次性绕过权限、GPU 直通、端口映射三大拦路虎从零到可用的总时长控制在 30 分钟内。本文你将学会用一张速览表判断你的机器是否具备部署条件通过 docker compose推荐与 docker run 两条路径跑通服务读懂端口、目录、PUID/PGID 等关键配置避免改错完成首次登录、Moonlight 配对与硬件编码验证应对 5 个最高频的翻车现场为什么我不直接装安装包而要绕一圈 Docker先别急着动手花一分钟确认你为什么选 Docker 路线——这决定了后面的每一步怎么走。Sunshine 官方文档其实明确提示Docker 镜像不推荐给大多数用户目前定位偏向实验性与基础镜像。换句话说如果你的机器是日常使用的图形化桌面直接装发行版安装包反而省事但如果你遇到下面三种情况Docker 就是最划算的选择无头服务器主机只有命令行没有显示器Docker 能一次把运行时依赖打包到位不用手动解决 libavcodec、CUDA 等依赖地狱。环境隔离想让串流服务与主系统互不污染升级、回滚只需替换镜像标签配置目录独立挂载。容器化集成想把 Sunshine 作为某个更大项目如 Games on Whales 这类云端游戏平台的组件官方镜像本身就是按基础镜像设计的。部署前三分钟自检清单 ✔以下条件用勾选列表过一遍全部满足再进入部署环节。宿主机是LinuxDebian / Ubuntu / Arch 等内核版本 ≥ 4.15Windows/macOS 宿主机暂不支持官方镜像已安装Docker Engine ≥ 20.10或Podman ≥ 4.0并确认docker info能正常返回GPU 驱动已装好NVIDIA 装好驱动即可AMD / Intel 核显确认存在/dev/dri/renderD128设备节点无 GPU 也能跑Sunshine 提供软件编码兜底只是延迟与画质会打折网络可达宿主机能访问外网拉取镜像且局域网内客户端与宿主机互通端口空闲47984-47990/tcp、48010/tcp、47998-48000/udp未被占用检查命令见踩坑锦囊第 1 条一张图看懂整体方案串流数据的流向决定了你要开哪些口子、挂哪些目录。记住下面这张链路图后面所有配置都是围绕它展开的┌─────────────────────┐ │ Moonlight 客户端 │ 手机 / 平板 / 电视 / 另一台电脑 └──────────┬──────────┘ │ TCP 47984-47990 / 48010控制、配对、Web UI │ UDP 47998-48000视频 / 音频 / 输入流 ┌──────────▼──────────┐ │ Sunshine 容器 │ lizardbyte/sunshine:latest-ubuntu-24.04 │ · /config ← 配置持久化 │ · /dev/dri ← GPU 直通硬件编码 └──────────┬──────────┘ │ 采集桌面 / 编码 ┌──────────▼──────────┐ │ 宿主机桌面与游戏 │ └─────────────────────┘部署中三条路径总有一条适合你下面三条路径都能跑通推荐度从高到低排列。推荐你优先使用路径一因为 compose 文件可以提交进 Git 版本管理换机器时一条docker compose up -d就能恢复整套环境。路径一推荐docker compose 最小可行示例先建一个项目目录并写入 compose 文件mkdir -p ~/sunshine cd ~/sunshine创建docker-compose.yml这是可直接复制跑通的最小可行示例services: sunshine: image: lizardbyte/sunshine:latest-ubuntu-24.04 container_name: sunshine restart: unless-stopped # 异常退出自动拉起 devices: - /dev/dri:/dev/dri # GPU 直通硬件编码的前提 volumes: - ./sunshine-config:/config # 配置持久化到宿主机 environment: - PUID1000 # 与宿主机当前用户 uid 保持一致 - PGID1000 # 与宿主机当前用户 gid 保持一致 - TZAsia/Shanghai # 时区影响日志时间 ipc: host # 共享宿主机内存降低串流延迟 ports: - 47984-47990:47984-47990/tcp - 48010:48010 - 47998-48000:47998-48000/udp然后启动并确认状态docker compose up -d docker compose ps # 看到 STATUS 为 Up 即成功 docker compose logs -f # 跟踪启动日志出现 Web UI 监听 47990 即就绪 提示如果宿主机没有/dev/dri设备无独显且无核显把devices段删掉即可Sunshine 会自动退回软件编码。路径二docker run 单条命令快速验证不想引入 compose 文件一条命令跑起来适合临时验证docker run -d \ --device /dev/dri/ \ # GPU 直通 --namesunshine \ --restartunless-stopped \ --ipchost \ # 共享内存 -e PUID1000 \ # 与 id 命令查到的 uid 对齐 -e PGID1000 \ -e TZAsia/Shanghai \ -v ~/sunshine/sunshine-config:/config \ # 配置目录 -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:latest-ubuntu-24.04路径三Podman 无守护进程方案受限于 root 权限、或不想常驻 Docker 守护进程时用 Podman 替代核心区别是把--ipchost换成--usernskeep-id让容器内用户 ID 自动对齐宿主机天然规避一部分权限问题podman run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --usernskeep-id \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v ~/sunshine/sunshine-config:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ docker.io/lizardbyte/sunshine:latest-ubuntu-24.04三条路径怎么选一张决策表你的情况推荐路径理由长期运行、配置想纳入版本管理路径一 docker compose配置声明式、可复现重启自动恢复快速验证、不想装 compose 插件路径二 docker run一条命令改参数即重启无 root、或不想常驻守护进程路径三 podman用户态运行userns 隔离更干净已有容器化平台如 Games on Whales以官方镜像为基础镜像叠加镜像本身按基础镜像设计关键配置解读四个必须搞懂的开关1. 镜像标签版本-操作系统组合规则这是最容易踩的第一个坑自 v0.18.0 起官方不再提供latest、master、vX.X.X这类裸标签必须组合成版本-操作系统的格式也可以直接用 commit hash 锁定某次提交。版本部分操作系统部分完整标签示例latest最新稳定版ubuntu-24.04latest-ubuntu-24.04master开发分支ubuntu-22.04master-ubuntu-22.04v0.18.0具体版本debian-bookwormv0.18.0-debian-bookworm某次 commit hashubuntu-24.04hash-ubuntu-24.04 提示镜像拉取时 Docker 会自动按宿主机 CPU 架构选择对应镜像无需手动指定平台。各操作系统后缀的架构支持见下表操作系统后缀amd64 / x86_64arm64 / aarch64debian-bookworm✅✅ubuntu-22.04✅✅ubuntu-24.04✅✅2. 端口映射哪些能改哪些别动端口协议作用示例值是否必填47990TCPWeb 管理界面可改为8080:47990是47984-47989TCPRTSP 控制与配对建议保持默认是48010TCP辅助控制通道建议保持默认是47998-48000UDP视频/音频/输入数据流建议保持默认是⚠️ 注意只有 47990 这个外部端口可以自由改例如-p 8080:47990其余端口改动可能造成客户端配对失败除非你清楚自己在做什么。3. 目录挂载与权限PUID / PGID / TZ容器内配置文件固定写入/config实际是用户目录下.config/sunshine的软链必须挂载到宿主机持久化否则容器重建即丢配置。环境变量作用示例值是否必填PUID容器内用户 ID1000推荐PGID容器内组 ID1000推荐TZ时区影响日志时间Asia/Shanghai可选UNAME容器内用户名lizard默认不建议改PUID/PGID 的正确取值来自你宿主机上要代表容器写文件的用户用id查询id # 输出形如 uid1000(yourname) gid1000(yourgroup)把数字填进环境变量4. 进阶以官方镜像为基础定制官方镜像的设计初衷是作为基础镜像叠加自己的运行时。例如加装 Steam 与 Wayland 组件后启动ARG SUNSHINE_VERSIONlatest ARG SUNSHINE_OSubuntu-22.04 FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS} RUN apt-get update apt-get install -y \ steam \ wayland-protocols \ weston ENTRYPOINT [bash, -c, steam sunshine] 进阶如果你需要改造源码再构建可克隆仓库后参考docker/目录下的构建脚本git clone https://gitcode.com/GitHub_Trending/su/Sunshine cd Sunshine # 查看各发行版 dockerfile 与构建脚本 docker/ 与 scripts/linux_build.sh部署后三步完成首次可用服务起来不等于能用按顺序做完这三步才算真正跑通。第 1 步设置 Web UI 账号浏览器访问http://宿主机IP:47990若改过端口用你的映射首次进入会要求设置用户名与密码这组凭证用来登录管理界面妥善保存。第 2 步添加应用并配对 Moonlight在 Web UI 的 Applications 页添加要串流的程序桌面、Steam 大屏模式等然后打开任意设备的 Moonlight 客户端让它扫描局域网内的 Sunshine 主机并输入 PIN 完成配对。配对过程在 Web UI 的 PIN 页面实时显示。第 3 步验证硬件编码是否生效进入 Configuration 页面检查编码器设置Video 相关配置项确认当前选择的是 NVENC / AMF / VAAPI 等硬件编码器而非软件编码。 进阶AMD 与 Intel 用户建议在配置页确认 启用硬件编码 开关并核对/dev/dri是否直通成功容器内执行ls /dev/dri应能看到renderD128。踩坑锦囊五个高频翻车现场① 端口冲突容器起不来报 bind address already in use原因宿主机已有进程占用 47990 等端口。 修复ss -tlnp | grep -E 47990|48010 # 定位占用进程 # 若确认是其他服务占用改用外部映射-p 8080:47990② 权限问题容器写不进配置目录原因宿主机挂载目录属主与容器内 PUID/PGID 不一致。 修复sudo chown -R 1000:1000 ~/sunshine/sunshine-config # 或把 compose 里的 PUID/PGID 改成挂载目录当前属主的 uid/gid③ GPU 没直通编码全程走 CPU原因/dev/dri未挂载或宿主驱动缺失。 修复ls -l /dev/dri/ # 必须能看到 renderD128 节点 # 确认后重启容器并加上 --device /dev/dri/ 或 compose 的 devices 段④ 日志时间差 8 小时原因镜像默认时区为 UTC未设置 TZ。 修复# 添加环境变量后重建容器 docker compose up -d --force-recreate --env TZAsia/Shanghai⑤ 客户端找不到主机或连不上原因宿主机防火墙未放行串流端口。 修复以 ufw 为例sudo ufw allow 47984:47990/tcp sudo ufw allow 48010/tcp sudo ufw allow 47998:48000/udp收尾下一步往哪走跑通之后你的进阶路线大致是先读配置手册把编码参数、码率、分辨率和客户端行为调顺再看性能调优指南压榨出更低的延迟遇到疑难问题按排查文档逐项定位。如果容器方案在生产中暴露了性能或稳定性的短板记得官方推荐的默认路径其实是裸机安装——容器化是手段不是目的。相关资源入门与安装总览docs/getting_started.md容器参数与端口详解DOCKER_README.md完整配置项手册docs/configuration.md常见问题排查docs/troubleshooting.md性能调优建议docs/performance_tuning.md镜像构建脚本与 dockerfiledocker/核心源码目录src/【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sunshine Docker 部署避坑实战：三十分钟从零跑通游戏串流服务
Sunshine Docker 部署避坑实战三十分钟从零跑通游戏串流服务【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一款自托管的游戏串流服务端Self-hosted game stream host for Moonlight它把宿主机上的桌面与游戏画面以低延迟串流出去配合任意 Moonlight 客户端即可在手机、平板、电视上畅玩。本文不打算复述官方文档而是聚焦用 Docker 把服务跑起来这条最短路径帮你一次性绕过权限、GPU 直通、端口映射三大拦路虎从零到可用的总时长控制在 30 分钟内。本文你将学会用一张速览表判断你的机器是否具备部署条件通过 docker compose推荐与 docker run 两条路径跑通服务读懂端口、目录、PUID/PGID 等关键配置避免改错完成首次登录、Moonlight 配对与硬件编码验证应对 5 个最高频的翻车现场为什么我不直接装安装包而要绕一圈 Docker先别急着动手花一分钟确认你为什么选 Docker 路线——这决定了后面的每一步怎么走。Sunshine 官方文档其实明确提示Docker 镜像不推荐给大多数用户目前定位偏向实验性与基础镜像。换句话说如果你的机器是日常使用的图形化桌面直接装发行版安装包反而省事但如果你遇到下面三种情况Docker 就是最划算的选择无头服务器主机只有命令行没有显示器Docker 能一次把运行时依赖打包到位不用手动解决 libavcodec、CUDA 等依赖地狱。环境隔离想让串流服务与主系统互不污染升级、回滚只需替换镜像标签配置目录独立挂载。容器化集成想把 Sunshine 作为某个更大项目如 Games on Whales 这类云端游戏平台的组件官方镜像本身就是按基础镜像设计的。部署前三分钟自检清单 ✔以下条件用勾选列表过一遍全部满足再进入部署环节。宿主机是LinuxDebian / Ubuntu / Arch 等内核版本 ≥ 4.15Windows/macOS 宿主机暂不支持官方镜像已安装Docker Engine ≥ 20.10或Podman ≥ 4.0并确认docker info能正常返回GPU 驱动已装好NVIDIA 装好驱动即可AMD / Intel 核显确认存在/dev/dri/renderD128设备节点无 GPU 也能跑Sunshine 提供软件编码兜底只是延迟与画质会打折网络可达宿主机能访问外网拉取镜像且局域网内客户端与宿主机互通端口空闲47984-47990/tcp、48010/tcp、47998-48000/udp未被占用检查命令见踩坑锦囊第 1 条一张图看懂整体方案串流数据的流向决定了你要开哪些口子、挂哪些目录。记住下面这张链路图后面所有配置都是围绕它展开的┌─────────────────────┐ │ Moonlight 客户端 │ 手机 / 平板 / 电视 / 另一台电脑 └──────────┬──────────┘ │ TCP 47984-47990 / 48010控制、配对、Web UI │ UDP 47998-48000视频 / 音频 / 输入流 ┌──────────▼──────────┐ │ Sunshine 容器 │ lizardbyte/sunshine:latest-ubuntu-24.04 │ · /config ← 配置持久化 │ · /dev/dri ← GPU 直通硬件编码 └──────────┬──────────┘ │ 采集桌面 / 编码 ┌──────────▼──────────┐ │ 宿主机桌面与游戏 │ └─────────────────────┘部署中三条路径总有一条适合你下面三条路径都能跑通推荐度从高到低排列。推荐你优先使用路径一因为 compose 文件可以提交进 Git 版本管理换机器时一条docker compose up -d就能恢复整套环境。路径一推荐docker compose 最小可行示例先建一个项目目录并写入 compose 文件mkdir -p ~/sunshine cd ~/sunshine创建docker-compose.yml这是可直接复制跑通的最小可行示例services: sunshine: image: lizardbyte/sunshine:latest-ubuntu-24.04 container_name: sunshine restart: unless-stopped # 异常退出自动拉起 devices: - /dev/dri:/dev/dri # GPU 直通硬件编码的前提 volumes: - ./sunshine-config:/config # 配置持久化到宿主机 environment: - PUID1000 # 与宿主机当前用户 uid 保持一致 - PGID1000 # 与宿主机当前用户 gid 保持一致 - TZAsia/Shanghai # 时区影响日志时间 ipc: host # 共享宿主机内存降低串流延迟 ports: - 47984-47990:47984-47990/tcp - 48010:48010 - 47998-48000:47998-48000/udp然后启动并确认状态docker compose up -d docker compose ps # 看到 STATUS 为 Up 即成功 docker compose logs -f # 跟踪启动日志出现 Web UI 监听 47990 即就绪 提示如果宿主机没有/dev/dri设备无独显且无核显把devices段删掉即可Sunshine 会自动退回软件编码。路径二docker run 单条命令快速验证不想引入 compose 文件一条命令跑起来适合临时验证docker run -d \ --device /dev/dri/ \ # GPU 直通 --namesunshine \ --restartunless-stopped \ --ipchost \ # 共享内存 -e PUID1000 \ # 与 id 命令查到的 uid 对齐 -e PGID1000 \ -e TZAsia/Shanghai \ -v ~/sunshine/sunshine-config:/config \ # 配置目录 -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ lizardbyte/sunshine:latest-ubuntu-24.04路径三Podman 无守护进程方案受限于 root 权限、或不想常驻 Docker 守护进程时用 Podman 替代核心区别是把--ipchost换成--usernskeep-id让容器内用户 ID 自动对齐宿主机天然规避一部分权限问题podman run -d \ --device /dev/dri/ \ --namesunshine \ --restartunless-stopped \ --usernskeep-id \ -e PUID1000 \ -e PGID1000 \ -e TZAsia/Shanghai \ -v ~/sunshine/sunshine-config:/config \ -p 47984-47990:47984-47990/tcp \ -p 48010:48010 \ -p 47998-48000:47998-48000/udp \ docker.io/lizardbyte/sunshine:latest-ubuntu-24.04三条路径怎么选一张决策表你的情况推荐路径理由长期运行、配置想纳入版本管理路径一 docker compose配置声明式、可复现重启自动恢复快速验证、不想装 compose 插件路径二 docker run一条命令改参数即重启无 root、或不想常驻守护进程路径三 podman用户态运行userns 隔离更干净已有容器化平台如 Games on Whales以官方镜像为基础镜像叠加镜像本身按基础镜像设计关键配置解读四个必须搞懂的开关1. 镜像标签版本-操作系统组合规则这是最容易踩的第一个坑自 v0.18.0 起官方不再提供latest、master、vX.X.X这类裸标签必须组合成版本-操作系统的格式也可以直接用 commit hash 锁定某次提交。版本部分操作系统部分完整标签示例latest最新稳定版ubuntu-24.04latest-ubuntu-24.04master开发分支ubuntu-22.04master-ubuntu-22.04v0.18.0具体版本debian-bookwormv0.18.0-debian-bookworm某次 commit hashubuntu-24.04hash-ubuntu-24.04 提示镜像拉取时 Docker 会自动按宿主机 CPU 架构选择对应镜像无需手动指定平台。各操作系统后缀的架构支持见下表操作系统后缀amd64 / x86_64arm64 / aarch64debian-bookworm✅✅ubuntu-22.04✅✅ubuntu-24.04✅✅2. 端口映射哪些能改哪些别动端口协议作用示例值是否必填47990TCPWeb 管理界面可改为8080:47990是47984-47989TCPRTSP 控制与配对建议保持默认是48010TCP辅助控制通道建议保持默认是47998-48000UDP视频/音频/输入数据流建议保持默认是⚠️ 注意只有 47990 这个外部端口可以自由改例如-p 8080:47990其余端口改动可能造成客户端配对失败除非你清楚自己在做什么。3. 目录挂载与权限PUID / PGID / TZ容器内配置文件固定写入/config实际是用户目录下.config/sunshine的软链必须挂载到宿主机持久化否则容器重建即丢配置。环境变量作用示例值是否必填PUID容器内用户 ID1000推荐PGID容器内组 ID1000推荐TZ时区影响日志时间Asia/Shanghai可选UNAME容器内用户名lizard默认不建议改PUID/PGID 的正确取值来自你宿主机上要代表容器写文件的用户用id查询id # 输出形如 uid1000(yourname) gid1000(yourgroup)把数字填进环境变量4. 进阶以官方镜像为基础定制官方镜像的设计初衷是作为基础镜像叠加自己的运行时。例如加装 Steam 与 Wayland 组件后启动ARG SUNSHINE_VERSIONlatest ARG SUNSHINE_OSubuntu-22.04 FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS} RUN apt-get update apt-get install -y \ steam \ wayland-protocols \ weston ENTRYPOINT [bash, -c, steam sunshine] 进阶如果你需要改造源码再构建可克隆仓库后参考docker/目录下的构建脚本git clone https://gitcode.com/GitHub_Trending/su/Sunshine cd Sunshine # 查看各发行版 dockerfile 与构建脚本 docker/ 与 scripts/linux_build.sh部署后三步完成首次可用服务起来不等于能用按顺序做完这三步才算真正跑通。第 1 步设置 Web UI 账号浏览器访问http://宿主机IP:47990若改过端口用你的映射首次进入会要求设置用户名与密码这组凭证用来登录管理界面妥善保存。第 2 步添加应用并配对 Moonlight在 Web UI 的 Applications 页添加要串流的程序桌面、Steam 大屏模式等然后打开任意设备的 Moonlight 客户端让它扫描局域网内的 Sunshine 主机并输入 PIN 完成配对。配对过程在 Web UI 的 PIN 页面实时显示。第 3 步验证硬件编码是否生效进入 Configuration 页面检查编码器设置Video 相关配置项确认当前选择的是 NVENC / AMF / VAAPI 等硬件编码器而非软件编码。 进阶AMD 与 Intel 用户建议在配置页确认 启用硬件编码 开关并核对/dev/dri是否直通成功容器内执行ls /dev/dri应能看到renderD128。踩坑锦囊五个高频翻车现场① 端口冲突容器起不来报 bind address already in use原因宿主机已有进程占用 47990 等端口。 修复ss -tlnp | grep -E 47990|48010 # 定位占用进程 # 若确认是其他服务占用改用外部映射-p 8080:47990② 权限问题容器写不进配置目录原因宿主机挂载目录属主与容器内 PUID/PGID 不一致。 修复sudo chown -R 1000:1000 ~/sunshine/sunshine-config # 或把 compose 里的 PUID/PGID 改成挂载目录当前属主的 uid/gid③ GPU 没直通编码全程走 CPU原因/dev/dri未挂载或宿主驱动缺失。 修复ls -l /dev/dri/ # 必须能看到 renderD128 节点 # 确认后重启容器并加上 --device /dev/dri/ 或 compose 的 devices 段④ 日志时间差 8 小时原因镜像默认时区为 UTC未设置 TZ。 修复# 添加环境变量后重建容器 docker compose up -d --force-recreate --env TZAsia/Shanghai⑤ 客户端找不到主机或连不上原因宿主机防火墙未放行串流端口。 修复以 ufw 为例sudo ufw allow 47984:47990/tcp sudo ufw allow 48010/tcp sudo ufw allow 47998:48000/udp收尾下一步往哪走跑通之后你的进阶路线大致是先读配置手册把编码参数、码率、分辨率和客户端行为调顺再看性能调优指南压榨出更低的延迟遇到疑难问题按排查文档逐项定位。如果容器方案在生产中暴露了性能或稳定性的短板记得官方推荐的默认路径其实是裸机安装——容器化是手段不是目的。相关资源入门与安装总览docs/getting_started.md容器参数与端口详解DOCKER_README.md完整配置项手册docs/configuration.md常见问题排查docs/troubleshooting.md性能调优建议docs/performance_tuning.md镜像构建脚本与 dockerfiledocker/核心源码目录src/【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考