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

的跨平台版本包含一个内置 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 环境中部署时可能遇到的常见问题，并包含每个问题的推荐解决方案。如需更多帮助，请通过 arcsupport@cdata.com 联系 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 启动

推荐解决方案