安装代理

Last published : Nov 13, 2026
本文首先介绍 Workspace Environment Management™ (WEM) 代理。本文的其余部分介绍了代理安装向导中的步骤。提供了与代理相关的其他信息。
Related information
开始使用：规划和构建部署

简介

WEM 管理的每台计算机都必须安装 WEM 代理。WEM 代理连接到 WEM 服务并强制执行您在管理控制台中配置的设置。所有通信都通过 HTTPS 使用 Citrix Cloud™ Messaging Service。所有代理都使用本地缓存，确保在网络连接中断时它们可以继续使用现有设置。
WEM 支持管理已加入域和未加入域的计算机。
  • 对于已加入域的计算机，请确保代理主机属于与配置的 Cloud Connector 相同的 Active Directory 域。此外，请确保每个资源位置中的代理主机已正确加入。
  • 在未加入域的计算机上安装代理的过程与在已加入域的计算机上安装代理的过程类似。但是，请确保您满足所有要求并在整个过程中选择正确的选项。有关详细信息，请参阅管理未加入域的计算机。
有三种方法可以将代理连接到 WEM 服务：
  • 云连接器
  • 未加入域
  • 注册
有关这些方法的更多信息，请参阅确定要使用的设置方法。

安装代理

注意：
要从管理控制台以应用程序快捷方式的形式访问 Citrix Workspace 中发布的资源，请确保代理计算机上安装了适用于 Windows 的 Citrix Workspace 应用程序。有关详细信息，请参阅系统要求。
使用以下顺序安装 WEM 代理。

步骤 1：下载代理

从 WEM 服务的“实用程序”选项卡下载 WEM 代理程序包 (Citrix-Workspace-Environment-Management-Agent-Setup.zip)，并在每个代理主机上保存一份副本。

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

重要提示：
如果您选择使用未加入域或注册方法，请跳过此步骤。
可选地，您可以选择配置组策略。WEM 代理程序包中提供的“代理组策略”管理模板添加了“代理主机配置”策略。
  1. 将 WEM 安装包中提供的“代理组策略”文件夹复制到您的 WEM 域控制器。
  2. 添加 .admx 文件。
    1. 转到“代理组策略 > ADMX”文件夹。
    2. 复制这两个文件（Citrix Workspace Environment Management Agent Host Configuration.admx 和 CitrixBase.admx）。
    3. 转到 <C:\Windows>\PolicyDefinitions 文件夹，然后粘贴文件。
  3. 添加 .adml 文件。
    1. 转到“代理组策略 > ADMX > en-US”文件夹。
    2. 复制这两个文件（Citrix Workspace Environment Management Agent Host Configuration.adml 和 CitrixBase.adml）。
    3. 转到 <C:\Windows>\PolicyDefinitions\en-US 文件夹，然后粘贴文件。
  4. 在“组策略管理编辑器”窗口中，转到“计算机配置 > 策略 > 管理模板 > Citrix 组件 > Workspace Environment Management > 代理主机配置”，然后配置以下设置：
    组策略管理编辑器 基本部署的自定义设置。用于部署的自定义代理设置。有关基本部署的可用代理设置的更多信息，请参阅管理基本部署代理。
    基本部署的自定义设置
覆盖代理部署类型。覆盖 WEM 代理部署类型。选择以下选项之一：
  • 云服务部署： 将代理连接到 Citrix Cloud 中的 WEM 服务，提供完整的 WEM 功能。
  • 本地部署： 将代理连接到本地 WEM 部署，提供完整的 WEM 功能。
  • 基本部署： 以单机模式运行代理，功能有限，不连接到 WEM 基础架构。
  • 已禁用： 禁用安装代理的计算机上的所有 WEM 功能。
代理代理配置。WEM 代理依赖 Internet 连接来连接 Citrix Cloud 中的 WEM 服务。代理与服务之间的通信用于以下目的：
  • 将统计信息和状态上传到 WEM 服务
  • 使代理缓存与 WEM 服务数据库保持同步
  • 检索代理设置以及特定于代理配置集的 WEM 设置
您可以选择配置 HTTPS 代理，以定义代理如何与服务通信。为此，请双击代理代理配置策略，然后按此格式键入代理服务器地址：http://<FQDN or IP address>:<port number>。示例：http://10.108.125.51:8080。
注意：
WEM 服务不支持需要身份验证的代理服务器。
代理服务端口。WEM 服务不需要。保持状态“未配置”。
缓存数据同步端口。WEM 服务不需要。保持状态“未配置”。
Citrix Cloud Connectors。配置至少一个 Citrix Cloud Connector。代理主机必须与配置的 Cloud Connector 计算机位于同一 AD 域中。
从 CVAD 服务发现 Citrix Cloud Connector。如果您尚未为代理配置 Cloud Connector，此设置可让您控制代理是否从相关的 Citrix DaaS（以前称为 Citrix Virtual Apps and Desktops™ 服务）部署中发现 Cloud Connector 信息。然后，代理会连接到相应的 Cloud Connector 计算机。
注意：
  • 此设置适用于 WEM 代理在 Citrix DaaS™ 部署中运行的场景。
  • 如果在代理安装期间配置了 Cloud Connector 或启用了 Citrix Cloud Connectors 策略设置，则此策略设置不起作用。
基础设施服务器。WEM 服务不需要。将状态保留为“未配置。”
VUEMAppCmd 额外同步延迟。指定代理应用程序启动器 (VUEMAppCmd.exe) 在启动已发布的资源之前等待的毫秒数。这可确保必要的代理工作首先完成。建议值为 100 到 200。默认值为 0。

步骤 3：安装代理

重要提示：
尽管 .NET Framework 可以在代理安装期间自动安装，但我们建议您在安装代理之前手动安装它。否则，您需要重新启动计算机才能继续安装代理，并且可能需要很长时间才能完成。
代理安装程序 Citrix Workspace™ Environment Management Agent 在代理下载中提供。您可以选择以交互方式或使用命令行安装代理。默认情况下，代理会安装到以下某个文件夹中，具体取决于您的操作系统 (OS)：
  • 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. 在“部署类型”页面上，选择适用的部署类型，然后单击下一步。在此示例中，选择云服务部署。
  6. 您还可以选择基本部署类型。当您选择基本部署类型时，代理将启用默认优化设置，而无需连接到基础架构服务。基本部署类型是全新安装的默认部署类型。
    基本部署
  7. 在“云服务配置”页面上，指定代理连接的 Citrix Cloud Connector，然后单击下一步。
    • 跳过配置。如果满足以下条件，请选择此选项：
      • 您已使用组策略配置了设置。
      • 代理计算机是非域加入计算机。请参阅管理非域加入计算机。
      • 您希望在不配置 Cloud Connector 的情况下注册代理。请参阅注册代理。
    • 配置 Citrix Cloud Connector。通过键入 Cloud Connector 的 FQDN 或 IP 地址的逗号分隔列表来配置代理连接的 Citrix Cloud Connector。
      注意：
      • 键入每个 Citrix Cloud Connector 的 FQDN 或 IP 地址。请务必用逗号 (,) 分隔 FQDN 或 IP 地址。
      • 在配置了多个 Cloud Connector 的情况下，WEM 代理会从列表中随机选择一个可访问的 Cloud Connector。此设计旨在将流量分配到所有 Cloud Connector。
    WEM 代理安装 02
  8. 在“高级设置”页面上，配置代理的高级设置，然后单击下一步。
    • 备用缓存位置（可选）。允许您为代理缓存指定备用位置。单击浏览以导航到适用的文件夹。或者，您可以通过注册表执行此操作。为此，请首先停止 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
  9. 在“准备安装”页面上，单击“安装”。
  10. 单击“完成”退出安装向导。
或者，您可以使用命令行选择 WEM 代理的静默安装。为此，请使用以下命令行:
  • Citrix Workspace Environment Management Agent.exe /quiet Cloud=1
提示：
  • 对于在 WEM 服务部署中运行的代理，请输入 Cloud=1。对于在本地 WEM 部署中运行的代理，请输入 Cloud=0。
  • 您可能需要查阅日志文件以排查代理安装问题。默认情况下，记录安装过程中发生的所有操作的日志文件会在 %TEMP% 中创建。您可以使用 /log log.txt 命令指定保存日志文件的特定位置。
您还可以使用命令行选项指定自定义参数。这样做可以在安装过程中自定义代理和系统设置。有关详细信息，请参阅须知。
安装后，代理作为以下服务运行: Citrix WEM Agent Host Service 和 Citrix WEM Agent User Logon Service。代理以 LocalSystem 身份运行。不支持更改此帐户。代理服务需要“作为本地系统登录”权限。

步骤 4: 重新启动计算机以完成安装

卸载代理

  1. 在安装了代理的计算机上，打开系统的控制面板。
  2. 单击程序和功能。
  3. 选择 Citrix Workspace Environment Management Agent，然后单击菜单中的卸载。
如果在安装 VDA 时将代理作为附加组件安装，请使用 VDA 安装程序随附的 WEM 安装程序 (MSI) 卸载代理。WEM 安装程序 citrix_wem_agent_core.msi 位于 <VDA installer path>\x64\Virtual Desktop Components 中。要卸载作为 VDA 附加组件安装的代理，请完成以下步骤：
  1. 在该文件夹中，右键单击 citrix_wem_agent_core.msi。
  2. 选择卸载。
注意：
卸载代理后，您可以使用 VDA 安装程序或 WEM 安装程序进行安装。从 Citrix Virtual Apps and Desktops 2209 开始，WEM 代理不再作为附加组件包含在 VDA 安装中。要安装它，请使用 Citrix Virtual Apps and Desktops 产品 ISO 上的完整产品安装程序。有关详细信息，请参阅安装核心组件。

下一步操作

如果您想将现有的本地 WEM 数据库迁移到 WEM 服务，请参阅迁移到云。
要直接开始使用 WEM 服务，请启动管理控制台并根据需要配置设置。有两种控制台可用：
我们正在将功能从旧版控制台迁移到 Web 控制台。Web 控制台的响应速度比旧版控制台更快，并提供更多功能。要查看仅在 Web 控制台中可用的功能，请参阅新增功能。

先决条件和建议

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

先决条件

验证是否满足以下要求：
  • Windows 服务 System Event Notification Service 配置为在启动时自动启动。
  • WEM 代理服务 Citrix WEM Agent Host Service 和 Citrix WEM User Logon Service 配置为在启动时自动启动。
  • 代理缓存尽可能驻留在持久位置。使用非持久缓存位置可能会导致潜在的缓存同步问题、过度的网络数据使用、性能问题等。
  • 如果您正在使用 Citrix Virtual Apps and Desktops，WEM 代理可以自动检测持久系统位置，从而无需手动配置。

建议

请遵循本节中的建议，以成功部署代理：
  • 请勿手动操作 Citrix WEM Agent Host Service，例如，使用登录或启动脚本。停止或重新启动 Citrix WEM Agent Host Service 等操作可能会导致 Net Logon 服务停止工作，从而导致其他应用程序出现问题。
  • 请勿使用登录脚本启动 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 代理安装程序会自动启动 Net Logon 服务。

代理缓存实用程序选项

Citrix WEM Agent Host Service 自动处理设置刷新和缓存同步。仅在需要立即刷新设置和同步缓存的情况下使用代理缓存实用程序。
使用命令行在代理安装文件夹中运行 AgentCacheUtility.exe。该可执行文件接受以下命令行参数：
  • -help：显示允许的参数列表。
  • -RefreshCache 或 -r：触发缓存构建或刷新，此功能目前已过时，仅适用于 2401.1.0.1 之前的代理版本。
  • -RefreshSettings 或 -S：刷新代理主机设置，包括适用于 2401.1.0.1 或更高版本代理的代理缓存。
  • -Reinitialize 或 -I：重新初始化代理上的代理缓存，代理会请求立即同步代理缓存，以直接从 WEM 数据库获取最新设置，没有任何延迟。
有关如何使用命令行的详细信息，请参阅以下示例：
  • 刷新代理主机设置：
    • AgentCacheUtility.exe -RefreshSettings
  • 同时刷新代理主机设置和代理缓存：
    • AgentCacheUtility.exe -RefreshSettings -RefreshCache
  • 重新初始化代理缓存：
    • AgentCacheUtility.exe -RefreshCache -Reinitialize

须知

代理可执行文件接受如下所述的自定义参数。

代理设置

请参阅下面的 WEM 代理设置。
  • AgentLocation。允许您指定代理安装位置。指定一个有效的文件夹路径。
  • CloudConnectorList。允许您指定每个 Citrix Cloud Connector 的 FQDN 或 IP 地址。请务必使用逗号 (,) 分隔 FQDN 或 IP 地址。
    云连接器列表(/en-us/workspace-environment-management/service/media/cloud-connector.png)
  • VUEMAppCmdDelay。允许您指定代理应用程序启动器 (VUEMAppCmd.exe) 在启动 Citrix Virtual Apps and Desktops 发布资源之前等待的时间。默认值为 0（毫秒）。您为额外同步延迟间隔键入的值必须是大于或等于零的整数。
  • AgentCacheLocation。允许您为代理缓存指定备用位置。如果配置，代理本地缓存文件将保存到指定位置，而不是代理安装文件夹中。
请考虑以下事项：
  • 如果通过命令行配置了设置，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 Explorer) 可能会在所有策略设置处理完毕之前启动。因此，某些设置可能在用户首次登录时不会生效。如果您希望所有策略设置在用户首次登录时都得到处理，请将该值设置为 1。
  • WaitForNetwork。允许您配置安装期间创建的 WaitForNetwork 注册表项的值（以秒为单位）。此参数指定代理主机等待网络完全初始化和可用的时间。该参数接受 0（最小值）到 300（最大值）范围内的任何整数。默认情况下，此值为 30。
上述三个键在安装期间均在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon 下创建。这些键用于确保用户环境在登录前接收到基础架构服务器地址 GPO。在 Active Directory 或域控制器服务器响应缓慢的网络环境中，这可能会导致在登录屏幕出现之前需要额外的处理时间。Citrix 建议您将 GpNetworkStartTimeoutPolicyValue 键的值设置为至少 30 以使其生效。
  • ServicesPipeTimeout。允许您配置 ServicesPipeTimeout 注册表项的值。该键在安装期间在 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control 下创建。此注册表项会在服务控制管理器报告 WEM 代理服务状态之前添加延迟。此延迟通过阻止代理服务在网络初始化之前启动来防止代理失败。此参数接受任何值（以毫秒为单位）。如果未指定，则使用默认值 60000（60 秒）。
    注意：
    如果未通过命令行配置上述设置，WEM 代理安装程序在安装期间不会处理它们。

示例

您还可以使用以下命令行格式配置设置：
  • "Citrix Workspace Environment Management Agent.exe" <key=value>
例如：
  • 指定代理安装位置和 Citrix Cloud Connectors
    • "Citrix Workspace Environment Management Agent.exe" /quiet AgentLocation="L:\WEM Agent" Cloud=1 CloudConnectorList=cc1.qa.local,cc2.qa.local
  • 将用户登录网络等待时间设置为 60 秒
    • "Citrix Workspace Environment Management Agent.exe" WaitForNetwork=60