跨平台版本

Version 26.1.9526

Windows
- 启动和停止服务
- 在没有服务的情况下启动
Linux
- 将知行之桥作为服务运行
- 运行独立应用程序
配置嵌入式 Jetty 服务器
使用 Apache Tomcat
- 部署 WAR 文件
JAAS（Java Authentication and Service）配置
在 WebSphere Liberty 中进行配置
在 Jetty 中进行配置
用户管理
查找并配置应用程序目录
- 内置 Java 服务器
- 外部 Java 服务器
配置应用程序数据库
登录锁定
- 内置 Jetty 服务器
- Tomcat
常见问题及解决方案
- 问题
- 解决方案

跨平台版本

知行之桥的跨平台版本与基于 Jetty 构建的 web 服务器绑定在一起，因此无需任何外部服务器配置即可运行。此外，该安装包括一个. WAR文件，可以部署到任何Java servlet容器，如 Apache Tomcat, Eclipse Jetty，或者IBM WebSphere Liberty。

内置 Jetty 服务器要求服务器上安装 JDK 17 或更高版本。部署到外部 Java servlet 则需要 Servlet 3.0 (Jetty 8+、Tomcat 7+、JBoss EAP 6/7、Glassfish 3、WebLogic 12+、WebSphere 8+等)。

注意：无论如何部署知行之桥，运行应用程序的用户都必须能够读写 AppDirectory 中的文件和文件夹。Java Edition 安装程序中包含的服务安装程序将使用 cdataarc 作为该用户。

如果该应用程序以前是以其他用户身份运行的，并且你希望恢复 cdataarc 用户运行该应用程序所需的权限，则命令类似于:

sudo chown -R cdataarc:cdataarc /opt/arc

Windows

在 Windows 中，知行之桥默认安装为服务。要访问该应用程序，必须首先确保该服务正在运行。服务运行后，可以通过打开网络浏览器并在 URL 字段中输入 http://localhost:8080/ 来访问知行之桥管理控制台。

还可以通过 java 命令在没有服务的情况下运行应用程序。我们建议使用服务，但此方法对于某些配置可能很有用。

启动和停止服务

可以通过以下任一方式启动和停止该服务：

开始菜单 (推荐)
服务管理控制台
命令提示符命令

开始菜单

知行之桥安装程序创建开始菜单快捷方式，使可以轻松使用该应用程序。要访问这些快捷方式，请打开开始菜单并展开 知行之桥 文件夹。这些快捷键可用：

启动知行之桥管理控制台：在默认 Web 浏览器中打开 Web 浏览器窗口，访问管理控制台 URL http://localhost:8080/。如果服务未运行，Web 浏览器将返回错误。
启动知行之桥：启动知行之桥服务。默认情况下，此服务在 Windows 启动时运行，因此无需每次运行应用程序时都运行此命令。
停止知行之桥：停止知行之桥服务。当升级知行之桥时，必须执行此操作。

服务管理控制台

要打开服务管理控制台，请打开开始菜单并键入服务。选择出现的服务应用程序。

向下滚动到名为 知行之桥 的服务。如果该服务正在运行，状态列显示正在运行。右键单击该服务可访问“启动”、“停止”和“重新启动”选项。

命令提示符

高级用户可以使用 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 配置。

提示：以下配置选项在实现过程中的所有 .properties 文件中均可使用。

生成 arc.properties 文件

在对嵌入式 Jetty 服务器进行任何自定义之前，必须创建 arc.properties 文件。在arc.jar所在的安装目录下执行以下命令：

java -jar arc.jar -GenerateProperties

这将在安装目录中创建 arc.properties 文件。该文件包含可以修改为更改端口或启用 TLS/SSL的参数。

注意：生成此文件后，升级到知行之桥不会覆盖它。

更改端口

要配置内置服务器侦听的端口:

在 InstallationDirectory 中找到 arc.properties 文件，在文本编辑器中打开。
找到有 cdata.http.port 的一行：

cdata.http.port=8080
将这里的值改为需要的值。

启用TLS/SSL

启用 TLS/SSL 连接 (HTTPS) 还涉及修改安装目录中的 arc.properties 文件：

设置 cdata.tls.keyStoreType 属性来指定 keystore 的类型。可用的值为：jks, pkcs12, 和 jceks。
设置 cdata.tls.keyStorePath 属性来指定 keystore 的路径。注意，可以用 ${cdata.home} 来代表安装目录。
设置 cdata.tls.keyStorePassword 属性来指定 keystore 的密码。
设置 cdata.tls.port 属性来指定服务器将监听的端口。
可选。设置 cdata.http.port 为空值以关闭非 TLS/SSL 连接。

最终的结果大概类似于下面这个样子：

;; HTTP
cdata.http.port=

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

注意：如果你在知行之桥中配置外部的私钥文件，请务必将证书的所有者更改为用于运行知行之桥的服务帐户 (如：cdataarc:cdataarc)。

将知行之桥指向不同的 .properties 文件

使用 -config 参数可以将知行之桥指向默认 .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 脚本已用于设置知行之桥服务，请参考下面的“作为服务运行”部分。否则，可参考“在进程中运行”部分。

在进程中运行

内置 Jetty 服务器通过执行从安装过程中下载的应用程序中提取的“arc.jar”文件来启动。标准 Java 语法可用于执行此文件并启动服务器：

java -jar arc.jar

要停止服务，只需向此命令传递一个 -stop 附加参数：

java -jar arc.jar -stop

作为服务运行

知行之桥可以使用标准的系统服务命令来操作服务，引用 &prod.objname:tolower; 作为服务的名称。

启动服务：

systemctl start arc

停止服务：

systemctl stop arc

重启服务：

systemctl restart arc

配置 LDAP 认证

如果您使用嵌入式 Jetty 服务器，则以下步骤将配置知行之桥使用 LDAP 对用户进行身份验证。

配置 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，则您必须在知行之桥中使用相同的用户名。

添加所有用户后，您可以停止应用程序。

测试配置

在创建的 arc.properties 文件中添加必要的 LDAP 设置，将 LDAP 用户添加到知行之桥并确认其配置符合 LDAP 服务器的要求后，您就可以测试功能了。

使用 java -jar arc.jar 或启动知行之桥服务来启动知行之桥。当您看到登录界面时，尝试使用您的某个 LDAP 用户登录。输入 LDAP 服务器上的用户名和密码（必须与您在知行之桥的用户部分中输入的用户名相同）。

登录过程会根据知行之桥中配置的用户检查登录用户，然后根据 LDAP 服务器检查登录用户，以确保用户存在并允许访问应用程序。如果配置成功，您将以该用户身份登录应用程序。

使用 Apache Tomcat

部署 WAR 文件

将 WAR 文件部署到 Tomcat 有多种选择。

将 WAR 文件复制到 webapps 文件夹中。
在 Tomcat 的管理控制台内部署 WAR 文件。 Tomcat 文档更详细地介绍了此方法。

WAR 文件可能会超过 Tomcat 中允许文件上传的默认最大大小。为了解决部署期间的错误，可以编辑管理器应用程序的 WEB.XML 文件以允许使用更大的文件。根据服务器的 tomcat 配置，此文件可能位于 /usr/share/tomcat7-admin/manager/WEB-INF 或其他类似目录中。在此文件中，你可以更改允许的最大文件大小的字节大小。例如，要允许部署 200MB WAR 文件，请编辑以下值以更改允许的最大文件大小：

<multipart-config>
  <!-- 最大 200 MB --> 
  <max-file-size>209715200</max-file-size>
  <max-request-size>209715200</max-request-size>
  <file-size-threshold>0</file-size-threshold>
</multipart-config>

JAAS（Java Authentication and Service）配置

要使知行之桥能够在应用程序内动态管理用户，您必须按照以下指南中的说明配置 JAAS。本指南使用 arc.xml 来控制 Tomcat 的配置。知行软件建议您使用 arc.xml 而不是 server.xml 来控制 Tomcat 配置。我们还建议您将任何应用程序上下文覆盖（例如 APP_DIRECTORY 或 APP_DB）重新定位到定义 JAASRealm 模块的 arc.xml。

注意：这是使用知行之桥设置任何 Tomcat 所需的第一步。

创建登录模块（Login Module）

在此处创建名为 jaas.config 的 JAAS 配置文件： $CATALINA_BASE/conf/jaas.config。

在 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 中定义的主机名。
通过将 copyXML 属性设置为 true，更新 Tomcat 服务器的 server.xml 配置文件中的 <Host/> 元素，如下所示：
```
 <Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true">
   ...
 </Host>
```
注意： 如果 server.xml 中存在特定于应用程序的上下文，则它优先于 arc.xml。知行软件建议在任何上下文覆盖中使用 arc.xml 而不是 server.xml。例如：
```
 <Context path="Arc">
    ...
 </Context>
```

使登录模块可见

JVM 必须指向登录模块 (jaas.config)，以便配置可见性。将 JVM 上的 java.security.auth.login.config 系统属性设置为 jaas.config 文件的路径。这可以通过附加到 $CATALINA_BASE/conf/catalina.properties 文件来完成，如下所示：

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.LoginModuleoptional;
 };
```
注意：如果任何值包含特殊令牌 {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=" 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 认证用户

在将知行之桥配置为配合 Liberty 使用 LDAP 之前，请按照配置 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">
          <!-- 此名称与 web.xml 中的 **login-config > realm-name** 相同。  -->
          <Set name="name">ArcRealm</Set>
          <!-- LoginModuleName 必须与您的 LoginModule 名称匹配，如您的登录模块配置文件中声明的那样。-->
          <Set name="loginModuleName">Arc</Set>
          <!-- 设置自定义角色的主体类名。-->
          <Set name="roleClassNames">
            <Array type="java.lang.String">
              <Item>arc.GroupPrincipal</Item>
            </Array>
          </Set>
        </New>
      </Set>
    </New>
  </Set>
</Configure>

配置 JAAS（Java Authentication and Service ）

需要以下步骤来配置 JAAS 并允许知行之桥管理应用程序用户。

添加 JAAS 模块

运行以下命令安装 JAAS 模块：

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

创建知行之桥登录模块

创建一个名为 login.conf 的登录配置文件，并将其放在以下路径：{JETTY_BASE}/etc/login.conf。将以下内容放入 login.conf 文件中：

文件内容如下：

 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"> 
     <!-- 此名称与 web.xml 中的 **login-config > realm-name** 相同。  -->
     <Set name="name">ArcRealm</Set> 
     <!-- LoginModuleName 必须与您的 LoginModule 名称匹配，如您的登录模块配置文件中声明的那样。-->
     <Set name="loginModuleName">Arc</Set> 
     <!-- 设置自定义角色的主体类名。-->
     <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 均设置为可选。这允许在尝试验证用户时使用两个登录模块。如果一个登录模块无法验证用户，则登录将回退到第二个模块。如果两个登录模块都无法验证用户，则登录将完全失败。
3. 使用必要的 LDAP 配置更新 login.conf 后，重新启动知行之桥。如果配置正确，您的 LDAP 用户现在可以登录知行之桥。

配置数据目录权限

允许运行 Java servlet 容器的进程的用户对数据目录进行读／写访问：

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

重新启动服务器并登录应用程序。

用户管理

首次启动时，知行之桥将提示创建具有用户名/密码的用户。创建第一个用户后，可以通过应用程序的 系统配置 页面的 Users 选项添加、删除和管理用户。

将知行之桥部署到外部 Java servlet 时（即不使用应用程序附带的内置服务器时），需要配置 JAAS 以允许知行之桥管理用户。以下节点详细介绍了各个特定外部 servlet 的 JAAS 配置步骤。

查找并配置应用程序目录

知行之桥的_应用程序目录保存应用程序使用的所有数据：配置数据、应用程序数据、日志数据、证书等。应用程序目录_的默认位置取决于知行之桥是通过内置 web 服务器还是外部 Java servlet 容器托管。

对于内置 web 服务器，_应用程序目录_与安装目录相同，默认情况下安装目录如下:

 /opt/arc

当在外部 Java servlet 容器中托管知行之桥时，_应用程序目录_相对于运行服务器的用户的主目录:

~/arc

其中 ‘~’ 解析为运行托管应用程序的服务器的用户的主目录。

配置_应用程序目录_文件夹，在多种情况下都很有用：

归并多个知行之桥实例
对应用程序数据使用共享网络驱动器
在访问相同文件夹的其它系统中嵌入知行之桥

更改_应用程序目录将移动应用程序的数据文件，但不会移动其它应用程序资源 .exe，.jar 等等。这些资源保存在安装目录中，安装目录可能与应用程序目录相同，但如果应用程序目录_发生变化，安装目录也不会发生变化。

内置 Java 服务器

当将跨平台版本与内置 Jetty 服务器一起使用时，会在 arc.properties 中文件中配置 ApplicationDirectory。在此服务器配置文件中，你必须将 cdata.app.directory 属性设置为所需目录的路径。以下示例演示了将数据目录设置为已装载驱动器上的共享文件夹时的情况:

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

如果知行之桥可以找到 cdata.app.directory 路径，并且具有在该路径读写的适当权限，它将在指定目录中创建数据文件夹。

外部 Java 服务器

将跨平台版本与外部 Java servlet（除了应用程序中包含的 Jetty 服务器之外的任何服务器）一起使用时，配置应用程序数据目录的细节取决于所使用的特定 servlet。使用适合特定 servlet 的语法，必须将环境变量设置为所需目录的路径。

如果知行之桥找到 AppDirectory 路径，并具有在指定路径上读写的权限，它将在指定的目录中创建数据文件夹。

配置应用程序数据库

知行之桥的应用程序数据库存储了几个应用程序数据表，包括：

交易日志-应用程序处理的每笔交易的元数据
应用程序日志-应用程序级错误和事件
访问日志-对应用程序的网络端的请求
审计日志-用户对知行之桥配置的更改

默认情况下，知行之桥默认使用_应用程序目录_中的 Derby 数据库为应用程序数据库，也可通过配置使用其它数据库，如 SQL Server, PostgreSQL 或 MySQL。

内置 Java 服务器

将跨平台版本与内置 Jetty 服务器一起使用时，应用程序数据库在 arc.properties 文件中进行配置。在此服务器配置文件中，必须将 cdata.app.db 属性设置为 Java 数据库连接(JDBC)连接字符串，该字符串包含所需数据库的适当连接参数。以下部分提供了各种服务器配置的示例连接字符串。你可以如下所示以明文设置这些值，或者你可以生成加密连接字符串来代替使用。

MySQL

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

PostgreSQL

cdata.app.db=jdbc:cdata:postgresql:server=localhost;port=5432;database=postgres;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。

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

知行之桥提供为你的应用程序数据库连接生成加密连接字符串的能力。你可以使用此加密连接字符串来指定应用程序数据库，而无需将你的登录凭据以明文形式存储在知行之桥配置文件中。要生成加密的连接字符串，请在安装目录中发出以下命令，用引号中的示例字符串替换你的连接信息：

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 连接字符串。

如果知行之桥可以使用 JDNI 数据源或 APP_DB 连接字符串来连接数据库，它将使用该数据库作为应用程序数据库。

登录锁定

知行之桥会自动锁定输入错误密码次数过多的用户，以防止暴力破解攻击。默认情况下，用户在 5 分钟内输入 6 次错误密码将被锁定 30 分钟。

可以通过编辑控制 Web 服务器的 XML 配置文件来修改此置。以下是3个与登录锁定相关的设置：

LockoutFailedAttempts：触发锁定的错误密码尝试次数（设置为 0 表示禁用登录锁定）
LockoutMinutes：锁定时间（默认 30 分钟）
LockoutTimeCheckPeriod：失败重试次数重置为 0 的时间间隔（默认为 5 分钟）

内置 Jetty 服务器

在 arc.properties 中，可以通过将逗号分隔的 name:value 值添加到 initParameters 属性，来修改锁定设置，如下所示：

cdata.initParameters=LockoutFailedAttempts:0

Tomcat

在 Tomcat 的 ‘server.xml’ 中配置示例如下：

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

常见问题及解决方案

本节列出了在 Java 环境中部署知行之桥时遇到的常见问题。包括针对每个问题的推荐解决方案，如需更多帮助，请联系 support@kasoftware.cn。

问题

知行之桥无法启动，或启动了非预期的应用程序目录。

此错误可能表明知行之桥没有访问应用程序目录所需的权限（应用程序目录是一个文件夹，用于存储有关工作流配置、证书等的关键信息）。可能的原因包括在将知行之桥设置为服务之前以本地用户身份运行它；在这种情况下，应用程序创建的某些资源可能是在本地用户下创建的，因此在作为服务运行时不可用。

解决方案

在 Linux 中，确保服务用户（或你要用于运行知行之桥的任何其他帐户）有权访问应用程序目录的最简单方法是使用 chown 命令。例如，如果应用程序目录位于默认的 linux 位置并且知行之桥应该在服务用户下运行，以下命令可以解决该错误：

sudo chown -R cdataarc:cdataarc /opt/arc`

跨平台版本

跨平台版本

Windows

启动和停止服务

开始菜单

服务管理控制台

命令提示符

在没有服务的情况下启动

Linux

将 知行之桥 作为服务运行

运行独立应用程序

配置嵌入式 Jetty 服务器

生成 arc.properties 文件

更改端口

启用TLS/SSL

将知行之桥指向不同的 .properties 文件

生成 Jetty XML 文件

启动和停止服务

在进程中运行

作为服务运行

配置 LDAP 认证

配置 arc.properties

在知行之桥中创建 LDAP 用户

测试配置

使用 Apache Tomcat

部署 WAR 文件

JAAS（Java Authentication and Service） 配置

创建登录模块（Login Module）

创建（或修改）JAASRealm 模块

使登录模块可见

使用 LDAP 验证用户

配置数据目录权限

在 WebSphere Liberty 中进行配置

在 WebSphere Liberty 中创建知行之桥应用程序

server.xml 示例文件

配置 Java 认证和服务 (JAAS)

使用 LDAP 认证用户

调试设置

配置数据目录权限

在 Jetty 中进行配置

部署 WAR 文件和 arc.xml

配置 JAAS（Java Authentication and Service ）

添加 JAAS 模块

创建知行之桥登录模块

更新安全处理程序

Jetty 中的 LDAP

配置数据目录权限

用户管理

查找并配置应用程序目录

内置 Java 服务器

外部 Java 服务器

配置应用程序数据库

内置 Java 服务器

MySQL

PostgreSQL

SQL Server

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

外部 Java 服务器

登录锁定

内置 Jetty 服务器

Tomcat

常见问题及解决方案

问题

解决方案

将知行之桥作为服务运行

JAAS（Java Authentication and Service）配置