Version: Unity 6.0 (6000.0)
语言 : 中文
Caching assets
Unity Accelerator requirements

Unity 加速器

概述

Unity__ 加速器__ (Unity Accelerator) 是一个缓存代理程序,可保留团队所导入资源的副本以加快团队合作。加速器的目标是帮助团队减少迭代时间。团队在同一本地网络中工作时,加速器会协调资源共享,因此无需重新导入项目的某些部分。这个过程通过资源导入管线 v2 Unity 编辑器功能来完成。

在本地网络中安装加速器后,Unity 编辑器(2019.3 或更高版本;请参阅下文的 Unity 编辑器要求)与加速器进行通信,以存储和获取其他团队成员需要、已更改或构建的资源。加速器会保留这些资源的临时副本以避免浪费时间和带宽来获取或重新导入资源。

加速器概览
加速器概览

内容

安装加速器

要求

本地托管要求

请在您团队经常使用的每个网络上都安装加速器。您的本地网络上必须有可以托管加速器的计算机。选择主机时,应考虑以下要求:

  • 本地主机必须运行以下操作系统之一:
    • Linux(Ubuntu 16.04 或 Ubuntu 18.04)
      对于 Linux,必须以 root 用户身份安装加速器。
    • Windows Server 2008R2/Windows 7 或更高版本(64 位)
    • Mac OS X 10.12 或更高版本(64 位)
  • 本地主机必须具有足够的本地存储空间来托管项目的大多数文件(最好在未托管操作系统的固态驱动器上)。
  • 本地主机应具有可合理负担成本的内存量。最少应是 2GB 的 RAM,但如果有更多内存可用,操作系统会使用它缓冲缓存项,从而提高经常访问项的性能。通常建议使用 32GB 的 RAM。
  • 本地主机必须与您的团队连接到同一网络,或者必须采用允许访问加速器 IP 地址和端口 (TCP) 的相应防火墙策略在本地进行路由。
  • 任何有权访问主机的人都可以访问您项目的文件,无论您 Unity 组织 (Unity Organization) 内的权限结构如何。因此,Unity 建议对该计算机进行限制,以便只有组织所有者或管理员才能访问加速器并与之交互。

Unity 编辑器要求

Unity 项目必须使用 2019.3 版本或更高版本的 Unity 引擎。

通过安装程序安装加速器

可以直接下载并安装 Unity 加速器,并在安装过程中取消选中注册令牌:

注意:如果将加速器安装在 Linux 系统上,请参阅验证加速器版本

还可以通过 Docker Hub 安装加速器。

在“无头”计算机中安装加速器

在每个平台上都可以从命令行运行安装程序。如果使用参数 --help 来执行安装程序,它将显示各种可用选项。要在没有任何提示的情况下进行完整安装,应该为以下项提供值:

  • --storagedir 设置加速器的目录以存储文件和配置。
  • --registration-token 指定创建加速器后在开发者控制面板中提供的令牌。
  • 使用 --mode unattended 来进行自动化安装,此类型的安装不应进行任何询问。这将使用默认值或提供的其他选项标志的值。
  • 在 Mac OS X 上,需要安装磁盘映像 (DMG) 并运行位于安装程序的应用程序目录中的二进制文件(位于 Contents/MacOS/installbuilder.sh)。

配置编辑器以使用加速器

安装加速器时,安装向导的最后一步按以下格式显示编辑器中引用的 IP 地址和端口:

[IP]:[Port]

要配置您的编辑器来将该加速器用作资源管线版本 2 缓存服务器,请遵循以下步骤进行操作:

  1. 在 Unity 编辑器中,选择编辑 (Edit) > 项目设置 (Project Settings)……(Windows) 或 Unity > 项目设置 (Project Settings)……(OSX)。
  2. 从左侧菜单中选择编辑器 (Editor)
  3. 缓存服务器 (Cache Server) 部分下,将模式 (Mode) 设置为已启用 (Enabled)
  4. 使用设置向导中的加速器 IP 地址填写 IP 地址 (IP address)
  5. 检查连接 (Check Connection) 按钮以测试连接。
项目设置
项目设置

如果希望确保与其他项目隔离,则可以选择与默认名称不同的命名空间前缀。此外,还可以根据需要单独禁用上传或下载。例如,可能希望构建系统只启用上传,而开发人员的编辑器只启用下载。请注意,TLS/SSL 选项是仅从 2020.1 开始的编辑器版本才有的功能,并且加速器还必须针对 TLS 进行配置。

在编辑器主视图中,可以通过查看右下方的状态栏来检查加速器连接(仅限自 2020.1 起的编辑器版本):

项目连接
项目连接

如果愿意,可以通过全局设置配置要使用的加速器,该加速器在默认情况下将用于所有项目,除非被项目设置所覆盖。要配置全局设置,请选择编辑 (Edit) > 偏好设置 (Preferences)……菜单项:

项目连接
项目连接

通过 Docker Hub 安装加速器

Docker Hub 上提供了一个容器,地址为 https://hub.docker.com/repository/docker/unitytechnologies/accelerator。

首次设置

Unity 建议使用持久存储区域托管加速器配置和缓存。若要首次进行此设置,需要在首次运行容器时使用以下一个或多个变量(下面会提供一些示例)。仅当启动过程找不到配置文件时才会使用这些变量,因此在连续运行时可安全地设置它们。

变量 用法
DISABLE_USAGE_STATS 设置为 true 可禁用使用情况统计信息 – 启用使用情况统计信息可以通过向 Unity 提供有价值的反馈来帮助改进加速器的功能和性能。
USER 本地内置面板的用户名。
PASSWORD 本地内置面板的密码。
CERT_HOSTNAME 用于实现 TLS 支持的主机名。这用于重定向等功能,与下面的 CERT_PEM 和 KEY_PEM 一起使用。
CERT_PEM 用于实现 TLS 支持的 cert.pem 路径。如果设置 CERT_HOSTNAME,但是未设置 CERT_PEM,则会采用 <persist_dir>/cert.pem。
KEY_PEM 用于实现 TLS 支持的 key.pem 路径。如果设置 CERT_HOSTNAME,但是未设置 KEY_PEM,则会采用 <persist_dir>/key.pem。

若要覆盖 TLS 设置,请确保在指定的 /agent 路径中有 cert.pem 和 key.pem,然后包含一个 CERT_HOSTNAME,如下所示:

$ docker run --rm -ti -v "${PWD}/agent:/agent" -e 'CERT_HOSTNAME=myhostname.com' -e 'COLLAB_REGISTRATION_TOKEN=ft0bJvbRD' unitytechnologies/accelerator:latest

后续执行

您还可以设置加速器通常会识别的任何环境变量。请参阅 unity-accelerator --all-help 并查找指示 Default: $SOME_VARIABLE 的选项。如果不执行此操作,容器将设置两个变量:

变量 用法
UNITY_ACCELERATOR_PERSIST 容器默认值为 /agent。这是 unity-accelerator.cfg 以及其他持久数据所驻留的目录(cachedir 可能不同)。
UNITY_ACCELERATOR_LOG_STDOUT 容器默认值为 true。如果为 true,则仅将日志输出到 stdout;如果希望将实际日志文件写入持久目录中,则为 false。

运行容器

我们会对我们的 Docker 镜像进行签名,因此强烈建议您启用 Docker 内容信任

$ export DOCKER_CONTENT_TRUST=1

通常,应该能够按如下所示运行加速器:

$ docker run -p 80:80 -p 443:443 -p 10080:10080 -v "${PWD}/agent:/agent" unitytechnologies/accelerator:latest

但是,如果要选择不同的位置供加速器存储配置和缓存工件,则可以选择提供附加环境变量配置值,如下所示:

$ docker run -p 80:80 -p 443:443 -p 10080:10080 -v "${PWD}/agent:/mnt/another_spot" -e "UNITY_ACCELERATOR_PERSIST=/mnt/another_spot" -e "UNITY_ACCELERATOR_DEBUG=true" unitytechnologies/accelerator:latest

若要为本地面板设置用户名和密码,可以使用 USER 和 PASSWORD 环境变量:

$ docker run -p 80:80 --env PASSWORD=[PASSWORD] --env USER=[USERNAME] unitytechnologies/accelerator:latest

公开的端口

以下是 Unity 加速器使用的端口的默认值:80、443、10080、10443。

源资源安全性

Unity Teams Advanced 配合使用时,每个加速器都会收到自己的安全证书以证明有权访问您的组织。在加速器上传或下载任何内容之前,发出请求的 Unity 编辑器使用 SSL/TLS 来安全连接到加速器并验证其真实性。Unity 编辑器发现并连接到加速器时,编辑器不会传递普通的 Unity 用户令牌,而是从 Unity Identity 服务接收特殊令牌。这些令牌用于验证用户的身份并可以访问您组织内的单个项目,从而在使用加速器时保护任何其他组织和项目的访问权限。

或者,在启动 Unity 编辑器时,您可以使用命令行参数来提供加速器缓存服务器配置详细信息。

要指定希望使用加速器缓存服务器,请使用 -EnableCacheServer 参数,而要指定地址和端口号,请使用 -cacheServerEndpoint Address:Port,并将地址 (Address) 和端口 (Port) 替换为缓存服务器的相应详细信息。

注意:加速器缓存服务器要求您的项目使用资源数据库 V2 (ADB2)。从命令行启动 Unity 时,可以使用 -adb2 参数来强制升级到 ADB2。

请参阅命令行参数以了解更多信息。

监测加速器

本地管理员面板

加速器有一个内置面板,用于进行快速监控和配置更改。

加速器配置
加速器配置

有关如何查明面板 URL 的信息,请参阅命令行工具部分;但是,如果知道加速器的 ip 和端口,那么只需使用 http://ip:port/dashboard,加速器便会处理任何需要的重定向。有关完整的指标监控,请参阅直接访问加速器指标,可通过加速器的 unity-accelerator.cfg 文件获得其完整配置。

直接访问加速器指标

每个加速器都将以 /metrics 的形式托管 Prometheus 指标报告,可以从本地网络查询此数据。以下是可以访问的完整指标列表:

指标 描述
process_resident_memory_bytes 加速器使用的内存量。
uta_agent_sys_cpu_percent 系统使用的 CPU 量。
uta_agent_sys_mem_bytes_used 系统使用的内存量。
uta_agent_protobuf_connects Unity 编辑器连接到资源导入管线的服务的次数。
uta_agent_protobuf_bytes_in 从资源导入管线接收到的字节数。
uta_agent_protobuf_bytes_out 发送到资源导入管线的字节数。
uta_agent_protobuf_requests{code="0",method="get"} 发送到资源导入管线的项数。
uta_agent_protobuf_requests{code="1",method="get"} 发送到资源导入管线的项中发生的错误数。
uta_agent_protobuf_requests{code="2",method="get"} 发送到资源导入管线的项中发生的命名空间错误数。
uta_agent_protobuf_requests{code="3",method="get"} 资源导入管线针对尚未缓存的项提出的请求数。
uta_agent_protobuf_requests{code="0",method="put"} 从资源导入管线接收到的项数。
uta_agent_protobuf_requests{code="1",method="put"} 从资源导入管线接收的项中发生的错误数。
uta_agent_protobuf_requests{code="2",method="put"} 从资源导入管线接收的项中发生的命名空间错误数。
uta_agent_protobuf_requests{code="0",method="delete"} 从资源导入管线提出的关于删除项的请求数。
uta_agent_protobuf_requests{code="1",method="delete"} 资源导入管线删除项时发生的错误数。
uta_agent_protobuf_requests{code="2",method="delete"} 资源导入管线提出的删除项请求中发生的命名空间错误数。
uta_agent_protobuf_requests{code="3",method="delete"} 资源导入管线针对尚未缓存的项提出的删除项请求数。
uta_agent_cache_bytes_evicted_unscheduled “计划外”通道过程中从缓存中逐出的字节数。在处理请求期间,磁盘空间不足时会发生计划外逐出。通常,计划的后台逐出应与需求保持一致,因此该指标值的增加表明服务器不堪重负。增加配置的 CacheMinFreeBytes 或 CacheMinFreePercent 可能有助于提供更多可用空间缓冲区,或者可能需要升级基础硬件或安装额外的加速器。
uta_agent_cache_files_evicted_unscheduled 类似于上面的 uta_agent_cache_bytes_evicted_unscheduled 指标,不过是对逐出的文件计数而不是进行字节计数。这可能是更容易发出警报的指标。例如:当文件指标每秒增加超过 1 时发出警报。
uta_agent_protobuf_cache_hits 从缓存满足的资源导入管线请求数。
uta_agent_protobuf_cache_misses 无法从缓存满足的资源导入管线请求数。
uta_agent_protobuf_cache_bytes_out 从缓存提供给资源导入管线的字节数。
uta_agent_protobuf_cache_bytes_in 从资源导入管线接收而存储到缓存中的字节数。

Unity 编辑器日志调试

Unity 编辑器日志可用于查看调试信息。

以下代码块显示了使用资源导入管线 v2 的加速器的日志输出示例。

2019-10-07T11:34:51-0700 Using Asset Import Pipeline V2.
  ...
  2019-08-08T09:04:03-0700 Start importing Assets/Scenes/tame-the-unicorn.png guid(07a0d449dcaef4d2ba104e9d9b350de6)
  2019-08-08T09:04:05-0700 Done importing asset: 'Assets/Scenes/tame-the-unicorn.png' (target hash: 'd5fddd470dd9beedcd7261b6455e436a') in 1.082988 seconds
  2019-08-08T09:04:05-0700 RemoteAssetCache::AddArtifactToCacheServer - artifactKey='Guid(07a0d449dcaef4d2ba104e9d9b350de6) Importer(-1,)' Target hash='d5fddd470dd9beedcd7261b6455e436a'

Querying for cacheable assets in Cache Server:
    86ac778e1a44c9143864797ddacf8cc9:Assets/New Material.mat
RemoteAssetCache - Download - Metadata - success:true, namespace:81e94844d19a16919208533e08183531, key:8d71d5006046bb9d5e4a7172eec3f3b2
RemoteAssetCache - Download - Artifact - success:true, namespace:78b2fdc254b0a4f8a4693a81bb96598a, key:de1eef03efd25a722d1500658bf19038 for asset:'Assets/New Material.mat', time elapsed: 0.005171 seconds
RemoteAssetCache - Download - Artifact - success:true, namespace:78b2fdc254b0a4f8a4693a81bb96598a, key:b19c9d64967a9691abecdb66364ae392 for extension:'Assets/New Material.mat.info', time elapsed: 0.004721 seconds

停止并重新启动加速器服务

加速器作为每个平台的后台进程运行。

Windows

在“设置”(Settings) 菜单中搜索“服务”(Services) 一词或者在运行 (Run) 对话框 (WIN + R) 中运行“_services.msc_”来打开服务面板 (Services Panel)。下一步,在生成的列表中找到“Unity Accelerator”服务。左面板中会显示停止服务 (Stop the service)重新启动服务 (Restart the service) 选项。

Mac OS X

在终端中运行 launchctl 命令以便从 LaunchControl 实用程序控制“com.unity.accelerator”服务。有关更多信息,请访问 https://www.launchd.info/

Linux

使用 service 控制台实用程序来控制“unity-accelerator”服务。有关更多信息,请访问 http://manpages.ubuntu.com/manpages/bionic/man8/service.8.html

维护

加速器服务会在维护期间自动自我更新。当前,该维护期根据运行加速器的计算机而设置为当地时间凌晨 01:00–02:00。仅当加速器发现可用的更新版本时,才会进行自我更新。

加速器的安装日志和卸载日志保存在操作系统的标准临时目录中,名为 unity-accelerator-*install.log。加速器的日志保存在存储目录中,名为 unity-accelerator.log

命令行工具

加速器具有一组大量的命令行工具,可以通过这些工具进行故障排除、配置在通常情况下使用一个或多个加速器。为了便于使用,最好将 unity-accelerator 可执行文件的位置添加到 PATH 中。该可执行文件安装在运行安装程序时选择的路径中,例如 C:\Program Files\Unity\accelerator。

CLI 工具有一个广泛的帮助系统;可以运行不带参数的 unity-accelerator 以开始使用:

$ unity-accelerator
Unity Accelerator v1.0.524+g96c5e18

Run on a local network to speed up transactions with Unity Services.

.....

此外,还可以运行 unity-accelerator --all-help,以便一次性输出所有命令的所有帮助文本。最好通过 less 命令对输出进行管道传输或是将输出重定向到文本文件以进行读取。

例如,在处理特定加速器时,若要重新配置它,最好将工作目录更改为与 unity-accelerator.cfg 文件相同的位置。此外,还可以将 UNITY_ACCELERATOR_PERSIST 环境变量设置为该目录,也可以尝试记住始终使用 --persist <dir> 选项,不过更改工作目录在大多数情况下都是最简单的做法。

一组相当常用的 CLI 工具是面板工具:

$ unity-accelerator dashboard password newaccount
Password: ****
   Again: ****
$ unity-accelerator dashboard list
admin
newaccount
$ unity-accelerator dashboard url
http://172.18.37.249:8080/dashboard/

最后一个工具 dashboard url 可用于查明在浏览器中放置什么 URL 来访问内置面板。

镜像多个加速器

如果需要,可以配置多个加速器以镜像相同的缓存数据。您可能希望在同一网络上运行两个镜像加速器以提高可用性 - 如果其中一个加速器崩溃、出现硬件故障或出于任何原因需要维护,另一个加速器可以作为替补。此外,还可以镜像彼此相距遥远的缓存服务器,例如,总部可能会将其数据镜像到分支机构,从而提供其缓存数据的副本以便在分支机构也可使用。

目前,镜像功能仅提供传出数据功能,也称为“推送”或“转发”。可以推送/转发到多个加速器,甚至是链接它们:A 发送给 B,B 发送给 C,甚至 C 发送回给 A。无需担心循环链;项具有时间戳,因此接收加速器会忽略任何不晚于已有内容的传入项。

我们来演练一个示例,其中加速器 A 的 IP 地址和端口号 (IP:Port) 为 1.1.1.1:1111,加速器 B 为 2.2.2.2:2222。假设两者在开始时都没有数据,因此我们将一个项放入 A 中,请注意它不在 B 中。

$ echo test1 | unity-accelerator cache put 1.1.1.1:1111 namespace1 key1
$ unity-accelerator cache get 1.1.1.1:1111 namespace1 key1
test1
$ unity-accelerator cache get 2.2.2.2:2222 namespace1 key1
key not found

现在我们将 A 配置为转发到 B。我们通过更改 A 的配置来实现此目标,因此登录运行加速器 A 的计算机,关闭加速器,然后:

# Shutdown Accelerator A
$ cd <directory where unity-accelerator.cfg is>
$ unity-accelerator config set ProtobufForwardPuts protobuf:2.2.2.2:2222
# Start Accelerator A back up

我们此时应该能够将另一个项放入 A 的缓存中并看到它转发给 B。

$ echo test2 | unity-accelerator cache put 1.1.1.1:1111 namespace2 key2
$ unity-accelerator cache get 1.1.1.1:1111 namespace2 key2
test2
$ unity-accelerator cache get 2.2.2.2:2222 namespace2 key2
key not found
# It will take up to a minute before the forwarding occurs, due to how the algorithm works with batching, etc. But within a minute or two you should see...
$ unity-accelerator cache get 2.2.2.2:2222 namespace2 key2
test2

但是,这仅涵盖新数据(放入加速器 A 的任何新项都会转发给加速器 B),但不涵盖任何现有数据。在我们的示例中,第一个项仍然不在加速器 B 中。

$ unity-accelerator cache get 2.2.2.2:2222 namespace1 key1
key not found

若要涵盖这种情况,并且如果只想一次性转发所有数据(在从一个加速器切换到新加速器时可能很有用),可以使用“推送”(push) 命令行工具:

$ unity-accelerator cache push 1.1.1.1:1111 2.2.2.2:2222
{"msg":"push completed", "destination":"2.2.2.2:2222", "namespaces":2, "keys":2, "bytes":12, "supercededs":1, "errors":0, "elapsed":"44.054078ms"}
$ unity-accelerator cache get 2.2.2.2:2222 namespace1 key1
test1

推送工具会向第一个加速器发送请求,要求它将所有数据发送给第二个加速器。完成后,第一个加速器会发送回“push completed”响应,其中包含有关所执行操作的详细信息。

可以通过运行unity-accelerator config help | less 并搜索 Forward,来研究附加高级配置选项。可以指定转发并发性、队列大小、错误处理等。

另请注意,您可能希望更改每个镜像加速器的 MaintenanceStart 和 MaintenanceDuration 的配置值,以便它们不会同时全部关闭以进行维护。

故障排除

如果您已经安装加速器,但是某些 Unity 编辑器无法使用它,此问题可能有多种原因。以下故障排除方案可能有助于解决此问题:

检查使用的 Unity 编辑器版本

每个项目参与者都必须使用编辑器版本 2019.3 或更高版本才能使用加速器。

验证用户是否在加速器的本地网络中

确保加速器与遇到问题的项目参与者在同一局域网中运行。加速器对远程工作的参与者无效。

测试加速器的连接

检查遇到问题的计算机是否可以访问加速器。

请将加速器的主机 IP 地址输入到以下 URL 路径中以显示其运行状况页面:

[AcceleratorIP]:[AcceleratorPort]/api/agent-health

如果测试未通过,请确保所有主机和网络防火墙都允许访问加速器的监听 IP 地址和端口 (TCP)。您可能需要与网络管理员协调以允许访问此端口。

验证加速器版本

对于 Linux 系统上安装的加速器,所有 Linux 可执行文件均具有签名文件,您可以对这些文件进行验证以确保没有恶意实体篡改您下载的加速器版本。可使用受信任的 GnuPG 版本来验证签名文件。以下密钥为当前版本签名。包含密钥的公钥块位于 https://collab-accelerator.cloud.unity3d.com/ 中。

pub     rsa4096 2019-12-02
Key fingerprint = 9BC4 B04D F2E8 74E5 64AA 47E7 6D44 3B8B 002C F61F
uid       Unity Technologies ApS (Accelerator signing key) <[email protected]>

要将密钥下载到您的 GPG 存储库,请使用以下命令之一:

$ gpg --keyserver https://collab-accelerator.cloud.unity3d.com/ --search-key "[email protected]"

$ gpg --keyserver https://collab-accelerator.cloud.unity3d.com/ --recv-key 9BC4B04DF2E874E564AA47E76D443B8B002CF62F

要检查您安装的加速器版本是不是原始版本且未经修改,请验证该文件的签名。

加速器安装文件随附了 https://storage.googleapis.com/unity-accelerator-prd/unity-accelerator-installer.sig 中提供的签名文件。使用此签名文件可以验证加速器安装程序:

$ gpg --verify unity-accelerator-installer.sig unity-accelerator-linux-x64-installer.run

在信任密钥之前,请将指纹与伪造或不受信任的密钥中显示的指纹进行对比。信任密钥后,您将看到如下内容:

gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg:                using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Good signature from "Unity Technologies ApS (Accelerator signing key) <[email protected]>" [ultimate]

这意味着签名有效,并且您已信任此密钥。

错误密钥

如果没有正确的分发密钥,以上命令的输出将如下所示:

gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg:                using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Can't check signature: No public key

在此情况下,您必须按照上文中的说明来获取密钥。

伪造或不受信任的密钥

如果您有包含有效签名的密钥副本,但是该密钥未被标记为受信任或该密钥是伪造的,则输出将如下所示:

gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg:                using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Good signature from "Unity Technologies ApS (Accelerator signing key) <[email protected]>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 9BC4 B04D F2E8 74E5 64AA  47E7 6D44 3B8B 002C F61F

如果密钥是伪造的,则必须使用签名文件来验证指纹。如果密钥未被标记为受信任,请编辑密钥,将其标记为受信任。有关更多信息,请参阅 https://www.gnupg.org/gph/en/manual/x334.html

支持

有关将加速器与资源导入管线配合使用的帮助信息,请访问加速器论坛

Caching assets
Unity Accelerator requirements