内容纲要

最近在 B站 上偶然发现一个名为 Steam-Headless 的开源项目，它允许我们将一台带显卡的服务器变成远程游戏主机，通过浏览器或 Moonlight 等串流工具来运行 Steam 游戏。家里正好有一台闲置的 Ubuntu 服务器配备了 NVIDIA 显卡，于是决定动手尝试。
【强烈推荐参考文献的教程！！！】
本文将完整记录我在 Ubuntu 系统上部署 Steam-Headless 容器化服务的全过程，涵盖：

  • Docker 与 NVIDIA 驱动环境搭建
  • NVIDIA Container Toolkit 安装
  • docker-compose 配置与启动
  • 真实踩坑与排错全过程
  • 最终实现远程畅玩 Steam 游戏

💡 目标：打造一台支持 GPU 加速、可通过网页访问、并能串流运行 Steam 游戏的家庭云游戏服务器。

✅ 前置条件

请确保你的主机满足以下要求：

条件 说明
操作系统 Ubuntu 20.04 / 22.04 LTS（推荐）
GPU NVIDIA 显卡（Kepler 架构及以上，支持 CUDA）
驱动 已安装最新版 NVIDIA 驱动
Docker 已安装 Docker CE
网络 能够访问外网，防火墙开放必要端口

📌 本文基于 Ubuntu 22.04 测试，其他 Debian 衍生系统也可参考。

1️⃣ 安装 Docker（如未安装）

如果你还未安装 Docker，推荐使用官方脚本方式快速部署：

# 卸载旧版本（如有）
sudo apt-get remove -y docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common

# 添加 Docker 官方 GPG 密钥（使用清华镜像加速）
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加仓库（清华源）
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 更新并安装
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 验证安装
sudo docker run hello-world

🔐 非 root 用户运行 Docker

sudo groupadd docker
sudo gpasswd -a $USER docker
newgrp docker  # 刷新组权限

测试：docker ps 是否无需 sudo 即可执行。

2️⃣ 安装 NVIDIA 驱动（如未安装）

# 添加图形驱动 PPA
sudo add-apt-repository ppa:graphics-drivers/ppa -y

# 查看推荐驱动版本
ubuntu-drivers devices

# 示例输出中会显示类似：
# driver   : nvidia-driver-535 - distro non-free recommended

# 安装推荐版本（以 535 为例）
sudo apt install -y nvidia-driver-535

# 重启生效
sudo reboot

验证驱动是否安装成功：

nvidia-smi

你应该看到 GPU 信息和驱动版本，例如：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.113.01   Driver Version: 535.113.01   CUDA Version: 12.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce RTX 3060  Off | 00000000:01:00.0  On |                  N/A |
+-------------------------------+----------------------+----------------------+

3️⃣ 安装 NVIDIA Container Toolkit（关键步骤）

为了让 Docker 容器能调用 GPU，必须安装 NVIDIA Container Toolkit。

方法一：标准安装（推荐）

# 配置生产仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
  && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 更新包列表
sudo apt-get update

# 安装 nvidia-docker2（自动包含所有依赖）
sudo apt-get install -y nvidia-docker2

# 重启 Docker
sudo systemctl restart docker

✅ 验证安装

sudo docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

如果输出与宿主机 nvidia-smi 一致，则说明 GPU 已可在容器中使用。

4️⃣ 创建目录结构

根据 Steam-Headless 官方文档，我们需要创建几个持久化目录。

# 服务配置目录
sudo mkdir -p /opt/container-services/steam-headless

# 数据存储目录
sudo mkdir -p /opt/container-data/steam-headless/{home,.X11-unix,pulse}

# 可选：游戏安装目录
sudo mkdir -p /mnt/games
sudo chmod -R 777 /mnt/games

# 修改所有者为当前用户
sudo chown -R $(id -u):$(id -g) /opt/container-data/steam-headless
sudo chown -R $(id -u):$(id -g) /opt/container-services/steam-headless
sudo chown -R $(id -u):$(id -g) /mnt/games

5️⃣ 配置 Docker Compose 项目

进入服务目录：

cd /opt/container-services/steam-headless

5.1 下载 compose 文件和环境变量模板

# 下载 NVIDIA 专用 compose 文件并重命名为 docker-compose.yml
wget -O docker-compose.yml https://raw.githubusercontent.com/Steam-Headless/docker-steam-headless/master/docs/compose-files/docker-compose.nvidia.yml

# 下载 .env 环境配置文件
wget -O .env https://raw.githubusercontent.com/Steam-Headless/docker-steam-headless/master/docs/compose-files/.env

6️⃣ 修改 .env 配置文件（重点）

nano .env

🔧 关键修改项如下：

参数 推荐值 说明
TZ Asia/Shanghai 设置为中国时区
PUID / PGID $(id -u) / $(id -g) 运行用户的 UID/GID
USER_PASSWORD 自定义密码（如 mypass123） 用于登录 Web 界面
HOME_DIR /opt/container-data/steam-headless/home 挂载路径
GAMES_DIR /mnt/games 游戏库路径
DISPLAY :55 X Server 显示编号
MODE primary 主模式（独立运行 X）
WEB_UI_MODE vnc 使用 noVNC 访问桌面
PORT_NOVNC_WEB 8083 Web 访问端口
ENABLE_STEAM true 自动启动 Steam
ENABLE_EVDEV_INPUTS true 支持键鼠穿透
NVIDIA_VISIBLE_DEVICES all 所有 GPU 可见

✅ 保存退出。

7️⃣ 启动容器

sudo docker-compose up -d --force-recreate

查看日志：

sudo docker-compose logs -f

等待几分钟，镜像拉取完成后，服务应正常启动。

🌐 访问 Web 界面

打开浏览器访问：

http://<你的服务器IP>:8083

你应该看到 noVNC 的登录界面。点击连接后，会进入一个轻量级桌面环境，并自动启动 Steam。

web_connect

⚠️ 我的真实排错全过程（非常重要！）

❌ 问题1：网页能打开，但点击“Connect”后无法连接

现象：noVNC 页面显示“Disconnected”，日志提示 Failed to connect to server。

初步怀疑：网络问题？STUN/TURN 配置？TLS？

深入排查：

  • 查看容器日志：docker-compose logs steam-headless
  • 发现关键错误：Xorg failed to start 或 Cannot establish any listening sockets

根本原因：宿主机运行了桌面环境（GNOME），占用了 X Server 和 GPU 资源，导致容器内无法创建虚拟显示。

解决方案：

# 停止桌面管理器（GDM3 为例）
sudo systemctl stop gdm3

# 或者禁用开机启动（谨慎）
sudo systemctl disable gdm3

💡 不同桌面环境对应的服务名：

  • GNOME: gdm3
  • KDE: sddm
  • XFCE: lightdm

此外，我还连接了一根 HDMI 线到显示器（即使不亮屏），这有助于 GPU 正常初始化，避免“无头模式”下的驱动问题。

✅ 解决效果：重启容器后，Xorg 正常启动，noVNC 成功连接！

❌ 问题2：Moonlight 连接后黑屏

现象：Sunshine 已启用，Moonlight 客户端能发现设备并连接，但画面为黑色。

排查思路：

  • 检查 Sunshine 是否运行：ps aux | grep sunshine
  • 检查防火墙是否放行 Sunshine 端口（UDP 47984~47999）
  • 检查容器日志是否有编码错误

发现线索：

  • 日志显示视频流已发送
  • 客户端收到帧但无法渲染

灵光一现：会不会是码率太低导致解码失败？

解决方案：
在 Moonlight 客户端设置中，将视频比特率从默认的 20 Mbps 拉高到 150 Mbps，分辨率设为 1080p，编码 H.265。

✅ 奇迹发生：画面瞬间清晰显示，游戏流畅运行！

🎯 原因分析：低码率下 H.265 编码可能出现关键帧丢失或解码器超时，高码率更稳定，尤其在局域网环境下完全可行。

❌ 问题3：Steam 登录后反复重启或卡住

现象：Steam 启动后登录账号，但不久自动退出或卡在加载界面。

可能原因：

  • 共享内存不足（shm_size 太小）
  • 权限问题（PUID/PGID 不匹配）
  • 磁盘空间不足

解决方案：
在 docker-compose.yml 中调整：

shm_size: 4G  # 原为 2G，升级为 4G

并确保 .env 中的 PUID 和 PGID 与宿主机用户一致。

这里我增加了swap后就好很多了。

✅ 成功运行后的体验

现在你可以：

  • 在 noVNC 页面中登录 Steam 账号
  • 下载并安装游戏（路径 /mnt/games）
  • 使用 Moonlight 从手机、平板、TV 上串流游玩
  • 实现真正的“家庭云游戏”体验！

🧩 功能扩展建议

功能 实现方式
多用户支持 复制容器实例，使用不同 PUID/PGID
自动备份 使用 rsync 或 borg 定期备份 /home
开机自启 将 docker-compose up -d 加入 /etc/rc.local 或 systemd 服务
性能监控 安装 netdata 实时查看 GPU 使用率

🔐 安全提醒

  • .env 文件包含密码，请勿提交到 Git
  • 生产环境建议开启 TLS 加密（设置证书）
  • 使用防火墙限制 8083 和 Sunshine 端口的访问范围
  • 定期更新镜像和系统补丁

📚 参考资料

最后修改日期: 2025年 8月 25日

作者

留言

撰写回覆或留言

发布留言必须填写的电子邮件地址不会公开。