排查 Microsoft Purview 自承载集成运行时 (SHIR) 的问题

项目
12/21/2023

本文探讨 Microsoft Purview 中的自承载集成运行时 (SHIR) 的常用故障排除方法。

Azure 数据工厂和 Azure Synapse Analytics 也使用自承载集成运行时 (SHIR)。尽管许多故障排除步骤是相同的，但本指南中的 SHIR 故障排除方法适用于以下产品：

排查 Azure 数据工厂和 Azure Synapse Analytics 的 SHIR 问题

收集特定于 Microsoft Purview 的 SHIR 自承载集成运行时日志

对于在自承载 IR 上运行失败的 Microsoft Purview 扫描，该服务支持从 Windows 事件查看器查看和上传错误日志。

可在以下错误指南中查找你看到的任何错误。若要获得 SHIR 问题的支持和故障排除指导，可能需要生成错误报告 ID 并联系 Azure 支持部门。

若要生成错误报告 ID 以获取 Azure 支持，请按照以下说明操作：

在 Microsoft Purview 治理门户中开始扫描之前：
1. 导航到安装了自承载集成运行时的计算机，并打开 Windows 事件查看器。
2. 在“集成运行时”部分清除 Windows 事件查看器日志。右键单击日志并选择“清除日志”选项。
3. 导航回到 Microsoft Purview 治理门户并开始扫描。
在扫描显示“状态”失败后，导航回到 SHIR VM 或计算机，并在“集成运行时”部分刷新事件查看器。
将显示失败的扫描运行的活动日志。
如需 Microsoft 的更多帮助，请选择“发送日志”。

此时会打开“与 Microsoft 共享自承载集成运行时(SHIR)日志”窗口。
上传日志后，请保存报告 ID 的记录，以便在联系 Azure 支持人员时使用。

自承载集成运行时 (SHIR) 一般故障或错误

Purview SHIR、Azure 数据工厂或 Azure Synapse SHIR 之间存在许多共同错误、警告和问题。以下指南涵盖了许多最常见的问题。

自承载 IR 一般性故障或错误

内存不足问题

现象

尝试使用自承载 IR 运行扫描时，出现 OutOfMemoryException (OOM) 错误。

原因

如果 IR 计算机瞬时内存占用量高，新扫描可能会引发 OOM 错误。该问题可能是由大量的并发活动或内存不足导致的，该错误是设计使然。

解决方案

请检查资源使用情况，确认是否有任何其他软件同时运行，并确认 SHIR 计算机是否满足建议的配置。

自承载 IR 未能加载文件或程序集

现象

您会看到以下错误信息：

“无法加载文件或程序集‘XXXXXXXXXXXXXXXX, Version=4.0.2.0, Culture=neutral, PublicKeyToken=XXXXXXXXX’或其依赖项之一。系统找不到指定的文件。活动 ID:92693b45-b4bf-4fc8-89da-2d3dc56f27c3”

下面是更为具体的错误消息：

“无法加载文件或程序集‘System.ValueTuple, Version=4.0.2.0, Culture=neutral, PublicKeyToken=XXXXXXXXX’或其依赖项之一。系统找不到指定的文件。活动 ID:92693b45-b4bf-4fc8-89da-2d3dc56f27c3”

在进程监视器中，你可以按以下屏幕截图所示设置筛选器。前面的错误消息告诉我们 DLL System.ValueTuple 不在“全局程序集缓存”(GAC) 文件夹中，不在 C:\Program Files\Microsoft Integration Runtime\4.0\Gateway 文件夹中，也不在 C:\Program Files\Microsoft Integration Runtime\4.0\Shared 文件夹中。简单来说，该进程加载 DLL 的顺序是：首先从 GAC 文件夹加载，再从共享文件夹加载，最后从网关文件夹加载。因此，可以从任何有用的路径加载 DLL。

Screenshot of the "Process Monitor Filter" page, listing the filters for the DLL.

解决方案

可以在 C:\Program Files\Microsoft Integration Runtime\4.0\Gateway\DataScan 文件夹中发现 System.ValueTuple.dll 。若要解决此问题，请将 System.ValueTuple.dll 文件复制到 C:\Program Files\Microsoft Integration Runtime\4.0\Gateway 文件夹中。

你可以使用相同的方法来解决其他文件或程序集缺失问题。

详细信息

System.ValueTuple.dll 位于 %windir%\Microsoft.NET\assembly 和 %windir%\assembly 下，因为这是 .NET 行为。

在以下错误中，你可以清楚地了解到 System.ValueTuple 程序集缺失。应用程序尝试检查 System.ValueTuple.dll 程序集时会出现此问题。

"<LogProperties><ErrorInfo>[{"Code":0,"Message":"PoolManager 的类型初始值设定项引发了一个错误。","EventType":0,"Category":5,"Data":{},"MsgId":null,"ExceptionType":"System.TypeInitializationException","Source":"Npgsql","StackTrace":"","InnerEventInfos":[{"Code":0,"Message":"法加载文件或程序集 'System.ValueTuple, Version=4.0.2.0, Culture=neutral, PublicKeyToken=XXXXXXXXX' 或其依赖项之一。系统找不到指定的文件。","EventType":0,"Category":5,"Data":{},"MsgId":null,"ExceptionType":"System.IO.FileNotFoundException","Source":"Npgsql","StackTrace":"","InnerEventInfos":[]}]}]</ErrorInfo></LogProperties>"

有关 GAC 的详细信息，请参阅全局程序集缓存。

自承载集成运行时身份验证密钥缺失

现象

自承载集成运行时在无身份验证密钥的情况下突然脱机，事件日志显示以下错误消息：

“尚未分配身份验证密钥”

Screenshot of the integration runtime event pane showing that the Authentication Key is not yet assigned.

原因

Microsoft Purview 门户中的自承载 IR 节点或逻辑自承载 IR 已被删除，或者执行了干净卸载操作。

解决方案

如果上述两个原因均不适用，你可前往 %programdata%\Microsoft\Data Transfer\DataManagementGateway 文件夹，检查是否删除了 Configurations 文件。如果已删除，请按照 Netwrix 文章检测从 Windows 文件服务器中删除文件的人员中的说明进行操作。

Screenshot of the event log details pane for checking the Configurations file.

由于私钥缺失而无法选择证书

现象

你已将 PFX 文件导入到证书存储中。
通过 IR 配置管理器 UI 选择证书时，收到以下错误消息：

“更改 Intranet 通信加密模式失败。证书 <证书名称> 可能没有能够进行密钥交换的私钥，或者进程可能不具有对私钥的访问权限。有关详细信息，请参阅内部异常。”

Screenshot of the Integration Runtime Configuration Manager Settings pane, displaying a "private key missing" error message.

原因

用户帐户的权限级别较低，无法访问私钥。
此证书是作为签名证书（而不是密钥交换证书）生成的。

解决方案

若要操作 UI，请使用具有适当权限的帐户访问私钥。
通过运行以下命令导入证书：

certutil -importpfx FILENAME.pfx AT_KEYEXCHANGE

运行扫描时，出现 UserErrorJreNotFound 错误消息

现象

尝试使用基于 Java 的工具或程序扫描数据源（例如 Parquet 格式文件）时，会收到类似于以下内容的错误消息：

ErrorCode=UserErrorJreNotFound,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Java Runtime Environment 未找到。转到 http://go.microsoft.com/fwlink/?LinkId=808605 以在 Integration Runtime（自承载）节点机上进行下载和安装。注意 64 位 Integration Runtime 需要 64 位 JRE，而 32 位 Integration Runtime 需要 32 位 JRE。,Source=Microsoft.DataTransfer.Common,''Type=System.DllNotFoundException,Message=无法加载 DLL 'jvm.dll': 无法找到指定模块。 (HRESULT 异常: 0x8007007E),Source=Microsoft.DataTransfer.Richfile.HiveOrcBridge

原因

此问题由以下原因之一导致：

Java Runtime Environment (JRE) 未正确安装在 Integration Runtime 服务器上。
Integration Runtime 服务器缺少 JRE 所需的依赖项。

默认情况下，Integration Runtime 使用注册表项解析 JRE 路径。这些项应在 JRE 安装期间自动设置。

解决方案

请认真遵循本部分所述的步骤。如果注册表修改不正确，可能会发生严重问题。在修改注册表之前，请备份注册表，以便在出现问题时可以还原。

要解决此问题，请按照以下步骤验证 JRE 安装的状态：

请确保在同一平台安装 Integration Runtime (Diahost.exe) 和 JRE。检查以下情况：
- 应在文件夹 C:\Program Files\Java\ 中安装适用于 64 位 ADF Integration Runtime 的 64 位 JRE
  
  注意
  
  文件夹不是 C:\Program Files (x86)\Java\
- JRE 11 支持扫描。 JRE 8 也支持，但低于 JRE 8 的版本尚未针对此用途进行验证。
检查注册表中的相应设置。为此，请按照下列步骤进行操作：
在“运行”菜单中，键入 Regedit，然后按 Enter。
在导航窗格中，找到以下子项：

HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment。

在“详细信息”窗格中，应该有一个“当前版本”项，显示 JRE 版本（例如 1.8）。
在导航窗格的 JRE 文件夹下，找到与版本（例如 1.8）完全匹配的子项。在详细信息窗格中，应该有一个“JavaHome”项。此项的值是 JRE 安装路径。
在以下路径中找到 bin\server 文件夹：

C:\Program Files\Java\jre1.xx.xxx
检查此文件夹是否包含 jvm.dll 文件。如果不包含，请检查 bin\client 文件夹中是否包含。

注意

如果配置与这些步骤中所述不同，请使用 JRE Windows Installer 来解决问题。
如果这些步骤中的所有配置与所述一致，则系统中可能缺少一个 VC++ 运行时库。你可以通过安装 VC++ 2010 可再发行包来解决此问题。

自承载 IR 设置

Integration Runtime 注册错误

现象

出于以下原因之一，你可能偶尔希望在不同的帐户中运行自承载 IR：

公司策略不允许使用服务帐户。
需要进行一些身份验证。

在服务窗格中更改服务帐户后，你可能会发现集成运行时停止工作，并收到以下错误消息：

“Integration Runtime (自承载)节点在注册期间遇到错误。无法连接到 Integration Runtime (自承载)主机服务。”

Screenshot of the Integration Runtime Configuration Manager window, showing an IR registration error.

原因

许多资源仅授予服务帐户访问。将服务帐户更改为另一个帐户时，所有从属资源的权限保持不变。

解决方案

查看 Integration Runtime 事件日志以检查错误。

Screenshot of the IR event log, showing that a runtime error has occurred.

如果事件日志中的错误为“UnauthorizedAccessException”，请执行以下操作：
1. 在 Windows 服务面板中，勾选 DIAHostService 登录服务帐户。
2. 检查登录服务帐户是否具有对 %programdata%\Microsoft\DataTransfer\DataManagementGateway 文件夹的读取/写入权限：。
  - 默认情况下，如果未更改服务登录帐户，则它应具有读取/写入权限。
  - 如果更改了服务登录帐户，请执行以下操作来缓解此问题：
    1. 对当前自承载 IR 执行完全卸载。
    2. 安装自承载 IR 位。
    3. 通过执行以下操作更改服务帐户：
      1. 转到自承载 IR 安装文件夹，然后切换到 Microsoft Integration Runtime\4.0\Shared 文件夹。
      2. 使用提升的权限打开命令提示符窗口。将 <user> 和 <password> 替换为你自己的用户名和密码，然后运行以下命令：dmgcmd.exe -SwitchServiceAccount "<user>" "<password>"
      3. 如果要更改为 LocalSystem 帐户，请确保为此帐户使用正确的格式：dmgcmd.exe -SwitchServiceAccount "NT Authority\System" ""
      4. 请勿使用此格式：dmgcmd.exe -SwitchServiceAccount "LocalSystem" ""
      5. （可选）由于 Local System 具有高于管理员的权限，因此你也可以直接在“服务”中进行更改。
      6. 你可以使用本地/域用户作为 IR 服务登录帐户。
    4. 注册 Integration Runtime。
如果错误为“Integration Runtime 服务 (DIAHostService) 未能启动。请确保有足够的权限启动系统服务”，请执行以下操作：
1. 在 Windows 服务面板中，勾选 DIAHostService 登录服务帐户。
2. 检查登录服务帐户是否具有用于启动 Windows 服务的“以服务形式登录”权限：

详细信息

如果上述两种解决方法模式都不适用于你的情况，请尝试收集以下 Windows 事件日志：

应用程序和服务日志 > Integration Runtime
Windows 日志 > 应用程序

找不到“注册”按钮来注册自承载 IR

现象

注册自承载 IR 时，“注册”按钮未显示在“配置管理器”窗格中。

原因

自 Integration Runtime 3.0 发行以来，为了实现更干净、更安全的环境，删除了现有集成运行时节点上的“注册”按钮。如果某个节点已注册到某个集成运行时（无论是否联机），则必须卸载之前的节点，然后安装并注册该节点，才能将该节点重新注册到另一个集成运行时。

解决方案

在控制面板中，卸载现有的 Integration Runtime。

重要

在下面的过程中，选择“是”。在卸载过程中请勿保留数据。
如果没有 Integration Runtime 安装程序 MSI 文件，请转到下载中心以下载最新的 Integration Runtime。
安装 MSI 文件，并注册 Integration Runtime。

因 localhost 而无法注册自承载 IR

现象

使用 get_LoopbackIpOrName 时，无法在新计算机上注册自承载 IR。

调试： 出现运行时错误。 “Microsoft.DataTransfer.DIAgentHost.DataSourceCache”的类型初始化表达式引发了异常。数据库查找期间发生不可恢复的错误。

异常详细信息： System.TypeInitializationException：“Microsoft.DataTransfer.DIAgentHost.DataSourceCache”的类型初始化表达式引发了异常。 ---> System.Net.Sockets.SocketException: 数据库查找 System.Net.Dns.GetAddrInfo(String name) 期间发生不可恢复的错误。

原因

此问题通常在解决 localhost 时出现。

分辨率

使用 localhost IP 地址 127.0.0.1 托管文件，然后解决问题。

自承载设置失败

现象

无法卸载现有 IR，无法安装新 IR，或无法将现有 IR 升级为新 IR。

原因

集成运行时的安装取决于 Windows Installer 服务。你可能会遇到安装问题，原因如下：

可用磁盘空间不足。
权限不足。
Windows NT 服务已锁定。
CPU 使用率太高。
MSI 文件托管位置的网络慢。
意外改动了某些系统文件或注册表。

IR 服务帐户无法获取证书访问权限

现象

通过 Microsoft Integration Runtime 配置管理器安装自承载 IR 时，会生成一个包含受信任证书颁发机构 (CA) 的证书。无法将证书应用于加密两个节点之间的通信，并显示以下错误消息：

"未能更改内部网通信加密模式: 未能授予集成运行时服务帐户对证书 <证书名称> 的访问权限。错误代码 103

Screenshot displaying the error message "... Failed to grant Integration Runtime service account certificate access".

原因

证书使用的是尚不受支持的密钥存储提供程序 (KSP) 存储。到目前为止，自承载 IR 仅支持加密服务提供程序 (CSP) 存储。

解决方案

在这种情况下，建议使用 CSP 证书。

解决方案 1

若要导入证书，请运行以下命令：

Certutil.exe -CSP "CSP or KSP" -ImportPFX FILENAME.pfx

Screenshot of the certutil command for importing the certificate.

解决方案 2

若要转换证书，请运行以下命令：

openssl pkcs12 -in .\xxxx.pfx -out .\xxxx_new.pem -password pass: <EnterPassword> openssl pkcs12 -export -in .\xxxx_new.pem -out xxxx_new.pfx

转换前后：

Screenshot of the result before the certificate conversion.

Screenshot of the result after the certificate conversion.

自承载集成运行时版本 5.x

若要升级为自承载集成运行时版本 5.x，我们需要 .NET Framework 运行时 4.7.2 或更高版本。在下载页中，你会发现最新的 4.x 版本和最新的两个 5.x 版本的下载链接。

对于 Azure 数据工厂 v2 和 Azure Synapse 客户：

如果自动更新已打开，并且你已将 .NET Framework 运行时升级到 4.7.2 或更高版本，则自承载集成运行时会自动升级到最新的 5.x 版本。
如果自动更新已打开，并且你尚未将 .NET Framework 运行时升级到 4.7.2 或更高版本，则自承载集成运行时不会自动升级到最新的 5.x 版本。自承载集成运行时仍然保留为当前的 4.x 版本。你可以在门户和自承载集成运行时客户端中看到有关 .NET Framework 运行时升级的警告。
如果自动更新已关闭，并且你已将 .NET Framework 运行时升级到 4.7.2 或更高版本，则可以手动下载最新的 5.x，并将其安装在计算机上。
如果自动更新已关闭，并且你尚未将 .NET Framework 运行时升级到 4.7.2 或更高版本。则当你尝试手动安装自承载集成运行时 5.x 并注册密钥时，你需要先升级 .NET Framework 运行时版本。

对于 Azure 数据工厂 v1 客户：

自承载集成运行时 5.X 不支持 Azure 数据工厂 v1。
自承载集成运行时将自动升级到最新版本 4.x。并且最新版本 4.x 不会过期。
如果尝试手动安装自承载集成运行时 5.x 并注册密钥，将收到自承载集成运行时 5.x 不支持 Azure 数据工厂 v1 的通知。

自承载 IR 连接问题

自承载集成运行时无法连接到云服务

现象

尝试注册自承载集成运行时的时候，配置管理器显示以下错误消息：

“Integration Runtime (自承载)节点在注册期间遇到错误。”

Screenshot of the "The Integration Runtime (Self-hosted) node has encountered an error during registration" message.

原因

自承载 IR 无法连接到服务后端。此问题通常是防火墙中的网络设置导致的。

解决方案

检查集成运行时服务是否正在运行。如果是，转到步骤 2。
如果自承载 IR 上没有配置代理（这是默认设置），请在安装了自承载集成运行时的计算机上运行以下 PowerShell 命令：
```
 (New-Object System.Net.WebClient).DownloadString("https://wu2.frontend.clouddatahub.net/")
```
注意

服务 URL 可能会有所不同，具体取决于数据工厂或 Synapse 工作区实例的位置。若要查找服务 URL，请使用数据工厂或 Azure Synapse 实例中 UI 的“管理”页查找“集成运行时”，并单击自承载 IR 对其进行编辑。然后选择“节点”选项卡，并单击“查看服务 URL” 。
下面是预期的响应：
如果未收到预期的响应，请根据情况使用以下方法之一：
- 如果收到“无法解析远程名称”消息，则表明存在域名系统 (DNS) 问题。请联系你的网络团队来修复此问题。
- 如果收到“ssl/tls 证书不受信任”消息，请检查证书 (https://wu2.frontend.clouddatahub.net/) 在计算机上是否受信任，然后使用证书管理器安装公共证书。此操作应该会缓解此问题。
- 转到“Windows”>“事件查看器(日志)”>“应用程序和服务日志”>“Integration Runtime”，检查是否存在由 DNS、防火墙规则或公司网络设置导致的故障。如果发现此类故障，请强行关闭连接。每个公司都有自己自定义的网络设置，因此请与网络团队联系以排查这些问题。

如果在自承载集成运行时上配置了“代理”，请验证代理服务器是否可以访问服务终结点。有关示例命令，请参阅 PowerShell, web requests, and proxies（PowerShell、Web 请求和代理）。

 $user = $env:username
 $webproxy = (get-itemproperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet
 Settings').ProxyServer
 $pwd = Read-Host "Password?" -assecurestring
 $proxy = new-object System.Net.WebProxy
 $proxy.Address = $webproxy
 $account = new-object System.Net.NetworkCredential($user,	[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($pwd)), "")
 $proxy.credentials = $account
 $url = "https://wu2.frontend.clouddatahub.net/"
 $wc = new-object system.net.WebClient
 $wc.proxy = $proxy
 $webpage = $wc.DownloadData($url)
 $string = [System.Text.Encoding]::ASCII.GetString($webpage)
 $string

下面是预期的响应：

Screenshot of the expected PowerShell command response.

注意

代理注意事项：

检查是否需要将代理服务器放在“安全接收方”列表中。如果需要，请确保这些域在“安全接收方”列表中。
检查 SSL/TLS 证书“wu2.frontend.clouddatahub.net/”在代理服务器上是否受信任。
如果在代理上使用 Active Directory 身份验证，请将服务帐户更改为可作为“Integration Runtime 服务”访问该代理的用户帐户。

无法建立 SSL/TLS 安全通道的信任关系

现象

自承载 IR 无法连接到 Microsoft Purview。

转到 Windows>事件查看器（日志）>应用程序和服务日志>Integration Runtime 查看自承载 IR 事件日志时，你将看到以下错误消息：

“The underlying connection was closed:无法建立 SSL/TLS 安全通道的信任关系。根据验证过程，远程证书无效。”

检查服务的服务器证书最简单方法是在浏览器中打开服务 URL。例如，在安装了自承载 IR 的计算机上打开检查服务器证书链接 ((https://eu.frontend.clouddatahub.net/)，然后查看服务器证书信息。

Screenshot of the check server certificate pane of the Azure Data Factory service.

Screenshot of the window for checking the server certification path.

原因

此问题有两个可能的原因：

原因 1：服务的服务器证书的根 CA 在安装了自承载 IR 的计算机上不受信任。
原因 2：你在环境中使用了代理，代理替代了服务的服务器证书，而安装了自承载 IR 的计算机不信任已替换的服务器证书。

解决方案

对于原因 1：请确保服务的服务器证书及其证书链在安装了自承载 IR 的计算机上受信任。
对于原因 2：请在自承载 IR 计算机上信任被替换的根 CA，或者将代理配置为不替换服务的服务器证书。

有关在 Windows 上信任证书的详细信息，请参阅安装受信任的根证书。

详细信息

我们推出了一个新的 SSL 证书，该证书从 DigiCert 签名。查看 DigiCert 全局根 G2 是否在受信任的根 CA 中。

Screenshot showing the DigiCert Global Root G2 folder in the Trusted Root Certification Authorities directory.

如果此证书不在受信任的根 CA 中，请在此处下载。

后续步骤

有关故障排除的更多帮助，请尝试以下资源：

通过

排查 Microsoft Purview 自承载集成运行时 (SHIR) 的问题

收集特定于 Microsoft Purview 的 SHIR 自承载集成运行时日志

自承载集成运行时 (SHIR) 一般故障或错误

自承载 IR 一般性故障或错误

内存不足问题

自承载 IR 未能加载文件或程序集

自承载集成运行时身份验证密钥缺失

由于私钥缺失而无法选择证书

运行扫描时，出现 UserErrorJreNotFound 错误消息

自承载 IR 设置

Integration Runtime 注册错误

找不到“注册”按钮来注册自承载 IR

因 localhost 而无法注册自承载 IR

自承载设置失败

IR 服务帐户无法获取证书访问权限

自承载集成运行时版本 5.x

自承载 IR 连接问题

自承载集成运行时无法连接到云服务

无法建立 SSL/TLS 安全通道的信任关系

后续步骤

其他资源