跨平臺版本 - 知行之桥文档

的跨平臺版本包含一個內建 Eclipse Jetty Web 伺服器，因此無需任何外部伺服器配置即可執行。此外，安裝包還包含一個 WAR 檔案，可部署到任何 Java servlet 容器，例如 Apache Tomcat、Eclipse Jetty 或 IBM WebSphere Liberty。要求機器上安裝 Java 17 或更高版本。部署到外部 Java servlet 容器需要 Servlet 3.0（Jetty 8+、Tomcat 7+、WebSphere Liberty 8.5+ 等）。

無論您選擇如何部署，執行應用程式的使用者都必須能夠讀取和寫入 AppDirectory 中的檔案和資料夾。Java Edition 安裝程式中包含的服務安裝程式使用 cdatarc 作為此使用者。如果應用程式之前以其他使用者身份執行，而您想恢復 cdatarc 使用者執行應用程式所需的權限，應使用類似以下範例的命令：sudo chown -R cdatarc:cdatarc /opt/arc

Windows

在 Windows 中，預設安裝為服務。若要存取應用程式，必須先確保服務正在執行。服務執行後，可以開啟 Web 瀏覽器並在 URL 欄位中輸入 http://localhost:8080/ 來存取管理控制檯。您也可以透過 java 命令在不使用服務的情況下執行應用程式。建議使用服務，但此方法對某些配置很有用。

啟動和停止服務

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

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

開始功能表快捷方式

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

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

服務管理控制檯

若要開啟服務管理控制檯，請開啟開始功能表並輸入 services。選擇出現的 Services 應用程式。向下滾動到名為的服務。如果該服務正在執行，Status 列會顯示 Running。右鍵單擊該服務即可存取 Start、Stop 和 Restart 選項。

命令提示符

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

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

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

arc.exe -start

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

arc.exe --restart --ServiceName "知行之桥"
arc.exe --stop --ServiceName "知行之桥"

不使用服務啟動

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

java -jar arc.jar

Linux

將安裝到您選擇的位置後，可以將作為服務執行，也可以手動執行應用程式。如果將用於關鍵應用程式，建議使用服務。

將作為服務執行

將作為服務執行，可使應用程式獨立於任何使用者處理程序執行，並在重新啟動時自動重啟。這是關鍵應用程式的首選方法。建議建立一個守護處理程序來管理 Linux 上的應用程式。安裝包中包含的指令碼可以自動完成此操作。如有必要，也可以手動建立守護處理程序。配置守護處理程序的最安全方式是執行安裝包中包含的指令碼，前提是系統使用 systemd 守護處理程序管理器：

bash ./service.sh

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

systemctl enable arc
systemctl start arc

執行獨立應用程式

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

java -jar arc.jar

配置嵌入式 Jetty 伺服器

已預先配置，可在任何環境中立即工作。不過，您可以透過在安裝目錄（Windows 預設是 C:\Program Files\CData\CData Arc）中生成 arc.properties 檔案，來自定義存取中公開資料的方式。有關所有 arc.properties 配置選項的詳細資訊，請參閱 arc.properties 配置。

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

生成 arc.properties 檔案

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

java -jar arc.jar -GenerateProperties

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

生成此檔案後，升級不會覆蓋它。

更改端口

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

在 InstallationDirectory 中找到 arc.properties 檔案，並在文字編輯器中開啟。
找到設定端口的以下行： cdata.http.port=8080
將該值更改為所需的端口號。

啟用 TLS/SSL

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

將 cdata.tls.keyStoreType 設定為要使用的 keystore 型別。有效值包括 jks、pkcs12 和 jceks。
將 cdata.tls.keyStorePath 設定為要使用的 keystore 路徑。請注意，可以使用 ${cdata.home} 來引用 InstallationDirectory。
將 cdata.tls.keyStorePassword 設定為 keystore 的密碼。
將 cdata.tls.port 設定為託管伺服器應使用的端口。
（可選）將 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

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

將指向其他 .properties 檔案

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

java -jar arc.jar -config test

生成 Jetty XML 檔案

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

java -jar arc.jar -GenerateXML

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

啟動和停止伺服器

如果使用 service.sh 指令碼設定服務，請參閱作為服務執行。否則，請參閱在處理程序中執行部分。

在處理程序中執行

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

java -jar arc.jar

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

java -jar arc.jar -stop

作為服務執行

可以使用標準系統服務命令操作服務，並將 arc 作為服務名稱引用。若要啟動服務，請提交以下命令：

systemctl start arc

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

systemctl stop arc

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

systemctl restart arc

配置 LDAP 身分驗證

如果使用嵌入式 Jetty Web 伺服器，以下步驟會配置使用 LDAP 對使用者進行身分驗證。

配置 arc.properties

如果預設 arc.properties 檔案尚不存在，請使用以下命令生成預設 arc.properties檔案： java -jar arc.jar -GenerateProperties 以下必需設定指示嵌入式 Jetty 伺服器使用 LDAP 進行身分驗證： cdata.loginService.ldap.enabled=true 您可能希望像其他部分一樣在檔案中將其單獨分段：

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

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

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"

在中建立 LDAP 使用者

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

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

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

測試配置

建立包含必要 LDAP 設定的 arc.properties 檔案、將 LDAP 使用者新增到，並根據 LDAP 伺服器要求確認其配置正確後，即可測試該功能。使用 java -jar arc.jar 或透過啟動服務來啟動。顯示登入螢幕後，嘗試使用某個 LDAP 使用者登入。輸入 LDAP 伺服器上的使用者名稱和密碼（必須與您在 使用者 部分輸入的內容完全相同）。登入過程會先檢查登入使用者是否存在於中配置的使用者中，然後再檢查 LDAP 伺服器，以確保該使用者存在並允許存取應用程式。如果配置成功，您將以該使用者身份登入應用程式。

LDAP 配置疑難排解

如果在向 LDAP 伺服器進行身分驗證時遇到問題，建議使用 Apache Directory Studio 測試 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 檔案，請編輯以下值以更改允許的最大檔案大小：

<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)

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

這是任何 Tomcat 環境中設定所必需的第一步。

建立登入模組

在此資料夾中建立名為 jaas.config 的 JAAS 配置檔案：$CATALINA_BASE/conf/。在 jaas.config 中包含以下內容，以使用標準身分驗證：

Arc {
  arc.LoginModule required;
};

如果要使用 LDAP，請繼續完成標準登入模組設定。完成後，請按照使用 LDAP 認證使用者中的步驟操作。

建立（或修改）JAASRealm 模組

檢查 $CATALINA_BASE/conf/Catalina/localhost/ 中是否存在 arc.xml 檔案。如果存在，請編輯 arc.xml 並新增下面的 XML 上下文塊。如果該路徑中不存在 arc.xml，則需要建立它，然後新增下面的 XML 上下文塊。這應該是 arc.xml 中唯一的內容。
<Context> <Realm className="org.apache.catalina.realm.JAASRealm" appName="Arc" userClassNames="arc.SimplePrincipal" roleClassNames="arc.GroupPrincipal" /> </Context>
根據 Tomcat 例項的配置方式，此路徑可能略有不同。在此範例中，Catalina 指引擎名稱，localhost 是 server.xml 中定義的主機名。
在 Tomcat 伺服器的 server.xml 配置檔案中更新 <Host/> 元素，將 copyXML 屬性設定為 true，如下所示：
<Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true"> ... </Host>
如果 server.xml 中存在特定於應用程式的上下文，它會優先於 arc.xml。建議在任何上下文覆蓋中使用 arc.xml 而不是 server.xml。例如：
<Context path="Arc"> ... </Context>

使登入模組可見

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

java.security.auth.login.config=${catalina.base}/conf/jaas.config

使用 LDAP 認證使用者

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

以管理員使用者身份登入。若要建立需要存取的所有 LDAP 使用者，請單擊導覽列上的設定齒輪圖示，然後選擇 使用者。使用者必須與 LDAP 使用者完全相同。例如，如果 LDAP 使用者為 user01 和 user02，則必須在中使用相同的使用者名稱。
修改在建立登入模組中建立的 $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; };
如果任何值包含特殊權杖 {USERNAME}，該權杖會在登入時替換為提供的使用者名稱值。

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

配置資料目錄權限

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

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

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

WebSphere Liberty 中的配置

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

在 WebSphere Liberty 中建立應用程式

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

從 Open Liberty 或 WebSphere Application Server Liberty 24.0.0.12 下載 Liberty。需要 Web Profile 8 包。
執行以下命令建立名為 arc 的伺服器：
- Windows: .\bin\server.bat create arc
- Linux: ./bin/server create arc
將 arc.war 檔案複製到 ./usr/servers/arc/apps 目錄。
如有必要，在 ./usr/servers/arc/server.xml 的 httpEndpoint 元素中更改 HTTP 和 HTTPS 端口（下方提供 server.xml 範例檔案）。
透過編輯 server.xml 檔案進行任何其他應用程式配置更新。
執行以下命令啟動伺服器：
- Windows: .\bin\server.bat start arc
- Linux: ./bin/server start arc

server.xml 範例檔案

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

<?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，並使能夠在 Liberty 應用程式伺服器中動態管理使用者。如果已複製上面的 server.xml 範例檔案，則這些元素已存在。否則，請按照以下步驟操作：

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

<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" />

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

<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 部分將的安全形色對映到使用者組，用於控制不同使用者在應用程式中的權限。每個 security-role 元素定義的一個權限級別，並將其與對應使用者組關聯。請確保為 cdata_admin、cdata_standard、cdata_support 和 cdata_user 配置 security-role 元素。

透過向 webContainer 元素新增 AllowQueryParamWithNoEqual 屬性，啟用不帶等號 (=) 的查詢參數。此設定允許正確處理某些不包含等號的 URL 查詢參數。
<webContainer AllowQueryParamWithNoEqual="true" />
重新啟動 Liberty。

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

使用 LDAP 認證使用者

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

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

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

<!-- Enable features -->
<featureManager>
  <feature>webProfile-8.0</feature>
  <feature>ldapRegistry-3.0</feature>
</featureManager>

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

<!-- 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>

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

<jaasLoginModule id="arcLoginModule" className="arc.LoginModule" controlFlag="OPTIONAL" classProviderRef="arc-app">
     <options isWebSphere="true" />
</jaasLoginModule>

以本地管理員使用者身份登入。若要在中建立 LDAP 使用者，請單擊導覽列中的設定齒輪圖示並選擇 使用者。使用者必須與 LDAP 伺服器中的使用者完全相同。例如，如果 LDAP 使用者為 user01 和 user02，則必須在中使用相同的使用者名稱。
儲存更改並重新啟動 Liberty 以完成該過程。配置成功後，登入的使用者會透過 LDAP 進行身分驗證。

偵錯設定

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

<!-- 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 容器操作以及所有和 RSSBus 模組。此配置提供了詳盡的診斷資訊，有助於排查身分驗證問題、授權問題和應用程式特定錯誤。日誌會寫入 ${server.config.dir}/logs 目錄，並分別使用訊息檔案 (messages.log) 和跟蹤資料檔案 (trace.log)。對於生產環境，您可能希望降低日誌詳細程度以提高效能，並儘量減少日誌檔案增長。為此，可以將特定跟蹤規範從 all 更改為 info，或移除不需要監控的元件。例如，如果不排查安全問題，可以將配置簡化為 traceSpecification="arc.*=all:rssbus.*=all"，以僅關注特定日誌。相反，如果在疑難排解期間需要更詳細的診斷，可以臨時設定 traceSpecification="*=all"，以啟用所有 Liberty 元件的全面日誌記錄。請注意，這會快速生成大型日誌檔案，應僅用於短期偵錯。

配置資料目錄權限

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

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

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

Jetty 中的配置

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

部署 WAR 檔案和 arc.xml

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

<?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，並使能夠管理應用程式使用者，必須執行以下各節所述步驟。

新增 JAAS 模組

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

java -jar start.jar --add-modules=deploy,jsp,http,jaas

建立登入模組

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

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

更新安全處理程序

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

<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 中執行時配置 LDAP，需要先使用標準登入模組配置在 Jetty 中執行。當已在 Jetty 中使用登入模組啟動並執行後，請按照以下步驟配置 Jetty 使用 LDAP 進行使用者身分驗證。

將 LDAP 使用者新增到。
1. 以管理員使用者身份登入，將 LDAP 使用者新增到。若要在中建立 LDAP 使用者，請單擊導覽列中的設定齒輪圖示並選擇 使用者。使用者必須與 LDAP 伺服器中的使用者完全相同。例如，如果 LDAP 使用者為 user01 和 user02，則必須在中使用相同的使用者名稱。
2. 完成後，停止。
在 login.conf 中為 Jetty LDAP 登入模組建立 JAAS 配置。
1. 開啟位於 ${JETTY_BASE}/etc/login.conf 的 login.conf 檔案，併為 Jetty LDAP 模組新增 JAAS 配置。有許多可用的配置設定，但 JAAS 的配置取決於您的具體要求和 LDAP 伺服器配置。可在 Jetty 文件以及下方找到可用 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 後，重新啟動。如果配置正確，LDAP 使用者現在即可登入。

配置資料目錄權限

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

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

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

使用者管理

首次啟動時，會提示您建立具有使用者名稱和密碼憑據的使用者。建立第一個使用者後，可以在應用程式 系統設定 頁面的 使用者 索引標籤上新增、刪除和管理使用者。將部署到外部 Java servlet 時（即不使用應用程式隨附的嵌入式伺服器時），需要配置 JAAS，以允許管理使用者。前面的各節詳細說明了每個特定外部 servlet 的 JAAS 配置過程。

查詢並配置應用程式目錄

ApplicationDirectory 資料夾包含應用程式使用的所有資料：配置資料、應用程式資料、日誌資料、憑證等。ApplicationDirectory 的預設位置取決於是透過嵌入式 Web 伺服器託管，還是透過外部 Java servlet 容器託管。對於嵌入式 Web 伺服器，ApplicationDirectory 與 InstallationDirectory 相同。預設情況下，該位置如下：

/opt/arc

當託管在外部 Java servlet 容器中時，ApplicationDirectory 相對於執行伺服器的使用者的主目錄： ~/arc 在此路徑中，~ 解析為執行託管應用程式伺服器的使用者主目錄。可以配置 ApplicationDirectory 資料夾，這在多種場景中很有用：

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

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

嵌入式 Java 伺服器

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

cdata.app.directory=/mnt/shared/arc

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

外部 Java 伺服器

將跨平臺版本與外部 Java servlet（應用程式隨附的 Jetty 伺服器以外的任何伺服器）配合使用時，配置應用程式資料目錄的細節取決於所使用的具體 servlet。必須使用適合該 servlet 的語法，將 AppDirectory 環境變數設定為所需目錄的路徑。如果能夠找到 AppDirectory 路徑，並且具有在該路徑讀取和寫入的適當權限，它會在指定目錄中建立資料資料夾。

配置應用程式資料庫

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

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

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

出於安全原因，如果您切換到其他應用程式資料庫，必須執行 integrityResetTampering 操作來重置雜湊鏈。

嵌入式 Java 伺服器

將跨平臺版本與嵌入式 Jetty 伺服器配合使用時，預設應用程式資料庫是 ApplicationDirectory 中的 H2 資料庫。若要修改此設定，請生成 arc.properties 檔案。在文字編輯器中開啟該檔案，然後將 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

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

為降低使用 SQL Server 作為應用程式資料庫時發生死鎖的可能性，建議確保已啟用 READ_COMMITTED_SNAPSHOT。

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

提供為應用程式資料庫連線生成加密連接字串的功能。可以使用此加密連接字串指定應用程式資料庫，而無需在配置檔案中以明文形式儲存登入憑據。若要生成加密連接字串，請在 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 連接字串。

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

指定預設字元集（僅限 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

登入鎖定

會自動鎖定輸入錯誤密碼次數過多的使用者，以防止暴力破解攻擊。預設情況下，使用者在五分鐘內輸入六次錯誤密碼會被鎖定三十分鐘。可以透過編輯控制 Web 伺服器行為的 XML 配置檔案來修改鎖定設定。以下三個設定與鎖定相關：

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

嵌入式 Jetty 伺服器

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

cdata.initParameters=LockoutFailedAttempts:0

Tomcat

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

<Context>
  <Parameter name="LockoutFailedAttempts" value="0" />
</Context>

常見問題和解決方案

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

問題

無法啟動，或使用非預期的 AppDirectory 啟動

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

​Windows

​啟動和停止服務

​開始功能表快捷方式

​服務管理控制檯

​命令提示符

​不使用服務啟動

​Linux

​將 作為服務執行

​執行獨立應用程式

​配置嵌入式 Jetty 伺服器

​生成 arc.properties 檔案

​更改端口

​啟用 TLS/SSL

​將 指向其他 .properties 檔案

​生成 Jetty XML 檔案

​啟動和停止伺服器

​在處理程序中執行

​作為服務執行

​配置 LDAP 身分驗證

​配置 arc.properties

​在 中建立 LDAP 使用者

​測試配置

​LDAP 配置疑難排解

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

​Tomcat 中的配置

​部署 WAR 檔案

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

​建立登入模組

​建立（或修改）JAASRealm 模組

​使登入模組可見

​使用 LDAP 認證使用者

​配置資料目錄權限

​WebSphere Liberty 中的配置

​在 WebSphere Liberty 中建立 應用程式

​server.xml 範例檔案

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

​使用 LDAP 認證使用者

​偵錯設定

​配置資料目錄權限

​Jetty 中的配置

​部署 WAR 檔案和 arc.xml

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

​新增 JAAS 模組

​建立 登入模組

​更新安全處理程序

​Jetty 中的 LDAP

​配置資料目錄權限

​使用者管理

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

​嵌入式 Java 伺服器

​外部 Java 伺服器

​配置應用程式資料庫

​嵌入式 Java 伺服器

​MySQL

​PostgreSQL

​SQL Server

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

​外部 Java 伺服器

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

​登入鎖定

​嵌入式 Jetty 伺服器

​Tomcat

​常見問題和解決方案

​問題

​ 無法啟動，或使用非預期的 AppDirectory 啟動

​推薦解決方案

Windows

啟動和停止服務

開始功能表快捷方式

服務管理控制檯

命令提示符

不使用服務啟動

Linux

將作為服務執行

執行獨立應用程式

配置嵌入式 Jetty 伺服器

生成 arc.properties 檔案

更改端口

啟用 TLS/SSL

將指向其他 .properties 檔案

生成 Jetty XML 檔案

啟動和停止伺服器

在處理程序中執行

作為服務執行

配置 LDAP 身分驗證

配置 arc.properties

在中建立 LDAP 使用者

測試配置

LDAP 配置疑難排解

Tomcat 中的配置

部署 WAR 檔案

配置 Java 認證和服務 (JAAS)

建立登入模組

建立（或修改）JAASRealm 模組

使登入模組可見

使用 LDAP 認證使用者

配置資料目錄權限

WebSphere Liberty 中的配置

在 WebSphere Liberty 中建立應用程式

server.xml 範例檔案

配置 Java 認證和服務 (JAAS)

使用 LDAP 認證使用者

偵錯設定

配置資料目錄權限

Jetty 中的配置

部署 WAR 檔案和 arc.xml

配置 Java 認證和服務 (JAAS)

新增 JAAS 模組

建立登入模組

更新安全處理程序

Jetty 中的 LDAP

配置資料目錄權限

使用者管理

查詢並配置應用程式目錄

嵌入式 Java 伺服器

外部 Java 伺服器

配置應用程式資料庫

嵌入式 Java 伺服器

MySQL

PostgreSQL

SQL Server

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

外部 Java 伺服器

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

登入鎖定

嵌入式 Jetty 伺服器

Tomcat

常見問題和解決方案

問題

無法啟動，或使用非預期的 AppDirectory 啟動

推薦解決方案