.NET 版本 - 知行之桥文档

的 .NET 版本包含一个独立的内置 Web 服务器，也可以托管在 IIS 中。本节介绍在 Windows 中托管应用程序的各种选项。如果没有使用 IIS 的经验，建议使用内置服务器。内置服务器会在安装时自动部署，并为服务器级管理任务提供简单界面，例如配置日志、将应用程序作为服务运行以及启用 TLS/SSL。

使用内置服务器

本节说明如何配置独立的内置 Web 服务器，包括如何托管 SSL/TLS 连接以及配置云网关（反向 SSH 隧道）。托管在内置服务器上时，应用程序可以作为 Windows 服务运行：

右键单击任务栏中的图标，然后单击 服务器选项。
选择 作为 Windows 服务运行。
保存更改。

如果需要在 Connections 系统设置 页面上安装驱动程序，并在安装过程中遇到权限错误，请为知行之桥服务账户（默认是 Network Service）授予对 www\Web.Config 和 www\bin 的 write 权限。

托管 TLS/SSL 连接（内置服务器）

您可以要求使用 TLS，也可以继续以明文形式提供服务。本节介绍如何在 Windows 版应用程序随附的内置服务器中托管 TLS/SSL 连接。若要为 Java 版本部署 TLS/SSL，请参阅用于托管应用程序的 Java servlet 文档。

右键单击 Windows 系统托盘中的应用程序图标，然后单击 服务器选项。
在 Web 服务器选项卡上，选择 启用 TLS，并选择要监听 TLS 连接的端口。
单击 TLS 服务器证书 框旁边的按钮以选择私钥证书。带私钥的证书必须安装到本地计算机证书存储区。如果没有符合条件的可用证书，请单击 创建新证书 来为此用途创建一个简单证书。

保存更改后，服务器会重新启动并开始处理 TLS 请求。

管理个人证书

证书选择对话框中可用的证书位于本地计算机的 “个人”证书存储区。若要将证书添加到 Windows 存储区：

在“运行”菜单中输入 mmc 以启动 Microsoft 管理控制台。
单击 文件 > 添加/删除管理单元。
从可用管理单元表中选择证书，然后单击添加。
选择 计算机账户 > 本地计算机。
添加管理单元后，单击 证书（本地计算机）> 个人 > 证书 以显示可用证书。可使用私钥的证书会在证书图标上叠加钥匙图标。
若要将本地磁盘中的证书导入此存储区，请单击 操作 > 所有任务 > 导入。完成导入向导后，这些证书将在应用程序的证书选择对话框中可用。

云网关

云网关提供了一种简单方式，可在不更改防火墙的情况下将应用程序公开到 Internet。只要有可公开访问的 SSH 服务器，就可以利用 SSH 反向隧道，通过该 SSH 服务器上的端口进行访问。若要使用此功能，请右键单击系统托盘中的应用程序图标并选择 服务器选项。导航到 云网关选项卡（如下所示），并输入以下信息：

设置	描述
主机	要连接的 SSH 服务器。
端口	SSH 主机监听连接的端口。大多数 SSH 服务器监听端口 22，这是默认值。
认证类型	要使用的身份验证类型。支持 Password、Public Key、Multi-Factor 和 Keyboard Interactive。
用户	用于向 SSH 服务器进行身份验证的用户名。
密码	如果所选认证类型需要密码，则为用于身份验证的密码。
证书	使用 Public Key 身份验证时，用于向 SSH 服务器进行身份验证的证书。
服务器指纹	SSH 服务器的 SSH 主机密钥指纹。该值为只读，仅供参考。
转发端口	可公开访问的 SSH 服务器监听的端口，用于将连接转发到。

此外，您可能需要更改 SSH 服务器的配置以允许端口转发。默认 SSH 服务器配置可能并不总是允许将端口转发到非 localhost 地址。例如，如果连接到 OpenSSH 服务器，则必须在 SSH 服务器配置文件中将 GatewayPorts 属性设置为 yes 或 clientspecified。输入这些信息后，单击 测试连接 测试与 SSH 服务器的连接，以验证所提供的信息。如果成功，应用程序重新启动后，即可通过 SSH 主机上的 转发端口 访问。例如，如果指定 SSH 服务器 my.ssh.host 且 转发端口 为 8401，则在浏览器中输入 https://my.ssh.host:8401 会将通信转发到运行的本地计算机，即使无法直接访问该计算机，也可以实现公共访问。

Windows 身份验证

默认情况下，内置 Web 服务器使用 ASP.NET 的基于表单的身份验证，需要在 Web 表单（登录门户）中输入用户名/密码组合才能访问管理控制台。也支持 Windows 身份验证，以向特定 Windows 用户或安全组授予应用程序访问权限。在内置 Web 服务器上启用 Windows 身份验证之前，应将所有需要访问的用户添加到应用程序。所有 Windows AD 用户名都必须使用以下语法：DOMAIN\Username。该语法如下图所示。

Add AD user dialog showing DOMAIN\Username format

必须逐个添加用户，因为不能授予整个组访问应用程序的权限。

接下来，若要启用 Windows 身份验证，请打开内置 Web 服务器配置 UI（右键单击系统托盘中的图标并选择 服务器选项），然后切换 Web 服务器选项卡下的 身份验证类型字段。单击 保存更改。这会重新启动 Web 服务器和应用程序。

Authentication type toggle in Server Options

之后，已添加到的 Windows AD 用户登录其计算机并在浏览器中导航到时，会自动登录。

使用 IIS

支持 IIS 10，并且系统要求指定计算机必须运行 Windows 10 或 Windows Server 2016 或更高版本。如果设置 IIS 时遇到困难，请参阅 IIS 故障排除部分。如果仍有疑问，请联系我们的支持团队以获得进一步帮助。

创建新的 Web 应用程序

此示例使用默认网站。

若要在网站上托管应用程序：

在 IIS 管理器中，展开连接面板中的服务器节点。
展开站点节点，右键单击您的网站，然后单击 添加应用程序。
在显示的 添加应用程序 对话框中输入以下信息：

设置	描述
别名	应用程序的名称。例如 `arc`。
应用程序池	与应用程序关联的应用程序池。此示例使用 `DefaultAppPool`。
物理路径	www 目录的路径，位于应用程序安装目录中。默认位置为 `C:\Program Files\CData\CData Arc\www`。

配置目录权限

应用程序必须对应用程序目录具有完全访问权限，才能使用完整功能。在 ArcESB 2021 及更早版本中，应用程序目录和安装目录相同，默认是 C:\Program Files\ArcESB\。如果您从的旧版本升级到 20，这很可能仍是您的应用程序目录。在 2021 中，应用程序目录从安装目录中分离出来。安装目录现在是 C:\Program Files\CData\CData Arc。应用程序目录现在是 C:\ProgramData\CData\Arc\。应用程序目录包含以下文件夹：

connectors
data
db
locks
logs
schemas
workspaces

安装目录包含：

程序可执行文件（CData.Arc.exe 和 arc.exe）及配置文件
www 文件夹及子文件夹
www_services 文件夹及子文件夹

若要设置权限，请找到安装的应用程序目录，并执行以下步骤：

右键单击该文件夹并单击属性。在安全选项卡上，单击 编辑 > 添加。
在 输入要选择的对象名称 框中输入以下内容，并替换应用程序池名称：IIS AppPool\[your-application-pool]。例如：IIS AppPool\DefaultAppPool。
确保应用程序池具有以下权限：
- 读取
- 写入
- 修改
- 读取和执行
- 列出文件夹内容

也可以使用命令行允许应用程序池访问。例如：icacls "<application directory>" /grant "IIS APPPOOL\DefaultAppPool":(OI)(M)

配置服务器权限

如果使用 sftpserver 或 ftpserver，必须确保应用程序池对为服务器配置的根目录具有正确权限。如果将根目录创建为应用程序目录路径的子目录，则在父应用程序目录及其子文件夹上设置权限通常就足够了。

防止卸载应用程序进程

IIS 可能会因多种原因关闭 Web 应用程序，包括超过空闲超时，或判定应用程序池资源使用率过高。这可能会阻止应用程序中的后台任务运行。请通过修改以下设置确保应用程序保持运行：

启用可选的应用程序初始化功能。在 Windows Server 2016 中，打开 服务器管理器，然后单击 仪表板 > 快速入门 > 添加角色和功能。此时会打开 添加角色和功能向导。在服务器角色步骤中，单击 Web 服务器 (IIS) > Web 服务器 > 应用程序开发 > 应用程序初始化。在 Windows 10 中，打开 控制面板，然后单击 程序和功能 > 启用或关闭 Windows 功能。单击 Internet Information Services > 万维网服务 > 应用程序开发功能 > 应用程序初始化。
在 IIS 管理器中，单击连接面板中的 应用程序池。
在工作区中，右键单击应用程序池并单击 高级设置。
在常规设置中，将 启动模式 设置为 AlwaysRunning。
在进程模型设置中，将 闲置超时 设置为 0。
在 CPU 部分，将 限制间隔 设置为 0。
在回收部分，将 固定时间间隔 设置为 0。
在生成回收事件日志条目节点中，在回收部分下，将 固定时间间隔 设置为 False。单击 OK 按钮。
返回 IIS 管理器，右键单击您的网站并单击 管理网站 > 高级设置。
在常规设置中，将 Preload Enabled 设置为 True，然后单击 OK。这可确保应用程序在回收后立即启动。

配置 ASP.NET 应用程序池回收

IIS 会定期回收，以便清理 ASP.NET 应用程序池进程。您可以改为将回收安排在非高峰时段：导航到回收部分，将 特定时间 设置为 True，并按 hh:mm:ss 格式输入回收时间。

预加载应用程序

IIS 的预加载功能允许应用程序在用户连接之前运行，从而提高性能。若要启用此功能，请在连接面板中右键单击与关联的 Web 应用程序，然后选择 管理应用程序 > 高级设置。在 PreloadEnabled 菜单中选择 True。当 PreloadEnabled 设置为 True 时，IIS 会模拟用户对网站或虚拟目录默认页面的请求，以便初始化应用程序。

确认设置

若要打开应用程序，请导航到 http://localhost/arc。如果遇到任何错误，请参阅 IIS 故障排除。

托管 TLS/SSL 连接（IIS）

您可以使用 TLS/SSL 保护与交易伙伴之间关键业务和关键任务通信的机密性。以下步骤假设您已经拥有可用于在服务器上启用 TLS/SSL 的证书。

在 IIS 管理器中，从连接窗格单击网站节点。
在操作窗格中单击绑定。
单击添加并选择 HTTPS。
选择服务器证书。
如果要要求 TLS/SSL，请在网站节点仍处于选中状态时，在工作区中双击 SSL/TLS 设置图标。选择 需要 SSL/TLS，然后在操作窗格中单击应用。

Windows 身份验证

在 IIS 中托管时，配置使用 Windows 身份验证与使用 .NET 内置 Web 服务器时所需的配置类似。不过，此时不是在内置 Web 服务器中进行更改，而是在 IIS 中进行必要更改。若要在 IIS 中托管时设置 Windows 身份验证，请执行以下步骤：

登录，并将所有需要访问的 Windows AD 用户添加到应用程序。Windows AD 用户名必须使用以下语法：DOMAIN\Username。
必须逐个添加用户，因为不能授予整个组访问应用程序的权限。
打开 IIS，停止为配置的站点。右键单击该站点并选择 管理网站 > 停止。
单击站点以打开主页。在 IIS 部分下选择 身份验证。此时会出现一个屏幕，列出一组身份验证方法。右键单击 表单身份验证 并选择禁用。这会关闭默认的用户名和密码登录身份验证方法。
右键单击 Windows 身份验证 并选择启用。
在 IIS 中重新启动您的站点。

您可能需要在 IIS 中编辑 Windows 身份验证提供程序，使 IIS 在访问时不再提示输入用户名和密码。若要从 IIS 身份验证设置中执行此操作，请右键单击 Windows 身份验证 并选择 提供程序。此时会打开提供程序列表：

确保 NTLM 位于列表顶部，使该提供程序在进行身份验证时具有优先级。您可能需要完全移除 Negotiate 才能停止用户名和密码提示。在 IIS 中正确配置 Windows 身份验证后，访问应用程序时会自动以已登录的 Windows AD 用户身份登录。

IIS 故障排除

以下各节提供了几种常见错误的解决方法。

注销一段时间后应用程序停止响应

IIS 可能会在应用程序因不活动而超时后卸载应用程序。默认情况下，IIS 会在应用程序不活动 20 分钟后终止分配给应用程序的工作进程。请参阅防止卸载应用程序进程，了解如何覆盖此功能。

访问 http://localhost/application 导致“Page Cannot Be Displayed”错误（HTTP 404 错误）

这可能表示 ASP.NET 未启用。如果您可以成功浏览静态图像（如 favicon.ico，例如 http://localhost/arc/favicon.ico），但无法浏览 login.rst，则强烈表明 ASP.NET 未启用。在 IIS 中，选择 Control Panel > Programs (or Programs and Features) > Turn Windows Features On or Off > Internet Information Services > World Wide Web Services > Application Development Features。选中 ASP.NET 旁边的复选框。

该部分在父级被锁定

锁定可能是默认设置（overrideModeDefault="Deny"），也可能由带有 overrideMode="Deny" 的 location 标记或旧版 allowOverride="false" 显式设置。如果未安装 ASP.NET，可能会出现此错误。

HTTP 503 错误：服务不可用

如果在 IIS 中选择了之前曾与内置 Web 服务器一起使用的端口，可能会出现此错误。这表示服务未成功启动。IIS 在启动服务时不会报告任何问题，但当您尝试访问站点时会出现此错误。发生这种情况是因为内置 Web 服务器会保留您绑定的任何端口，使其他尝试绑定到该端口的进程无法进行保留。若要确认问题是否由端口保留引起，请打开命令提示符并运行以下命令：

netsh http show urlacl

这会列出计算机上的所有保留条目。如果您尝试绑定的 URL 在列表中（例如 Reserved URL : http://+:8001/），则可以使用另一个 netsh 命令删除该保留（使用 show 列表中的相同值）。例如，以下命令会删除端口 8001 的保留：

netsh http delete urlacl http://+:8001/

管理用户

首次启动时，它会提示您创建具有用户名/密码凭据的用户。创建第一个用户后，可以在系统设置页面的用户选项卡上添加、删除和管理用户。请参阅用户角色以了解有关用户管理和角色的更多信息。

配置应用程序目录

应用程序目录包含应用程序使用的所有数据：配置数据、应用程序数据、日志数据、证书等。应用程序目录默认位于以下位置：

C:\ProgramData\CData\Arc

您可以将应用程序目录更改为其他文件夹，这在多种场景中很有用：

集群多个实例
使用共享网络驱动器存储应用程序数据
将嵌入访问同一文件夹的其他系统中

更改应用程序目录会移动应用程序的数据文件，但不会移动其他应用程序资源，例如 .exe 或 .jar 文件。

更改应用程序目录

若要设置自定义应用程序目录，请打开安装目录 www 文件夹中的 Web.Config 文件。在文件底部的 <appSettings> 标记内，找到以下值：

<add key="AppDirectory" value="C:\ProgramData\CData\Arc" />

将 value 后引号内的文本替换为新的应用程序目录。这可以是应用程序具有读写权限的任何本地或网络路径。

配置应用程序数据库

应用程序数据库存储多个应用程序数据表，包括：

事务日志（应用程序处理的每个事务的元数据）
应用程序日志（应用程序级错误和事件）
访问日志（对应用程序 Web 端点的请求）
审计日志（用户对配置所做的更改）

默认情况下，使用安装目录中的 SQLite 数据库作为应用程序数据库。此数据库建议用于最多 100,000 条事务。达到该数量后，建议迁移到外部数据库。您可以将应用程序配置为使用 SQL Server、PostgreSQL 或 MySQL 等企业数据库。

出于安全原因，如果您切换到其他应用程序数据库，必须运行 integrityResetTampering 操作来重置哈希链。

应用程序数据库在安装目录 www 文件夹中的 Web.Config 文件中配置。该文件包含一个注释掉的 AppDb 块，用于说明后面的 connectionStrings 标记。请在 AppDb 键中设置目标数据库的连接字符串和提供程序名称。

设置连接字符串

以下各节提供了 Web.Config 文件中各种服务器配置的示例连接字符串。您可以以明文形式设置这些值，也可以生成加密的连接字符串来用作 connectionString 值。

SQL Server

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;database=sqlserver;user=MyUserName;password=MyPassword;" providerName="System.Data.CData.SQL" />
</connectionStrings>

为降低使用 SQL Server 作为应用程序数据库时发生死锁的可能性，知行软件建议确保已启用 READ_COMMITTED_SNAPSHOT。

MySQL

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;database=appdb;user=MyUserName;password=MyPassword;" providerName="System.Data.CData.MySQL" />
</connectionStrings>

PostgreSQL

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;port=5432;database=postgres;user=postgres;password=MySecretPassword;" providerName="System.Data.CData.PostgreSQL" />
</connectionStrings>

生成加密的数据库连接字符串

提供为应用程序数据库连接生成加密连接字符串的功能。您可以使用此加密连接字符串指定应用程序数据库，而无需在配置文件中以明文形式存储登录凭据。若要生成加密连接字符串，请在 CData.Arc.exe 所在的安装目录中发出以下命令，并将末尾的示例字符串替换为您的连接信息：

CData.Arc.exe -EncryptConnectionString server=serverName;database=databaseName;user=userName;password=passwordSample;

发出命令后，命令窗口会打印加密字符串。例如：

ENCRYPTEDA:XuUY73BQHKdzWn52z6AqLvZ7uG6jlwkcsQL8yGM8sQ2Znfm1HwG6BpH+LP92mGBBCQX2/IWMal2V5a1AujfltOwResXjAijDzxJ7JmvgUt4=

随后，您可以使用此加密字符串替代 connectionString 的明文值，如设置连接字符串中所示。

指定默认字符集（仅限 MySQL）

对于 MySQL 8.0 及更高版本，数据库及其表的默认字符集 (charset) 为 UTF8（具体为 utf8mb4）。但是，在 MySQL 8.0 之前的版本中，默认字符集通常为 Latin1，这可能会导致包含基本拉丁字母表以外字符的数据出现问题。如果使用较旧版本的 MySQL，可以通过将数据库配置为使用 utf8mb4 来避免这些问题。有两种方式可以进行此更改：直接更新现有数据库，或使用 MySQL 的导出和导入工具将数据迁移到新的 UTF8 编码数据库。

直接更新数据库

备份数据库：mysqldump -u root -p --default-character-set=latin1 --databases [database name] > backup.sql
将默认字符集更改为 UTF8：ALTER DATABASE [database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

生成 SQL 语句，将所有数据库表的默认字符集更改为 UTF8：

SELECT CONCAT('ALTER TABLE ', table_name, ' CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;') AS alter_sql
FROM information_schema.TABLES
WHERE table_schema = '[database name]' AND table_type = 'BASE TABLE';

执行上一步生成的 SQL 语句。

使用导出和导入工具

导出数据定义语言 (DDL) 和数据：

mysqldump -u root -p --default-character-set=latin1 --no-create-info [database name] > data.sql
mysqldump -u root -p --no-data [database name] > schemas.sql

将 schemas.sql 中的默认字符集从 CHARSET=latin1 更改为 CHARSET=utf8mb4。
创建一个以 UTF8 为默认字符集的新数据库：CREATE DATABASE [new database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

导入到新数据库：

mysql -u root -p [new database name] < schema.sql
mysql -u root -p [new database name] < data.sql

设置登录锁定

为防止暴力破解攻击，会自动锁定输入错误密码次数过多的用户。默认情况下，用户在 5 分钟内输入 6 次错误密码后，第 7 次尝试失败时会被锁定 30 分钟。您可以通过编辑安装目录 www 文件夹中的 Web.Config 文件来修改这些设置。有 3 个与锁定相关的设置：

LockoutFailedAttempts：触发锁定的错误密码次数（将此设置为 0 可禁用锁定）
LockoutMinutes：锁定持续时间（默认 30 分钟）
LockoutTimeCheckPeriod：失败尝试次数重置为 0 的时间段（默认 5 分钟）

这些设置都可以在 Web.Config 文件的 <appSettings> 标记下设置。例如，以下代码片段会禁用锁定：

<appSettings>
     <add key="LockoutFailedAttempts" value="0"/>
</appSettings>

​使用内置服务器

​托管 TLS/SSL 连接（内置服务器）

​管理个人证书

​云网关

​Windows 身份验证

​使用 IIS

​创建新的 Web 应用程序

​配置目录权限

​配置服务器权限

​防止卸载应用程序进程

​配置 ASP.NET 应用程序池回收

​预加载应用程序

​确认设置

​托管 TLS/SSL 连接（IIS）

​Windows 身份验证

​IIS 故障排除

​注销一段时间后应用程序停止响应

​访问 http://localhost/application 导致“Page Cannot Be Displayed”错误（HTTP 404 错误）

​该部分在父级被锁定

​HTTP 503 错误：服务不可用

​管理用户

​配置应用程序目录

​更改应用程序目录

​配置应用程序数据库

​设置连接字符串

​SQL Server

​MySQL

​PostgreSQL

​生成加密的数据库连接字符串

​指定默认字符集（仅限 MySQL）

​直接更新数据库

​使用导出和导入工具

​设置登录锁定

使用内置服务器

托管 TLS/SSL 连接（内置服务器）

管理个人证书

云网关

Windows 身份验证

使用 IIS

创建新的 Web 应用程序

配置目录权限

配置服务器权限

防止卸载应用程序进程

配置 ASP.NET 应用程序池回收

预加载应用程序

确认设置

托管 TLS/SSL 连接（IIS）

Windows 身份验证

IIS 故障排除

注销一段时间后应用程序停止响应

访问 http://localhost/application 导致“Page Cannot Be Displayed”错误（HTTP 404 错误）

该部分在父级被锁定

HTTP 503 错误：服务不可用

管理用户

配置应用程序目录

更改应用程序目录

配置应用程序数据库

设置连接字符串

SQL Server

MySQL

PostgreSQL

生成加密的数据库连接字符串

指定默认字符集（仅限 MySQL）

直接更新数据库

使用导出和导入工具

设置登录锁定