# FeiLingPixelStreaming
**Repository Path**: flkjxx/feilingpixelstreaming
## Basic Information
- **Project Name**: FeiLingPixelStreaming
- **Description**: UE像素流送工具
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-07-14
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Pixel Streaming 自动化管理系统
一个基于 Unreal Engine 5.5 Pixel Streaming 的自动化管理系统，提供图形化界面管理、自动扩缩容、排队系统等企业级功能。
[功能特性](#功能特性) • [快速开始](#快速开始) • [系统架构](#系统架构) • [配置说明](#配置说明) • [开发指南](#开发指南)
---
## 📖 项目简介
本项目是基于 Epic Games Pixel Streaming Infrastructure 的增强版本，专为生产环境设计。通过 Python + PyQt6 实现的图形化管理界面，可以轻松管理多个 UE 实例、Cirrus 信令服务器和 Matchmaker 服务，支持自动扩缩容、用户排队、负载均衡等企业级特性。
### 核心优势
- 🖥️ **图形化管理界面** - 基于 PyQt6 的现代化界面，所有操作可视化
- 🚀 **自动扩缩容** - 根据用户排队数量自动启动/关闭 UE 实例，节省资源
- 👥 **用户排队系统** - 支持多用户排队，自动分配空闲实例
- ⚡ **零延迟启动** - Nginx 反向代理 + 动态路由，用户无感知切换
- 📊 **实时监控** - 实时显示实例状态、玩家数量、队列长度
- 🔧 **灵活配置** - 支持自定义端口范围、最大实例数、超时时间等
- 🎮 **自动播放** - 自动跳过连接和播放按钮，用户直接进入场景
---
## ✨ 功能特性
### 1. 图形化管理界面（PyQtManager）
- **一键启动/停止** Matchmaker 和所有实例
- **实时日志查看** - 支持 Matchmaker、Cirrus、UE 日志分别查看
- **配置管理** - 可视化配置编辑器，支持保存/加载配置
- **实例监控** - 实时显示每个实例的状态、端口、进程 ID、玩家数
### 2. 智能扩缩容
- **按需启动** - 根据排队人数自动启动新实例
- **自动回收** - 实例无玩家连接 15 秒后自动关闭
- **资源限制** - 设置最大实例数，防止资源耗尽
- **优雅关闭** - 关闭时自动清理 UE 进程树和相关资源
### 3. 增强的排队系统
- **公平排队** - FIFO 队列，先到先得
- **心跳保活** - 客户端自动刷新，防止排队丢失
- **实时推送** - WebSocket 推送队列状态和分配结果
- **可视化等待页面** - 显示排队位置、预计等待时间
### 4. Nginx 反向代理
- **统一入口** - 单一端口对外服务，内部动态路由
- **WebSocket 支持** - 完整支持 Pixel Streaming 的 WebSocket 连接
- **静态资源托管** - 直接返回 JS/CSS 文件，减轻 Cirrus 负载
- **动态路由** - `/server/{port}` 自动路由到对应的 Cirrus 实例
### 5. 自动播放优化
- **跳过连接按钮** - URL 携带 `AutoConnect=true` 参数
- **跳过播放按钮** - URL 携带 `AutoPlayVideo=true` 参数
- **智能识别** - 自动点击脚本兜底，应对浏览器自动播放限制
- **断线重连** - 检测到断开后自动跳转回排队页面（可选）
---
## 🏗️ 系统架构
```
┌─────────────────────────────────────────────────────────┐
│ 用户浏览器 │
└────────────────────┬────────────────────────────────────┘
│ HTTP/WebSocket
▼
┌─────────────────────────────────────────────────────────┐
│ Nginx (端口 8083) │
│ • 反向代理所有请求 │
│ • WebSocket 升级支持 │
│ • 静态资源托管（player.js 等） │
└────────┬────────────────────────────────────────────────┘
│
├──► Matchmaker (端口 92)
│ • 排队管理
│ • 实例分配
│ • 心跳检测
│
├──► Cirrus 0 (端口 81) ─────► UE 实例 0
│ └─ WebSocket: 1888
│
├──► Cirrus 1 (端口 82) ─────► UE 实例 1
│ └─ WebSocket: 1889
│
└──► Cirrus N (端口 81+N) ─────► UE 实例 N
└─ WebSocket: 1888+N
┌─────────────────────────────────────────────────────────┐
│ PyQtManager (管理界面) │
│ • 启动/停止服务 │
│ • 监控实例状态 │
│ • 查看日志 │
│ • 配置管理 │
└─────────────────────────────────────────────────────────┘
```
---
## 🚀 快速开始
### 环境要求
- **操作系统**: Windows 10/11 (64-bit)
- **Python**: 3.8 或更高版本
- **Node.js**: 18.17.0 或更高版本
- **Unreal Engine**: 5.5 (已打包为 Pixel Streaming 项目)
- **Nginx**: 1.26.2 (项目已包含)
### 安装步骤
1. **克隆项目**
```bash
git clone https://gitee.com/your-username/pixel-streaming-manager.git
cd pixel-streaming-manager
```
2. **安装 Python 依赖**
```bash
cd PyQtManager
pip install -r requirements.txt
```
3. **安装 Node.js 依赖**
```bash
# 安装 Matchmaker 依赖
cd Matchmaker
npm install
# 安装 SignallingWebServer 依赖（Cirrus）
cd ../SignallingWebServer
npm install
```
4. **配置 UE 项目路径**
编辑 `PyQtManager/manager_config.json`，设置你的 UE 打包项目路径：
```json
{
"ue_exe_path": "D:/YourProject/Windows/YourProject.exe",
"ue_working_dir": "D:/YourProject/Windows"
}
```
5. **启动管理界面**
```bash
cd PyQtManager
python main_window.py
```
6. **启动服务**
在管理界面中点击 **"启动 Matchmaker"** 按钮，系统会自动：
- 启动 Nginx (端口 8083)
- 启动 Matchmaker (端口 92)
- 等待用户访问时自动启动 UE 实例
7. **访问服务**
在浏览器中打开：`http://your-ip:8083`
---
## ⚙️ 配置说明
### PyQtManager 配置 (`PyQtManager/manager_config.json`)
```json
{
"ue_exe_path": "UE 可执行文件路径",
"ue_working_dir": "UE 工作目录",
"http_port_start": 81, // Cirrus HTTP 端口起始值
"streamer_port_start": 1888, // UE Streamer 端口起始值
"max_auto_instances": 5, // 最大自动启动实例数
"player_timeout_seconds": 15, // 无玩家自动关闭延迟（秒）
"matchmaker_port": 92, // Matchmaker 端口
"nginx_port": 8083, // Nginx 对外端口
"nginx_path": "../nginx-1.26.2" // Nginx 安装路径
}
```
### Matchmaker 配置 (`Matchmaker/config.json`)
```json
{
"HttpPort": 92,
"UseHTTPS": false,
"MatchmakerPort": 9999,
"LogToFile": true,
"EnableWebserver": true
}
```
### Cirrus 配置 (`SignallingWebServer/config.json`)
```json
{
"UseFrontend": "true",
"UseMatchmaker": "true",
"LogToFile": true,
"HomepageFile": "player.html",
"MaxPlayerCount": 1
}
```
---
## 🎯 使用场景
### 场景 1: 企业级 3D/VR 展示
适合需要高并发访问的 3D 产品展示、虚拟展厅等场景：
- 支持多用户排队访问
- 自动扩缩容节省服务器成本
- 统一入口便于管理和监控
### 场景 2: 在线培训/教学
适合 VR 培训、虚拟仿真教学等场景：
- 每个用户独立实例，互不干扰
- 自动分配实例，无需手动管理
- 实时监控每个学员的连接状态
### 场景 3: 建筑/地产可视化
适合建筑漫游、房地产虚拟看房等场景：
- 零延迟启动，用户无感知
- 自动回收闲置资源
- 支持高峰期自动扩容
---
## 🛠️ 开发指南
### 项目结构
```
feilingpixelstreaming/
├── PyQtManager/ # Python 管理界面
│ ├── main_window.py # 主窗口
│ ├── process_manager.py # 进程管理器（核心逻辑）
│ ├── config_manager.py # 配置管理
│ └── requirements.txt # Python 依赖
│
├── Matchmaker/ # 排队与分配服务
│ ├── matchmaker_withqueue.js # 主程序（增强版）
│ ├── html/sample/queue/ # 排队页面
│ └── config.json # 配置文件
│
├── SignallingWebServer/ # Cirrus 信令服务器
│ ├── cirrus.ts # 主程序
│ ├── Public/ # 静态资源
│ │ └── player.html # 播放器页面（含自动播放脚本）
│ └── config.json # 配置文件
│
├── nginx-1.26.2/ # Nginx 反向代理
│ └── conf/nginx.conf # 配置文件（包含动态路由）
│
└── Frontend/ # Pixel Streaming 前端库
└── library/ # TypeScript 库源码
```
### 关键修改点
#### 1. Matchmaker 排队增强
`Matchmaker/matchmaker_withqueue.js`:
- 添加排队队列管理
- WebSocket 实时推送队列状态
- 重定向 URL 携带 `AutoConnect=true&AutoPlayVideo=true`
#### 2. 自动播放脚本
`SignallingWebServer/Public/player.html`:
- 自动识别并点击播放按钮
- 绕过浏览器自动播放限制
- 可选的断线自动跳转功能
#### 3. 进程管理器
`PyQtManager/process_manager.py`:
- 监控 Matchmaker 队列状态
- 自动启动/关闭 UE 实例
- 进程树管理，确保资源完全释放
#### 4. Nginx 动态路由
`nginx-1.26.2/conf/nginx.conf`:
- `/server/{port}` 路由到对应 Cirrus 实例
- WebSocket 升级支持
- 静态资源直接返回
### 扩展开发
#### 添加新的自动扩容策略
编辑 `PyQtManager/process_manager.py`:
```python
def on_queue_stats_changed(self, stats):
# 自定义扩容逻辑
queue_size = stats.get('totalWaiting', 0)
busy_count = stats.get('totalBusy', 0)
# 例：高峰期预留 2 个空闲实例
target = queue_size + busy_count + 2
# 触发扩容/缩容
self.adjust_instances(target)
```
#### 自定义排队页面
编辑 `Matchmaker/html/sample/queue/queue.html`，修改样式和交互逻辑。
---
## 📝 常见问题
### Q: 为什么播放按钮有时需要点击？
**A**: 这是浏览器的自动播放策略限制。Chrome 需要用户有过交互操作才允许自动播放带声音的媒体。解决方案：
1. 项目已包含自动点击脚本作为兜底
2. 将域名加入浏览器自动播放白名单
3. 或在首次访问时点击一次，浏览器会记住
### Q: 如何调整最大实例数？
**A**: 编辑 `PyQtManager/manager_config.json`，修改 `max_auto_instances` 值。
### Q: Nginx 启动失败怎么办？
**A**: 检查端口是否被占用：
```bash
netstat -ano | findstr :8083
```
如果被占用，修改 `manager_config.json` 中的 `nginx_port`。
### Q: UE 实例启动慢怎么优化？
**A**:
1. 使用 SSD 存储 UE 项目
2. 减少 UE 项目体积（移除未使用的插件和内容）
3. 增加 `player_timeout_seconds` 保持实例在线
### Q: 如何支持 HTTPS？
**A**:
1. 准备 SSL 证书（`.pem` 和 `.key` 文件）
2. 修改 `Matchmaker/config.json` 和 `SignallingWebServer/config.json`，设置 `UseHTTPS: true`
3. 修改 `nginx.conf`，添加 SSL 配置
---
## 🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
### 提交规范
- **Bug 修复**: `fix: 简短描述问题`
- **新功能**: `feat: 功能名称`
- **文档更新**: `docs: 更新内容`
- **性能优化**: `perf: 优化内容`
### 开发流程
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request
---
## 📄 开源协议
本项目基于 [MIT License](LICENSE.md) 开源。
部分代码基于 Epic Games 的 Pixel Streaming Infrastructure (Unreal Engine 5.5)，遵循其原有协议。
---
## 🙏 致谢
- [Epic Games](https://www.unrealengine.com/) - Pixel Streaming 技术
- [Nginx](https://nginx.org/) - 高性能反向代理
- [PyQt6](https://www.riverbankcomputing.com/software/pyqt/) - Python GUI 框架
---
## 📧 问题反馈
- [提交 Issue](https://gitee.com/your-username/pixel-streaming-manager/issues)
---
**如果这个项目对你有帮助，请给个 ⭐️ Star 支持一下！**