代理

Last published : Nov 13, 2026
Related information
安装和配置

安装和配置代理

注意：
  • 请勿在基础架构服务器上安装 Workspace Environment Management™ (WEM) 代理。
  • 请勿在同一台计算机上安装 WEM 代理和管理控制台。
  • 如果您打算从管理控制台将 Citrix StoreFront 商店中发布的资源作为应用程序快捷方式分配到 WEM 中，请确保在管理控制台和代理主机上安装了适用于 Windows 的 Citrix Workspace 应用程序。有关详细信息，请参阅系统要求。

步骤 1：配置组策略（可选）

您可以选择使用 Agent Group Policies 管理模板为代理配置组策略。WEM 安装包中包含此模板。模板文件分为 .admx 文件和特定语言的 .adml 文件。建议您在域控制器上配置组策略。
要添加代理主机配置策略，请完成以下步骤：
  1. 将 WEM 安装包中提供的 Agent Group Policies 文件夹复制到您的 WEM 域控制器。
  2. 添加 .admx 文件。
    1. 转到 Agent Group Policies > ADMX 文件夹。
    2. 复制这两个文件（Citrix Workspace Environment Management Agent Host Configuration.admx 和 CitrixBase.admx）。
    3. 转到 <C:\Windows>\PolicyDefinitions 文件夹，然后粘贴文件。
  3. 添加 .adml 文件。
    1. 导航到 Agent Group Policies > ADMX > en-US 文件夹。
    2. 复制这两个文件（Citrix Workspace Environment Management Agent Host Configuration.adml 和 CitrixBase.adml）。
    3. 导航到 <C:\Windows>\PolicyDefinitions\en-US 文件夹，然后粘贴文件。
使用 组策略管理编辑器 配置具有以下设置的 GPO：
组策略管理编辑器
基础架构服务器。WEM 基础架构服务器的地址。键入安装了基础架构服务的计算机的名称或 IP 地址。
代理服务端口。代理连接到基础架构服务器的端口。代理服务端口必须与您在基础架构服务配置期间为代理服务端口配置的端口相同。如果未指定，则端口默认为 8286。
缓存数据同步端口。(适用于 Workspace Environment Management 1912 及更高版本；取代 Workspace Environment Management 1909 及更早版本中的缓存同步端口。) 代理缓存同步进程连接到基础架构服务以将代理缓存与基础架构服务器同步的端口。缓存数据同步端口必须与您在基础架构服务配置期间为缓存数据同步端口（WEM 基础架构服务配置 > 网络设置）配置的端口相同。端口默认为 8288，对应于 CachedDataSyncPort 命令行参数。或者，您可以在 WEM 代理的静默安装中使用命令行选项指定端口。例如：
  • citrix_wem_agent_bundle.exe /quiet CachedDataSyncPort=9000
Citrix Cloud™ 连接器。不适用于 WEM 的本地版本。将状态保留为 未配置。
代理配置。不适用于 WEM 的本地版本。将状态保留为 未配置。
VUEMAppCmd 额外同步延迟。指定代理应用程序启动器 (VUEMAppCmd.exe) 在启动 Citrix Virtual Apps and Desktops 已发布资源之前等待的毫秒数。这可确保必要的代理工作首先完成。建议值为 100 到 200。默认值为 0。

步骤 2：安装代理

重要提示：
尽管 .NET Framework 可以在代理安装期间自动安装，但我们建议您在安装代理之前手动安装它。否则，您需要重新启动计算机才能继续代理安装，并且可能需要很长时间才能完成。
您可以在用户环境中运行 Citrix Workspace™ Environment Management Agent。您也可以选择使用命令行安装代理。默认情况下，代理会安装到以下某个文件夹中，具体取决于您的操作系统：
  • C:\Program Files (x86)\Citrix\Workspace Environment Management Agent (在 64 位操作系统上)
  • C:\Program Files\ Citrix\Workspace Environment Management Agent (在 32 位操作系统上)
要以交互方式安装代理，请完成以下步骤：
  1. 在您的计算机上运行 Citrix Workspace Environment Management Agent.exe。
  2. 选择我同意许可条款和条件，然后单击安装。
  3. 在“欢迎”页面上，单击下一步。
    注意：
    “欢迎”页面可能需要一些时间才能显示。当缺少所需软件并在后台安装时，会出现此延迟。
  4. 在“目标文件夹”页面上，单击下一步。
    • 默认情况下，“目标文件夹”字段会自动填充默认文件夹路径。如果要将代理安装到其他文件夹，请单击更改以导航到该文件夹，然后单击下一步。
    • 如果您已安装 WEM 代理，“目标文件夹”字段会自动填充现有安装文件夹路径。
  5. 在“部署类型”页面上，选择适用的部署类型，然后单击下一步。在此示例中，选择本地部署。
    WEM 代理安装 01
  6. 在“基础架构服务配置”页面上，指定代理连接的基础架构服务，然后单击下一步。
    • 跳过配置。如果您已使用组策略配置了此设置，请选择此选项。
    • 配置基础结构服务。允许您通过键入基础结构服务的 FQDN 或 IP 地址来配置基础结构服务。
    • 代理服务端口。默认情况下，值为 8286。
    • 缓存数据同步端口。默认情况下，值为 8288。
    WEM 代理安装 02
  7. 在“高级设置”页面上，为代理配置高级设置，然后单击“下一步”。
    • 备用缓存位置（可选）。允许您为代理缓存指定备用位置。单击“浏览”以导航到适用的文件夹。或者，您可以通过注册表执行此操作。为此，请首先停止 Citrix WEM Agent Host Service，然后修改以下注册表项。
      HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale\代理主机
      名称: AgentCacheAlternateLocation
      类型: REG_SZ
      值: 空
      默认情况下，该值为空。默认文件夹为：<WEM agent installation folder path>\Local Databases Set。如有必要，请指定其他文件夹路径。要使更改生效，请重新启动 Citrix WEM Agent Host Service。如果更改生效，以下文件将显示在文件夹中：LocalAgentCache.db 和 LocalAgentDatabase.db。
      注意：
      错误编辑注册表可能会导致严重问题，可能需要重新安装操作系统。Citrix 无法保证能够解决因不正确使用注册表编辑器而导致的问题。请自行承担使用注册表编辑器的风险。编辑注册表之前，请务必备份注册表。
    • VUEMAppCmd 额外同步延迟（可选）。允许您指定代理应用程序启动器 (VUEMAppCmd.exe) 在已发布资源启动前等待的时间。设置此延迟可确保必要的代理工作首先完成。默认值为 0。
      注意：
      您为额外同步延迟间隔输入的值必须是大于或等于零的整数。
    WEM 代理安装 03
  8. 在“准备安装”页面上，单击“安装”。
  9. 单击“完成”退出安装向导。
或者，您可以选择静默安装 WEM 代理。为此，请使用以下命令行：
  • "Citrix Workspace Environment Management Agent.exe" /quiet Cloud=0
提示：
  • 对于在本地 WEM 部署中运行的代理，请输入 Cloud=0。对于在 WEM 服务部署中运行的代理，请输入 Cloud=1。
  • 您可能需要查阅日志文件以排查代理安装问题。默认情况下，记录安装过程中发生的所有操作的日志文件会在 %TEMP% 中创建。您可以使用 /log log.txt 命令指定日志文件的保存位置。
您还可以使用命令行选项指定自定义参数。这样做可以在安装过程中自定义代理和系统设置。有关详细信息，请参阅须知。
安装后，代理作为 Citrix WEM Agent Host Service（以前称为 Norskale Agent Host Service）和 Citrix WEM Agent User Logon Service 运行。代理以 LocalSystem 帐户运行。我们不支持更改此帐户。该服务需要“作为本地系统登录”权限。

步骤 3：重新启动计算机以完成安装

必备条件和建议

为确保 WEM 代理正常工作，请注意以下必备条件和建议：

先决条件

请验证是否满足以下要求：
  • Windows 服务 System Event Notification Service 配置为在启动时自动启动。
  • WEM 代理服务 Citrix WEM Agent Host Service 和 Citrix WEM User Logon Service 配置为在启动时自动启动。
  • 代理缓存应尽可能驻留在持久位置。使用非持久缓存位置可能会导致潜在的缓存同步问题、过度的网络数据使用、性能问题等。

建议

请遵循本节中的建议，以成功部署代理：
  • 请勿手动操作 Citrix WEM Agent Host Service，例如，使用登录或启动脚本。停止或重新启动 Citrix WEM Agent Host Service 等操作可能会导致 Netlogon 服务停止工作，从而导致其他应用程序出现问题。
  • 请勿使用登录脚本启动 UI 模式或 CMD 模式代理。否则，某些功能可能无法正常工作。

代理启动行为

  • 服务启动后，Citrix WEM Agent Host Service 会自动重新加载通过组策略配置的 Cloud Connector 设置。
  • 如果在首次登录期间代理主机服务未启动，Citrix WEM Agent User Logon Service 会自动启动 Citrix WEM Agent Host Service。此行为可确保正确处理用户配置。
  • 启动时，Citrix WEM Agent Host Service 会自动检查以下本地数据库文件：LocalAgentCache.db 和 LocalAgentDatabase.db。如果虚拟机已预配且本地数据库文件来自基础映像，则数据库文件将自动清除。
  • 当 Citrix WEM Agent Host Service 启动时，它会自动验证代理本地缓存是否已最近更新。如果缓存超过两个配置的缓存同步时间间隔未更新，则会立即同步缓存。例如，假设默认代理缓存同步间隔为 30 分钟。如果缓存在过去 60 分钟内未更新，则在 Citrix WEM Agent Host Service 启动后会立即同步。
  • 在安装过程中，WEM 代理安装程序会将 Windows 服务 System Event Notification Service 配置为自动启动。
  • WEM 代理安装程序在 WEM 代理升级完成后自动启动 Netlogon 服务。

代理缓存实用程序选项

Citrix WEM Agent Host Service 自动处理设置刷新和缓存同步。仅在需要立即刷新设置和同步缓存的情况下使用代理缓存实用程序。
使用命令行在代理安装文件夹中运行 AgentCacheUtility.exe。该可执行文件接受以下命令行参数：
  • -help：显示允许的参数列表。
  • -RefreshCache 或 -r：触发缓存构建或刷新。
  • -RefreshSettings 或 -S：刷新代理主机设置。
  • -Reinitialize 或 -I：与 -RefreshCache 选项一起使用时，重新初始化代理缓存。
有关如何使用命令行的详细信息，请参阅以下示例：
  • 刷新代理主机设置：
    • AgentCacheUtility.exe -RefreshSettings
  • 同时刷新代理主机设置和代理缓存：
    • AgentCacheUtility.exe -RefreshSettings -RefreshCache
  • 重新初始化代理缓存：
    • AgentCacheUtility.exe -RefreshCache -Reinitialize

须知

代理可执行文件接受自定义参数，如“代理设置”和“系统设置”部分中所述。

代理设置

WEM 代理设置包括：
  • AgentLocation。允许您指定代理安装位置。指定一个有效的文件夹路径。
  • AgentCacheLocation。允许您为代理缓存指定一个备用位置。如果已配置，代理本地缓存文件将保存到指定位置，而不是代理安装文件夹中。
  • AgentCacheSyncPort。允许您指定端口，代理缓存同步进程通过该端口连接到基础架构服务，以将代理缓存与基础架构服务器同步。
  • AgentServicePort。允许您指定代理连接到基础架构服务器的端口。
  • InfrastructureServer。允许您指定运行基础架构服务的基础架构服务器的 FQDN 或 IP 地址。
  • VUEMAppCmdDelay。允许您指定代理应用程序启动器 (VUEMAppCmd.exe) 在 Citrix Virtual Apps and Desktops 发布资源启动之前等待多长时间。默认值为 0（毫秒）。您为额外同步延迟间隔输入的值必须是大于或等于零的整数。
请注意以下事项：
  • 如果您通过命令行配置设置，WEM 代理安装程序将使用已配置的设置。
  • 如果您未通过命令行配置设置，并且存在以前配置的设置，安装程序将使用以前配置的设置。
  • 如果您未通过命令行配置设置，并且没有以前配置的设置，安装程序将使用默认设置。

系统设置

与代理主机关联的系统设置包括：
  • GpNetworkStartTimeoutPolicyValue。允许您配置安装期间创建的 GpNetworkStartTimeoutPolicyValue 注册表项的值（以秒为单位）。此参数指定组策略在登录时处理策略期间等待网络可用性通知的时间。该参数接受 1（最小值）到 600（最大值）范围内的任何整数。默认情况下，此值为 120。
  • SyncForegroundPolicy。允许您在代理安装期间配置 SyncForegroundPolicy 注册表值。此策略设置确定组策略处理是否同步。接受的值：0、1。如果未设置该值或您将该值设置为 0，Citrix WEM Agent User Logon Service 不会延迟登录，并且用户组策略设置在后台处理。如果您将该值设置为 1，Citrix WEM Agent User Logon Service 会延迟登录，直到用户组策略设置处理完成。默认情况下，该值在安装期间不会更改。
    重要提示：
    如果组策略设置在后台处理，Windows Shell (Windows 资源管理器) 可能会在所有策略设置处理完毕之前启动。因此，某些设置在用户首次登录时可能不会生效。如果您希望所有策略设置在用户首次登录时都得到处理，请将该值设置为 1。
  • WaitForNetwork。允许您配置安装期间创建的 WaitForNetwork 注册表项的值（以秒为单位）。此参数指定代理主机等待网络完全初始化和可用的时间。该参数接受 0（最小值）到 300（最大值）范围内的任何整数。默认情况下，此值为 30。
前面三个键确保 WEM 代理服务在 Windows 登录屏幕出现之前启动。所有这三个键都在安装期间在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon 下创建。这些键还确保用户环境在登录前接收到基础架构服务器地址 GPO。在 Active Directory 或域控制器服务器响应缓慢的网络环境中，登录屏幕出现之前可能会导致额外的处理时间。我们建议您将 GpNetworkStartTimeoutPolicyValue 键的值设置为至少 30，以使其生效。
  • ServicesPipeTimeout。允许您配置 ServicesPipeTimeout 注册表项的值。该键在安装期间在 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control 下创建。此注册表项会在服务控制管理器被允许报告 WEM 代理服务状态之前添加一个延迟。该延迟通过阻止代理服务在网络初始化之前启动来防止代理失败。此参数接受任何值，以毫秒为单位。如果未指定，则使用默认值 60000（60 秒）。
    注意：
    如果您不使用命令行配置上述设置，WEM 代理安装程序在安装期间不会处理它们。

示例

您可以使用以下命令行格式配置设置：
  • "Citrix Workspace Environment Management Agent.exe" <key=value>
例如：
  • 选择 WEM 代理的静默安装或升级
    • "Citrix Workspace Environment Management Agent.exe" /quiet Cloud=0
  • 将用户登录网络等待时间设置为 60 秒
    • "Citrix Workspace Environment Management Agent.exe" WaitForNetwork=60