企业官网建设流程全解析

1. 项目概述：为什么SignallingWebServer是Pixel Streaming的“交通枢纽”？

如果你正在尝试将用虚幻引擎（Unreal Engine）开发的3D应用或游戏，通过网页浏览器直接串流给用户，那么你肯定绕不开Pixel Streaming这项技术。而在这个过程中，SignallingWebServer（信令Web服务器）扮演的角色，远比一个简单的“服务器”要核心得多。你可以把它想象成一个大型在线游戏大厅的“前台”和“调度中心”：玩家的浏览器（客户端）和运行在服务器上的虚幻引擎应用实例（服务端）彼此不认识，它们需要一个中间人来交换“联系方式”（网络地址）、协商“沟通语言”（音视频编码格式），并最终牵线搭桥，建立一条点对点的“高速公路”（WebRTC连接）。这个中间人，就是SignallingWebServer。

很多开发者第一次接触Pixel Streaming官方教程时，往往会在SignallingWebServer这一步卡住。不是找不到文件，就是脚本运行报错，看着命令行里一串串红色的错误信息一头雾水。这很正常，因为官方文档有时会假设你已经具备了一些系统管理和网络配置的基础知识，而实际上，从打包好的虚幻应用，到一个能在浏览器里流畅运行的串流服务，中间隔着配置、网络、安全策略好几道坎。这篇教程的目的，就是帮你把这些坎一一踏平，不仅告诉你每一步怎么做，更会解释清楚每一步背后的逻辑，让你在遇到类似问题时，能自己举一反三，快速定位。

无论你是想为你的UE项目增加一个零安装的网页端演示入口，还是构建一个云游戏的原型，理解并成功部署SignallingWebServer都是至关重要的第一步。接下来，我会以一个UE5项目为例，带你从零开始，完成一次完整的SignallingWebServer本地部署与调试，过程中遇到的典型坑点及其解决方案，我都会结合自己的实操经验详细说明。

2. 核心组件解析与部署前准备

在动手敲命令之前，我们必须先理清Pixel Streaming架构中的几个核心组件及其关系，这能帮助你在后续排查问题时，清晰地知道是哪个环节出了岔子。

2.1 Pixel Streaming 技术栈拆解

一个典型的Pixel Streaming系统包含三个主要部分：

1. UE4/UE5 应用程序（信令客户端）：这是你的虚幻引擎项目打包后的可执行文件（例如MyGame.exe）。在启动时，它会内置一个Pixel Streaming插件，这个插件会主动去连接我们即将部署的SignallingWebServer，宣告自己“准备就绪，等待玩家连接”。

2. SignallingWebServer（信令服务器）：这是本教程的核心。它是一个基于Node.js的Web服务器。主要职责有两个：

   • HTTP/WebSocket 服务器：托管一个前端网页（通常位于www文件夹），用户通过浏览器访问这个网页。同时，它通过WebSocket与浏览器和UE应用保持长连接，用于交换信令消息。
   • 信令交换中介：在浏览器和UE应用之间传递SDP（会话描述协议）Offer/Answer和ICE（交互式连接建立）候选者信息。简单说，就是帮它们交换“网络名片”和“沟通能力清单”，让它们能直接建立P2P连接。

3. 用户浏览器（信令客户端）：用户通过Chrome、Edge等现代浏览器访问SignallingWebServer提供的网页。该网页包含JavaScript代码，负责捕获用户输入（鼠标、键盘），接收并解码来自UE应用的视频流，并通过WebRTC将输入事件回传给UE应用。

它们之间的关系如下图所示（概念示意）：

[用户浏览器] <--(WebRTC媒体流/数据通道)--> [UE4/5应用程序] ^ ^ | | (WebSocket信令) (WebSocket信令) | | +--------------[SignallingWebServer]--------------+

SignallingWebServer是通信的发起和协调中心，但它不传输沉重的音视频数据流，数据流是浏览器和UE应用点对点直连的，这保证了低延迟。

2.2 环境与文件定位：你的“工具”在哪？

最常见的第一个坑就是：“我根本找不到教程里说的那些脚本文件！” 这通常是因为引擎版本或安装路径的差异。

对于UE5（以5.3版本为例）： SignallingWebServer的默认路径通常在引擎安装目录下：C:\Program Files\Epic Games\UE_5.3\Samples\PixelStreaming\WebServers\SignallingWebServer\

关键目录说明：

• platform_scripts\：包含各平台（Windows cmd、PowerShell、Linux bash）的部署和启动脚本。这是我们主要操作的目录。
• www\：存放前端网页文件（HTML, JS, CSS）。你可以在这里自定义你的播放器界面。
• cirrus.js：信令服务器的核心JavaScript逻辑。
• config.json：服务器配置文件，可以设置端口、STUN/TURN服务器地址等。

注意：有些教程或旧版本可能会提到在项目打包输出目录（如WindowsNoEditor\）下也有这个文件夹。但在较新版本的UE中，官方推荐并默认使用的是引擎安装目录下的样本文件。打包时，引擎会将这些必要的Web服务器文件复制到打包输出目录的\Engine\Source\Programs\PixelStreaming\WebServers\下，但结构可能略有不同。为减少混淆，我强烈建议在学习和初次部署时，直接使用引擎安装目录下的样本。

你需要准备的工具：

1. Windows PowerShell（管理员权限）：我们将主要使用它来执行脚本。
2. 一个打包好的UE项目（Windows平台）：确保你的项目已启用Pixel Streaming插件并成功打包。你可以在项目设置中搜索“Pixel Streaming”启用相关插件。
3. 文本编辑器：如VSCode、Notepad++，用于查看和修改配置文件。

3. 逐步部署与配置SignallingWebServer

现在，我们进入实操环节。请打开你的Windows PowerShell（务必以管理员身份运行，否则可能因权限不足导致操作失败）。

3.1 步骤一：导航至脚本目录并修改执行策略

首先，我们需要切换到SignallingWebServer的脚本目录。打开PowerShell后，输入以下命令（请将路径替换为你自己的UE安装路径）：

cd "C:\Program Files\Epic Games\UE_5.3\Samples\PixelStreaming\WebServers\SignallingWebServer\platform_scripts\cmd"

按回车后，你应该能看到路径提示符变更为上述目录。

接下来是几乎所有新手都会遇到的拦路虎：PowerShell执行策略。出于安全考虑，Windows默认禁止运行未签名的本地脚本（.ps1文件）。我们必须临时放宽这个限制。

方法A（推荐，仅限当前会话）： 在PowerShell中输入：

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force

这条命令的意思是：仅针对当前这个PowerShell进程，绕过执行策略检查。它不会永久修改你的系统设置，关闭这个窗口后策略即恢复原样，最为安全。

方法B（永久修改，需谨慎）： 如果你希望一劳永逸（但会降低安全性），可以运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这条命令将为你当前用户设置为允许运行本地脚本和来自互联网但已签名的脚本。系统可能会弹出确认提示，输入Y确认。

实操心得：我强烈推荐使用方法A。特别是在公司或公用电脑上，随意修改全局执行策略可能违反IT规定。每次打开新的PowerShell窗口运行这些脚本时，都先执行一次Bypass命令即可。这也是为什么很多教程里直接运行脚本会报错...ps1 cannot be loaded because running scripts is disabled on this system的根本原因。

3.2 步骤二：安装依赖与启动信令服务器

确保你在...\platform_scripts\cmd\目录下，并且执行策略已绕过。

1. 安装依赖： 运行安装脚本，它会自动安装Node.js运行时所必需的npm包。

.\setup.ps1

这个脚本主要做两件事：检查本地是否安装了Node.js（如果没安装会尝试安装），然后运行npm install来安装package.json中列出的所有依赖项（如ws,express等）。你会在窗口中看到大量的npm下载和安装日志。

2. 启动信令服务器： 依赖安装完成后，就可以启动服务器了。

.\Start_SignallingServer.ps1

如果一切顺利，你将看到类似以下的输出：

> node cirrus.js Pixel Streaming Signalling Server started on :80

这表示信令服务器已在80端口启动。默认端口是80，如果你的80端口被其他程序（如IIS、Apache）占用，启动会失败。别急，我们马上讲如何修改端口。

3.3 步骤三：关键配置解析（config.json）

服务器能跑起来只是第一步，让它按照我们的需求工作，还需要理解并修改config.json文件。这个文件位于SignallingWebServer的根目录（与cirrus.js同级）。

让我们打开它，看看几个最关键的配置项：

{ "UseFrontend": false, "UseMatchmaker": false, "UseHTTPS": false, "UseAuthentication": false, "LogToFile": true, "HomepageFile": "player.html", "AdditionalRoutes": {}, "EnableWebserver": true, "StreamerPort": 80, "SFUPort": 8888, "httpPort": 80, "httpsPort": 443, "sslcert": "", "sslkey": "", "EnableSFU": false }

• UseFrontend和UseMatchmaker：涉及多实例匹配的高级功能，初次部署保持false。
• UseHTTPS和UseAuthentication：用于生产环境的安全设置，本地测试保持false。
• HomepageFile：默认加载的首页文件，通常是player.html。你可以替换成自己定制的页面。
• StreamerPort/httpPort：这是最容易混淆和出错的地方！
  • StreamerPort：UE应用程序（流送端）连接信令服务器时使用的端口。
  • httpPort：浏览器（客户端）访问信令服务器网页时使用的端口。
  • 在简单部署中，为了简化，通常让它们使用同一个端口（如都设为80）。但如果你遇到冲突，可以将httpPort改为其他端口，比如8080。
• SFUPort和EnableSFU：SFU（选择性转发单元）用于多人观看同一流的高级模式，单人测试保持false。

修改端口示例： 假设你的80端口被占用，可以将httpPort改为8080：

"httpPort": 8080, "StreamerPort": 80, // 可以保持不变，但UE应用连接时需要指定端口

保存文件后，需要重启Start_SignallingServer.ps1脚本才能生效。

注意事项：修改端口后，你访问服务器的地址也需要变化。原来是http://localhost，现在需要http://localhost:8080。同时，在启动UE应用程序时，也需要通过命令行参数指定信令服务器地址为127.0.0.1:80（如果StreamerPort没改的话）。

4. 连接UE应用程序与问题深度排查

信令服务器在后台跑起来了，接下来就是让我们的UE打包程序连接上去。

4.1 启动UE应用程序并连接信令服务器

找到你打包好的UE应用程序（例如MyProject.exe）。我们不是直接双击运行它，而是需要通过命令行传递参数来启动Pixel Streaming功能。

1. 在打包输出目录（如WindowsNoEditor）中，按住Shift键并右键点击空白处，选择“在此处打开 PowerShell 窗口”或“打开命令窗口”。
2. 输入以下命令（请根据你的实际情况替换应用名和IP地址）：

.\MyProject.exe -PixelStreamingURL="ws://127.0.0.1:80"

参数解释：

• -PixelStreamingURL：指定信令服务器的WebSocket地址。格式是ws://[服务器IP]:[StreamerPort]。
• 如果你的信令服务器运行在另一台电脑上，需要将127.0.0.1替换为那台电脑的局域网IP地址。
• 端口80对应config.json中的StreamerPort。如果你修改了它，这里也要同步修改。

如果连接成功，你会在UE应用程序的启动日志窗口，以及SignallingWebServer的PowerShell窗口中，看到连接建立的提示信息。

4.2 从浏览器访问与测试

现在，打开你的Chrome或Edge浏览器，输入信令服务器的地址：

• 如果使用默认配置：http://localhost
• 如果修改了httpPort为8080：http://localhost:8080

你应该能看到Pixel Streaming的默认播放器界面。点击“播放”或类似按钮，浏览器就会通过信令服务器与UE应用建立连接。稍等片刻，UE应用的画面就应该出现在浏览器中了！你可以尝试在浏览器中操作，鼠标键盘事件应该能控制UE应用。

4.3 典型问题排查手册

即使按照步骤操作，你也可能遇到问题。下面是一个快速排查清单：

4.4 进阶：配置STUN/TURN服务器解决连接问题

“黑屏转圈”问题90%的根源在于NAT穿透失败。WebRTC使用STUN服务器获取设备的公网IP和端口，在简单的网络环境下可能成功。但在企业网络、双重NAT或严格防火墙后，就需要TURN服务器进行流量中转。

修改config.json配置STUN/TURN： 在config.json文件中，找到或添加PeerConnectionOptions部分：

{ ... // 其他配置 "PeerConnectionOptions": { "iceServers": [ { "urls": ["stun:stun.l.google.com:19302"] }, { "urls": "turn:your-turn-server.com:3478", "username": "your-username", "credential": "your-password" } ] } }

• STUN服务器：你可以使用谷歌的公共STUN服务器stun:stun.l.google.com:19302。对于本地局域网测试，有时甚至不需要STUN服务器。
• TURN服务器：这是解决复杂网络问题的关键。你需要自己搭建或购买一个TURN服务器（如使用开源软件CoTURN搭建）。将上述示例中的your-turn-server.com、username、password替换为你自己的TURN服务器信息。

重要提示：公共的STUN服务器可能不稳定或被墙，TURN服务器则涉及流量和成本。对于本地局域网（LAN）测试，如果UE应用和浏览器在同一台机器或同一交换机下，通常不需要配置STUN/TURN即可直接连接。只有当你需要从外部网络（互联网）访问时，才必须配置一个可靠的TURN服务器。

5. 生产环境考量与优化建议

当你成功在本地跑通后，可能会考虑将其部署到云服务器上，供他人通过互联网访问。这涉及到更多方面：

1. 使用HTTPS：现代浏览器（特别是Chrome）强制要求通过HTTPS访问的页面才能使用某些API（如获取摄像头麦克风，WebRTC也强烈推荐）。你需要：

   • 将config.json中的UseHTTPS设为true。
   • 准备有效的SSL证书和私钥，并正确配置sslcert和sslkey路径。可以使用Let‘s Encrypt获取免费证书。
   • 将httpsPort设为443（HTTPS默认端口）。

2. 使用反向代理：不建议直接将Node.js服务暴露在公网。通常使用Nginx或Apache作为反向代理，处理HTTPS终结、静态文件服务和负载均衡，将请求转发给后端的SignallingWebServer。这能提升安全性和性能。

3. 进程管理：在Linux服务器上，使用systemd或pm2来管理SignallingWebServer进程，确保其崩溃后能自动重启。

4. 资源监控：Pixel Streaming对服务器CPU（编码）和GPU（渲染）资源消耗很大。确保你的云服务器有足够的性能，并监控其负载。

5. 安全加固：

   • 启用UseAuthentication，为信令服务器添加简单的令牌认证，防止未授权连接。
   • 定期更新Node.js依赖，修补安全漏洞。
   • 配置防火墙，只开放必要的端口（如80/443, 信令端口）。

最后，一个小技巧：在开发调试时，多关注信令服务器和浏览器控制台的日志。它们包含了连接建立、信令交换、错误发生的详细时间线，是定位问题最直接的依据。Pixel Streaming的部署就像搭积木，每一步都环环相扣，耐心理清每个组件的职责和它们之间的对话方式，就能让串流的画面稳定地出现在世界的任何一个角落。