> ## 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} 时可能遇到的常见问题，并包含每个问题的推荐解决方案。如需更多帮助，请通过 **[arcsupport@cdata.com](mailto:arcsupport@cdata.com)** 联系 {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
```