UE Horde 部署与使用笔记

February 15, 2024About 9 min

UE Horde 部署与使用笔记

这是我在 UE5.6 上搭建 Horde 的整理笔记,重点放在远程 C++ 编译这条链路:Server 装好、配上 SSL、Agent 注册进来、客户端开启 UBA 远程编译。中间踩的坑(Agent CPU 100%、Shader 分配只剩一个 Agent 等)也记在末尾,这些是实测遇到的,不是文档里写的。

Horde 5.6 还是 WIP 状态,很多附属功能(Symbol Server、Test Automation、UGS、设备管理)都没完全可用,下面会标注。官方文档其实跟着 Server 一起装好了,装完 Server 后访问 http://localhost:13340/docs 就能看到,内容和 Epic GitHub 上的 Horde README 一致。

Horde 是什么

Horde 是 Epic 给大团队做的一套构建/计算基础设施,核心能力:

远程执行(C++ 编译):把编译任务分发到其他机器,配合 Unreal Build Accelerator (UBA) 加速本地构建。这是目前最成熟、最值得用的功能。
远程 Shader 编译:同样走 UBA,把 Shader 编译分发出去。实测有 Agent 分配问题(见 Troubleshooting)。
Symbol Server:符号服务器。WIP。
构建自动化(CI/CD):基于 BuildGraph,面向大型 Perforce 仓库的构建系统。WIP。
测试自动化:跨 stream/project 查询自动化测试结果的前端,对接 Automation Tool 和 Gauntlet。WIP。
Studio Analytics:接收 Unreal Editor 的遥测,画关键工作流指标的图表。WIP。
UnrealGameSync (UGS):给团队分发预编译 Editor;UGS Metadata Server 提供构建状态上报、评论聚合、众包构建健康度等功能。WIP。
设备管理:管理移动/主机开发机集群。WIP。

实际能稳定跑起来的就是远程 C++ 编译,本文重点也在这。

Server 部署

安装

运行 Engine\Extras\Horde\UnrealHordeServer.msi 安装 Server。

默认端口:13340(HTTP)、13342(HTTP/2)。
推荐启用 HTTPS,配置见下一节 SSL。
装完后访问 http://localhost:13340 能看到完整文档,等同于 Epic GitHub 上的 Horde README。

修改下面这些配置文件后需要重启 Server 才能生效:

<ServerInstallDir>/globals.json
$(HordeDir)/Defaults/default.global.json(默认在 C:\Program Files\Epic Games\Horde\Server\Defaults\default.global.json)

配置 SSL

生产环境建议用公司签发的 wildcard 证书走 HTTPS。流程上向公司 IT 申请 wildcard 证书即可,IT 一般能提供两种形式:

直接给 PFX 文件;或
给 .key(私钥)和 .pem(公钥)。

PFX(Personal Information Exchange)是一种二进制格式,同时打包公钥证书和对应的私钥,通常加密并用密码保护,用于在系统间安全交换证书与私钥。

如果 IT 只给了 key + pem,需要自己用 openssl 合成 PFX:

openssl pkcs12 -export -out <wildcard-cert>.pfx -inkey <wildcard-cert>.key -in <wildcard-cert>.pem -certfile Intermediate.pem

各文件含义:

Intermediate.pem:中间证书 + 根证书的公钥
<wildcard-cert>.key:SSL 私钥
<wildcard-cert>.pem:SSL 公钥

证书准备好后,在 <InstallDir>/Data/server.json 里配置证书路径并重启 Server。验证是否生效可以访问 OpenID 配置端点:

https://<horde-server>:13341/api/v1/oauth2/.well-known/openid-configuration

相关官方文档(都在本地 Server 的 docs 下,装完即可访问):

<HordeServer>/docs/Tutorials/Authentication.md
<HordeServer>/docs/Deployment/Server.md
<HordeServer>/docs/Tutorials/SelfSignedCerts.md
<HordeServer>/docs/Config/Orientation.md
<HordeServer>/docs/Deployment/ServerSettings.md
<HordeServer>/docs/Config/Schema/Globals.md

server.json 与认证模式

<HordeServerInstallDir>\server.json 里的 AuthMode 决定登录方式。最简单的内置模式:把 AuthMode 设为 "Horde" 后重启 Server。

首次启动会提示设置管理员密码。登录后(用 <admin-user> / <password>),Server 菜单下会多出 Accounts 项,可以管理允许登录的用户以及他们的 claims。

要让用户能发起远程编译,需要给用户开 AddComputeTasks 权限(改完配置文件同样要重启 Server)。用户想看自己有哪些 claim,登录后访问 /account 页面即可。

Agent 端第一次编译时会自动弹出登录页,登录后就能自动参与编译。

认证相关文档:

https://<horde-server>:13341/docs/Tutorials/Authentication.md
https://<horde-server>:13341/docs/Config/Schema/Globals.md#aclprofileconfig

注意几个配置文件之间存在引用关系,改之前先确认正在使用的文件和文档里描述的引用关系一致,否则改了不生效。

Agent 部署

安装

两种方式。

方式一:MSI 安装(推荐,作为 Windows 服务运行)

用 Windows Installer 安装,会注册成系统服务,后续在服务列表里能看到对应的 Service。卸载也走标准流程。

安装教程文档:https://<horde-server>:13341/docs/Tutorials/InstallHorde.md

方式二:手动用裸数据包安装

# 下载 agent.zip
Invoke-WebRequest -Uri http://<horde-server-ip>:13340/api/v1/agentsoftware/default/zip -OutFile HordeAgent.zip
# 解压
expand-archive -LiteralPath HordeAgent.zip -Destination E:\horde -Force

# 配置 Server Profile
dotnet .\HordeAgent.dll SetServer -Name=HordeAgent -Url=<HordeServerURL>
# 注册为 Windows 服务
dotnet .\HordeAgent.dll service install -Server=HordeAgent

# 查看帮助
dotnet .\HordeAgent.dll -Help
dotnet .\HordeAgent.dll <Command> -Help

安装完按文档完成 Agent 注册即可。

开启远程 C++ 编译

在 Engine/Saved/UnrealBuildTool/BuildConfiguration.xml 里配置 Horde 地址和机器池:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">

    <BuildConfiguration>
        <!-- 启用 UnrealBuildAccelerator -->
        <bAllowUBAExecutor>true</bAllowUBAExecutor>
    </BuildConfiguration>

    <Horde>
        <!-- Horde 服务器地址 -->
        <Server>https://<horde-server>:13341</Server>

        <!-- 分发任务的机器池,Horde 默认配了 Win-UE5 -->
        <WindowsPool>Win-UE5</WindowsPool>
    </Horde>

    <UnrealBuildAccelerator>
        <!-- 可选:打开 UBA 进度可视化窗口 -->
        <bLaunchVisualizer>true</bLaunchVisualizer>
        <!-- 可选:强制所有编译任务走远程 -->
        <bForceBuildAllRemote>true</bForceBuildAllRemote>
    </UnrealBuildAccelerator>

</Configuration>

配好后正常触发编译,UBA 会自动把任务分发到 Pool 里的 Agent 上。

参考文档:https://<horde-server>:13341/docs/Tutorials/RemoteCompilation.md

开启远程 Shader 编译

这条链路实测有 Agent 分配问题(见 Troubleshooting),先记步骤。

先编译出带 ShaderCompileWorker 的 Editor:

Engine\Build\BatchFiles\RunUBT.bat <Project>Editor ShaderCompileWorker Win64 Development -Project=..\<ProjectPath>\Lyra.uproject

配置 <ProjectRoot>\Config\DefaultEngine.ini:

[UbaController]
Enabled = true
Horde = (Pool=Win-UE5,MaxCores=600)  # MaxCores: 本次 UBA session 尝试分配多少 CPU 核心
bForceRemote = true  # 可选:强制所有编译任务走远程

[Horde]
ServerUrl="https://<horde-server>:13341/"

Cook 数据触发 Shader 编译:

Engine\Binaries\Win64\UnrealEditor-Cmd.exe <ProjectPath>\<ProjectName>.uproject -run=cook -targetplatform=Windows -noshaderddc

参考文档:https://<horde-server>:13341/docs/Tutorials/RemoteShaderCompilation.md

Azure AD 认证(5.7)

5.7 支持 Azure AD,但不支持 LDAP。配置 Azure AD 需要先在 Azure 上注册应用拿到凭据,这一步要走公司 IT 流程,比较麻烦。

1. 在 Azure AD 上注册应用

登录 Azure 门户。
进入 Azure Active Directory -> 应用注册 -> 新注册。
填应用名称,如 HordeAuth。
重定向 URI 填 Horde 前端或后端的回调地址,通常格式为 https://your-horde-domain.com/auth/azuread/callback。
点"注册"完成。
记下生成的"应用程序(客户端)ID"和"目录(租户)ID"。

2. 配置客户端密钥(Client Secret)

在刚注册的应用里进入 证书和密码。
新建客户端密钥,记录密钥值(只显示一次,务必保存)。
该密钥用于 Horde 服务端与 Azure AD 通信认证。

3. 配置 API 权限

进入 API 权限,添加 Microsoft Graph 权限,建议选 openid、profile、email。
授予管理员同意让权限生效。

Agent 列表页功能

Agent 列表页地址:http(s)://<horde-server>/agents。

每个 Agent 上可以做的操作:

Remote Desktop:通过远程桌面连接自动连到对应 Agent。如果之前在远程桌面连接里保存过该机器的用户名密码,会自动登录。
Audit:查看 Agent 信息和历史。记录四种状态各自来自哪个 IP;View Agent 显示 Agent 详细信息。
Request Restart:几秒后重启成功。
Request Shutdown:关机。
Delete:删除 Agent。

这里有个权限隐患:admin 能在网页端直接控制 Agent 机器重启/关机,目前没找到关闭这个权限的开关(见下方对比)。

Horde vs Incredibuild

UE5.5 上和 Incredibuild(IB)做的对比,参考了 Epic 的 Unreal Build Accelerator v.s. Incredibuild 文档,加上自己实测。

维度	Horde (UBA)	Incredibuild
编译速度	一致	一致
Agent 设置 CPU 数	支持	未找到
禁用 Agent help 功能	支持	未找到
admin 在网页端控制 Agent 机器强制重启/关机	不支持	支持
Agent Pool	不支持	支持
Server 显示 Agent 系统信息	不支持	支持

注意上表的"支持/不支持"是从各自的优势角度填的:Horde 在 CPU 数设置、禁用 help 上有配置项而 IB 没找到;IB 在网页端管控、Pool、系统信息展示上更完善。

总结一下实测结论:Horde 目前能正常用于编译,但附属功能不完善,主要问题:

Agent 权限过大:可在 Horde 网页端控制 Agent 机器关机/重启,目前没找到关闭此权限的功能。
Agent help 时默认吃满 100% CPU 去帮其他 Agent 编译。试过 agent.json 的 cpuCount、cpuMultiplier,以及环境变量 UE_HORDE_CPU_COUNT,设置后都无效。
历史记录在 Agent 端找不到:只有管理员或无用户登录限制时,才能在网页端看到 Agent 实际编译的历史记录,而且不是编译发起者的完整编译历史。
Shader 编译跑一段时间后只剩一个 Agent help:其余 help Agent 会自动 disconnected 且再也连不上。

Troubleshooting

Agent CPU 100% 限不住

这是最头疼的问题,记录一下试过的:

启动编译后,Agent help 直接占满本机 100% CPU。
当 Agent 本身也在编译时,Agent help 不会停、CPU 不释放,本机和 help 抢资源:help 的占用率会降,但本机 + help 加起来还是 100%。
agent.json 里的 cpu 数设置和 cpuMultiplier 并不是限制 Agent help 上限的开关。
找到了文档里的相关配置,但设置后功能没生效,所有 Agent 依旧 100% CPU。
目前还没找到能真正限制 help CPU 占用的方式。

CPU 配置相关文档:https://<horde-server>:13341/docs/Deployment/AgentSettings.md

修改 Agent 存储路径

作为 Windows 服务运行时:

编辑 C:\ProgramData\Epic\Horde\Agent\agent.json:

{
  "horde": {
    "workingDir": "F:\\NewStorage\\HordeWorkingDir",
    "logsDir": "F:\\NewStorage\\HordeLogs"
  }
}

两个目录不存在会自动创建。

重启服务 Horde Agent。

查看日志

Agent 日志:C:\ProgramData\Epic\Horde\Agent\*.txt
Server 日志:<InstallDir>\Data\Logs

查看构建历史

管理员侧,Horde Server 存的是每个 Agent 的执行历史(Agent 实际执行编译的历史),不是发起编译那台机器的历史。用户侧目前没找到看自己完整编译历史的入口。

卸载 / 重新注册 Agent

卸载:走标准卸载流程。
重新注册:手动触发注册后等待刷新,注册状态页在 https://<horde-server>:13341/agents/registration。

修改 Agent 连接的 Server

通过修改 Agent 的注册配置改变它连接的 Server IP,改完重启 Agent 服务。