先说结论要在 Linux 上跑通虚幻引擎UE的像素流送Pixel Streaming完全可行而且一旦跑顺了比 Windows 部署更省心——但它绝不是把 Windows 那套命令照搬过来就能收工的。很多团队在 Windows 开发机上几分钟就能把 Pixel Streaming 的示例页面弹出来换到 Linux 服务器上就开始各种黑屏、无编码器、信令握手失败。我踩过一轮之后回头看问题基本不在 UE 本身而是对 Linux 下的图形栈、GPU 权限、无显示环境、WebRTC 信令链路不熟。这篇文章是我把一个 UE 项目从 Windows 开发机搬到 Linux 服务器做像素流送部署的完整记录涵盖环境准备、项目打包、信令服务器、启动流程、差异对照和常见坑点适合有 UE 基础但 Linux 经验不太多的开发者参考。1. 项目概述与部署思路1.1 像素流送到底解决什么问题像素流送的核心思路是把 UE 渲染出来的画面通过 WebRTC 实时推送到浏览器终端用户不需要下载安装包不需要高配电脑打开网页就能操作一个运行在服务器上的实时 3D 应用。典型场景包括数字孪生、建筑方案展示、产品在线配置器、虚拟展厅还有需要多人同时查看同一画面的协作评审。这里有个很容易被忽略的点像素流送不只是“传视频”。它同时承担了交互事件的双向通道浏览器端的鼠标键盘操作会通过信令通道发回 UE 进程UE 处理后画面帧再编码推回来。所以它天然适合“终端零安装 内容集中在服务端”的业务。资产和场景数据不出服务器浏览器看到的只是一路视频流从内容安全角度也有优势。对最终用户来说Chrome 打开链接就能用完全没有 UE 客户端的概念。1.2 为什么偏偏要部署在 Linux 上很多团队的开发机是 Windows但生产服务器往往希望用 Linux。原因很现实Linux 服务器没有桌面环境资源占用低系统长时间运行更稳定云主机、容器化、自动化运维那一套工具链对 Linux 的支持最好许可和镜像成本通常也更低。如果一个 UE 应用要作为常驻服务跑在机房或云上Windows Server 虽然也能做但多年运维下来大家更倾向 Linux。但把 UE 跑在 Linux 上有个天然门槛虚幻引擎对 Linux 的支持虽然完整却不像 Windows 那样“开箱即用”。尤其是像素流送它依赖 GPU 硬件编码、Vulkan 渲染、无头显示环境任何一个环节不对浏览器端就是一张黑屏。再加上 UE 官方文档里关于 Linux 部署的细节比较分散很多参数要靠试错才能确认。这篇文章的定位就是把这条链路从头到尾打通。1.3 整体部署链路像素流送的完整链路可以拆成几段UE 应用进程渲染 3D 场景接收浏览器回传的交互事件。像素流送插件采集渲染画面交给编码器编码为视频流同时处理 WebRTC 协商。信令服务器负责浏览器与 UE 进程之间的连接配对传递 SDP 和 ICE 候选。浏览器端播放器接收视频流并渲染到网页同时把用户输入发回 UE。辅助设施Nginx 反向代理、TURN/STUN 服务、HTTPS 证书按部署环境按需引入。整个部署过程中最容易被忽略的是“信令先于媒体”这个时序。浏览器要先跟信令服务器握上手再由信令服务器牵线找到 UE 进程之后两者才能建立 WebRTC 连接。很多人启动 UE 后浏览器一直转圈不弹画面十有八九是信令服务器没起、端口不通或者 UE 进程没有连上信令服务器。后面我会按启动顺序一步步讲。2. 服务器环境准备2.1 系统选型与基础配置我这次用的是 Ubuntu Server 22.04 LTS选它的原因主要是 UE 官方对 Ubuntu 的兼容性说明最明确社区踩坑案例也多。内核和图形栈的更新节奏适中不像某些滚动发行版那样动不动把驱动搞崩。系统安装时建议选最小化安装不需要装桌面环境也不需要装多余的服务。装机后第一件事是更新软件源和系统包sudo apt update sudo apt upgrade -y然后确认硬件信息。像素流送对 CPU 和内存的要求取决于场景复杂度如果是几千平方米的 BIM 模型加实时光照建议 8 核以上 CPU、32GB 内存起步如果只是简单产品展示4 核 16GB 也能跑但编码和渲染都吃资源宁可多配不要少配。显卡方面NVIDIA 显卡是首选因为像素流送的硬件编码走 NVENCAMD 和 Intel 在 Linux 下的编码器支持比较折腾不建议拿来生产。lspci | grep -i nvidia nvidia-smi先看系统能不能认出显卡。如果nvidia-smi不存在说明驱动还没装如果 lspci 里根本看不到显卡那要检查是不是云主机没分配 GPU 直通或者物理机显卡没插好。这一步排查清楚再往下走不然后面所有问题都会归因到“显卡不存在”上。2.2 GPU 驱动与视频编码环境Linux 下装 NVIDIA 驱动有几种方式我推荐用官方驱动加 CUDA 库的组合。先禁用系统自带的 nouveau 开源驱动不然会和官方驱动冲突sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nouveau.conf sudo update-initramfs -u然后重启机器确认 nouveau 已经不再加载lsmod | grep nouveau没有输出就说明屏蔽成功。下载 NVIDIA 驱动时要注意选择对应显卡型号和系统架构的版本建议直接去官方驱动页查型号下载。安装过程如果用 runfile 方式要确保编译内核模块所需的 gcc、make、kernel headers 已经装好sudo apt install build-essential linux-headers-$(uname -r) -y sudo sh ./NVIDIA-Linux-x86_64-xxx.xx.run安装完成后用nvidia-smi验证能看到 GPU 型号、驱动版本、显存容量就基本没问题。像素流送编码要走 NVENC驱动程序版本不能太老建议使用较新的稳定版太老的驱动可能不支持新版 UE 调用的编码接口。这一步有个容易忽略的细节检查/dev/nvidia0和/dev/nvidiactl是否存在。如果设备节点没生成UE 进程虽然能跑但硬编码的时候会报错。另外有些云主机会把显卡设备权限限制住如果 UE 用普通用户启动需要确认用户对/dev/nvidia*有读写权限。2.3 无显示环境与图形栈处理Linux 服务器通常没有显示器UE 要渲染画面就得处理“往哪画”的问题。UE 像素流送提供了离屏渲染模式通过启动参数-RenderOffScreen让引擎不创建窗口画面直接渲染到后台缓冲区再交给编码器。这样不需要 X Server省掉不少麻烦。但离屏渲染不等于不需要图形库。UE 在 Linux 下走 Vulkan 渲染所以要安装 Vulkan 运行时和依赖库。另外还需要一些运行时链接库缺了它们 UE 进程会启动失败。我用到的依赖安装命令大致如下sudo apt install libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libasound2-dev libpulse-dev libgl1-mesa-dev mesa-common-dev libvulkan1 libvulkan-dev vulkan-tools如果机器上有声卡设备但不想让 UE 抢音频或者干脆没有音频设备可以装一个虚拟声卡模块让 UE 的音频采集不报错sudo apt install snd-aloop sudo modprobe snd-aloop这个不是必须的但服务器如果不装声卡UE 启动时可能会刷一条音频设备初始化的警告某些版本还会因为找不到音频设备而崩溃。我建议在服务器环境里把虚拟声卡装上对音频采集类需求也有帮助。所有依赖装完后可以跑一下vulkaninfo --summary确认 Vulkan 能识别到渲染设备和编码设备。如果这里输出为空或者只看到软件渲染器那说明驱动装得有问题后面 UE 肯定也起不来。3. UE 项目打包与像素流送插件配置3.1 插件启用与参数在 UE Editor 里打开项目确认 Pixel Streaming 插件已经启用。这个插件在 UE4.26 之后属于官方标准插件一般不需要额外下载位置在“编辑-插件”窗口的“流送”分类下。启用后重新启动编辑器插件会生成一些默认配置。像素流送有几个关键参数要在项目配置里确认-PixelStreamingIP信令服务器的 IP 或域名UE 进程启动时用这个参数告诉插件去连接哪个信令服务器。-PixelStreamingPort信令服务器的 WebSocket 端口默认通常是 80 或自定义端口。-RenderOffScreen离屏渲染开关Linux 无显示环境必备。-PixelStreamingCodec编码格式常见是 H.264新版本也可能支持 AV1需要根据浏览器兼容性选择。这些参数可以直接写在命令行里也可以写进DefaultEngine.ini。我建议命令行传参为主因为部署环境变了只要改启动脚本就行不用重新打包。插件在项目打包时会被一起编进去只要插件启用且没在打包设置里被排除。3.2 Linux 打包关键设置如果你在 Windows 开发机上做事打包 Linux 版需要先在启动器里安装 Linux 平台的工具链。UE 编辑器默认只带本机平台打包其他平台会提示缺少组件。安装好之后文件菜单里的“打包项目”会出现 Linux 选项。Linux 服务器版本的项目类型可以选“Linux Server”但我实际测下来像素流送用“Linux”类型的包更稳妥因为 Server 类型会裁剪掉一些渲染和媒体相关的模块。如果你直接在 Linux 机器上装 UE Editor 来打包那就不存在交叉编译的问题但要注意编辑器本身也要能跑起来显卡驱动和图形库必须先装好。打包命令如果走自动化管线可以用 UnrealBuildTool 配合 RunUAT 脚本./Engine/Build/BatchFiles/RunUAT.sh BuildCookRun \ -project/path/to/YourProject.uproject \ -platformLinux \ -clientconfigDevelopment \ -build -cook -stage -pak -archive \ -archivedirectory/path/to/output打包完成后输出目录里能找到一个可执行文件名字和项目名一致。这个可执行文件加上-RenderOffScreen和像素流送参数就是最终的运行程序。3.3 打包后的目录结构Linux 打包产物跟 Windows 的结构类似但要注意几个细节可执行文件需要添加执行权限chmod x YourProject。某些 .so 动态库依赖系统的 libc、libstdc 版本一般 Ubuntu 22.04 没问题但如果你跑在更旧的发行版上可能会遇到 GLIBC 版本不兼容那就只能换系统或升级。可以用ldd ./YourProject | grep not found检查缺失的依赖库。我之前就碰到过缺libnvidia-glcore.so的情况原因是 32 位兼容库没装后来在 Ubuntu 上装了libnvidia-gl-xxx才解决。还有一点打包目录里有一个YourProject/Saved/文件夹运行时日志写在里面。排查问题第一件事就是看Logs/YourProject.log很多问题不用猜日志里写得很明白。4. 信令服务器与流媒体链路部署4.1 官方信令服务器部署信令服务器的作用是让浏览器和 UE 进程先建立“联系”。UE 早期的像素流送方案需要单独从官方仓库拉取 PixelStreamingInfra部署方式是基于 Node.js 的服务。新版本 UE 已经把信令服务器集成到了插件或示例目录里不同版本位置不一样。我这次用的是 UE5.3在引擎安装目录下的 Samples/PixelStreaming 里能找到现成的信令服务器程序相比早期版本省了很多配置工作。如果是自己拉取 PixelStreamingInfra 部署流程是git clone https://github.com/EpicGames/PixelStreamingInfra.git cd PixelStreamingInfra/SignallingServer npm install npm start启动后信令服务器默认监听 80 端口。你可以先用浏览器访问http://服务器IP如果能看到信令服务器默认页面或一个简单的连接测试页面就说明服务正常。Node.js 版本建议 16 以上太老跑不起来新版依赖。这里有个容易被忽略的点信令服务器的 WebSocket 端口和 UE 进程的媒体端口不是一回事。浏览器先通过 WebSocket 连信令服务器信令服务器再把 UE 进程的连接信息返回给浏览器之后媒体数据走的是另一条 WebRTC 通道。所以“信令服务器能访问”不代表“像素流送能通”后面要分开排查。4.2 配置 TURN、STUN 与反向代理内网部署时浏览器和服务器在同一内网一般不需要 TURN/STUN。但如果服务器在云上或者浏览器和服务器之间有复杂的 NAT 和防火墙WebRTC 的 P2P 连接可能建立不起来这时候就需要 STUN/TURN 服务器辅助。STUN 负责探测公网地址TURN 则在 P2P 失败时中转流量。最常用的开源方案是 coturnsudo apt install coturn配置 TURN 服务时需要指定监听端口和认证方式。生产环境建议启用静态认证并把 TURN 端口在防火墙里放开。如果只是测试临时跑一下也可以。如果还要走 HTTPS 和域名访问Nginx 可以作为反向代理放在信令服务器前面。WebRTC 在浏览器里有一些安全上下文限制生产环境强烈建议启用 HTTPS否则部分浏览器会拒绝 WebRTC 连接或静音视频流。Nginx 配置需要额外处理 WebSocket 的升级头location / { proxy_pass http://127.0.0.1:80; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }这只是信令层面的反代真正的媒体流端口还需要在安全组或防火墙里放行。具体端口因 UE 版本而异通常 UE 进程会监听一个媒体端口用于 WebRTC 传输需要提前规划好并放行。4.3 用 systemd 管理服务像素流送的两个核心进程——信令服务器和 UE 应用——都应该用 systemd 托管避免 SSH 断开后进程被一起带走。为信令服务器写一个 service 文件[Unit] DescriptionUE Pixel Streaming Signalling Server Afternetwork.target [Service] WorkingDirectory/opt/pixelstreaming/SignallingServer ExecStart/usr/bin/node /opt/pixelstreaming/SignallingServer/SignallingServer.js Restartalways RestartSec5 Userpixelstream EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.targetUE 应用进程的 service 文件类似但要注意启动参数和环境变量。如果 UE 崩溃systemd 的Restartalways会自动拉起来对生产环境很有用。日志查看也比较方便journalctl -u pixelstreaming-ue -f。我习惯把服务名区分开信令叫signallingUE 叫ue-streamer这样看状态和日志不会混淆。5. 实际启动流程与联调5.1 启动顺序与参数启动顺序很重要信令服务器要先起UE 进程再连上来。顺序反了虽然 UE 进程会重试但第一次握手会多出很多等待看起来就像卡死了一样。示范命令# 第一步启动信令服务器 cd /opt/pixelstreaming/SignallingServer npm start # 第二步启动 UE 应用 cd /opt/ue/YourProject ./YourProject \ -RenderOffScreen \ -PixelStreamingIP127.0.0.1 \ -PixelStreamingPort80 \ -PixelStreamingCodech264 \ -windowed \ -ResX1280 \ -ResY720我用127.0.0.1做信令地址是因为信令服务器和 UE 进程在同一台机器上。如果分开部署要改成信令服务器的实际地址。分辨率参数控制渲染画幅码率和延迟控制可以在下游的 WebRTC 参数里调也可以在 UE 启动时加一些像素流送特有参数。启动后观察 UE 日志如果一切正常会出现类似“WebRTC video encoder initialized”或“Signalling server connected”的关键字。看到这些再打开浏览器基本就能出画面了。5.2 浏览器端连接验证浏览器打开信令服务器提供的页面通常是http://服务器IP。按下 F12 打开开发者工具在控制台和网络面板里观察 WebSocket 连接状态。正常情况下会看到WebSocket 到信令服务器的连接建立成功。浏览器发出加入或查询请求。信令服务器返回 UE 进程的连接信息。ICE 候选交换完成后媒体通道建立视频画面出现。如果停留在某个阶段不动就顺着对应环节查。WebSocket 连不上查信令端口SDP 交换不出来查 UE 进程是否活着媒体流黑屏查编码器和显卡。我建议在测试阶段用同一台电脑开两个浏览器标签页一个看画面一个开开发者工具抓连接过程。很多问题看日志比看黑屏更容易定位。新会话连接时如果 UE 进程已经在运行浏览器应该能在几秒内看到画面如果等待时间过长检查是不是信令服务器同时只能支持一个 UE 实例或者端口被占用了。5.3 Windows 与 Linux 部署差异对照把像素流送从 Windows 切换到 Linux最大的感受是思路要变。下面这个对照表是我实践后的总结比较有代表性对比项Windows 部署Linux 部署渲染 APID3D11/D3D12主要是 Vulkan窗口模式可开窗口也可离屏无桌面环境必须离屏显示驱动显卡厂商驱动自动管理手动装驱动注意屏蔽 nouveau编码器NVIDIA NVENC驱动装好即可NVENC 依赖驱动和 Vulkan 栈启动方式双击或批处理systemd 或 shell 脚本依赖库DLL 大多随包携带依赖系统 .so需手动检查缺失日志排查事件查看器加 UE 日志journalctl 加 UE 日志远程维护远程桌面SSH注意进程会话管理Windows 部署时桌面环境会把很多事情“顺便”解决掉比如显示设备、音频设备、显卡驱动初始化。Linux 部署没有这些隐形帮助每一个环节都要自己确认。但也正因为如此Linux 部署一旦跑通运行环境非常干净资源占用低崩溃重启也容易自动化。6. 常见问题排查与避坑记录6.1 黑屏无画面黑屏是像素流送 Linux 部署里最常遇到的问题而且原因有好几种。我建议按照下面顺序排查看 UE 日志是否正常启动是否出现渲染错误。确认 UE 进程有没有崩溃ps aux | grep YourProject看看进程还在不在。执行nvidia-smi确认 GPU 上有 UE 进程在占用显存。看信令服务器端日志确认有没有收到 UE 的注册。浏览器开发者工具里看 WebRTC 的iceConnectionState如果不是 connected说明媒体通道没建立。我踩过的一个典型坑是UE 进程起来了信令也通了但画面一直是黑屏日志里也没有明显错误。最后发现是显卡驱动没问题但缺少 Vulkan 的 ICD 配置文件导致 UE 用软件渲染跑了一圈编码接口拿不到 NVENC。解决办法是重装 vulkan 驱动并确认vulkaninfo --summary里的 deviceName 是 NVIDIA 显卡而不是 llvmpipe。6.2 视频编码失败启动日志如果出现Encoder not available、Failed to create video encoder、NVENC error这类关键字基本可以锁定是编码器的问题。一种是驱动太老另一种是 GPU 型号太老不支持 NVENC还有一种是权限问题进程无法访问 /dev/nvidia*。排查命令journalctl -u ue-streamer -n 50 dmesg | grep -i nvidia如果确认是权限问题最简单的做法是把运行 UE 的用户加入video组sudo usermod -aG video pixelstream还有一种情况是并发编码数超过显卡限制。消费级显卡对 NVENC 会话数有上限多开几个 UE 实例后后面的实例就会抢不到编码器。如果是这种情况要么换专业卡要么降低并发实例数。6.3 延迟过高像素流送本身会有一定延迟但延迟高到影响操作就需要调优。影响延迟的因素包括编码码率、分辨率、帧率、网络 RTT、WebRTC 缓冲策略。我一般先看网络局域网里如果延迟还在 200ms 以上问题多半在编码参数或缓冲设置。常见调整手段提高帧率减少丢帧导致的画面卡顿。调整码率不要设得过低否则编码器会为了压缩而引入延迟。在 UE 启动参数里关掉垂直同步减少渲染管线等待。检查浏览器端的硬件加速是否开启软件解码也会增加延迟。Linux 下特别要注意的是离屏渲染模式下如果服务器 CPU 或 GPU 负载过高编码器排队会非常明显。用nvidia-smi看 GPU 利用率和编码器利用率如果编码器一直在满负荷说明并发已经到瓶颈了。6.4 端口与信令问题浏览器访问信令服务器没问题但 WebSocket 连接失败或者浏览器能连信令但 UE 进程连不上信令这是端口和地址配置的问题。先确认信令服务器监听的端口再确认防火墙规则sudo ufw status sudo netstat -tlnp | grep -E 80|8888如果服务器有多个网卡注意 UE 启动参数里-PixelStreamingIP应该填浏览器能访问到的那个地址不能填localhost。浏览器到信令服务器、信令服务器到 UE 进程、UE 进程到信令服务器这三条链路的地址要能互通缺一条都不行。有的发行版默认开了 SELinux会拦截非标准端口的 WebSocket 流量。如果是 CentOS 或 Rocky Linux检查 SELinux 状态必要时候把对应端口加入允许列表或者临时 setenforce 0 测试。6.5 权限与崩溃问题用 root 用户跑 UE 进程不是一个好习惯。UE 在 Linux 下以 root 身份运行时某些模块会尝试读取用户配置文件权限不一致会导致奇怪的问题。建议创建一个专用用户比如pixelstream把打包目录和日志目录的所有权交给它sudo useradd -m pixelstream sudo chown -R pixelstream:pixelstream /opt/ue崩溃自动重启用 systemd 配置。除了Restartalways我还习惯加一个健康检查用一个 cron 脚本定时探测信令服务器的 HTTP 接口发现异常就重启服务。这样做的好处是即使 systemd 没有检测到进程退出比如某个线程死锁也能通过外部探测恢复。内存不足也是 UE 进程崩溃的常见原因。UE 打包后默认可能吃掉好几个 GB 内存如果服务器内存不够OOM Killer 会直接杀掉 UE 进程。用journalctl -k | grep -i oom能查到相关记录这个问题加 swap 只是治标最好的方案是加内存或者降低场景复杂度。7. 一点生产环境建议像素流送服务跑起来之后下一步要考虑的是可维护性。我这里只说几个自己实践下来觉得划算的投入。第一个是日志集中处理。UE 进程的日志和信令服务器的日志分开存放再配一个简单的 logrotate 做轮转避免磁盘被日志填满。第二个是监控 GPU 状态nvidia-smi可以定期记录显存、温度、编码器利用率既能发现硬件故障的苗头也能判断当前负载离瓶颈还有多远。第三个是给 UE 进程加一个看得见的版本号在启动脚本里把 Git 提交号打到日志里不然多版本迭代时根本不知道服务器上跑的是哪一版。我个人的体会是Linux 部署像素流送真正难的不是 UE而是把 Linux 图形栈、GPU 驱动、WebRTC 信令这三条线串起来。每一条线单独看都有完整文档但放到一起就全是文档没写的细节。如果你也准备做这件事先从最小场景开始用示例项目在本地 Linux 机器上跑通再逐步加真实场景和并发不要一上来就把所有环节都堆到生产环境里。这样每一步出问题都知道该去查哪个方向。