用户手册

# 前言

本文档为金蝶 Apusic 迁移工具使用说明，详细介绍金蝶 Apusic 迁移工具相关配置方法。

# 面向对象

本手册主要面向对象为使用金蝶 Apusic 迁移工具进行资源迁移的相关管理人员和运维人员。

# 版本说明

本文档为金蝶 Apusic 迁移工具使用手册，根据工具版本更新情况累积修订本文档内容。

日期	手册版本	适用产品	更新说明
2021年12月	V01E01F01	Migration-AAS V1.0	介绍使用说明

# 产品简介

# 概述

金蝶Apusic迁移工具版本1.0（简称“Migration-AAS V1.0”）使用Java技术开发，实现应用/配置分析、依赖检测、迁移到AAS。该工具整体由解析工具和安装工具组成，解析分析工具对目标服务器的WEB、EJB、数据源解析分析，依赖检测；安装工具把解析分析工具的输出安装到AAS服务器。

# 平台环境

操作系统	说明
Windows	Windows7、Windows10、Windows Server
Linux	CentOS、Ubuntu、SUSE、Redhat
国产平台	银河麒麟系列、中标麒麟系列、普华、中科红旗、深度等

# 系统环境

系统组件	系统要求
Java环境	JDK8
内存	至少需要 512MB 的内存
磁盘空间	至少需要 1024MB 的磁盘空间

# 术语

Migration-AAS：金蝶Apusic迁移工具

AAS：金蝶Apusic应用服务器

# 产品清单

下表说明产品资源，其中${Migration-AAS_HOME}表示金蝶Apusic迁移工具安装目录。

目录资源	说明
${Migration-AAS_HOME}/applications	需要安装的独立应用程序包，如jar、war、ear包
${Migration-AAS_HOME}/bin	迁移工具启动脚本（Linux平台是migrate，Windows平台是migrate.cmd）
${Migration-AAS_HOME}/classes	迁移工具Java字节码文件目录
${Migration-AAS_HOME}/common	迁移工具公共资源目录
${Migration-AAS_HOME}/conf	迁移工具配置conf目录
${Migration-AAS_HOME}/lib	迁移工具依赖jar目录
${Migration-AAS_HOME}/log	工具log文件目录
${Migration-AAS_HOME}/out	运行迁移工具后保存迁移的应用、配置、jar包安全分析结果等
${Migration-AAS_HOME}/temp	运行迁移工具后迁移数据源、war、ejb应用生产的临时目录
${Migration-AAS_HOME}/backup	迁移应用、配置到AAS应用服务器时生成的备份AAS相关应用、配置的备份目录

# 使用向导

下面介绍金蝶Apusic迁移工具作为一个完整的产品进行使用，${Migration-AAS_HOME}表示金蝶Apusic迁移工具安装目录。

# 安装

金蝶Apusic迁移工具支持在Linux、Windows等操作系统上安装，需要准备JDK8环境。

Windows、Linux系统下压缩包直接解压到相关目录即可，以Linux操作系统为例。

终端解压安装包：unzip migration.zip解压成功后进入安装目录，其目录结构如下：

# 配置说明

迁移工具配置文件为conf/conf.properties，内部配置说明如下：

">说明

参数	默认值
server_home	待迁移应用服务器的安装目录。若迁移独立应用只需把独立应用放置到applications目录即可，不用配置该项	D:/develop/wls1036
install_home	迁移安装的AASV9/AASV10 服务器安装目录	D:/develop/aas/AAS-V10
wls.domainPath	WebLogic 域路径名,不指定将解析所有域，从Weblogic迁移应用或其他资源时才需要配置	D:/develop/wls1036/user_projects/domains/base_domain
security.checker.update.enable	安全检测更新，启用安全检测更新则在安全检测时会联网校验	false

![](./assets/user-manual/image2.png)

# 命令说明

进入安装目录并运行对应平台下的migrate，如Linux执行sh bin/migrate，效果如下。

# migrate analyse

对待迁移服务器或独立应用目录(applications)的应用进行分析，生成迁移应用、迁移配置、依赖检测和安全检测至out目录。

# migrate install

迁移生成的out目录配置、应用到AAS服务器，conf/conf.properties配置文件需要配置install_home配置项指定AAS服务器安装目录。安装时还会生成backup目录，其内保存AAS服务器对应的备份文件，在迁移失败时使用保存的backup文件中的备份文件恢复AAS服务器配置和应用信息。

# migrate rollback

AAS配置、应用回退会使用backup目录中离当前最近的备份恢复AAS服务器。

# 卸载

进入金蝶Apusic迁移工具安装目录，将整个目录删除即可卸载该工具。

# 独立应用迁移

金蝶Apusic迁移工具支持将应用包从工具对应目录中迁移到金蝶Apusic应用服务器。

# 应用分析

把独立应用war、jar、ear包放置于applications目录，如web.war。

配置conf/conf.properties 的install_home配置项为金蝶Apusic应用服务器安装目录，配置项server_home不用配置。

执行sh bin/migrate analyse 生成输出配置、应用目录out。

out目录结构如下:

20210720163731：按时间顺序生成的虚拟域目录，如果解析的为WebLogic则为WebLogic的域名称
applications： 待迁移的应用程序包目录
class-conflict： 类冲突检测的输出目录
config： 迁移应用解析后的配置文件目录
dependency-check： 安全检测输出目录
manufacturer-dependent-testing： 厂商依赖检测输出目录

# 应用部署

执行 sh bin/migrate install 将应用部署到金蝶Apusic应用服务器。

执行完成后，迁移工具安装目录有/backup 目录，backup目录结构按时间命名文件夹保存AAS服务器相关备份配置、应用。

部署完成后，启动金蝶Apusic应用服务器并访问迁移的应用。如果金蝶Apusic应用服务器处于运行状态，需要重启。

# AAS备份恢复

AAS配置/应用回退：执行sh bin/migrate rollback 会使用backup目录中离当前最近的备份恢复AAS服务器。

重启AAS服务器并登录查看管理控制台已无迁移的应用。

# 非本机迁移

迁移工具支持非本机迁移(即AAS服务器安装目录与分析输出不在同一台机器)，只需要把分析输出out目录拷贝至AAS目标机器迁移工具安装目录。

执行应用迁移。

启动AAS服务器并登录管控台。访问非本机迁移的应用。

# 迁移格式

迁移工具对配置项server_home/独立应用的解析输出配置为AASV10格式的配置文件，在安装到目标AAS服务器时会自动判断目标平台，生成最终对应平台的配置文件信息，最终的配置、应用在temp目录。

如对独立应用web.war生成的信息如下，out目录子目录config/domain.xml就是AASV10格式配置文件。

如迁移配置项为AASV9，install_home=/opt/aas/aasv9，则运行sh bin/migrate install 迁移应用至AASV9过程中会在temp目录下生成最终AASV9的信息输出。

# WebLogic 应用迁移

WebLogic 是美国 Oracle 公司的一款基于 JAVAEE 架构的中间件产品，用于开发、部署、管理Web应用、EAR应用、EJB应用。

# WebLogic管控台

浏览器打开： http://localhost:7001/console 并登录

# 数据源迁移

金蝶迁移工具可将WebLogic的数据源信息迁移到AAS。通过WebLogic 管控台配置数据源。如已配置有数据源信息，可忽略。

配置conf/conf.properties的配置项server_home为WebLogic安装目录。

# 迁移分析

执行sh migrate analyse 生成分析输出信息，数据源配置的JDBC驱动会被自动扫描并保存到out相关子目录lib下，在迁移安装时会被拷贝到AAS。

WebLogic 迁移数据源会执行WebLogic的相关脚本以解密数据源AES密文，执行脚本时如出现如下错误需要配置MW_HOME环境变量为WebLogic安装目录，可在终端中零时配置环境变量 export MW_HOME=xxxxxx。

执行成功后生成输出信息目录。

# 迁移至AASV10

执行迁移安装时会自动把JDBC驱动包拷贝到AAS服务器。conf/conf.properties配置install_home 为AASV10安装目录。

执行sh bin/migrate install 迁移数据源至AASV10。

重启AAS服务器并登录管控台，测试数据源迁移效果如下图。

AAS管控台测试数据源迁移效果。

# 迁移至AASV9

配置install_home配置项为AASV9安装目录。

执行sh bin/migrate install 迁移数据源至AASV9。

重启AAS服务器并登录管控台，测试数据源迁移效果如下图。

# EJB迁移

之前将WebLogic 中的EJB应用迁移到AAS。如已部署应用程序包ejb2-web.ear。

# 配置迁移分析目录

配置conf/conf.properties的配置项server_home为WebLogic安装目录。

# 迁移分析

执行sh bin/migrate analyse 生成迁移输出信息。

# 安装至AASV10

修改配置项install_home为AASV10安装目录。

执行sh bin/migrate install 迁移应用/配置到AASV10。

重启AAS并登录管理控制台查看迁移的应用。

# 安装至AASV9

配置AASV9安装目录。

执行sh bin/migrate install 迁移应用/配置到AASV9。

# 迁移回退

迁移过程中会备份相关应用/配置到迁移工具目录backup目录。

执行sh bin/migrate rollback 会使用backup目录下离当前时刻最近的备份文件恢复AAS相关配置，配置回退后重启AAS服务器即可。

# 问题解答

# 数据源AES解密异常

# 安装重名

迁移应用/配置到AAS服务器时会和AAS已有配置对比，如果配置重名将会提示操作选择。

迁移应用到AAS服务器时如果AAS服务器相关目录已有文件存在也会提示相关操作选择。

# Tomcat迁移

Tomcat是Apache开源的轻量级Java Web应用服务器，支持Servlet和JSP，具有开源免费、轻量灵活、扩展性好等特点，应用广泛。

# 支持迁移的功能

1）Tomcat部署的war包,位于 tomcat安装根目录下的webapps目录下。

2）Tomcat JDBC Datasource，配置文件位于

${TOMCAT_HOME}/conf/server.xml
${TOMCAT_HOME}/conf/context.xml
${TOMCAT_HOME}/conf/[EngineName]/[HostName]/context.xml.default
${TOMCAT_HOME}/conf/[EngineName]/[HostName]/[应用名].xml

注意： tomcat默认引擎EngineName为Catalina , 以及默认HostName为localhost 。所在目录为 /conf/Catalina/localhost。

3）Tomcat JavaMail Sessions。配置文件位置同上。

# Tomcat 中的示例应用和示例配置

1）示例tomcat服务器webapps目录中包含了demo.war应用。

2）示例tomcat服务器安装目录下conf/server.xml中配置了如下示例 JDBC Datasource数据源以及示例 JavaMail Sessions。以下迁移说明均已该示例为演示。

# 迁移至AAS10

# 安装迁移工具包

1）获取安装包migration.zip，解压至服务器任意目录。假设指定安装解压的目录为 /usr/local/migration,以下操作均以/usr/local/migration为相对目录操作。

2）进入“安装路径/conf”目录。编辑目录下的 conf.properties ，填写对应的配置。配置文件配置示例如下：

server_home配置tomcat服务器所在目录，执行配置分析(migrate analyse )时必填。

install_home配置AASV9或AASV10的安装目录。执行配置迁移安装(migrate install)时必填。

# 配置分析

1）执行./migrate.sh analyse 命令开始分析Tomcat服务器的配置。

如有疑问，执行./migrate -help 查看命令说明。

# 生成分析文件

1）切换到“安装路径/out”目录下，可以查看生成的配置信息。

注意：生成的配置文件可以迁移至AASV10或者AASV9。如需同时迁移至AASV10和AASV9,只需分析一次即可。

# 安装解析好的配置至AAS10

1）切换到“安装路径/bin”目录下执行./migrate.sh install 命令开始安装解析好的配置至AASV10。

如有疑问，执行./migrate -help 查看命令说明。安装执行成功如图所示：

# 重启AAS10 查看应用是否迁移成功

重启AAS10，查看应用是否迁移成功。

# 查看已部署的应用程序

查看部署的应用，可以看到部署成功。

# 查看已迁移的 JDBC Resources

查看迁移的JDBC资源，点击：资源管理->JDBC->JDBC资源。

# 查看已迁移的JavaMail Sessions

查看迁移的JavaMail Sessions，点击：资源管理->JavaMail 。

# 回滚迁移至AAS10的功能

1）切换到“安装路径/bin”目录下执行./migrate.sh rollback 命令开始迁移配置回滚操作。回滚前关闭AASV10。

关闭AAS10执行：切换到“/AAS10/bin”目录下，进行AAS10的关闭操作。

Linux 环境： ./asadmin stop-domain

windows环境： ./asadmin.bat stop-domain

注意区分系统环境。

# 迁移至AAS9

# 配置解析以及安装

1).如已经执行过Tomcat服务器的配置分析操作。2) 3) 跳过。

2).切换到“安装路径/bin”目录下执行./migrate.sh analyse 命令开始分析Tomcat服务器的配置。

3).切换到“安装路径/out”目录下，可以查看生成的配置信息。

注意：生成的配置文件可以迁移至AASV10或者AASV9。所以如需迁移至AASV10和AASV9,步骤二只需分析一次即可。

.进入“${Migration_home}/conf”目录。编辑目录下的 conf.properties ，填写AASV9的安装目录。配置文件配置示例如下：执行安装解析好的配置时，server_home可以不填写。

5).切换到“${Migration_home}/bin”目录下执行./migrate.sh install 命令开始安装解析好的配置至AASV9。如有疑问，执行./migrate -help 查看命令说明。

# 重启AAS9,查看应用是否迁移成功

重启AASV9的启动操作。如执行：./startapusic。

# 查看已部署的应用程序

查看部署的应用，点击：应用管理，以下可以看到部署成功。

# 查看已迁移的 JDBC Resources

查看迁移的JDBC资源，点击：数据源。

# 查看已迁移的JavaMail Sessions

查看迁移的JavaMail Sessions，点击：JNDI资源。

# 回滚迁移至AAS9的功能

1）切换到“${Migration_home}/bin”目录下执行./migrate.sh rollback 命令开始迁移配置回滚操作。回滚前请关闭AASV9服务器。

2）关闭AAS9执行，如下。

Linxu 系统: ./stopapusic

windows系统: ./stopapusic.cmd

注意区分系统环境。

# 类冲突检测

1.进入安装目录执行命令 ./bin/migrate class-conflict。

输出文件至/out/domains/mydomain/class-conflict/[应用名]\[时间戳]/class-conflict.docx。

# Jar安全漏洞检测

进入安装目录执行命令 ./bin/migrate security-scan。

输出检测结果至/out/domains/mydomain/dependency-check/[应用名]/dependency-check-report.html。

# 厂商依赖检测

1）切换到“${Migration_home}/bin”目录下执行./migrate.sh dependent-testing 命令开始分析Tomcat服务器内部应用的厂商依赖。如有疑问，执行./migrate -help 查看命令说明。日志查看 /out/domains/mydomain/manufacturer-dependent-testing/[应用]/manufacturer-dependent-testing.txt。

Tomcat 中使用JavaMail会话:

   Context initCtx = new InitialContext();

   Context envCtx = (Context) initCtx.lookup("java:comp/env");

   Session session = (Session) envCtx.lookup("mail/Session")

     ...   

Tomcat 中使用DataSource:

   InitialContext initCtx = new InitialContext();

   DataSource dataSource = (DataSource) initCtx.lookup("java:comp/env/jdbc/demo");

     ...    

Apusic10 中使用JavaMail会话:

   Context initCtx = new InitialContext();

   Session session = (Session) initCtx.lookup("mail/Session");

     ...    

Apusic10 中使用DataSource:

   InitialContext initCtx = new InitialContext();

   DataSource dataSource = (DataSource) initCtx.lookup("jdbc/demo")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

AASV9中使用方式和Tomcat保持一致。

注意：如果Tomcat使用了这种会话方式。在迁移至AAS10时需修改代码中如上列出的使用代码进行更换。

迁移过程中如使用到了Tomcat底层依赖的类，也需要进行依赖的更换才能在AAS服务器上部署。

# 常见问题解答

1）执行安装过程中提示资源或节点已存在。说明AAS10或者AAS9已经存在同名的JDBC Resources 或 JavaMail Sessions。解决方案:①修改Tomcat 配置文件中的JDBC Resources 或 JavaMail Sessions的配置命名，即<Resource>描述符中的name 属性值。更改完毕后，应用内部对此资源的引用命名也需要更改(具体查看厂商依赖功能)。②修改应用war包名称,默认项目请求前缀为项目war包名。更改完毕后再重新进行迁移配置分析。进行安装。