在 Windows 服务器上设置 Qlik Data Gateway - Direct Access

上次更新日期：2026/10/28

本主题概述了如何在 Windows 服务器上设置 Qlik Data Gateway - Direct Access。它提供了先决条件和安装说明，并描述了在 Windows 服务器上使用 Qlik Data Gateway - Direct Access 时应注意的限制和注意事项。

使用 Qlik Data Gateway - Direct Access 时的最佳实践

为了在使用 Qlik Data Gateway - Direct Access 时获得成功体验，强烈建议遵守以下最佳实践：

不要将 Direct Access gateway 用于开发、用户验收测试和生产，因为这会增加可用资源过载的风险，并影响系统稳定性。从业务角度来看，资源不足和稳定性下降的组合可能会导致生产应用程序数据的更新延迟。
为了获得最佳性能，请在尽可能靠近数据源的服务器上安装 Direct Access gateway。
Direct Access gateway 应按照以下系统要求安装在专用的 Windows Server 上。不要将其安装在实际的数据库服务器上，也不要与其他 Qlik 产品一起安装，包括但不限于 Qlik DataTransfer、Qlik Sense Desktop 和 Qlik Sense Enterprise。

系统先决条件

本部分介绍了在 Windows 服务器上使用 Qlik Data Gateway - Direct Access 的软件、端口和硬件要求。

软件前提条件

直接访问网关应安装在防火墙后面的 Windows Server 计算机上。服务器应该能够访问您的数据源。

支持的 Windows Server 版本：
- 2016
- 2019
- 2022
- 2025
  
  Windows Server 2025 需要 Qlik Data Gateway - Direct Access 1.7.0 或更高版本。
需要安装三个不同的 .NET 版本。仅安装以下 .NET 版本：
- .NET 4.8：安装时需要。
- .NET 6.0.x 运行时 (x64) 和 ASP.NET Core Runtime 6.0.x (x64)（最新补丁）
  
  新闻注释从 Direct Access gateway 1.6.8开始。NET 6.0.x 不再为必需。
- .NET 8.0.x 运行时 (x64) 和 ASP.NET Core Runtime 8.0.x (x64)（最新补丁）
信息注释
- 不支持安装高于 8.0.x 的 .NET 运行时版本。
- Direct Access gateway 1.6.6 和 1.6.7 需要 .NET 和 ASP.NET Core Runtimes 的 6.0.x 和 8.0.x 两个版本。
有关如何验证当前安装的 .NET 版本的说明，请参阅 https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed。
Microsoft Visual C++ 2015-2022 Redistributable (x64)。如果 Direct Access gateway 安装程序检测到当前未安装可再发行版本，它将提示您安装该软件。

使用 SAP 数据源时的其他软件前提条件

按照为 Qlik Data Gateway - Direct Access 安装 SAP NetWeaver RFC SDK （仅提供英文版本）中的说明，在 Qlik Data Gateway - Direct Access 计算机上安装 SAP NetWeaver RFC SDK。
在 Qlik Data Gateway - Direct Access 计算机上安装 Microsoft Visual C++ 2013 Redistributable (x64)。

所需端口和协议

有关所需的端口和协议，请参阅 所需端口和协议。

系统密码

仅当 Windows 配置为以FIPS 140-2批准的操作模式（FIPS模式）运行时，Qlik Cloud 政府才支持使用 Qlik Data Gateway - Direct Access。要打开 FIPS 模式，请启用 Windows 策略：系统密码：使用符合 FIPS 的算法进行加密、哈希算法和签署。有关更多信息，请参阅在 FIPS 140-2 批准的操作模式下使用 Windows 程序的步骤3。

无需安装其他模块。Qlik Data Gateway - Direct Access 仅使用 Windows 已提供并包含在已验证模块列表中的模块。Qlik Data Gateway - Direct Access通过 .NET 运行时强制仅使用 FIPS 验证的加密算法。

安装 Qlik Data Gateway - Direct Access

设置 Direct Access gateway 涉及需要在 Administration 活动中心和 Direct Access gateway 服务器上执行的步骤。

需要在 Administration 活动中心中执行的数据网关过程需要租户管理员权限。

直接访问网关流程图 - 在 Windows 服务器上的安装步骤。 — Qlik Data Gateway - Direct Access 设置步骤 — 在 Windows 服务器上安装

阶段一：下载 Qlik Data Gateway - Direct Access

在 Administration 活动中心中，选择数据网关。

任何现有的数据网关都将列在一个表中，其中显示了每个网关的基本信息。
单击部署工具栏按钮。

部署数据网关对话框打开。
选择数据网关 - 直接访问 (Windows)，接受 Qlik 客户协议，然后单击下载。Direct Access gateway 安装程序文件 (qlik-data-gateway-direct-access.exe) 将下载到您的机器。

阶段二：在保护数据源的防火墙后面的服务器上安装 Direct Access gateway

这一阶段包括安装 Direct Access gateway。您可以交互或静默安装 Direct Access gateway。

卸载Direct Access gateway不会删除配置设置。换句话说，如果卸载一个版本的 Direct Access gateway ，然后安装另一个版本，新安装的版本将使用与卸载版本相同的配置。

覆盖默认的 Windows 服务帐户需要 Direct Access gateway 1.7.4 或更高版本。

交互式安装 Direct Access gateway

下载完成后，将安装文件复制到防火墙后面的 Windows Server 计算机。确保计算机可以与您的数据源通信。
打开 qlik-data-gateway-direct-access.exe 文件以启动安装向导。
信息注释
- Direct Access gateway 需要 Microsoft .NET 6.x 和 .NET 8.x。如果安装程序检测到已安装早期版本，系统将提示您安装所需的版本。.NET 安装完成后，您需要重新启动 Direct Access gateway 计算机，然后再次运行 Direct Access gateway 安装程序。
- 如果安装程序检测到当前未安装 Microsoft Visual C++ 2015-2022 Redistributable (x64) ，将提示您安装它。
信息注释
- 在设置过程中，您可以选择覆盖以下默认值：
  - 安装路径 (C:\Program Files\Qlik\ConnectorAgent)。
  - 将在其下安装 Direct Access gateway 的 Windows 服务帐户 (LocalSystem)。指定的服务帐户必须对 Direct Access gateway 安装文件夹具有“作为服务登录”权限和“写入”权限。
继续点击下一步直至安装完成。

静默安装、升级和卸载 Direct Access gateway

从 Direct Access gateway 1.6.4 起支持。

静默安装 Direct Access gateway 非常有用，例如，如果您需要在整个组织的多台计算机上安装 Direct Access gateway。如果需要，您还可以覆盖默认的 Windows 服务帐户 (LocalSystem)。

先决条件

在开始静默安装之前，请确保安装所有必备软件的正确版本，因为与交互式安装不同，这在安装过程中无法完成。

安装或升级 Direct Access gateway

以管理员身份打开 CMD 提示符，然后从包含 Direct Access gateway 可执行文件的文件夹中运行以下命令：

qlik-data-gateway-direct-access.exe /S InstallPath="full-path" AcceptEula=yes

其中 full-path 应替换为引号中的实际安装路径，例如 C:\TMP\Qlik。

需要将 AcceptEula 参数设置为“是”。将 AcceptEula 参数设置为“是”，表示您同意 Qlik 客户协议的条款。

覆盖默认的 Windows 服务帐户

默认情况下，Direct Access gateway 安装在 LocalSystem Windows 服务帐户下。

要在其他帐户下安装 Direct Access gateway，请在命令中包含以下参数：

ServiceAccount：服务帐户名称。

信息注释指定的服务帐户必须对 Direct Access gateway 安装文件夹具有“作为服务登录”权限和“写入”权限。
ServicePassword：指定服务帐户的密码。

带有用于覆盖 Windows 服务帐户的参数的示例命令

qlik-data-gateway-direct-access.exe /S InstallPath="C:\TMP\Qlik" AcceptEula=yes ServiceAccount="qliktech.com\user" ServicePassword=kZmbkb8m8BGGz91

卸载 Direct Access gateway

以管理员身份打开 CMD 提示符，然后从包含 Direct Access gateway 可执行文件的文件夹中运行以下命令：

qlik-data-gateway-direct-access.exe /S /uninstall

安装故障排除

安装日志文件可以用于排除安装或升级过程中的故障：

从 Direct Access gateway 1.7.7开始，日志文件的完整路径为：

<Direct Access gateway installation folder>\data\logs\Qlik Data Gateway - Direct Access_<时间戳>.log

如果 Direct Access gateway 版本早于 1.7.7，则日志文件的完整路径为

C:\Users\<user>\AppData\Local\Temp\Qlik Data Gateway - Direct Access_<Timestamp>.log

阶段三：设置 Direct Access gateway

有关详细的设置说明，请参阅 阶段三：设置 Direct Access gateway。

阶段四：注册数据网关

下一步是注册数据网关。这可以通过 Administration 活动中心或在命令行中完成。

您可以使用 Administration 活动中心注册网关。请参阅 选项 1：通过 Administration 活动中心。

您还可以通过命令行自动注册 Direct Access gateway，而无需使用 Administration 活动中心。此方法使用从 OAuth 客户端生成的短期会话令牌。

要自动注册和移除自动注册的网关，您需要以下权限：

自动注册：您需要将注册 Direct Access gateway 管理员权限设置为允许。
移除自动注册的网关：您需要将注册 Direct Access gateway 管理员权限设置为允许。

有关权限的详细信息，请参阅 默认权限和自定义角色。

自动注册仅支持通过命令行进行。用于网关自动注册的 REST API 目前不可用。

先决条件

具有创建和管理 OAuth 客户端的租户管理员权限的 API 密钥。

通过自动注册方式注册网关

在 Direct Access gateway 机器上生成 JSON Web Key (JWK)。此命令在 Direct Access gateway 机器上创建私钥：

ConnectorAgent.exe qcs generate_jwk
复制命令返回的 JWK。
使用 API 密钥，通过租户管理 API 为网关创建 OAuth 客户端，并提供在上一步中复制的 JWK。

curl "https://<tenant-url>/api/v1/oauth-clients" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <api-key>' -d '{"appType":"web","clientName":"<client-name>","description":"","allowedScopes":["admin.direct-access-gateways:register_gateway","admin.direct-access-gateways:delete_gateway"],"allowedAuthMethods":["private_key_jwt"],"publicKeys":[<jwk>],"allowedGrantTypes":["client_credentials"]}'
复制响应中返回的 client_id 值。
将 OAuth 客户端的同意方法设置为受信任。

curl "https://<tenant-url>/api/v1/oauth-clients/<client-id>/connection-configs/me" -X PATCH -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <api-key>' -d '[{"op":"replace","path":"/consentMethod","value":"trusted"}]'
在 Direct Access gateway 机器上创建注册断言：

ConnectorAgent.exe qcs generate_registration_assertion --tenant_url <tenant-url> --client-id <client-id>
请求访问令牌。这也会触发自动创建网关所使用的机器人用户账户。

curl "https://<tenant-url>/oauth/token" -X POST -H 'content-type: application/x-www-form-urlencoded' -d "grant_type=client_credentials" -d "client_id=<client-id>" -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" -d "client_assertion=<assertion>" -d "scope=admin.direct-access-gateways:register_gateway admin.direct-access-gateways:delete_gateway"
查找自动创建的机器人用户。

curl "https://<tenant-url>/api/v1/users" -H 'accept: application/json' -H 'authorization: Bearer <API-key>'
复制 my-bot-client 的 ID。
创建“DAG 注册”角色。

curl "https://<tenant-url>/api/v1/roles" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer API-key' -d '{"name":"DAG Registration","description":"Role for registering a gateway","assignedScopes":["admin.direct-access-gateways:register_gateway", "admin.direct-access-gateways:delete_gateway"]}'
为机器人用户分配租户级角色。

curl "https://<tenant-url>/api/v1/users/<bot-user-ID>" -X PATCH -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <API-key>' -d ' [ { "op": "replace", "path": "/assignedRoles", "value": [ { "name": "DAG Registration" } ] } ]'
获取 Direct Access Gateway 空间。

curl "https://<tenant-url>/api/v1/spaces" -H 'authorization: Bearer <API-key>'
复制 Direct Access Gateway 空间 ID。
将机器人用户添加到空间，并赋予可编辑权限。

curl "https://<tenant-url>/api/v1/spaces/<DAG-space-ID>/assignments" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <API-key>' -d '{"assigneeId": "<Bot-user-ID>","roles": ["consumer","dataconsumer","producer"], "type": "user"}'
如果现有断言已过期，请生成新断言。

ConnectorAgent.exe qcs generate_registration_assertion --tenant_url <tenant-url> --client-id <client-ID>

在命令提示符中按照所需步骤操作。由于 OAuth 客户端已创建，需要使用此 API 调用更新 JWK：

curl "https://<tenant-url>/api/v1/oauth-clients/<client-ID>" -X PATCH -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <API-key>' -d '[{"op":"replace","path":"/publicKeys/0/y","value":"<Y-value-from-JWK>"},{"op":"replace","path":"/publicKeys/0/x","value":"<X-value-from-JWK>"},{"op":"remove","path":"/publicKeys/0/use"},{"op":"replace","path":"/publicKeys/0/kid","value":"<kid-value-from-JWK>"}]'
注册网关：

ConnectorAgent.exe qcs register_gateway --tenant_url <tenant-url> --gateway_name <gateway-name> --gateway_description <gateway-description> --space_name <space-name> --client-id <client-ID> --assertion <assertion>

移除自动注册的网关

使用以下步骤注销通过上述基于会话令牌的自动方法注册的网关。这些步骤还会删除为其创建的 OAuth 客户端、Bot 用户和角色。

生成断言，如使用会话令牌自动注册网关的步骤六中所述。如果现有断言已过期，请使用此命令生成新断言：

ConnectorAgent.exe qcs generate_registration_assertion --tenant_url <tenant-url> --client-id <client-ID>

在命令提示符中按照所需步骤操作。由于 OAuth 客户端已创建，需要使用此 API 调用更新 JWK：

curl "https://<tenant-url>/api/v1/oauth-clients/<client-ID>" -X PATCH -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <API-key>' -d '[{"op":"replace","path":"/publicKeys/0/y","value":"<Y-value-from-JWK>"},{"op":"replace","path":"/publicKeys/0/x","value":"<X-value-from-JWK>"},{"op":"remove","path":"/publicKeys/0/use"},{"op":"replace","path":"/publicKeys/0/kid","value":"<kid-value-from-JWK>"}]'
删除网关：

ConnectorAgent.exe qcs delete_gateway --tenant_url <tenant-url> --gateway_name <gateway-name> --client-id <client-ID> --assertion <assertion>
删除 JWK。

ConnectorAgent.exe qcs delete_jwk
查找为网关创建的机器人用户账户。

curl "https://<tenant-url>/api/v1/users" -H 'accept: application/json' -H 'authorization: Bearer <api-key>'
复制机器人 ID。
删除此机器人用户账户。

curl -X DELETE "https://<tenant-url>/api/v1/users/<bot-user-ID>" -H "Authorization: Bearer <api-key>"
查找为网关创建的“DAG Registration”角色。

curl "https://<tenant-url>/api/v1/roles?limit=1&filter=(name eq \"DAG Registration\")" -H "Authorization: Bearer <api-key>"
复制角色 ID。
删除此角色。

curl -X DELETE "https://<tenant-url>/api/v1/roles/<role-ID>" -H "Authorization: Bearer <api-key>"
删除 OAuth 客户端。

curl -X DELETE "https://<tenant-url>/api/v1/oauth-clients/<client-ID>" -H "qlik-confirm-delete: <client-ID>" -H "Authorization: Bearer <api-key>"

阶段五：在 Direct Access gateway 服务器上启动 Qlik Data Gateway - Direct Access 服务

在直接访问网关服务器上，执行以下操作之一以启动服务：

打开 Windows 服务控制台并启动 Qlik Data Gateway - Direct Access 服务。
以管理员身份打开命令提示符并将工作目录更改为 ConnectorAgent 子文件夹（对于默认安装为 C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent）。然后运行以下命令：

connectoragent service start

将显示服务成功启动的确认。

另请参阅：使用其他帐户运行该服务。

阶段六：将连接添加到数据源

请参阅 阶段六：将连接添加到数据源。

支持的数据源

Windows 服务器安装支持以下 ODBC 连接器：

ODBC 源。更多信息，请参阅 ODBC 数据库 - Qlik Cloud （仅提供英文版本）。
REST 源更多信息，请参阅 REST 源 ‒ Qlik Cloud （仅提供英文版本）。
SAP BW、SAP SQL 和 SAP ODP 源。需要 Direct Access gateway 1.2.0 或更高版本。

有关设置与这些源的连接的信息，请参阅 SAP NetWeaver （仅提供英文版本）。

了解详情

本页面有帮助吗？

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

在此处留下您的反馈