.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）

直接更新資料庫

使用匯出和匯入工具

設定登入鎖定