将 Steam 部署到 NAS 中运行游戏——完整教程

gleecalm · 发表于 2026-7-9 18:57:34

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要登录才可以下载或查看，没有账号？立即注册

×

本帖最后由 KsGoWL 于 2026-7-10 23:24 编辑

将 Steam 部署到 NAS 中运行游戏——完整教程

适用环境

本教程在以下环境验证通过：
[td]

项目	配置
NAS 型号	DXP4800PLUS
CPU	Intel(R) Pentium(R) Gold 8505
GPU	Intel® UHD Graphics for 12th Gen Intel® Processors
系统	Linux 6.12.30+ x86_64
Docker	29.4.3 (overlay2)
容器镜像	josh5/steam-headless:latest

如果你的 NAS 是 x86_64 架构、有 Intel 核显，均可参考本教程。无核显或使用 NVIDIA GPU 需调整部分配置。

第一步：SSH 登录 NAS

在你自己电脑上打开终端，连接到 NAS：
ssh [email protected] -p 22 输入密码后进入 NAS 的命令行。

注意：如果你的 NAS 用户名、IP、端口不同，请替换为实际值。本教程所有命令均在 NAS 上执行。

第二步：确认硬件环境

2.1 确认 CPU 架构（必须是 x86_64）
uname -m输出应当为 x86_64。如果输出 aarch64 或其他，表示是 ARM 架构 NAS，本教程不适用。

2.2 确认 Docker 已安装
docker version输出类似：
Client: Docker Engine - Community Version: 29.4.3 Server: Docker Engine - Community Version: 29.4.3如果提示 command not found，先安装 Docker：
# 使用群晖套件中心安装 Docker 即可# 或使用一键脚本：curl -fsSL https://get.docker.com | sh

2.3 确认 GPU 设备存在
ls /dev/dri/输出应当包含 card0 和 renderD128（或类似名称）：
card0 renderD128如果没有 /dev/dri 目录，说明 NAS 没有开启核显直通或者没有核显。

2.4 确认 video 和 render 组的 GID
# 查看 video 组 IDgetent group video | cut -d: -f3# 查看 render 组 ID getent group render | cut -d: -f3记下这两个数字，后面会用到。常见值为 video=44、render=109。

第三步：创建项目目录

<font color="#ffa500"># 项目主目录
mkdir -p /volume1/docker/steam-headless
# 补丁存放目录
mkdir -p /volume1/docker/steam-headless/patches
# Steam数据持久化目录
mkdir -p /volume1/docker/steam-headless/steam-data
# XFCE桌面配置目录
mkdir -p /volume1/docker/steam-headless/xfce-config
# 游戏安装库目录
mkdir -p /volume2/SteamGames
# 进入工作目录
cd /volume1/docker/steam-headless</font>

复制代码

提示：游戏库目录 /volume2/SteamGames 可以根据你的实际存储池路径修改。如果只有一个存储池，可以改为 /volume1/SteamGames。

第四步：创建 docker-compose.yaml
打开 docker ：选择项目点击创建
项目名称 steam-headless
存放路径：自动在docker目录下创建对应项目目录
将以下内容完整粘贴进去（注意：`group_add` 里的 `44` 和 `109` 改为你第二步查到的值）

<div class="blockcode"><blockquote>version: "3.8"
services:
steam-headless:
image: josh5/steam-headless:latest
container_name: steam-headless
restart: unless-stopped
ipc: host
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
shm_size: "2gb"
deploy:
resources:
limits:
memory: 6G
cpus: "3.5"
group_add:
- "44"
- "109"
environment:
- PUID=1000
- PGID=10
- USER_ID=100
- GROUP_ID=10
- TZ=Asia/Shanghai
- RESOLUTION=1280x720
- ENV_DISPLAY=:55
- ENV_XDG_RUNTIME_DIR=/tmp/.X11-unix/run
- LIBVA_DRIVER_NAME=iHD
- AUTOSTART_STEAM=true
- STEAM_ARGS=-bigpicture
- SUNSHINE_USER=admin
- SUNSHINE_PASS=123456
- WEB_PORT=8083
- VD_GPU=intel
- DISABLE_FLATPAK=1
- LANG=zh_CN.UTF-8
- LANGUAGE=zh_CN:zh
devices:
- /dev/dri/card0:/dev/dri/card0
- /dev/dri/renderD128:/dev/dri/renderD128
ports:
- "8088:8083"
- "47989:47989/tcp"
- "47989:47989/udp"
- "47991:47991"
- "48010:48010/tcp"
- "47984:47984/tcp"
- "47998:47998/udp"
- "47999:47999/udp"
- "48000:48000/udp"
volumes:
- ./steam-data:/home/default/.steam
- ./xfce-config:/home/default/.config
- /volume2/SteamGames:/mnt/games
- ./patches/start-xorg.sh:/usr/bin/start-xorg.sh
- ./patches/start-x11vnc.sh:/usr/bin/start-x11vnc.sh

复制代码

按 Ctrl+O 保存，Ctrl+X 退出。
关键改动：相较于原镜像脚本，新增了 -extension MIT-SHM 这一行。这是整个部署中最关键的修复——禁用 MIT-SHM 扩展后，Mesa 驱动不会尝试通过共享内存附着 X11 显示，从而避免了 MESA: error: Failed to attach to x11 shm 导致 Xorg 崩溃的问题。

第六步：创建 patches 子目录，并放入以下三个sh脚本
6.1 start-xorg.sh 粘贴以下内容：

<div class="blockcode"><blockquote>#!/usr/bin/env bash
set -e
source /usr/bin/common-functions.sh
_term() {
kill -TERM "$xorg_pid" 2>/dev/null
}
trap _term SIGTERM SIGINT
if [ $(grep autostart /etc/supervisor.d/udev.ini 2> /dev/null) == "autostart=true" ]; then
wait_for_udev
fi
/usr/bin/Xorg \
-ac \
-noreset \
-novtswitch \
-sharevts \
+extension RANDR \
+extension RENDER \
+extension GLX \
+extension XVideo \
+extension DOUBLE-BUFFER \
+extension SECURITY \
+extension DAMAGE \
+extension X-Resource \
+extension MIT-SHM \
-extension XINERAMA -xinerama \
+extension Composite +extension COMPOSITE \
-dpms \
-s off \
-nolisten tcp \
-iglx \
-verbose \
vt7 "${DISPLAY:?}" &
xorg_pid=$!
wait "$xorg_pid"

复制代码

6.2 start-x11vnc.sh

<div class="blockcode"><blockquote>#!/usr/bin/env bash
set -e
source /usr/bin/common-functions.sh
_term() {
kill -TERM "$x11vnc_pid" 2>/dev/null
kill -TERM "$sunshine_web_pid" 2>/dev/null
}
trap _term SIGTERM SIGINT
wait_for_x
# Start Sunshine Web UI
nohup python3 /usr/bin/sunshine-proxy.py &>/tmp/sunshine-proxy.log &
sunshine_web_pid=$!
/usr/bin/x11vnc -display ${DISPLAY} -rfbport ${PORT_VNC} -shared -forever &
x11vnc_pid=$!
wait "$x11vnc_pid"

复制代码

6.3 start-sunshine-web.sh

<div class="blockcode"><blockquote>#!/usr/bin/env bash
echo "[sunshine-web] Starting web UI"
cd /usr/share/sunshine/web && nohup python3 -m http.server 47991 --bind 0.0.0.0 &>/tmp/sunshine-web.log &
echo "PID: $!"

复制代码

使用步骤：
在 /docker/steam-headless/ 目录下创建 patches 子目录
将上述三个脚本放入 patches/

第七步：赋予脚本执行权限

chmod +x patches/start-xorg.sh patches/start-x11vnc.sh patches/start-sunshine-web.sh

复制代码

第八步：修复换行符（极其重要）

如果你是从 Windows 电脑复制粘贴上面的脚本内容，文件末尾会带有 Windows 风格的 CRLF 换行符（\r\n），而 Linux 只认 LF（\n）。如果忽略这一步，容器启动时 xorg 和 x11vnc 会直接 FATAL。
sed -i 's/\r//g' patches/start-xorg.sh patches/start-x11vnc.sh docker-compose.yaml验证换行符已修复：
head -1 patches/start-xorg.sh | cat -A正确输出应为 #!/usr/bin/env bash$（行尾是 $）。
错误输出是 #!/usr/bin/env bash^M$（行尾有 ^M），表示 CRLF 未修复，需重新执行 sed。

第九步：拉取镜像并启动

docker compose -f /volume1/docker/steam-headless/docker-compose.yaml up -d

复制代码

首次执行会从 Docker Hub 下载 josh5/steam-headless:latest 镜像（约 1.5 GB），请耐心等待。

第十步：等待初始化完成

容器启动后，系统会自动执行一系列初始化脚本。此时立即访问 Web UI 会无法打开，需要等待所有初始化完成。
10.1 实时查看初始化日志
docker logs -f steam-headless你会看到类似输出：
[ /etc/cont-init.d/60-configure_gpu_driver.sh: executing... ]**** Found Intel device 'Intel Corporation Alder Lake-UP3 GT1 [UHD Graphics] (rev 0c)' ****  - Enable i386 arch  - Install mesa vulkan drivers这一步会自动安装 Intel GPU 对应的 Mesa/Vulkan 驱动包，取决于网络速度，可能需要 3-10 分钟。
按 Ctrl+C 退出日志查看（不会停止容器）。

10.2 检查初始化是否完成
docker exec steam-headless ps aux | grep -v grep | head -5如果在进程列表中看到 supervisord，说明初始化已完成：
root  1  bash /entrypoint.shroot  X  /usr/bin/python3 /usr/bin/supervisord ...如果只看到 apt-get 或 apt-get install 相关的进程，说明仍在安装 GPU 驱动，继续等待。

10.3 查看所有服务状态
docker exec steam-headless supervisorctl status所有服务应为 RUNNING 状态：
accounts-daemon                RUNNINGaudiostream                   RUNNINGdbus                            RUNNINGdesktop                         RUNNINGfrontend                      RUNNINGpolkit                         RUNNINGpulseaudio                      RUNNINGsunshine                      RUNNINGudev                            RUNNINGx11vnc                         RUNNINGxorg                            RUNNING重中之重：xorg 和 x11vnc 必须是 RUNNING，如果是 FATAL，说明换行符没修复或 patche 脚本有误，回到第八步检查。

第十一步：访问 Steam
在你自己电脑的浏览器中打开：
http://192.168.1.207:8088

Steam-headless主页

你会看到一个 XFCE 桌面环境，Steam 会自动以 Big Picture 大屏模式启动。
第一次使用需要登录你的 Steam 账号。

Steam登录框

如果需要切换 Steam 为中文界面：
docker exec steam-headless sed -i 's/"english"/"schinese"/g' /home/default/.steam/registry.vdfdocker exec steam-headless supervisorctl restart steam

第十二步：安装并运行游戏

12.1 通过 Steam 客户端安装
在 Web UI 中操作 Steam，进入"库"，选择你想安装的游戏，安装路径选 /mnt/games（即你 NAS 上的 /volume2/SteamGames），这样游戏文件保存在宿主机上，不会因容器重建而丢失。

Steam主页

12.2 使用 Moonlight 串流玩游戏
如果浏览器操作不够流畅，可以使用 Moonlight 客户端串流：

Moonlight 客户端设置官网：https://moonlight-stream.org
主机地址：192.168.1.207:47990
PIN 码配对：首次连接时需要
浏览器打开 http://192.168.1.207:47991/
用户名：admin（即 SUNSHINE_USER）
密码：123456（即 SUNSHINE_PASS）
在 Sunshine 面板中点击 "PIN" 输入 Moonlight 显示的 4 位 PIN
连接后即可流畅串流，延迟比浏览器 Web VNC 低很多。

第十三步部署完整性校验（带结果解读 + 排错方案）

1. 校验 Xorg 是否加载禁用 MIT-SHM 参数（核心修复验证）

docker exec steam-headless ps aux | grep Xorg | grep "MIT-SHM"

复制代码

正常输出：会打印完整 Xorg 启动命令，包含 -extension MIT-SHM
无输出 = 补丁未生效：
- 检查脚本是否赋权 chmod +x patches/*.sh
- 重启容器 docker compose restart
- 确认 compose 内 volumes 挂载路径无误

2. 校验 Web 管理端口 8083 监听状态

docker exec steam-headless ss -tlnp | grep 8083

复制代码

Steam-Headless 常见问题汇总（整理优化，清晰可存）
Q1：登录 Steam 后立刻闪退
根因
Docker 默认 seccomp 安全策略拦截 bwrap 所需pivot_root系统调用。

修复
确认 compose 配置存在该行：

security_opt: - seccomp=unconfined

复制代码

修改后执行重建容器命令。

Q2：访问 8088 网页提示连接被拒绝
根因
容器刚启动，GPU、Xorg、Sunshine 还在初始化。
处理

等待 3～10 分钟自动初始化完成
实时看日志定位卡住环节：

docker logs -f steam-headless

复制代码

Q3：游戏卡顿、帧率低、延迟高
排查方案

分辨率过高：环境变量RESOLUTION=1280x720，不建议 1080P 以上
资源限制不足：mem_limit: 8g、cpus:4、shm_size:4gb
CPU 性能瓶颈：N100 这类低功耗 NAS 仅适合 2D / 轻量化老 3D 游戏
串流方案替换：放弃内置 VNC，使用 Moonlight 客户端连接 Sunshine 硬解串流，延迟更低

Q4：NAS 重启后容器不会自动启动
两层排查

compose 配置必须包含：

restart: unless-stopped

复制代码

2. Docker 服务设置开机自启（Linux NAS）

sudo systemctl enable docker

复制代码

Q5：容器内 /mnt/games 游戏目录不存在
修复步骤

# 检查宿主机游戏目录
ls /volume2/SteamGames
# 不存在则创建
mkdir -p /volume2/SteamGames
# 重建容器挂载生效
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml up -d --force-recreate

复制代码

补充高频报错（新增你部署会遇到的）
Q6 日志出现 MESA: Failed to attach to x11 shm、Xorg 反复崩溃
根因：未打 MIT-SHM 补丁
解决：确认 patches 脚本挂载、赋权、清除 CRLF 换行，重启容器。

Q7 Sunshine 串流黑屏无画面

确认devices正确透传/dev/dri/card0、renderD128
VD_GPU=intel环境变量匹配核显型号
shm_size 调至 4gb

Steam-Headless 日常维护命令（整理优化版，分类清晰）
一、容器整体启停更新

# 后台启动容器
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml up -d
# 重启容器（不重建，快速重启）
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml restart
# 停止并销毁容器（卷数据保留）
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml down
# 更新镜像+重建容器
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml pull
docker compose -f /volume1/docker/steam-headless/docker-compose.yaml up -d --force-recreate

复制代码

二、日志排查

# 实时滚动日志
docker logs -f steam-headless
# 仅查看末尾50行日志
docker logs --tail 50 steam-headless
# 过滤Xorg报错（排查shm崩溃）
docker logs steam-headless | grep -i xorg
# 过滤Sunshine串流日志
docker logs steam-headless | grep -i sunshine

复制代码

三、进入容器 & 内部服务管理

# 交互式进入容器终端
docker exec -it steam-headless bash
# 容器内单独重启服务（不用重启整个容器）
docker exec steam-headless supervisorctl restart xorg
docker exec steam-headless supervisorctl restart x11vnc
docker exec steam-headless supervisorctl restart steam
# 查看容器内所有supervisor服务状态
docker exec steam-headless supervisorctl status

复制代码

四、快捷优化小技巧
1.简化命令：给路径设置别名，不用重复长路径

# 临时生效，终端重启失效
alias steamd='docker compose -f /volume1/docker/steam-headless/docker-compose.yaml'
# 使用示例
steamd up -d
steamd restart
steamd pull && steamd up -d --force-recreate

复制代码

2.补丁脚本权限修复（补丁失效时执行）

chmod +x /volume1/docker/steam-headless/patches/*.sh

复制代码

DXP杰克彭老师 · 发表于 2026-7-9 23:49:08

好家伙，厉害👍进来之前以为是把steam游戏保存到nas，没想到是在nas里安装steam 😂

绿联NAS私有云 · 发表于 2026-7-10 09:17:12

3A老炮

橘霓暴 · 发表于 2026-7-10 09:57:19

我研究了一个星期了，跑不起来，游戏都是跑在CPU上，GPU没有任何负载
微信图片_20260708133048_16501_1.png

驱动都更新过了，能够识别到核显

但是openGL一直是livmpipe，软渲染，没跑在核显上

容器内使用ls /dev/dri/查看，只显示card0 renderD128，根本没有具体路径。我觉得是绿联根本就没有开放权限，哪怕是特权模式。

橘霓暴 · 发表于 2026-7-10 10:24:01

绿联NAS私有云发表于 2026-7-10 09:17
3A老炮

根本跑不起来，只有CPU负载，完全没法调用GPU。你看看我发的那个帖子，驱动重装了，权限全给了，就是没法跑GPU。你们是不是在宿主机层面就禁止了给核显GPU到容器啊？

恶魔程序员 · 发表于 2026-7-10 11:32:14

好家伙，玩点像素游戏够了

[玩法教程] 将 Steam 部署到 NAS 中运行游戏——完整教程

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

电梯直达
评论5

评论

浏览过的版块

[玩法教程] 将 Steam 部署到 NAS 中运行游戏——完整教程

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

电梯直达 评论5

评论

浏览过的版块

电梯直达
评论5