> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 跨平臺版本

> 如何安裝、配置並執行知行之橋的跨平臺版本，包括內建 Jetty、Tomcat、WebSphere Liberty 或外部 Jetty。

export const companyName = "知行軟件";

export const siteNameShort = "知行之橋";

export const siteName = "知行之橋";

{siteName} 的跨平臺版本包含一個內建 Eclipse Jetty Web 伺服器，因此無需任何外部伺服器配置即可執行 {siteNameShort}。此外，安裝包還包含一個 WAR 檔案，可部署到任何 Java servlet 容器，例如 Apache Tomcat、Eclipse Jetty 或 IBM WebSphere Liberty。

{siteNameShort} 要求機器上安裝 Java 17 或更高版本。部署到外部 Java servlet 容器需要 Servlet 3.0（Jetty 8+、Tomcat 7+、WebSphere Liberty 8.5+ 等）。

<Note>
  無論您選擇如何部署 {siteNameShort}，執行應用程式的使用者都必須能夠讀取和寫入 `AppDirectory` 中的檔案和資料夾。Java Edition 安裝程式中包含的服務安裝程式使用 **cdatarc** 作為此使用者。

  如果應用程式之前以其他使用者身份執行，而您想恢復 **cdatarc** 使用者執行應用程式所需的權限，應使用類似以下範例的命令：

  `sudo chown -R cdatarc:cdatarc /opt/arc`
</Note>

## Windows

在 Windows 中，{siteNameShort} 預設安裝為服務。若要存取應用程式，必須先確保服務正在執行。服務執行後，可以開啟 Web 瀏覽器並在 URL 欄位中輸入 [http://localhost:8080/](http://localhost:8080/) 來存取 {siteNameShort} 管理控制檯。

您也可以透過 `java` 命令在不使用服務的情況下執行應用程式。{companyName} 建議使用服務，但此方法對某些配置很有用。

### 啟動和停止服務

可以透過以下任一方式啟動和停止服務：

* [開始功能表快捷方式](#開始功能表快捷方式)（推薦）
* [服務管理控制檯](#服務管理控制檯)
* [命令提示符](#命令提示符)命令

#### 開始功能表快捷方式

{siteNameShort} 安裝程式會建立開始功能表快捷方式，以便輕鬆使用應用程式。若要存取這些快捷方式，請開啟 **Start** 功能表並展開 {siteName} 資料夾。以下快捷方式可用：

* **Launch {siteName} Admin Console**：在預設 Web 瀏覽器中開啟管理控制檯 URL [http://localhost:8080/。如果服務未執行，Web](http://localhost:8080/。如果服務未執行，Web) 瀏覽器會傳回錯誤。
* **Start {siteName}**：啟動 {siteNameShort} 服務。預設情況下，此服務會在 Windows 啟動時執行，因此無需每次執行應用程式時都執行此命令。
* **Stop {siteName}**：停止 {siteNameShort} 服務。[升級 {siteNameShort}](./how-to-upgrade) 時需要執行此操作。

#### 服務管理控制檯

若要開啟服務管理控制檯，請開啟開始功能表並輸入 *services*。選擇出現的 **Services** 應用程式。

向下滾動到名為 **{siteName}** 的服務。如果該服務正在執行，**Status** 列會顯示 **Running**。右鍵單擊該服務即可存取 **Start**、**Stop** 和 **Restart** 選項。

#### 命令提示符

高階使用者可以使用 Windows 命令提示符手動向服務發出命令。開啟命令提示符，並將目錄切換到安裝資料夾（預設情況下為 `C:\Program Files\CData\CData Arc`）。

<Note>也可以使用 Microsoft PowerShell 視窗發出這些命令，但語法略有不同。如果使用 PowerShell，請相應地修改命令。</Note>

若要啟動 {siteNameShort} 服務，請發出以下命令：

```sh theme={null}
arc.exe -start
```

使用以下命令重新啟動或停止服務：

```sh theme={null}
arc.exe --restart --ServiceName "知行之桥"
arc.exe --stop --ServiceName "知行之桥"
```

### 不使用服務啟動

若要在不啟動服務的情況下執行 {siteNameShort}，請在安裝資料夾中開啟命令提示符。發出以下命令啟動應用程式：

```sh theme={null}
java -jar arc.jar
```

## Linux

[將 {siteNameShort} 安裝到您選擇的位置](./installation-configuration#cross-platform-edition)後，可以將 {siteNameShort} 作為服務執行，也可以手動執行應用程式。如果將 {siteNameShort} 用於關鍵應用程式，{companyName} 建議使用服務。

### 將 {siteNameShort} 作為服務執行

將 {siteNameShort} 作為服務執行，可使應用程式獨立於任何使用者處理程序執行，並在重新啟動時自動重啟。這是關鍵應用程式的首選方法。

{companyName} 建議建立一個守護處理程序來管理 Linux 上的 {siteNameShort} 應用程式。安裝包中包含的指令碼可以自動完成此操作。如有必要，也可以手動建立守護處理程序。

配置 {siteNameShort} 守護處理程序的最安全方式是執行安裝包中包含的指令碼，前提是系統使用 *systemd* 守護處理程序管理器：

```bash theme={null}
bash ./service.sh
```

此指令碼會建立一個名為 `arc.service` 的守護處理程序。然後可以使用 `systemctl` 管理該守護處理程序：

```bash theme={null}
systemctl enable arc
systemctl start arc
```

### 執行獨立應用程式

若要在不建立服務的情況下啟動 {siteNameShort}，請使用終端在安裝目錄中開啟 arc.jar 檔案，如下所示：

```sh theme={null}
java -jar arc.jar
```

## 配置嵌入式 Jetty 伺服器

{siteNameShort} 已預先配置，可在任何環境中立即工作。不過，您可以透過在 {siteNameShort} 安裝目錄（Windows 預設是 `C:\Program Files\CData\CData Arc`）中[生成 arc.properties 檔案](#生成-arcproperties-檔案)，來自定義存取 {siteNameShort} 中公開資料的方式。

有關所有 `arc.properties` 配置選項的詳細資訊，請參閱 [arc.properties 配置](./arc-properties-configuration)。

<Tip>這些配置選項可用於實現中的所有 `.properties` 檔案。</Tip>

### 生成 arc.properties 檔案

在對嵌入式 Jetty 伺服器進行任何自定義之前，必須建立 `arc.properties` 檔案。在 arc.jar 所在的安裝目錄中執行以下命令：

```
java -jar arc.jar -GenerateProperties
```

這會在安裝目錄中建立 `arc.properties` 檔案。該檔案包含一些參數，可用於[更改端口](#更改端口)或[啟用 TLS/SSL](#啟用-tlsssl)。

<Note>生成此檔案後，升級 {siteNameShort} 不會覆蓋它。</Note>

#### 更改端口

若要更改嵌入式伺服器監聽的端口：

1. 在 *`InstallationDirectory`* 中找到 `arc.properties` 檔案，並在文字編輯器中開啟。

2. 找到設定端口的以下行：

   `cdata.http.port=8080`

3. 將該值更改為所需的端口號。

#### 啟用 TLS/SSL

若要啟用 TLS/SSL 連線 (HTTPS)，還需要按如下方式修改 *`InstallationDirectory`* 中的 `arc.properties` 檔案：

1. 將 `cdata.tls.keyStoreType` 設定為要使用的 keystore 型別。有效值包括 **jks**、**pkcs12** 和 **jceks**。

2. 將 `cdata.tls.keyStorePath` 設定為要使用的 keystore 路徑。請注意，可以使用 `${cdata.home}` 來引用 *`InstallationDirectory`*。

3. 將 `cdata.tls.keyStorePassword` 設定為 keystore 的密碼。

4. 將 `cdata.tls.port` 設定為託管伺服器應使用的端口。

5. （可選）將 `cdata.http.port` 設定為空字串，以停用明文連線。

最終結果應如下所示：

```
;; HTTP
cdata.http.port=

;; TLS
cdata.tls.port=8443
cdata.tls.keyStoreType=PKCS12
cdata.tls.keyStorePath=${cdata.home}/mycertificate.pfx
cdata.tls.keyStorePassword=mypassword
```

<Note>如果您取得外部私密金鑰用於 {siteNameShort} 配置，請務必將憑證所有者更改為用於託管 {siteNameShort} 的服務帳戶（**cdatarc:cdatarc**）。</Note>

#### 將 {siteNameShort} 指向其他 .properties 檔案

使用 `-config` 參數可將 {siteNameShort} 指向預設 `arc.properties` 以外的配置檔案。例如，執行以下命令時，{siteNameShort} 會查詢 `test.properties` 檔案：

```
java -jar arc.jar -config test
```

### 生成 Jetty XML 檔案

在大多數部署中，`arc.properties` 檔案為嵌入式 Jetty 伺服器提供了所需的完整配置選項。不過，如果需要更復雜的部署，可以生成一個 Jetty XML 檔案作為進一步修改的起點。若要生成此檔案，請在 arc.jar 所在的 {siteNameShort} 安裝目錄中執行以下命令：

```
java -jar arc.jar -GenerateXML
```

命令完成後，arc.xml 配置檔案會出現在 `webapp` 資料夾中。只要它保留在該資料夾中，就會用於啟動應用程式。

### 啟動和停止伺服器

如果使用 `service.sh` 指令碼設定 {siteNameShort} 服務，請參閱[作為服務執行](#作為服務執行)。否則，請參閱[在處理程序中執行](#在處理程序中執行)部分。

#### 在處理程序中執行

透過執行安裝過程中從應用程式下載包提取出的 arc.jar 檔案來啟動嵌入式 Jetty 伺服器。可以使用標準 Java 語法執行此檔案並啟動伺服器，如下所示：

```bash theme={null}
java -jar arc.jar
```

若要停止伺服器，請向此命令傳遞 `-stop` 參數：

```bash theme={null}
java -jar arc.jar -stop
```

#### 作為服務執行

可以使用標準系統服務命令操作 {siteNameShort} 服務，並將 **arc** 作為服務名稱引用。

若要啟動服務，請提交以下命令：

```bash theme={null}
systemctl start arc
```

若要停止服務，請提交以下命令：

```bash theme={null}
systemctl stop arc
```

若要重新啟動服務，請提交以下命令：

```bash theme={null}
systemctl restart arc
```

### 配置 LDAP 身分驗證

如果使用[嵌入式 Jetty Web 伺服器](#配置嵌入式-jetty-伺服器)，以下步驟會配置 {siteNameShort} 使用 LDAP 對使用者進行身分驗證。

#### 配置 arc.properties

如果預設 arc.properties 檔案尚不存在，請使用以下命令[生成預設 arc.properties](#生成-arcproperties-檔案)檔案：

`java -jar arc.jar -GenerateProperties`

以下必需設定指示嵌入式 Jetty 伺服器使用 LDAP 進行身分驗證：

`cdata.loginService.ldap.enabled=true`

您可能希望像其他部分一樣在檔案中將其單獨分段：

```
;; LDAP
cdata.loginService.ldap.enabled=true
```

插入特定 LDAP 伺服器所需的任何其他設定，以及 {siteNameShort} 所需的最低設定。{siteNameShort} 至少需要以下設定：

```
cdata.loginService.ldap.hostname
cdata.loginService.ldap.bindDn
cdata.loginService.ldap.bindPassword
```

可用設定的完整清單如下：

```
cdata.loginService.ldap.userIdAttribute
cdata.loginService.ldap.debug
cdata.loginService.ldap.forceBindingLogin
cdata.loginService.ldap.bindPassword
cdata.loginService.ldap.roleMemberAttribute
cdata.loginService.ldap.useLdaps
cdata.loginService.ldap.roleBaseDn
cdata.loginService.ldap.bindDn
cdata.loginService.ldap.userPasswordAttribute
cdata.loginService.ldap.hostname
cdata.loginService.ldap.userRdnAttribute
cdata.loginService.ldap.roleObjectClass
cdata.loginService.ldap.port
cdata.loginService.ldap.authenticationMethod
cdata.loginService.ldap.userBaseDn
cdata.loginService.ldap.contextFactory
cdata.loginService.ldap.userObjectClass
cdata.loginService.ldap.roleNameAttribute
```

以下是 `arc.properties` 中完整 LDAP 部分可能的範例：

```
;; LDAP
cdata.loginService.ldap.enabled=true
cdata.loginService.ldap.bindDn="CN=ldapuser,DC=example,DC=org"
cdata.loginService.ldap.hostname="127.0.0.1"
cdata.loginService.ldap.bindPassword="Adminpassword1"

cdata.loginService.ldap.port="1389"
cdata.loginService.ldap.debug=true
cdata.loginService.ldap.authenticationMethod="simple"
cdata.loginService.ldap.userBaseDn="DC=example,DC=org"
cdata.loginService.ldap.userRdnAttribute="cn"
cdata.loginService.ldap.userPasswordAttribute="userPassword"
cdata.loginService.ldap.forceBindingLogin="true"
cdata.loginService.ldap.roleBaseDn="DC=example,DC=org"
cdata.loginService.ldap.roleNameAttribute="cn"
cdata.loginService.ldap.roleMemberAttribute="member"
cdata.loginService.ldap.useLdaps="false"
```

#### 在 {siteNameShort} 中建立 LDAP 使用者

為了讓使用者透過您的 LDAP 伺服器登入 {siteNameShort}，必須將每個 LDAP 使用者新增到 {siteNameShort}。這允許 {siteNameShort} 將嘗試登入的使用者與配置的 LDAP 伺服器進行交叉引用。請按照以下步驟建立每個使用者（有關管理使用者的更多詳細資訊，請參閱[使用者管理和角色](../administration/settings/user-roles)）：

* 啟動 {siteNameShort}，並以 {siteNameShort} 管理員使用者身份登入。
* 建立所有需要存取 {siteNameShort} 的 LDAP 使用者。單擊導覽列中的齒輪圖示並選擇 **使用者**。{siteNameShort} 使用者必須與 LDAP 使用者完全相同。例如，如果 LDAP 使用者為 `user01` 和 `user02`，則必須在 {siteNameShort} 中使用相同的使用者名稱。

新增所有使用者後，可以停止應用程式。

#### 測試配置

建立包含必要 LDAP 設定的 `arc.properties` 檔案、將 LDAP 使用者新增到 {siteNameShort}，並根據 LDAP 伺服器要求確認其配置正確後，即可測試該功能。

使用 `java -jar arc.jar` 或透過啟動 {siteNameShort} 服務來啟動 {siteNameShort}。顯示登入螢幕後，嘗試使用某個 LDAP 使用者登入。輸入 LDAP 伺服器上的使用者名稱和密碼（必須與您在 {siteNameShort} **使用者** 部分輸入的內容完全相同）。

登入過程會先檢查登入使用者是否存在於 {siteNameShort} 中配置的使用者中，然後再檢查 LDAP 伺服器，以確保該使用者存在並允許存取應用程式。如果配置成功，您將以該使用者身份登入應用程式。

#### LDAP 配置疑難排解

如果在向 LDAP 伺服器進行身分驗證時遇到問題，{companyName} 建議使用 <a href="https://directory.apache.org/studio/" target="_blank">Apache Directory Studio</a> 測試 LDAP 連線和過濾器。您可以將相同的連線設定和搜尋過濾器應用到 `arc.properties` 或 `login.config` 檔案。

##### 為失敗的身分驗證嘗試建立偵錯日誌

可以在 `arc.properties` 檔案中使用此設定啟用偵錯：`cdata.loginService.ldap.debug`。

還可以將其他日誌資訊輸出到控制檯和 Web 伺服器日誌。在應用程式安裝目錄中，與 `arc.properties` 檔案和 `webapps` 資料夾相同的位置建立一個名為 `arc.logging.properties` 的檔案，幷包含以下內容：

```
handlers = java.util.logging.ConsoleHandler, arc.ArcRolloverFileHandler
java.util.logging.ConsoleHandler.level = FINE
arc.ArcRolloverFileHandler.filename = yyyy_mm_dd.log
arc.ArcRolloverFileHandler.formatter = java.util.logging.SimpleFormatter
arc.ArcRolloverFileHandler.level = FINE
# Enable LDAP and Jetty JAAS module debug logs
org.eclipse.jetty.jaas.level = FINE
com.sun.jndi.ldap.level = FINE
```

重啟服務後，有關 LDAP 身分驗證嘗試的其他日誌會輸出到控制檯。

## Tomcat 中的配置

### 部署 WAR 檔案

有兩種方式可將 WAR 檔案部署到 Tomcat。

* 將 WAR 檔案複製到 `webapps` 資料夾中。
* 從 Tomcat 管理控制檯內部署 WAR 檔案。Apache Tomcat 文件對這種方法有更詳細的介紹。請參閱您所用 Tomcat 版本的文件。

WAR 檔案可能會超過 Tomcat 預設允許上傳的最大檔案大小。若要解決部署期間的錯誤，可以編輯 manager 應用程式的 `web.xml` 檔案以允許更大的檔案。根據 Tomcat 配置，此檔案可能位於 `/usr/share/tomcat7-admin/manager/WEB-INF` 或類似目錄中。在此檔案中，可以更改允許的最大檔案大小（以位元組為單位）。例如，若要允許部署 200MB WAR 檔案，請編輯以下值以更改允許的最大檔案大小：

```xml theme={null}
<multipart-config>
     <!-- 200 MB max -->
  <max-file-size>209715200</max-file-size>
  <max-request-size>209715200</max-request-size>
  <file-size-threshold>0</file-size-threshold>
</multipart-config>
```

### 配置 Java 認證和服務 (JAAS)

若要讓 {siteNameShort} 能夠在應用程式內動態管理使用者，必須按以下指南配置 JAAS。本指南使用 `arc.xml` 控制 Tomcat 配置並定義任何上下文覆蓋。{companyName} 建議使用 `arc.xml` 而不是 `server.xml` 控制 Tomcat 配置。還建議將任何應用程式上下文覆蓋（例如 `APP_DIRECTORY` 或 `APP_DB`）移到定義 JAASRealm 模組的 `arc.xml` 中。

<Note>這是任何 Tomcat 環境中設定 {siteNameShort} 所必需的第一步。</Note>

#### 建立登入模組

在此資料夾中建立名為 `jaas.config` 的 JAAS 配置檔案：`$CATALINA_BASE/conf/`。

在 `jaas.config` 中包含以下內容，以使用標準身分驗證：

```xml theme={null}
Arc {
  arc.LoginModule required;
};
```

<Note>如果要使用 LDAP，請繼續完成標準登入模組設定。完成後，請按照[使用 LDAP 認證使用者](#使用-ldap-認證使用者)中的步驟操作。</Note>

#### 建立（或修改）JAASRealm 模組

1. 檢查 `$CATALINA_BASE/conf/Catalina/localhost/` 中是否存在 `arc.xml` 檔案。如果存在，請編輯 `arc.xml` 並新增下面的 XML 上下文塊。如果該路徑中不存在 `arc.xml`，則需要建立它，然後新增下面的 XML 上下文塊。這應該是 `arc.xml` 中唯一的內容。

   ```xml theme={null}
   <Context>
     <Realm className="org.apache.catalina.realm.JAASRealm" appName="Arc"
       userClassNames="arc.SimplePrincipal"
       roleClassNames="arc.GroupPrincipal" />
   </Context>
   ```

   <Note>根據 Tomcat 例項的配置方式，此路徑可能略有不同。在此範例中，`Catalina` 指引擎名稱，`localhost` 是 `server.xml` 中定義的主機名。</Note>

2. 在 Tomcat 伺服器的 `server.xml` 配置檔案中更新 `<Host/>` 元素，將 `copyXML` 屬性設定為 true，如下所示：

   ```xml theme={null}
   <Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true">
     ...
   </Host>
   ```

   <Note>
     如果 `server.xml` 中存在特定於應用程式的上下文，它會優先於 `arc.xml`。{companyName} 建議在任何上下文覆蓋中使用 `arc.xml` 而不是 `server.xml`。例如：

     ```xml theme={null}
     <Context path="Arc">
        ...
     </Context>
     ```
   </Note>

#### 使登入模組可見

必須將 Java 虛擬機器 (JVM) 指向登入模組 (`jaas.config`)，以便配置可見。透過將以下行追加到 `$CATALINA_BASE/conf/catalina.properties` 檔案，將 JVM 上的 `java.security.auth.login.config` 系統屬性設定為 `jaas.config` 檔案的路徑：

```bash theme={null}
java.security.auth.login.config=${catalina.base}/conf/jaas.config
```

#### 使用 LDAP 認證使用者

在配置 {siteNameShort} 將 LDAP 與 Tomcat 配合使用之前，請按照[配置 Java 認證和服務 (JAAS)](#配置-java-認證和服務-jaas)說明操作，以便建立管理員使用者；這是將 LDAP 使用者新增到 {siteNameShort} 之前的必要步驟。配置登入模組並能以管理員使用者身份成功登入 {siteNameShort} 後，請按照以下步驟配置 LDAP 支援。

1. 以管理員使用者身份登入 {siteNameShort}。若要建立需要存取 {siteNameShort} 的所有 LDAP 使用者，請單擊導覽列上的 **設定**齒輪圖示，然後選擇 **使用者**。{siteNameShort} 使用者必須與 LDAP 使用者完全相同。例如，如果 LDAP 使用者為 `user01` 和 `user02`，則必須在 {siteNameShort} 中使用相同的使用者名稱。

2. 修改在[建立登入模組](#建立登入模組)中建立的 `$CATALINA_BASE/conf/jaas.config` 檔案，使其適配您的 LDAP 伺服器。必須向 `jaas.config` 新增一些配置選項。

   a. 透過新增 `com.sun.security.auth.module.LdapLoginModule REQUIRED`，確保 LDAP 登入模組是必需的。還需要將之前建立的登入模組設為可選。為此，請設定 `arc.LoginModule optional;`。

   b. 新增所需的 LDAP 模組配置選項。至少需要以下選項：`userProvider`、`authIdentity`、`userFilter` 和 `useSSL`。您為這些選項提供的值取決於您的 LDAP 伺服器和要求：請諮詢伺服器管理員或 LDAP 文件以確定這些值。以下範例展示了可能的配置形式。請注意，`arc.loginModule` 設定為 `optional`，而 `com.sun.security.auth.module.LdapLoginModule` 設定為 `REQUIRED`：

   ```
   Arc {
     com.sun.security.auth.module.LdapLoginModule REQUIRED
       userProvider="ldap://openldap:1389/ou=users,dc=example,dc=org"
       authIdentity="CN={USERNAME},OU=users,DC=example,DC=org"
       userFilter="(cn={USERNAME})"
       useSSL=false;
       debug=false;
     arc.LoginModule optional;
   };
   ```

   <Note>如果任何值包含特殊權杖 `{USERNAME}`，該權杖會在登入時替換為提供的使用者名稱值。</Note>

完成這些步驟後，LDAP 使用者即可登入 {siteNameShort}。

### 配置資料目錄權限

為執行 Java servlet 容器的處理程序使用者授予對相應位置中資料目錄的讀/寫存取權限，如下所示：

* **Windows:** `C:\ProgramData\CData\Arc\`
* **Linux:** `~/cdata/arc`

重新啟動 Tomcat 伺服器以使更改生效。現在可以登入應用程式。

## WebSphere Liberty 中的配置

若要在 WebSphere Liberty 中配置 {siteNameShort}，請按照以下步驟操作。

### 在 WebSphere Liberty 中建立 {siteNameShort} 應用程式

<Note>本指南介紹了 {siteNameShort} 在 Liberty 中的基本安裝。如果需要更自定義的 Liberty 安裝，請諮詢內部團隊，瞭解可能需要包含的其他設定或選項。</Note>

1. 從 <a href="https://openliberty.io/start/" target="_blank">Open Liberty</a> 或 <a href="https://www.ibm.com/support/pages/240012-websphere-application-server-liberty-240012" target="_blank">WebSphere Application Server Liberty 24.0.0.12</a> 下載 Liberty。{siteNameShort} 需要 Web Profile 8 包。

2. 執行以下命令建立名為 `arc` 的伺服器：
   * Windows: `.\bin\server.bat create arc`
   * Linux: `./bin/server create arc`

3. 將 arc.war 檔案複製到 `./usr/servers/arc/apps` 目錄。

4. 如有必要，在 `./usr/servers/arc/server.xml` 的 `httpEndpoint` 元素中更改 HTTP 和 HTTPS 端口（下方提供 [server.xml 範例檔案](#serverxml-範例檔案)）。

5. 透過編輯 server.xml 檔案進行任何其他應用程式配置更新。

6. 執行以下命令啟動伺服器：
   * Windows: `.\bin\server.bat start arc`
   * Linux: `./bin/server start arc`

### server.xml 範例檔案

以下是一個 server.xml 範例檔案，其中包含 {siteNameShort} 在 Liberty 中執行所需的設定。它還包含 JAAS 配置所需的設定。以下章節會更詳細地說明此檔案的各個部分。

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<server description="Arc server">
  <!-- Enable features -->
  <featureManager>
    <feature>webProfile-8.0</feature>
  </featureManager>
  <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
  <httpEndpoint id="defaultHttpEndpoint" host="localhost" httpPort="9080" httpsPort="9443" />
  <!-- Automatically expand WAR files -->
  <applicationManager autoExpand="true"/>
  <!-- Default SSL configuration enables trust for default certificates from the Java runtime -->
  <ssl id="defaultSSLConfig" trustDefaultCerts="true" />
  <webContainer AllowQueryParamWithNoEqual="true" />
  <webApplication id="arc-app" contextRoot="/arc" location="arc.war">
    <!-- Map role to group -->
    <application-bnd>
      <security-role name="cdata_admin">
        <group name="cdata_admin" access-id="group:defaultWIMFileBasedRealm/cn=cdata_admin,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_standard">
        <group name="cdata_standard" access-id="group:defaultWIMFileBasedRealm/cn=cdata_standard,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_support">
        <group name="cdata_support" access-id="group:defaultWIMFileBasedRealm/cn=cdata_support,o=defaultWIMFileBasedRealm" />
      </security-role>
      <security-role name="cdata_user">
        <special-subject type="ALL_AUTHENTICATED_USERS" />
      </security-role>
    </application-bnd>
  </webApplication>
  <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="REQUIRED" classProviderRef="arc-app">
    <options isWebSphere="true" />
  </jaasLoginModule>
  <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="arcLoginModule, hashtable, userNameAndPassword" />
  <!-- logging is optional -->
  <logging traceSpecification="com.ibm.ws.security.appbnd.*=all:com.ibm.ws.security.authorization.*=all:com.ibm.wsspi.security.authorization.*=all:com.ibm.ws.security.jaas.*=all:com.ibm.ws.security.auth.context.*=all:com.ibm.ws.webcontainer.*=all:arc.*=all:rssbus.*=all"
    consoleLogLevel="INFO"
    logDirectory="${server.config.dir}/logs"
    messageFileName="messages.log"
    traceFileName="trace.log"
    hideMessageIDs="true"/>
</server>
```

### 配置 Java 認證和服務 (JAAS)

server.xml 中的以下設定會配置 JAAS，並使 {siteNameShort} 能夠在 Liberty 應用程式伺服器中動態管理使用者。如果已複製上面的 server.xml 範例檔案，則這些元素已存在。否則，請按照以下步驟操作：

1. 透過向 server.xml 新增以下元素，為 JAAS 身分驗證配置 {siteNameShort} 登入模組：

   ```xml theme={null}
   <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="REQUIRED" classProviderRef="arc-app">
      <options isWebSphere="true" />
   </jaasLoginModule>
   <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="arcLoginModule, hashtable, userNameAndPassword" />
   ```

2. 在 server.xml 的 `webApplication` 元素中配置使用者組和角色對映。

   ```xml theme={null}
   <webApplication id="arc-app" contextRoot="/arc" location="arc.war">
      <!-- Map role to group -->
      <application-bnd>
        <security-role name="cdata_admin">
          <group name="cdata_admin" access-id="group:defaultWIMFileBasedRealm/cn=cdata_admin,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_standard">
          <group name="cdata_standard" access-id="group:defaultWIMFileBasedRealm/cn=cdata_standard,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_support">
          <group name="cdata_support" access-id="group:defaultWIMFileBasedRealm/cn=cdata_support,o=defaultWIMFileBasedRealm" />
        </security-role>
        <security-role name="cdata_user">
          <special-subject type="ALL_AUTHENTICATED_USERS" />
        </security-role>
      </application-bnd>
   </webApplication>
   ```

   `application-bnd` 部分將 {siteNameShort} 的安全形色對映到使用者組，用於控制不同使用者在應用程式中的權限。每個 `security-role` 元素定義 {siteNameShort} 的一個權限級別，並將其與對應使用者組關聯。請確保為 **cdata\_admin**、**cdata\_standard**、**cdata\_support** 和 **cdata\_user** 配置 `security-role` 元素。

3. 透過向 `webContainer` 元素新增 `AllowQueryParamWithNoEqual` 屬性，啟用不帶等號 (=) 的查詢參數。此設定允許 {siteNameShort} 正確處理某些不包含等號的 URL 查詢參數。

   ```xml theme={null}
   <webContainer AllowQueryParamWithNoEqual="true" />
   ```

4. 重新啟動 Liberty。

現在即可存取 {siteNameShort}，並可與 {siteNameShort} 登入模組配合使用。該模組會在應用程式級別安全地管理使用者。若要配置 LDAP，請閱讀下一節。

### 使用 LDAP 認證使用者

在配置 {siteNameShort} 將 LDAP 與 Liberty 配合使用之前，請按照[配置 Java 認證和服務 (JAAS)](#配置-java-認證和服務-jaas-2)說明建立本地管理員使用者。在向 {siteNameShort} 新增 LDAP 使用者之前必須先建立該使用者。配置登入模組並能以管理員使用者身份成功登入 {siteNameShort} 後，請按照以下步驟配置 LDAP 支援。

1. 編輯 server.xml，將 LDAP 存放庫新增到 Liberty。

   1. 在 `featureManager` 元素中新增一個新功能：`ldapRegistry-3.0`。

      ```xml theme={null}
      <!-- Enable features -->
      <featureManager>
        <feature>webProfile-8.0</feature>
        <feature>ldapRegistry-3.0</feature>
      </featureManager>
      ```

   2. 在 `webContainer` 元素之後新增 LDAP 登錄檔的詳細資訊。

      ```xml theme={null}
      <!-- A LDAP registry sample connects to Microsoft Active Directory. The default activedFilters is used here.
           For more ldap types: https://www.openliberty.io/docs/latest/reference/config/ldapRegistry.html
        -->
      <ldapRegistry id="arcLdapRegistry" realm="testADRealm"
                    host="192.168.0.122" port="389" ignoreCase="true"
                    baseDN="CN=Users,DC=ka,DC=com"
                    bindAuthMechanism="simple"
                    bindDN="ka\nancyw"
                    bindPassword ="xA123456"
                    ldapType="Microsoft Active Directory">
      </ldapRegistry>
      ```

   3. 將 `arc.LoginModule` 控制標誌更改為 `OPTIONAL`。

      ```xml theme={null}
      <jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="OPTIONAL" classProviderRef="arc-app">
           <options isWebSphere="true" />
      </jaasLoginModule>
      ```

2. 以本地管理員使用者身份登入 {siteNameShort}。若要在 {siteNameShort} 中建立 LDAP 使用者，請單擊導覽列中的 **設定**齒輪圖示並選擇 **使用者**。{siteNameShort} 使用者必須與 LDAP 伺服器中的使用者完全相同。例如，如果 LDAP 使用者為 `user01` 和 `user02`，則必須在 {siteNameShort} 中使用相同的使用者名稱。

3. 儲存更改並重新啟動 Liberty 以完成該過程。配置成功後，登入 {siteNameShort} 的使用者會透過 LDAP 進行身分驗證。

### 偵錯設定

[server.xml 範例檔案](#serverxml-範例檔案)包含一套全面的日誌配置，可捕獲安全、身分驗證、Web 容器操作以及 {siteNameShort} 特定元件的詳細跟蹤資訊。如果遇到 LDAP 或其他設定配置問題，這會很有用。

```xml theme={null}
<!-- logging is optional -->
<logging traceSpecification="com.ibm.ws.security.appbnd.*=all:com.ibm.ws.security.authorization.*=all:com.ibm.wsspi.security.authorization.*=all:com.ibm.ws.security.jaas.*=all:com.ibm.ws.security.auth.context.*=all:com.ibm.ws.webcontainer.*=all:arc.*=all:rssbus.*=all"
  consoleLogLevel="INFO"
  logDirectory="${server.config.dir}/logs"
  messageFileName="messages.log"
  traceFileName="trace.log"
  hideMessageIDs="true"/>
```

`traceSpecification` 屬性針對多個關鍵元件組設定為 `all`，包括安全繫結、授權、JAAS 身分驗證、Web 容器操作以及所有 {siteNameShort} 和 RSSBus 模組。此配置提供了詳盡的診斷資訊，有助於排查身分驗證問題、授權問題和應用程式特定錯誤。日誌會寫入 `${server.config.dir}/logs` 目錄，並分別使用訊息檔案 (`messages.log`) 和跟蹤資料檔案 (`trace.log`)。

對於生產環境，您可能希望降低日誌詳細程度以提高效能，並儘量減少日誌檔案增長。為此，可以將特定跟蹤規範從 `all` 更改為 `info`，或移除不需要監控的元件。例如，如果不排查安全問題，可以將配置簡化為 `traceSpecification="arc.*=all:rssbus.*=all"`，以僅關注 {siteNameShort} 特定日誌。相反，如果在疑難排解期間需要更詳細的診斷，可以臨時設定 `traceSpecification="*=all"`，以啟用所有 Liberty 元件的全面日誌記錄。請注意，這會快速生成大型日誌檔案，應僅用於短期偵錯。

### 配置資料目錄權限

為執行 Java servlet 容器的處理程序使用者授予對資料目錄的讀寫存取權限：

* **Windows:** `C:\ProgramData\CData\Arc\`
* **Linux:** `~/cdata/arc`

重新啟動 Liberty 伺服器以使更改生效。現在可以登入應用程式。

## Jetty 中的配置

儘管 {siteNameShort} 隨附嵌入式 Jetty Web 伺服器，也可以將應用程式與外部 Jetty 設定配合使用。

### 部署 WAR 檔案和 arc.xml

將 arc.war 複製到 `${JETTY_BASE}` 的 `webapps` 資料夾中。同時將 arc.xml 檔案放在同一個 `${JETTY_BASE}` 資料夾中。如果沒有 arc.xml，則需要建立它。對於 Jetty 的標準配置，arc.xml 檔案至少需要包含以下內容：

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="arcServer" class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/var/lib/jetty/webapps/arc.war</Set>
  <Set name="securityHandler">
    <New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
      <Set name="loginService">
        <New class="org.eclipse.jetty.jaas.JAASLoginService">
          <!-- This name is the same as **login-config > realm-name** in web.xml.  -->
          <Set name="name">ArcRealm</Set>
          <!-- LoginModuleName must match the name of your LoginModule, as declared in your login-module configuration file. -->
          <Set name="loginModuleName">Arc</Set>
          <!-- Set the principal class name for the custom role. -->
          <Set name="roleClassNames">
            <Array type="java.lang.String">
              <Item>arc.GroupPrincipal</Item>
            </Array>
          </Set>
        </New>
      </Set>
    </New>
  </Set>
</Configure>
```

### 配置 Java 認證和服務 (JAAS)

若要配置 JAAS，並使 {siteNameShort} 能夠管理應用程式使用者，必須執行以下各節所述步驟。

#### 新增 JAAS 模組

提交以下命令安裝 JAAS 模組：

```bash theme={null}
java -jar start.jar --add-modules=deploy,jsp,http,jaas
```

#### 建立 {siteNameShort} 登入模組

建立名為 login.config 的登入配置檔案，並將其放在以下路徑：`{JETTY_BASE}/etc/login.conf`。在 login.config 檔案中放入以下內容：

```
Arc {
    arc.LoginModule required debug=true;
};
```

#### 更新安全處理程序

安全處理程序配置位於 arc.xml 配置檔案中。如果您使用[部署 WAR 檔案和 arc.xml](#部署-war-檔案和-arcxml)中的內容建立了 arc.xml 檔案，則可以跳過此步驟，因為該內容已包含此更改。否則，請按如下方式修改 `securityHandler` 塊：

```xml theme={null}
<Set name="securityHandler">
  <New class="org.eclipse.jetty.security.ConstraintSecurityHandler">
   <Set name="loginService">
     <New class="org.eclipse.jetty.jaas.JAASLoginService">
          <!-- This name is the same as **login-config > realm-name** in web.xml.  -->
       <Set name="name">ArcRealm</Set>
          <!-- LoginModuleName must match the name of your LoginModule, as declared in your login-module configuration file. -->
       <Set name="loginModuleName">Arc</Set>
       <!-- Set the principal class name for the custom role. -->
       <Set name="roleClassNames">
           <Array type="java.lang.String">
             <Item>arc.GroupPrincipal</Item>
           </Array>
         </Set>
     </New>
   </Set>
  </New>
</Set>
```

### Jetty 中的 LDAP

若要在 Jetty 中執行 {siteNameShort} 時配置 LDAP，需要先使用標準 {siteNameShort} 登入模組配置 {siteNameShort} 在 Jetty 中執行。當 {siteNameShort} 已在 Jetty 中使用 {siteNameShort} 登入模組啟動並執行後，請按照以下步驟配置 Jetty 使用 LDAP 進行使用者身分驗證。

1. 將 LDAP 使用者新增到 {siteNameShort}。
   1. 以管理員使用者身份登入，將 LDAP 使用者新增到 {siteNameShort}。若要在 {siteNameShort} 中建立 LDAP 使用者，請單擊導覽列中的設定齒輪圖示並選擇 **使用者**。{siteNameShort} 使用者必須與 LDAP 伺服器中的使用者完全相同。例如，如果 LDAP 使用者為 `user01` 和 `user02`，則必須在 {siteNameShort} 中使用相同的使用者名稱。
   2. 完成後，停止 {siteNameShort}。

2. 在 login.conf 中為 Jetty LDAP 登入模組建立 JAAS 配置。
   1. 開啟位於 `${JETTY_BASE}/etc/login.conf` 的 login.conf 檔案，併為 Jetty LDAP 模組新增 JAAS 配置。有許多可用的配置設定，但 JAAS 的配置取決於您的具體要求和 LDAP 伺服器配置。可在 <a href="https://jetty.org/docs/jetty/10/operations-guide/jaas/index.html#ldaploginmodule" target="_blank">Jetty 文件</a>以及下方找到可用 JAAS 配置設定清單：

      ```
      debug
      useLdaps
      contextFactory
      hostname
      port
      bindDn
      bindPassword
      authenticationMethod
      forceBindingLogin
      userBaseDn
      userRdnAttribute
      userIdAttribute
      userPasswordAttribute
      userObjectClass
      roleBaseDn
      roleNameAttribute
      roleMemberAttribute
      roleObjectClass
      ```

   2. 以下是配置了 LDAP 伺服器的 login.conf 檔案範例。請記住，所需設定和值取決於您的具體要求和 LDAP 伺服器配置。若要確定設定所需的值，請諮詢 LDAP 管理員或參閱 LDAP 伺服器文件。

      ```
      Arc {
          arc.LoginModule optional debug=true;
          org.eclipse.jetty.jaas.spi.LdapLoginModule optional
          debug="true"
          contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
          hostname="openldap"
          port="1389"
          bindDn="CN=ldapuser,DC=example,DC=org"
          bindPassword="Adminpassword1"
          authenticationMethod="simple"
          forceBindingLogin="true"
          userBaseDn="OU=users,DC=example,DC=org"
          userRdnAttribute="cn"
          userPasswordAttribute="userPassword"
          roleBaseDn="DC=example,DC=org"
          roleNameAttribute="cn"
          roleMemberAttribute="member"
          useLdaps="false";
      };
      ```

      請注意，`arc.LoginModule` 和 `org.eclipse.jetty.jaas.spi.LdapLoginModule` 都設定為 optional。這樣在嘗試驗證使用者時可以使用兩個登入模組。如果一個登入模組無法驗證使用者，登入會回退到第二個模組。如果兩個登入模組都無法驗證使用者，則登入完全失敗。

   3. 使用必要的 LDAP 配置更新 login.conf 後，重新啟動 {siteNameShort}。如果配置正確，LDAP 使用者現在即可登入 {siteNameShort}。

### 配置資料目錄權限

為執行 Java servlet 容器的處理程序使用者授予對資料目錄的讀/寫存取權限：

* **Windows:** `C:\ProgramData\CData\Arc\`
* **Linux:** `~/cdata/arc`

重新啟動 Jetty 伺服器以使更改生效。現在可以登入應用程式。

## 使用者管理

首次啟動時，{siteNameShort} 會提示您建立具有使用者名稱和密碼憑據的使用者。建立第一個使用者後，可以在應用程式 **系統設定** 頁面的 **使用者** 索引標籤上新增、刪除和管理使用者。

將 {siteNameShort} 部署到外部 Java servlet 時（即**不**使用應用程式隨附的嵌入式伺服器時），需要配置 JAAS，以允許 {siteNameShort} 管理使用者。前面的各節詳細說明了每個特定外部 servlet 的 JAAS 配置過程。

## 查詢並配置應用程式目錄

{siteNameShort} *`ApplicationDirectory`* 資料夾包含應用程式使用的所有資料：配置資料、應用程式資料、日誌資料、憑證等。*`ApplicationDirectory`* 的預設位置取決於 {siteNameShort} 是透過嵌入式 Web 伺服器託管，還是透過外部 Java servlet 容器託管。

對於嵌入式 Web 伺服器，*`ApplicationDirectory`* 與 *`InstallationDirectory`* 相同。預設情況下，該位置如下：

```bash theme={null}
/opt/arc
```

當 {siteNameShort} 託管在外部 Java servlet 容器中時，*`ApplicationDirectory`* 相對於執行伺服器的使用者的主目錄：

`~/arc`

在此路徑中，`~` 解析為執行託管應用程式伺服器的使用者主目錄。

可以配置 *`ApplicationDirectory`* 資料夾，這在多種場景中很有用：

* 將多個 {siteNameShort} 例項組成叢集
* 使用共享網路驅動器儲存應用程式資料
* 將 {siteNameShort} 嵌入存取相同資料夾的其他系統中

更改 *`ApplicationDirectory`* 會移動應用程式的資料檔案。但不會移動 EXE 檔案、JAR 檔案等其他應用程式資源。這些資源儲存在 *`InstallationDirectory`* 資料夾中，該資料夾可能與 *`ApplicationDirectory`* 相同；但如果更改 *`ApplicationDirectory`*，這些資源的位置不會改變。

### 嵌入式 Java 伺服器

將跨平臺版本與嵌入式 Jetty 伺服器配合使用時，預設情況下 *`ApplicationDirectory`* 就是 *`InstallationDirectory`*。若要修改此設定，請[生成 arc.properties 檔案](#生成-arcproperties-檔案)。在文字編輯器中開啟該檔案，然後將 `cdata.app.directory` 設定為所需目錄的路徑。以下範例演示了將資料目錄設定為掛載驅動器上的共享資料夾時的情況：

```bash theme={null}
cdata.app.directory=/mnt/shared/arc
```

如果 {siteNameShort} 能夠找到 `cdata.app.directory` 路徑，並且具有在該路徑讀取和寫入的適當權限，它會在指定目錄中建立資料資料夾。

### 外部 Java 伺服器

將跨平臺版本與外部 Java servlet（應用程式隨附的 Jetty 伺服器以外的任何伺服器）配合使用時，配置應用程式資料目錄的細節取決於所使用的具體 servlet。必須使用適合該 servlet 的語法，將 `AppDirectory` 環境變數設定為所需目錄的路徑。

如果 {siteNameShort} 能夠找到 `AppDirectory` 路徑，並且具有在該路徑讀取和寫入的適當權限，它會在指定目錄中建立資料資料夾。

## 配置應用程式資料庫

{siteNameShort} 應用程式資料庫儲存多個應用程式資料表，包括：

* Transaction Log：應用程式處理的每個交易的中繼資料
* Application Log：應用程式級錯誤和事件
* Access Log：對應用程式 Web 端點的請求
* Audit Log：使用者對 {siteNameShort} 配置所做的更改

預設情況下，{siteNameShort} 使用位於 *`ApplicationDirectory`* 中的 H2 資料庫作為應用程式資料庫。此資料庫建議用於最多 100,000 條交易。達到該數量後，{companyName} 建議移轉到外部資料庫。可以將應用程式配置為使用 SQL Server、PostgreSQL 或 MySQL 等企業資料庫。

<Note>出於安全原因，如果您切換到其他應用程式資料庫，必須執行 [integrityResetTampering](../../scripting/operations/op-integrity-reset-tampering) 操作來重置雜湊鏈。</Note>

### 嵌入式 Java 伺服器

將跨平臺版本與嵌入式 Jetty 伺服器配合使用時，預設應用程式資料庫是 *`ApplicationDirectory`* 中的 H2 資料庫。若要修改此設定，請[生成 arc.properties 檔案](#生成-arcproperties-檔案)。在文字編輯器中開啟該檔案，然後將 `cdata.app.db` 設定為 Java Database Connectivity (JDBC) 連接字串，其中包含所需資料庫的適當連線參數。以下範例展示了 MySQL、PostgreSQL 和 SQL Server 的此設定：

#### MySQL

```
cdata.app.db=jdbc:cdata:mysql:server=localhost;port=3306;database=mysql;user=MyUserName;password=MyPassword
```

#### PostgreSQL

```
cdata.app.db=jdbc:cdata:postgresql:server=localhost;port=5432;database=postgresql;user=MyUserName;password=MyPassword
```

#### SQL Server

```
cdata.app.db=jdbc:cdata:sql:server=localhost;database=sqlserver;user=MyUserName;password=MyPassword
```

如果 {siteNameShort} 能夠使用 `cdata.app.db` 連接字串成功建立連線，它會將該資料庫用作應用程式資料庫。

<Note>為降低使用 SQL Server 作為應用程式資料庫時發生死鎖的可能性，{companyName} 建議確保已啟用 READ\_COMMITTED\_SNAPSHOT。</Note>

### 生成加密的資料庫連接字串

{siteNameShort} 提供為應用程式資料庫連線生成加密連接字串的功能。可以使用此加密連接字串指定應用程式資料庫，而無需在 {siteNameShort} 配置檔案中以明文形式儲存登入憑據。若要生成加密連接字串，請在 arc.jar 所在的安裝目錄中發出以下命令，並將引號中的範例字串替換為您的連線資訊：

```
java -jar arc.jar -EncryptConnectionString "jdbc:cdata:mysql:Server=serverName;Port=1234;Database=databaseName;User=userName;Password=passwordSample"
```

發出命令後，命令視窗會列印加密字串。例如：

```
ENCRYPTEDA:5TWyjE0U4GBEVNkd51SqbMXaBwVGqj5uyMfTHt48y/F5l3sDPZynNnPMb/ppXzuFTzFPywA1/SSKUgLy9nAuvA7RAdZj7WsKI1xAgDMmEFNQ68/lHjFYZpS10sIaoUloyZVDkj4uLHTZ0SaMD5PPUA==
```

然後，您可以使用此加密字串替代 `cdata.app.db` 的明文值，如[上文所示](#配置應用程式資料庫)。

### 外部 Java 伺服器

將跨平臺版本與外部 Java servlet（應用程式隨附的 Jetty 伺服器以外的任何伺服器）配合使用時，配置應用程式資料庫的細節取決於所使用的具體 servlet。配置伺服器時，請使用適合該 servlet 的語法，選擇以下方法之一：

* 定義 JNDI 資料來源，以包含目標資料庫的連線屬性。
* 將 `APP_DB` 環境變數設定為 JDBC 連接字串。

如果 {siteNameShort} 能夠使用 JNDI 資料來源或 `APP_DB` 連接字串連線到資料庫，它會將該資料庫用作應用程式資料庫。

### 指定預設字元集（僅限 MySQL）

對於 MySQL 8.0 及更高版本，資料庫及其表的預設字元集 (charset) 為 UTF8（具體為 `utf8mb4`）。但是，在 MySQL 8.0 之前的版本中，預設字元集通常為 Latin1，這可能會導致包含基本拉丁字母表以外字元的資料出現問題。

如果使用較舊版本的 MySQL，可以透過將資料庫配置為使用 `utf8mb4` 來避免這些問題。有兩種方式可以進行此更改：直接更新現有資料庫，或使用 MySQL 的匯出和匯入工具將資料移轉到新的 UTF8 編碼資料庫。

**直接更新資料庫**

1. 備份資料庫：`mysqldump -u root -p --default-character-set=latin1 --databases [database name] > backup.sql`

2. 將預設字元集更改為 UTF8：`ALTER DATABASE [database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`

3. 生成 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';
   ```

4. 執行上一步生成的 SQL 語句。

**使用匯出和匯入工具**

1. 匯出資料定義語言 (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
   ```

2. 將 schemas.sql 中的預設字元集從 `CHARSET=latin1` 更改為 `CHARSET=utf8mb4`。

3. 建立一個以 UTF8 為預設字元集的新資料庫：`CREATE DATABASE [new database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`

4. 匯入到新資料庫：

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

## 登入鎖定

{siteNameShort} 會自動鎖定輸入錯誤密碼次數過多的使用者，以防止暴力破解攻擊。預設情況下，使用者在五分鐘內輸入六次錯誤密碼會被鎖定三十分鐘。

可以透過編輯控制 Web 伺服器行為的 XML 配置檔案來修改鎖定設定。以下三個設定與鎖定相關：

* **LockoutFailedAttempts**：觸發鎖定的錯誤密碼次數。將 LockoutFailedAttempts 設定為 0 可停用鎖定。
* **LockoutMinutes**：鎖定持續時間。預設持續時間為三十分鐘。
* **LockoutTimeCheckPeriod**：失敗嘗試次數重置為 0 之前的時間段。預設時間段為五分鐘。

### 嵌入式 Jetty 伺服器

可以透過[生成 arc.properties 檔案](#生成-arcproperties-檔案)並向 `initParameters` 新增以逗號分隔的 *name:value* 對清單來修改鎖定設定，如下所示：

```bash theme={null}
cdata.initParameters=LockoutFailedAttempts:0
```

### Tomcat

在 Tomcat arc.xml 檔案中編輯鎖定設定的語法如下：

```xml theme={null}
<Context>
  <Parameter name="LockoutFailedAttempts" value="0" />
</Context>
```

## 常見問題和解決方案

本節列出了在 Java 環境中部署 {siteNameShort} 時可能遇到的常見問題，幷包含每個問題的推薦解決方案。如需更多幫助，請透過 **[edi@kasoftware.cn](mailto:edi@kasoftware.cn)** 聯絡 {companyName} Technical Support。

### 問題

#### {siteNameShort} 無法啟動，或使用非預期的 AppDirectory 啟動

此錯誤可能表明 {siteNameShort} 沒有存取 *`ApplicationDirectory`* 所需的權限。(*`ApplicationDirectory`* 是用於儲存作業、連線、轉換等配置資訊的關鍵資料夾。) 此錯誤的一個可能原因是在將 {siteNameShort} 設定為服務之前，以本地使用者身份執行了它。在這種情況下，應用程式建立的某些資源可能是在本地使用者下建立的。因此，當以服務方式執行 {siteNameShort} 時，這些資源不可用。

### 推薦解決方案

在 Linux 操作環境中，確保服務帳戶（或任何您希望用於執行 {siteNameShort} 的其他帳戶）可以存取 *`ApplicationDirectory`* 的最簡單方式是使用 `chown` 命令。例如，如果 *`ApplicationDirectory`* 位於預設 Linux 位置，並且 {siteNameShort} 應在服務帳戶下執行，則以下命令應可解決該錯誤：

```bash theme={null}
sudo chown -R cdatarc:cdatarc /opt/arc
```