# 配置和故障排除 Qlik Data Gateway - Direct Access

本主题描述了您可以执行的用于 Direct Access gateway 配置和故障排除的各种操作。

信息注释本主题中描述的所有配置选项也可通过 Direct Access gateway 公共 API 执行。如需了解更多信息，请参阅 https://qlik.dev/apis/rest/direct-access-agents/

## 从 Qlik Cloud 租户配置 Direct Access gateway

虽然 Direct Access gateway 默认设置适用于大多数环境，但您可能需要覆盖默认设置以提高性能、解决问题（通过日志记录设置）或克服各种连接问题。

信息注释

* 1.7.2 或更高版本支持从 Qlik Cloud 配置 Direct Access gateway，但建议升级到最新版本，以便从全套配置选项中获益。

* 虽然大多数 Direct Access gateway 设置都可以在 Qlik CloudAdministration 活动心进行配置，但有些设置只能通过[直接在 Direct Access gateway 机器上](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Configur2)编辑配置文件来更改

要编辑 Qlik Cloud 中的设置，需要以下任一权限：

* 租户管理员和网关空间所有者

* 网关空间中具有可使用数据权限的租户成员

要打开网关设置：

1. 在 Qlik Cloud 租户中，导航至 Administration > 数据网关，然后找到 Direct Access gateway 。

2. 单击行末尾的 the 网关设置 icon，然后选择。

   此时将打开 <名称> 的网关设置 对话框。

   设置分为常规设置（如下）及[连接器设置](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Connecto)。请注意，更改设置可能还需要[重新启动 Direct Access gateway 服务](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Restarti)。

### 一般设置

无论使用哪个连接器，这些设置都与 Direct Access gateway 的一般功能相关。

#### 代理 ID

与 Direct Access gateway 公共 API 一起使用的代理 ID。

#### 连接器代理端口

连接到连接器代理时使用的端口。此设置无法更改。

#### 连接器代理运行状况故障阈值

对 Direct Access gateway 组件执行定期健康检查。健康检查有时最初失败，然后成功。如果在达到指定阈值后健康检查持续失败，Direct Access gateway 服务将被重启。只有在 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)人员请求时，您才可以更改此设置。

#### 加载请求超时

当网络中断发生时，重新加载可能会失败，并出现以下错误：

Connector error: The session does not exist (DirectAccess-1509)

Connector error: The stream session expired for the load data request (DirectAccess-1012)

如果您经常遇到上述错误，请尝试将超时时间延长至 5-10 分钟。

#### 连接器代理日志记录级别

出于故障排查目的，您可能需要更改连接器代理组件的日志记录级别。只有在 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)人员请求时，您才可以更改此设置。

#### 连接器代理日志记录选项

若要排查特定连接器代理组件的问题，您可能需要选择其对应的日志文件。 只有在 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)人员请求时，您才可以更改此设置。

#### 将连接器代理日志文件大小限制为

设置连接器代理日志文件在滚动到新文件之前的最大大小（以 MB 为单位）。

#### 将连接器代理文件的保留期限限制为

设置连接器代理日志文件在自动删除前的保留天数。

#### 缓存数据块的内存

对于每次重新加载操作，Direct Access gateway 可将数据块缓存在内存中，并将其卸载到磁盘（当超出分配给缓存的大小时）。如果您不使用自动恢复，并且经常遇到 4025、4020 和 4021 错误，这尤其有用。当达到指定的阈值时，网关将把下一个加密块卸载到 Direct Access gateway 机器的磁盘上。值为 0（默认值）将禁用分块恢复。

#### 块恢复持续时间阈值

这是区块恢复持续时间的阈值（以分钟为单位）。如果在达到恢复持续时间阈值时重新加载尚未恢复，则将失败并显示相应的消息。

此选项对于在长时间恢复后可能超过三小时限制的重新加载非常有用。例如，假设从数据库检索数据需要 90 分钟，但一旦重新加载开始，其中一个块就会遭到损坏。在这种情况下，所有区块都将存储在缓存中，并从缓存发送。在这种情况下，整个重新加载过程（存储在缓存中 + 实际重新加载）可能需要三个小时才能完成。

#### 覆盖默认缓存目录

设置新的缓存目录。

#### DCaaS 端口

连接到 DCaaS 时要使用的端口。此设置无法更改。

#### DCaaS 日志记录级别

出于故障排除目的，您可能需要更改 DCaaS 日志的日志级别。只有在 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)人员请求时，您才可以更改此设置。

#### 将 DCaaS 日志文件的保留时间限制为（天）

您可以限制 Qlik Data Gateway - Direct Access 保留组件日志文件（连接器、DCaaS、代理等）的天数。超过指定天数的日志文件将被自动删除。

#### 数据端口范围起始

设置用于进程隔离的数据端口范围起始端口。

#### 加载性能指标

这些配置属性与负载性能结果相关。这些属性控制网关计算机上保留的数据量，以及随着时间的推移如何清理这些数据。

信息注释从 Direct Access gateway 1.7.17 开始支持。

* 启用加载性能指标记录：选择是否持久化加载性能指标。

* 启用基准保留清理：选择是否自动清理基准记录。

* 基准保留：设置在清理前保留基准记录的天数。

* 基准保留检查间隔：设置检查可清理的基准记录的时间间隔。

* 基准保留数据库大小：为基准记录设置以 MB 为单位的目标数据库大小。

* 基准保留清理批次大小：设置每个清理批次要删除的基准记录数。

### 连接器设置

要更改连接器设置，请选择左侧的连接器类型，然后根据需要在下方更改设置。

#### 端口：

连接到数据源时要使用的端口。此设置无法更改。

#### 日志记录级别

出于故障排除目的，您可能需要更改连接器日志的日志级别。只有在 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)人员请求时，您才可以更改此设置。

#### 进程分离

信息注释

需要 Direct Access gateway 1.6.1 或更高版本。

进程隔离允许具有 Direct Access gateway 服务器操作系统访问权限的管理员控制每个连接器类型可用于重新加载和/或元数据命令的进程数。在多个连接器进程之间分散重新加载和/或元数据命令，通过减少每个连接器进程上同时运行的重新加载和/或元数据命令的次数，可以提高隔离级别。这反过来又可以在发生连接器崩溃的情况下提高整体 Direct Access gateway 稳定性。

在洁净安装的情况下，默认情况下会启用进程隔离。每种连接器类型的并发重新加载/或元数据命令的默认数量为 9。您可以按照下文 并发重新加载/命令进程数 中所述覆盖默认值。

有以下选项可用：

* 已禁用：出于故障排除目的，x 可能会要求您禁用进程隔离。

* 元数据：仅对元数据命令启用进程隔离。这可能很有用，例如，对于使用不支持多线程的ODBC驱动程序，但希望并发运行元数据命令（主要用于预览目的）的客户。

  信息注释支持版本 Direct Access gateway 1.7.9。

* 重新加载（默认）：仅对重新加载命令启用进程隔离。

* 全部：为 reload 和 metadata 命令启用进程隔离。

  信息注释支持版本 Direct Access gateway 1.7.9。

#### 并发重新加载/命令进程数

为连接器分配的并发重新加载/命令进程数目，包括命令进程。因此，例如，值为 30 意味着最多 29 次并发重新加载/命令。请注意，只在启用进程隔离时，该设置才有意义。

信息注释从 1.6.7 版本 Direct Access gateway 开始，此值可以超过 10，无需更改其他设置。为了完全隔离特定连接器类型的重新加载（即每个连接器进程不超过一个重新加载），此值应设置为最小值 30，但根据工作负载，您可能需要将其设置为高达 60。

#### 重新加载会话寿命

信息注释仅与 ODBC（通过 Direct Access gateway）连接器相关。

如果 Direct Access gateway 和 Qlik Cloud 之间的连接空闲 20 秒或更长时间，则重新加载操作有时可能会失败，并出现以下错误：

Invalid object name '#<TempTableName>' (indicating that the Direct Access gateway temp tables are unavailable).

默认会话寿命为 20 秒，但如果您经常遇到此错误，可以根据需要延长会话寿命。

#### 要卸载的最大表数

信息注释

* 仅与 ODBC（通过 Direct Access gateway）连接器相关。

* 需要 Direct Access gateway 1.7.1 或更多版本。

默认情况下，从数据库中最多检索 10000 个表。若您的数据库有 10,000 多个表，则可以覆盖默认值。

#### 显示详细错误消息

信息注释

* 仅与基于 ODBC 的连接器相关。

* UI 中的可见性需要 Direct Access gateway 1.7.11 或更高版本。

出于安全考虑，ODBC 驱动程序返回的默认错误消息包含的信息很少。但是，在某些情况下，您可能需要更多信息来解决特定问题。要生成更详细的错误消息，请启用此选项。解决问题后，为了获得最佳安全性，强烈建议禁用此选项。

#### 限制 Direct Access gateway 使用 REST 连接器可以访问的 URL

您可以限制对可通过 REST 连接器访问的特定 URL 或 URL 路径的访问。

信息注释您所做的任何更改（添加、编辑或删除 URL）只有在重新启动 Direct Access gateway 服务后才会生效。

要限制对特定 URL 的访问，请在 允许的 URL 字段中输入该 URL，然后点击 添加。要限制对 URL 路径的访问，请执行相同的操作，但要在 URL 后附加一个星号 (\*)。根据需要重复。

示例

在以下示例中，允许的URL列表包含两个条目：

* 第一个条目仅允许访问`https://mypublicrestservice.com/restricted/source`。

* 第二个条目允许访问`https://mypublicrestservice.com/open`及其下的任何路径，例如`https://mypublicrestservice.com/open/shared`

| 允许的 URL |
| --- |
| `https://mypublicrestservice.com/restricted/source` |
| `https://mypublicrestservice.com/open`\* |

编辑或删除URL

要编辑 URL，请单击行末尾的 the Edit Outline icon 按钮，然后根据需要编辑 URL。然后单击 the Tick icon 以保存更改，或单击 the Cross icon 以取消。

要删除 URL，请单击行末尾的 the Bin Outline icon 按钮。

另请参阅：[创建 REST 连接](https://help.qlik.com/en-US/cloud-services/Subsystems/REST_Connector_help/Content/Connectors_REST/Create-REST-connection/Create-REST-connection.htm) （仅提供英文版本）。

#### 使用文件连接器限制 Direct Access gateway 可访问的路径列表

您可以限制通过文件连接器访问的路径。您还可以将一个路径与一个或多个空间配对，以进一步限制对指定路径的访问。

信息注释

* 从 Direct Access gateway 1.7.6 开始支持配对空间。

* 当使用 Direct Access gateway 1.7.4 或 1.7.5 时，您所做的任何更改（添加、编辑或删除路径或空间）只有在重启 Direct Access gateway 服务后才会生效。

* 只有具有 可使用数据 角色或更高级别（可编辑、可在应用程序中编辑数据、可管理）的用户才能访问这些路径。

* 所有 Windows 文件系统和网络驱动器都受支持，包括标准 DOS 路径和 UNC 路径。

要限制对特定路径的访问，请在文件路径字段中输入路径，然后点击添加。根据需要重复。

要将空间与路径配对，在添加路径后，点击行末尾的the Edit Outline icon按钮，然后从配对空间 列的下拉列表中选择一个或多个空间。如果路径与空间配对，则只有属于至少一个空间的用户才能访问指定的路径。请注意，指定空间的成员将能够从他们所属的任何空间（即使未明确定义）访问路径，包括他们的个人空间。

示例

在以下示例中，文件路径列表包含两个条目：

* 第一个条目允许任何具有所需角色的用户访问`C:\mypath\source.`

* 第二个条目仅允许mosheSharedSpace空间的成员访问`C:\restricted`。

| 源文件路径 | 成对空间 |
| --- | --- |
| C:\mypath\source | 未选择空间 |
| C:\restricted | mosheSharedSpace |

编辑或删除条目

要编辑条目，请单击行末尾的 the Edit Outline icon 按钮，然后根据需要编辑条目。然后单击 the Tick icon 以保存更改，或单击 the Cross icon 以恢复更改。

要删除条目，请单击行末尾的 the Bin Outline icon 按钮。

另请参阅：[文件（通过 Direct Access gateway）](https://help.qlik.com/en-US/cloud-services/Subsystems/Web_Storage_Provider_Connectors_help/Content/Connectors_StorageProvider/Storage%20provider%20connectors/File-DG-storage-provider-connector.htm) （仅提供英文版本）。

### 按连接禁用分块恢复

信息注释需要 Direct Access gateway 1.7.16 或更高版本。

Direct Access gateway 会在重新加载操作期间自动恢复损坏的数据块（加密数据段）。即使网络中断或数据源问题导致分块丢失，这也有助于重新加载成功。

默认情况下，所有连接均已启用分块恢复。但是，如果您希望优先考虑重新加载速度而非弹性，或者您的工作负载不需要恢复，则可以针对每个连接禁用此功能。

要禁用特定连接的分块恢复：

1. 在您的 Qlik Cloud 租户中，打开相关的连接器。
2. 找到高级部分。
3. 将 disableDataChunksRecovery (名称) 设置为 true (值)
4. 保存您的更改。

您还可以通过 Direct Access gateway 公共 API 禁用分块恢复。有关 API 详细信息，请参阅 [Direct Access Gateway REST API](https://qlik.dev/apis/rest/direct-access-agents/#put-api-v1-direct-access-agents-agentId-connectors-connectorType-files-fileType)。

信息注释每个连接的设置优先于全局 块恢复持续时间阈值 设置（在常规网关设置中配置）。这允许针对每个连接进行细粒度控制。

### 监控 1.7.16 中的重新加载性能

信息注释需要 Direct Access gateway 1.7.16 或更高版本。

Direct Access gateway 1.7.16 包含针对重新加载数据流吞吐量的自动性能增强。这些优化默认启用，不需要任何配置。

包括以下改进：

* 线程池优化：增强的线程池管理减少了开销，并提升了高并发重新加载期间的资源利用率。

* WebSocket 协议增强：改进了 Direct Access gateway 与 Qlik Cloud 之间的 WebSocket 处理，降低了延迟并提高了吞吐量。

* 自适应调步：动态调步算法可根据网络状况和队列深度调整数据传输速率，从而防止拥塞和超时。

若要验证性能改进，请监控您环境中的重新加载时间和日志。与先前版本相比，您应该会注意到重新加载完成时间更快。如果您遇到异常行为或性能下降，请联系 [x](https://community.qlik.com/t5/Support/ct-p/qlikSupport)。

### 其他 ODBC（通过 Direct Access gateway）连接器设置

使用 ODBC（通过 Direct Access gateway）连接器时，您可以限制特定 DSN 和驱动程序的使用，并覆盖默认数据类型映射。

信息注释

* 仅与 ODBC（通过 Direct Access gateway）连接器相关。

* UI 中的可见性需要 Direct Access gateway 1.7.11 或更高版本。

#### 仅允许特定 DSN

出于安全或管理原因，您可能希望限制某些 DSN 的使用。

为此

1. 从连接器列表中选择 ODBC 并向下滚动到 DSNs 部分。

2. 仅启用您想要允许的 DSN。

   在ODBC（通过 Direct Access gateway）连接器对话框中，当选择系统 DSN时，只有允许的 DSN 会出现在ODBC 源下拉列表中。

3. 重启 Qlik Data Gateway - Direct Access 服务。

#### 仅允许特定驱动程序

出于安全或管理原因，您可能希望限制某些驱动程序的使用。

为此

1. 从连接器列表中选择ODBC ，然后向下滚动到驱动程序部分。

2. 仅打开您要允许的驱动程序。

3. 重启 Qlik Data Gateway - Direct Access 服务。

   在 ODBC（通过 Direct Access gateway）连接器对话框中，当选择 ODBC 驱动程序时，只有允许的驱动程序才会显示在 ODBC 源下拉列表中。

#### 覆盖默认的 Qlik Cloud 数据类型映射

有时，由于供应商 ODBC 驱动程序处理源数据类型的问题，在重新加载过程中会出现错误，或者会向 Qlik Cloud 加载不正确的数据。在这种情况下，您可以覆盖源数据类型与 Qlik Cloud 数据类型之间的默认映射。

为此

1. 从连接器列表中选择ODBC ，然后向下滚动到驱动程序部分。

2. 找到您的驱动程序，然后点击行尾的![](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/Icons/arrow_down.svg)以展开该部分。

3. 点击添加数据类型映射。

   将显示以下列（属性）：

   * 源数据类型： 源数据类型。

   * Qlik Cloud 数据类型：源数据类型将映射到的 Qlik Cloud 上的数据类型。

   * 大小：Qlik Cloud 上映射的数据类型的大小（精确度）。

   * IsBit：映射的数据类型是否为 bit（存储 1 或 0 值）。

4. 设置每个属性并保存您的设置。

   映射将保存，如下例所示：

   | 源数据类型 | Qlik Cloud 数据类型 | 大小 | IsBit |
   | --- | --- | --- | --- |
   | 带时区的时间戳 | 日期时间 | 27 | false |

5. 重启 Qlik Data Gateway - Direct Access 服务。

6. 重新加载数据。

警告注释虽然许多问题可以通过简单地更改 QlikDataType 为 String 来解决，但如果无法做到这一点，我们建议联系 [Qlik 支持](https://community.qlik.com/t5/Support/ct-p/qlikSupport)部门，以获取有关源数据类型可以映射到的 Qlik Cloud 数据类型的指导。

编辑和删除映射

编辑映射

* 单击行末尾的 ![](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/Icons/edit.svg) 并根据需要编辑列。

删除映射

* 单击行末尾的 ![](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/Icons/delete.svg)。

### 更改设置后重新启动 Direct Access gateway

某些设置只有在重启 Direct Access gateway 服务后才会应用。在这种情况下，保存设置时会提示您重启服务。如果有激活的重载，在重载完成之前，您将无法重启服务。当没有激活重载时，您可以随时按以下方式重启服务：

1. 在 Qlik Cloud 租户中，导航至 Administration > 数据网关，然后找到 Direct Access gateway 。

2. 单击行末尾的 the 重启服务 icon，然后选择。

您也可以直接在 Direct Access gateway 机器上重启服务，具体方法见[启动、停止或重新启动服务](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-managing.htm#Starting)

## 直接在 Direct Access gateway 机器上配置 Direct Access gateway

虽然大多数 Direct Access gateway 设置都可以[在 Qlik Cloud 中进行配置](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Configur)，但有些设置只能通过直接在 Direct Access gateway 机器上编辑配置文件来更改。

### 覆盖默认的块缓存目录

信息注释需要 Direct Access gateway 1.7.1 或更多版本。

对于每次重新加载操作，Direct Access gateway 可将数据块缓存在内存中，并将其卸载到磁盘（当超出分配给缓存的大小时）。如果系统驱动器上没有足够的磁盘空间，则可以覆盖默认块缓存目录 (C:\ProgramData\Qlik\Gateway\tmp) 。

信息注释为了确保稳定性和优化性能，最佳做法是只使用本地路径。

为此：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 定位 OVERRIDE\_CHUNKS\_CACHE\_DIR 属性，并将其设置为所选目录。

   示例：

   OVERRIDE\_CHUNKS\_CACHE\_DIR=C:\tmp

   信息注释不要将路径括在引号中。

3. 保存 configuration.properties 文件。

4. 根据安装工作流，执行以下选项之一：

   * Windows 服务器安装：

     重新启动 Qlik Data Gateway - Direct Access 服务，如[配置和故障排除 Qlik Data Gateway - Direct Access](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Managing)中所述。

   * 容器化安装：

     重启 direct-access-agent 容器。

另请参阅：[缓存数据块的内存](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Memory)

### 强制 Direct Access gateway 重新连接到 Qlik Cloud

默认情况下，如果Direct Access gateway 与 Qlik Cloud 断开连接，则应在 45 秒后重新连接。如果您发现需要更长的时间，可以强制网关更快地重新连接。

为此：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。该文件包含 Qlik Cloud 数据类型的一个示例源。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 将 AGENT\_PONG\_TIMEOUT\_SECONDS=<time-in-seconds> 添加到文件开头的 # Connector Agent 部分。

   示例：

   AGENT\_PONG\_TIMEOUT\_SECONDS=30

   信息注释最短时间为 30 秒。

3. 保存 configuration.properties 文件。

4. 根据安装工作流，执行以下选项之一：

   * Windows 服务器安装：

     重新启动 Qlik Data Gateway - Direct Access 服务，如[配置和故障排除 Qlik Data Gateway - Direct Access](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Managing)中所述。

   * 容器化安装：

     重启 direct-access-agent 容器。

### 异步执行加载数据请求

信息注释

需要 Direct Access gateway 1.7.5 或更高版本。

在代理上异步执行加载数据请求显著缩短了云服务需要等待代理响应的时间。

要启用异步加载数据请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 如果文件还不存在，请将以下一行添加至文件：

   OPTIONAL\_CAPABILITIES=AsyncLoadDataRequest

   如果 OPTIONAL\_CAPABILITIES= 已经存在另一个参数（例如AsyncLoadSlotRequest），只需将其追加到现有参数中，中间用逗号分隔，不留空格。

   示例：

   OPTIONAL\_CAPABILITIES=AsyncLoadSlotRequest,AsyncLoadDataRequest

3. 保存 configuration.properties 文件。

4. 仅适用于容器化安装：重启 direct-access-agent 容器。

提示注释下一次重新加载时将接收更改，因此无需重新启动 Direct Access gateway 服务。所有更改都将记录到 connector-agent\_logs\_[date].txt 文件中。

要禁用异步加载数据请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 设置 OPTIONAL\_CAPABILITIES=None，如果有其他 AsyncLoadDataRequest 参数，则直接删除 OPTIONAL\_CAPABILITIES。

3. 保存 configuration.properties 文件。

4. 仅适用于容器化安装：重启 direct-access-agent 容器。

### 异步下载文件

信息注释从 Direct Access gateway 1.8.1 开始支持。

AsyncFileDownloadRequest 是文件连接器下载的一项可选功能。如果未协商该功能，文件下载仍保持同步。

要启用异步文件下载请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 如果文件还不存在，请将以下一行添加至文件：

   OPTIONAL\_CAPABILITIES=AsyncFileDownloadRequest

   如果 OPTIONAL\_CAPABILITIES= 已经存在另一个参数（例如AsyncFileDownloadRequest），只需将其追加到现有参数中，中间用逗号分隔，不留空格。

   示例：

   OPTIONAL\_CAPABILITIES=AsyncLoadDataRequest,AsyncFileDownloadRequest

3. 保存 configuration.properties 文件。

提示注释下一次重新加载时将接收更改，因此无需重新启动 Direct Access gateway 服务。所有更改都将记录到 connector-agent\_logs\_[date].txt 文件中。

要禁用异步文件下载请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 设置 OPTIONAL\_CAPABILITIES=None，如果有其他 AsyncFileDownloadRequest 参数，则直接删除 OPTIONAL\_CAPABILITIES。

3. 保存 configuration.properties 文件。

### 异步请求负载时段

信息注释

需要 Direct Access gateway 1.7.7 或更高版本。

在创建重载数据 WebSocket 至 Qlik Cloud 的过程中，异步请求加载时段可缓解 Direct Access gateway 的临时命令管道拥塞。这在同时进行大量重新加载时可能很有用。

信息注释只有在 [Qlik 支持人员](https://community.qlik.com/t5/Support/ct-p/qlikSupport)的指导下，您才可以启用此功能。

要启用异步加载插槽请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 如果文件还不存在，请将以下一行添加至文件：

   OPTIONAL\_CAPABILITIES=AsyncLoadSlotRequest

   如果 OPTIONAL\_CAPABILITIES= 已经存在另一个参数（例如AsyncLoadDataRequest），只需将其追加到现有参数中，中间用逗号分隔，不留空格。

   示例：

   OPTIONAL\_CAPABILITIES=AsyncLoadDataRequest,AsyncLoadSlotRequest

3. 保存 configuration.properties 文件。

提示注释下一次重新加载时将接收更改，因此无需重新启动 Direct Access gateway 服务。所有更改都将记录到 connector-agent\_logs\_[date].txt 文件中。

要禁用异步加载插槽请求，请执行以下操作：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 设置 OPTIONAL\_CAPABILITIES=None，如果有其他 AsyncLoadSlotRequest 参数，则直接删除 OPTIONAL\_CAPABILITIES。

3. 保存 configuration.properties 文件。

### 配置连接器启动

您可以增大超时值和连接器启动的尝试次数。这在同时进行大量重新加载时可能很有用。增加这些参数会给 Direct Access gateway 更多的时间和尝试来运行连接器，然后以失败退出并要求重新启动。

信息注释只有在 [Qlik 支持人员](https://community.qlik.com/t5/Support/ct-p/qlikSupport)的指导下，您才可以启用此功能。

信息注释

需要 Direct Access gateway 1.7.7 或更高版本。

调整连接器启动参数：

1. 使用文本编辑器以管理员身份打开以下文件。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

   * Windows 服务器安装：

     C:\ProgramData\Qlik\Gateway\configuration.properties

   * 容器化安装：

     /usr/share/Qlik/Gateway/configuration.properties

2. 将以下行添加到文件中：

   # CONNECTOR STARTUP TIMEOUT between 30 and 120 seconds

   CONNECTOR\_STARTUP\_TIMEOUT\_SECONDS=your-value

   # CONNECTOR STARTUP MAX ATTEMPTS between 1 and 5

   CONNECTOR\_STARTUP\_MAX\_ATTEMPTS=your-value

   信息注释为防止命令管道拥塞，调整这些值时需要启用 AsyncLoadDataRequest，如上文异步请求载入槽中所述。禁用 AsyncLoadSlotRequest 之后，这些设置将分别恢复为固定的传统值 30 和 3。

3. 保存 configuration.properties 文件。

4. 仅适用于容器化安装：重启 direct-access-agent 容器。

### 覆盖进程隔离设置的默认起始端口

启用进程隔离后，您现在可以覆盖 Direct Access gateway 用于与所有隔离的连接器进程进行进程间通信的默认起始端口 (49152)。当默认端口被其他进程占用时，这会很有用。

信息注释

* 只有在 [Qlik 支持人员](https://community.qlik.com/t5/Support/ct-p/qlikSupport)的指导下，您才可以启用此功能。

* 需要 Direct Access gateway 1.7.8 或更高版本。

* 此功能也通过[公共 API](https://qlik.dev/apis/rest/direct-access-agents/) 提供支持。

为此：

1. 使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。

2. 在 # Connector Agent 部分下，将以下行添加到文件中：

   DATA\_PORT\_RANGE\_START=port-value

   其中 port-value 是默认起始端口。

3. 保存 configuration.properties 文件。

4. 根据安装工作流，执行以下选项之一：

   * Windows 服务器安装：

     重新启动 Qlik Data Gateway - Direct Access 服务，如[配置和故障排除 Qlik Data Gateway - Direct Access](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Managing)中所述。

   * 容器化安装：

     重启 direct-access-agent 容器。

## 指标收集器

在典型的客户环境中，每天都存在大量数据重新加载通过 Direct Access gateway 进入 Qlik Cloud 分析。记录与监控受这些重新加载影响的资源消耗和利用率的能力将帮助客户相应地规划其重新加载。

新的指标收集器（在 Direct Access gateway 机器上后台运行）提供 Direct Access gateway、连接器及操作系统的基本资源利用率日志记录和监控。指标收集器可以在本地通过 JSON 文件配置，也可通过[公共 API](https://qlik.dev/apis/rest/direct-access-agents/) 配置。

### 配置指标收集器

在 Direct Access gateway 计算机上，打开以下文件并根据需要进行配置：

* Windows 服务器安装：

  <INSTALL\_DIR>\ConnectorAgent\MetricsCollector\metricscollectorsettings.json

* 容器化安装：

  /usr/runMetricsCollector/metricscollectorsettings.json

#### 配置收集器设置 (MetricsCollectorSettings)

* `Enabled`: 设置为 `true` (默认) 以启用指标收集，或 `false` 以禁用它。

* `BaseScrapeIntervalSeconds`: 每隔多久（秒）轮询一次连接器指标。每个连接器都有自己的轮询间隔。

* `Port`: API 或指标连接器使用的端口（通过 Direct Access gateway 的 REST）。

* `LocalDataRetentionDays`: 早于指定值的数据将从本地数据库中删除。

* `localDataRetentionDatabaseSizeInMb:` 要在网关计算机上存储的指标数据的总大小（以 MB 为单位）。默认值为 500 MB。旧数据会被删除，以确保配额不会超出。

  信息注释

  * 需要 Direct Access gateway 1.7.10 或更高版本。

  * 大量并发重新加载可能需要增加默认值。例如，一个有 60 个并发重新加载的租户可能需要多达 1 GB。

* `DataRetentionCheckIntervalMinutes`: 保留检查的频率。

* `LocalDatabaseFileLocation`：本地数据库的 位置。这也可以是 UNC 路径。默认位置如下：

  * Windows 服务器安装：

    C:\ProgramData\Qlik\Gateway\tmp

  * 容器化安装：

    /usr/share/Qlik/Gateway/tmp

#### 配置连接器设置 (ConnectorConfigurations)

对于所有 Direct Access gateway 连接器，您可以设置指标轮询间隔 (`ScrapeIntervalSeconds`) 并启用 (`true`) 或禁用 (`false`) 指标收集。

#### 示例 metricscollectorsettings.json 文件

```
{
  "MetricsCollectorSettings": {
    "Enabled": true,
    "BaseScrapeIntervalSeconds": 1,
    "Port": 5052,
    "LocalDataRetentionDays": 30,
    "localDataRetentionDatabaseSizeInMb": 500,
    "DataRetentionCheckIntervalMinutes": 60,
    "LocalDatabaseFileLocation": ""
  },
  "ConnectorConfigurations": {
    "OdbcConnector": {
      "MetricsCollectionEnabled": true,
      "ScrapeIntervalSeconds": 30
    },
    "SystemMetrics": {
      "MetricsCollectionEnabled": true,
      "ScrapeIntervalSeconds": 30
    },
    "ConnectorAgent": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    },
    "RestConnector": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    },
    "SapSqlConnector": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    },
    "SapBwConnector": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    },
    "SapPackageConnector": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    },
    "FileConnector": {
      "MetricsCollectionEnabled": false,
      "ScrapeIntervalSeconds": 30
    }
  }
}
```

### 加载指标

使用 REST（通过 Direct Access gateway）连接器从 Direct Access gateway 机器收集指标。

为此：

1. 在 REST（通过 Direct Access gateway） 连接设置中，启用 允许使用 localhost 连接。

   有关详细信息，请参见 [创建 REST 连接](https://help.qlik.com/en-US/cloud-services/Subsystems/REST_Connector_help/Content/Connectors_REST/Create-REST-connection/Create-REST-connection.htm) （仅提供英文版本）。

2. 将 http://localhost:5052/api/metrics 添加到允许的 URL 列表中。

   请参见上文中的 [限制 Direct Access gateway 使用 REST 连接器可以访问的 URL](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Limiting)。

3. 重启 Direct Access gateway 服务。

4. 创建应用程序，并通过 REST（通过 Direct Access gateway）连接从 http://localhost:5052/api/metrics 加载指标。

### 支持的指标

* 系统指标：

  * network\_bytes\_sent\_total: 自系统启动以来通过 Direct Access gateway 传输的总字节数

  * network\_bytes\_received\_total: 自系统启动以来通过 Direct Access gateway 接收的总字节数

* 连接器指标：

  * process\_start\_time\_seconds: 进程启动以来经过的时间（秒）。

  * process\_cpu\_seconds\_total: CPU处于特定状态的累计秒数

  * process\_virtual\_memory\_bytes: 进程消耗的虚拟内存当前大小（字节）。

  * process\_working\_set\_bytes: 进程工作集的当前大小（以字节为单位）。

  * process\_private\_memory\_bytes: 进程消耗的私有内存的当前大小（以字节为单位）。

  * process\_num\_threads: 进程使用的线程数。

## 查看和下载日志文件

日志文件提供有关 Direct Access gateway 操作的信息。Qlik 支持人员可能会要求您提供日志文件以进行故障排除。您可以在日志查看器中查看或下载日志文件。在正常情况下，没有理由检查日志文件，但如果您遇到重复故障或其他问题，日志文件通常有助于查明原因。

信息注释查看和下载日志需要可以使用数据角色。

要打开日志查看器，请执行以下操作：

1. 在 Administration 活动中心中，转到数据网关并找到您的 Direct Access gateway。

2. 单击行末尾的 the 查看日志 icon，然后选择。

   日志查看器窗口打开。

3. 从左上角的下拉列表中，选择 Qlik 支持部门要求您查看或下载的日志类型。

   有以下日志可用：

   * Direct Access gateway 日志 (DirectAccessAgent)

   * DCaaS logs (dcaas\_logs)

   * 基于 ODBC 的连接器日志 (odbc-connector\_logs)

   * SAP BW 连接器日志（QvSAPBwConnector-<日期 + 时间戳>）

   * SAP SQL 连接器日志（QvSqlBwConnector-<日期 + 时间戳>）

   * 连接器代理日志 (connector-agent\_logs\_<日期>)

   * SAP ODP 和 SAP Report 连接器日志 (QvSapConnectorPackage-<process\_id>)

   * REST 连接器日志 (rest-connector\_logs\_<timestamp>)

   * 文件连接器日志 (file-connector\_logs\_<timestamp>)

   信息注释从 Direct Access gateway 1.7.1 开始，连接器的启动、退出和重启事件都将写入 Direct Access gateway(DirectAccessAgent) 日志文件。在以前的版本中，它们被写入连接器代理日志 (connector-agent\_logs\_<date>) 日志文件。

4. 从相邻的下拉列表中，选择要查看或下载的日志。日志文件按从最新（当前活动的日志文件）到最旧的顺序排列。选择日志文件后，可以使用 the 用于滚动到顶部的箭头 icon 和 the 用于滚动到底部的箭头 icon 按钮分别跳到日志文件的开头或末尾。

   提示注释日志文件的视图不会自动更新为最新消息。要更新视图，请单击 the 用于滚动到底部的箭头 icon 跳到日志文件的末尾，日志文件将用最新消息更新。

5. 要下载日志文件，请单击下载。

   该文件将被下载到您的计算机上，或者系统会提示您保存该文件，具体取决于您的浏览器设置。

### 正在打开 Direct Access gateway 计算机上的 Direct Access gateway 日志

除了可以从 Direct Access gateway 活动中心下载 Administration (DirectAccessAgent) 日志外，还可以直接从 Direct Access gateway 计算机打开这些日志。

对于默认安装，这些日志位于：

C:\Program Files\Qlik\ConnectorAgent\data\logs

* Windows 服务器安装：

  C:\Program Files\Qlik\ConnectorAgent\data\logs

* 容器化安装：

  /usr/data/logs

#### 更改 DirectAccessAgent 日志级别

为排除故障，您可能需要更改 DirectAccessAgent 日志的记录级别。DirectAccessAgent 负责连接 Qlik Cloud 服务。要查看和更改 DirectAccessAgent 日志的日志详细级别，请从 ConnectorAgent 子文件夹运行以下命令（默认安装位置为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent）。

* 要查看当前日志记录级别，请运行：

  * Windows 服务器安装：

    connectoragent configuration getloggers

  * 容器化安装：

    dotnet ConnectorAgent.dll configuration getloggers

* 要将日志记录级别设置为“跟踪”，请运行：

  * Windows 服务器安装：

    connectoragent configuration setloggers -l Root -v DEBUG

  * 容器化安装：

    dotnet ConnectorAgent.dll configuration setloggers -l Root -v DEBUG

* 要将日志记录级别设置为“详细”，请运行：

  * Windows 服务器安装：

    connectoragent configuration setloggers -l Root –v DETAILED\_DEBUG

  * 容器化安装：

    dotnet ConnectorAgent.dll configuration setloggers -l Root –v DETAILED\_DEBUG

有关其他日志记录选项，请参阅下文 Qlik Cloud 中的配置 Direct Access gateway 。

## 更新注册密钥

如果密钥损坏或怀疑数据网关服务器被未经授权的用户访问，则可能需要更改注册密钥。

更新注册密钥：

1. 根据您的安装工作流，执行以下选项之一：

   * Windows 服务器安装：

     在 Direct Access gateway 服务器上，以管理员身份打开命令提示符并将工作目录更改为 ConnectorAgent 子文件夹（对于默认安装为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent）。

   * 容器化安装：

     在 direct-access-agent 容器中打开控制台。

2. 然后运行以下命令：

   * 生成新的密钥：

     * Windows 服务器安装：

       connectoragent qcs generate\_keys

     * 容器化安装：

       dotnet ConnectorAgent.dll qcs generate\_keys

   * 显示密钥：

     * Windows 服务器安装：

       connectoragent qcs get\_registration

     * 容器化安装：

       dotnet ConnectorAgent.dll qcs get\_registration

     显示密钥：

     ![Direct Access 注册密钥的图像](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/da_reg_key.png)

3. 复制整个密钥，如上面的示例所示。

4. 在 Administration 活动中心中，通过单击相关行末尾的 the 编辑 icon 按钮并选择来打开数据网关设置。

5. 将密钥粘贴到密钥字段（替换当前密钥）并保存设置。

6. 返回 Direct Access gateway 服务器，并根据安装工作流执行以下操作之一：

   * Windows 服务器安装：

     重新启动 Qlik Data Gateway - Direct Access 服务，如[配置和故障排除 Qlik Data Gateway - Direct Access](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Gateways/direct-access-gateway-troubleshooting.htm#Managing)中所述。

   * 容器化安装：

     重启 direct-access-agent 容器。