配置和故障排除 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 Cloud Administration 活动心进行配置，但有些设置只能通过直接在 Direct Access gateway 机器上编辑配置文件来更改

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

租户管理员和网关空间所有者
网关空间中具有可使用数据权限的租户成员

要打开网关设置：

在 Qlik Cloud 租户中，导航至 Administration > 数据网关，然后找到 Direct Access gateway 。
单击行末尾的，然后选择网关设置。

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

设置分为常规设置（如下）及连接器设置。请注意，更改设置可能还需要重新启动 Direct Access gateway 服务。

一般设置

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

代理 ID

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

连接器代理端口

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

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

对 Direct Access gateway 组件执行定期健康检查。健康检查有时最初失败，然后成功。如果运行状况检查在指定阈值后继续失败，则将重新启动 Direct Access gateway 服务。只有在 Qlik 支持人员请求时，您才可以更改此设置。

加载请求超时

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

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 支持人员请求时，您才可以更改此设置。

连接器代理日志记录选项

要排除特定连接器代理组件的故障，有可能需要选择其相应的日志文件。只有在 Qlik 支持人员请求时，您才可以更改此设置。

缓存数据块的内存

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

块恢复持续时间阈值

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

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

DCaaS 端口

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

DCaaS 日志记录级别

为排除故障，您可能需要更改 DCaaS 日志的记录级别。只有在 Qlik 支持人员请求时，您才可以更改此设置。

连接器设置

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

端口

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

日志记录级别

为排除故障，您可能需要更改连接器日志的记录级别。只有在 Qlik 支持人员请求时，您才可以更改此设置。

进程分离

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

在洁净安装的情况下，默认情况下会启用进程隔离。每种连接器类型的默认并发重新加载次数为 9。您可以按照下面的并发重新加载进程数中的说明覆盖默认值。

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

禁用进程分离

Qlik 支持团队可能会要求您禁用进程隔离以进行故障排除。

要关闭进程隔离，请选择禁用。

并发重新加载进程数

为连接器分配的并发重载进程数目，包括命令进程。因此，例如，值为 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 多个表，则可以覆盖默认值。

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

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

在 Qlik Cloud 租户中，导航至 Administration > 数据网关，然后找到 Direct Access gateway 。
单击行末尾的，然后选择重启服务。

您也可以直接在 Direct Access gateway 机器上重启服务，具体方法见启动、停止或重新启动服务

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

虽然大多数 Direct Access gateway 设置都可以在 Qlik Cloud 中进行配置，但有些设置只能通过直接在 Direct Access gateway 机器上编辑配置文件来更改。

覆盖默认的块缓存目录

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

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

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

为此：

使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。
定位 OVERRIDE_CHUNKS_CACHE_DIR 属性，并将其设置为所选目录。
示例：
OVERRIDE_CHUNKS_CACHE_DIR=C:\tmp
信息注释不要将路径括在引号中。
保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。

另请参阅： 缓存数据块的内存

使用 ODBC（经由 Direct Access gateway）连接器时覆盖默认 Qlik Cloud 数据类型

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

有时，由于供应商 ODBC 驱动程序处理源数据类型的问题，在重新加载过程中会出现错误，或者会向 Qlik Cloud 加载不正确的数据。在这种情况下，您可以覆盖 Qlik Cloud 数据类型或其规范（例如比例或精度）。

虽然许多问题可以通过简单地更改 QlikDataType 为 String 来解决，但如果无法做到这一点，我们建议联系 Qlik 支持部门，以获取有关源数据类型可以映射到的 Qlik Cloud 数据类型的指导。

为此：

使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\custom_type_mappings.json 。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。该文件包含 Qlik Cloud 数据类型的一个示例源。
添加一个部分，将有问题的数据类型映射到所需的 Qlik Cloud 数据类型。
在以下示例中（包含在 custom_type_mappings.json 文件中），客户需要将 Qlik Cloud DateTime 数据类型的大小更改为 27。
保存 custom_type_mappings.json 文件并重新启动 Qlik Data Gateway - Direct Access 服务。
重新加载数据。

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

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

为此：

使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。该文件包含 Qlik Cloud 数据类型的一个示例源。
将 AGENT_PONG_TIMEOUT_SECONDS=<time-in-seconds> 添加到文件开头的 # Connector Agent 部分。

示例：
```
{
"Identifier": "Amazon Athena ODBC (x64)",
"NativeDataType": "timestamp with time zone",
"QlikDataType": "DateTime",
"Size": 27,
"IsBit": false
}
```
AGENT_PONG_TIMEOUT_SECONDS=30
信息注释最短时间为 30 秒。
保存 configuration.properties 文件并重新启动 Qlik Data Gateway - Direct Access 服务。

异步执行加载数据请求

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

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

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

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

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

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

使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。
如下所示，将 AsyncLoadDataRequest 替换为 None：
OPTIONAL_CAPABILITIES=None
保存 configuration.properties 文件。

允许使用 REST（通过 Direct Access gateway）连接器连接到localhost

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

您可以允许 REST（通过 Direct Access gateway）连接器连接到 localhost。这便于使用本地（指向网关服务器）REST 端点（如 connector-agent/ 状态端点）来确定代理上的活动负载数。

使用文本编辑器以管理员身份打开 C:\ProgramData\Qlik\Gateway\configuration.properties。如果是通过 Windows 资源管理器执行此操作，请确保已选中显示 > 隐藏项目。
设置 REST_ALLOW_LOCALHOST_CONNECTION=true（设置为 false 以禁用此功能）
保存 configuration.properties 文件。

增加连接到 ODBC 数据源时的错误消息详细信息

出于安全考虑，ODBC 驱动程序返回的默认错误消息包含的信息很少。但是，在某些情况下，您可能需要更多信息来解决特定问题。要获取更详细的错误消息，请将 ShowErrorDetailMessage 属性添加到连接器对话框的高级部分，并将其设置为 True。解决问题后，为了获得最佳安全性，强烈建议删除该属性或将其设置为 False。

查看和下载日志文件

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

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

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

在 Administration 活动中心中，转到数据网关并找到您的 Direct Access gateway。
单击行末尾的，然后选择查看日志。
日志查看器窗口打开。
从左上角的下拉列表中，选择 Qlik 支持部门要求您查看或下载的日志类型。
有以下日志可用：
- Direct Access gateway 日志 (DirectAccessAgent)
- DCaaS logs (dcaas_logs)
- 基于 ODBC 的连接器日志 (odbc-connector_logs)
- SAP BW 连接器日志（QvSAPBwConnector-<日期 + 时间戳>）
- SAP SQL 连接器日志（QvSqlBwConnector-<日期 + 时间戳>）
- 连接器代理日志 (connector-agent_logs_<日期>)
- SAP ODP 连接器日志 (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>) 日志文件。
从相邻的下拉列表中，选择要查看或下载的日志。日志文件按从最新（当前活动的日志文件）到最旧的顺序排列。选择日志文件后，可以使用和按钮分别跳到日志文件的开头或末尾。
提示注释日志文件的视图不会自动更新为最新消息。要更新视图，请单击跳到日志文件的末尾，日志文件将用最新消息更新。
要下载日志文件，请单击下载。
该文件将被下载到您的计算机上，或者系统会提示您保存该文件，具体取决于您的浏览器设置。

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

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

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

更改 DirectAccessAgent 日志级别

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

要查看当前日志记录级别，请运行：
connectoragent configuration getloggers
要将日志记录级别设置为“跟踪”，请运行：
connectoragent configuration setloggers -l Root -v DEBUG
要将日志记录级别设置为“详细”，请运行：
connectoragent configuration setloggers -l Root –v DETAILED_DEBUG

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

更新注册密钥

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

更新注册密钥：

在 Direct Access gateway 服务器上，以管理员身份打开命令提示符并将工作目录更改为 ConnectorAgent 子文件夹（对于默认安装为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent）。
然后运行以下命令：
- 生成新的密钥：
  connectoragent qcs generate_keys
- 显示密钥：
  connectoragent qcs get_registration
  显示密钥：
复制整个密钥，如上面的示例所示。
在 Administration 活动中心中，通过单击相关行末尾的按钮并选择编辑来打开数据网关设置。
将密钥粘贴到密钥字段（替换当前密钥）并保存设置。
返回到直接访问网关服务器并重新启动 Qlik Data Gateway - Direct Access 服务，如管理 Qlik Data Gateway - Direct Access 服务中所述。

本页面有帮助吗？

如果您发现此页面或其内容有任何问题 – 打字错误、遗漏步骤或技术错误 – 请告诉我们！

在此处留下您的反馈