跨平台版本

Version 23.4.8843


跨平台版本


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

内置 Jetty 服务器要求服务器上安装 JDK 11 或更高版本。部署到外部 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 命令在没有服务的情况下运行应用程序。我们建议使用服务,但此方法对于某些配置可能很有用。

启动和停止服务

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

开始菜单

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

  • 启动 知行之桥 管理控制台:在默认 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 文件

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

java -jar arc.jar -GenerateProperties

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

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

更改端口

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

  1. 请找到’arc.properties’文件,并在文本编辑器中打开。

  2. 找到有 cdata.http.port 的一行:

    cdata.http.port=8080

  3. 将这里的值改为需要的值。

启用TLS/SSL

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

  1. 设置 cdata.tls.keyStoreType 属性来制定 keystore 的类型。可用的值为:jks, pkcs12, 和 jceks

  2. 设置 cdata.tls.keyStorePath 属性来指定 keystore 的路径。注意,可以用 ${cdata.home} 来代表安装目录。

  3. 设置 cdata.tls.keyStorePassword 属性来指定 keystore 的密码。

  4. 设置 cdata.tls.port 属性来指定服务器将监听的端口。

  5. 可选。设置 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)。

生成 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

使用 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 --> 
  <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。

创建登录模块(Login Module)

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

在 jaas.config 中添加如下内容以使用标准身份验证:

Arc {
  arc.LoginModule required;
};

如果需要使用 LDAP 认证(或者 Windows AD),则使用如下内容:

 Arc {
  com.sun.security.auth.module.LdapLoginModule REQUIRED
    userProvider="ldaps://ab1cdef234.wfsaas.net:636/CN=Users,DC=example,DC=com"
    authIdentity="{USERNAME}@@example.com"
    userFilter="(&(|(samAccountName={USERNAME})(userPrincipalName={USERNAME})(cn={USERNAME}))(objectClass=user))"
    useSSL=true;
  arc.LoginModule OPTIONAL;
 };

在此示例中,你应该修改 “userProvider”、“authIdentity”和“userFilter”属性的值以适应你的环境。

创建(或修改)JAASRealm 模块

通过创建(或修改)位于此处的配置 XML 文件为知行之桥创建 context:

$CATALINA_BASE/conf/Catalina/localhost/arc.xml

注意: 根据 Tomcat 的配置方式,此路径可能略有不同。 在此示例中,Catalina 指引擎名称,localhost 是 server.xml 中定义的主机名。

定义一个 &lt;Context&gt; 块并添加如下的 &lt;Realm&gt; 元素:

<Context>
 <Realm className="org.apache.catalina.realm.JAASRealm" appName="Arc"
   userClassNames="arc.SimplePrincipal"
   roleClassNames="arc.GroupPrincipal" />
</Context>

然后,通过将 copyXML 属性设置为 true 来更新 Tomcat 服务器的 server.xml 配置文件中的 &lt;Host&gt; 元素,如下所示:

<Host name="localhost" appBase="webapps" unpackWARS="true" autoDeploy="true" copyXML="true">
  ...
</Host>

注意: 如果 server.xml 中存在特定于应用程序的上下文,它将优先于 arc.xml。 例如:

<Context path="arc">
   ...
</Context>

建议你将任何应用程序上下文覆盖(例如 APP_DIRECTORY 或 APP_DB)重新定位到定义 JAASRealm 的 arc.xml。

使登录模块可见

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

配置数据目录权限

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

  • Windows: C:\ProgramData\CData\Arc\

  • Linux: ~/cdata/arc/

重新启动 Tomcat 服务器以使更改生效。 你现在可以登录到该应用程序。

在 WebSphere 中进行配置

配置 WebSphere

为了使 WebSphere 能够正确加载应用程序资源,需要执行以下步骤:

  1. 在 WebSphere 中,导航至:Application > Application Types > WebSphere enterprise applications

  2. 选择 Arc

  3. 选择 Class loading and update detection

  4. 选择 Classes loaded with local class loader first (parent last)

  5. 选择 Single class loader for application

  6. 点击 OK,然后是 Save

JAAS(Java Authentication and Service)配置

为了允许知行之桥在 WebSphere Application Server 中动态管理用户,需要以下操作:

  1. 部署 知行之桥

    1. 启用 application security(导航至:Security > Global security > Enable application security)。

    2. 添加自定义登录模块到系统登录

      1. 导航至:Security > Global security > Java Authentication and Authorization Service > System logins > WEB_INBOUND

      2. 点击 New 以添加一个新的项目 arc.LoginModule. 注意:arcLoginModule 必须在 com.ibm.ws.security.server.lm.ltpaLoginModule 之前。

      3. 选择 Use login module proxy 单选框。

      4. 选择 Authentication strategy 下面的 OPTIONAL

  2. 创建组:

    1. 导航至:Users and Groups > Manage Groups > Create

    2. 创建组: cdata_admin, cdata_standard, cdata_support

  3. 将组映射到角色:

  4. 导航至:Applications > Application Types > WebSphere enterprise applications > arc_war > Security role to user/group mapping

  5. cdata_admin 组映射到 cdata_admin 角色。

  6. cdata_standard 组映射到 cdata_standard 角色。

  7. cdata_support 组映射到 cdata_support 角色。

  8. All Authenticated in Application’s Realm 映射到 cdata_user 角色。

  9. com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual 属性设置为 true:

  10. 进入到 Server > Server Types > Web Sphere Application Servers, 选择托管知行之桥的服务器。

  11. 选择 Container Settings > Web Container Settings > Web Container

  12. 选择 Additional Properties > Custom Properties

  13. 添加新属性: com.ibm.ws.webcontainer.AllowQueryParamWithNoEqual

  14. 将值设置为 true

  15. 重启 WebSphere。

配置数据目录权限

允许运行用户对数据目录进行读/写访问:

  • Windows: C:\ProgramData\CData\Arc\

  • Linux: ~/cdata/arc/

重新启动 WebSphere 服务器以使更改生效。 现在可以登录该应用程序。

在 Jetty 中进行配置

尽管 知行之桥 附带嵌入式 Jetty Web 服务器,但也可以通过外部 Jetty 设置来使用该应用程序。

部署 WAR 文件

将 WAR 文件复制到 Jetty 的 webapps 文件夹中。

配置 JAAS(Java Authentication and Service )

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

添加 JAAS 模块

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

 java -jar {JETTY_HOME}/start.jar --add-to-start=jaas

创建登录模块

创建一个名为 ‘login.config’ 的登录配置文件,放于此处:{JETTY_BASE}/etc/login.conf

文件内容如下:

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

更新安全处理程序

可以在 ‘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> 
        <!-- The LoginModuleName must match the name of your LoginModule as declared in your login module configuration file --> 
     <Set name="loginModuleName">Arc</Set> 
        <!-- Set custom role principal class name --> 
     <Set name="roleClassNames"> 
       <Array type="java.lang.String"> 
         <Item>arc.GroupPrincipal</Item> 
       </Array> 
     </Set> 
   </New> 
 </Set> 
</New> 
</Set>

配置数据目录权限

允许运行 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`