简介: 本文讲解新的 IBM® Lotus® Connections 2.5 迁移工具,包括架构、如何使用,以及如何排除故障和执行恢复。这个新工具基于 Extensible Stylesheet Language Transformation (XSLT) 技术,提供了迁移所有所需工件的简单有效的方法,让你不必再手工重新应用配置。
迁移工件是迁移现有 Lotus Connections 版本时的关键任务。使用 2.0.1 版本的迁移工具,您可以在一定程度上完成这项任务;例如,可以迁移部分配置和所有数据文件。但还需要手工定制很多配置,这是迁移过程中最痛苦的任务。
Lotus Connections 2.5 中新加入的特性意味着很多其他的配置要迁移。最新的迁移工具,基于 XSLT 技术,提供了迁移所有所需工件和数据文件的简单有效的方法。有了它的帮助,您不必再手工重新应用所有配置。
本文讲解了如何使用 Lotus Connections 2.5 迁移工具,包括如何排除故障和执行恢复,以便让您理解迁移工具,并正确迁移现有 Lotus Connections 环境中的工件。
本文假设您对 IBM WebSphere® Application Server 有深入的了解,对 XSLT 和 XML Path Language (XPath) 技术有一般性了解。
让我们从 Lotus Connections V2.5 迁移工具基础架构概览开始。图 1 演示了迁移工具的高级运行时拓扑结构。
用于迁移数据文件的机制与 Lotus Connections 2.0.1 中基本一致,除了源和目标数据文件列表不同,以及迁移 XML 配置文件的机制完全不同。图 2 演示了迁移工具的工作机制。
图 3 显示的是 XML 配置文件迁移的简化视图。六角型的元素表示帮助文件,长方形的元素表示 XML 配置文件。可以看到 XML 配置文件迁移的演化过程。
XML 配置文件位于此目录下:
/AppServer/profiles//config/cells//LotusConnections-config
其中:
- 是 WebSphere Application Server 的安装位置
- 是 Lotus Connections 配置文件名称
- 是单元名称,它是管理域
大多数 XML 配置文件可由用户定制,有些可以扩展定制,因此迁移定制配置是 Lotus Connections V2.5 迁移工具中最重要的功能。
对于每个即将迁移的 XML 配置文件,都有一个(且只有一个)TXT 文件和 0-3 个 XSL 文件。XML 配置文件属于特定的应用程序,它的 XSL 和 TXT 文件位于特定应用程序相关的目录下。所有目录如下:
- /activities/activities/activities/properties
- /blogs/blogs/blogs/properties
- /communities/communities/communities/properties
- /dogear/dogear/dogear
- /homepage/homepage/homepage/homepage.config
- /profiles/profiles/profiles/profiles.config
- /search/search/search/search.config
- /files/files/files/properties
- /wikis/wikis/wikis/properties
现在让我们深入迁移 XML 配置文件的工作机制的两个阶段的细节。
XML 配置文件不断演化,各版本不同。本文中,迁移的源版本是 V2.0.1,目标版本是 V2.5。请注意,尽管如此,两者之间有两个 “中间版本”,即 V2.5 beta1 和 V2.5 beta2。
迁移工具使用 XSL 文件,通过应用目标版本的模式更改来取得目标版本的 XML 配置文件。XSL 文件随 Lotus Connections 的目标版本提供。
对有些 XML 配置文件,没有 XSL 文件,因为 2.0.1 和 2.5 版本之间没有模式变化。但对其他 XML 配置文件,可能有多个 XSL 文件,因为只要下一个(目标)版本有模式变化,就有 XSL 文件,包括中间的 V2.5 beta1 和 V2.5 beta2 版本。换句话说,XSL 文件只是按需提供。
XSL 文件名称清楚表明它的作用。例如,LotusConnections-config-update-201-25b1.xsl 是专门用于 XML 文件 LotusConnections-config.xml 的 XSL 文件。它告诉我们 V2.5 beta1 中的 XML 文件与 V2.0.1 中相比有模式变化,源 XML 配置文件的版本是 V2.0.1,它由 XSL 文件转化到 V2.5。
在迁移过程中,V2.0.1 源产品是在用的产品,目标 V2.5 产品必须也要部署。为了迁移 XML 配置文件,迁移工具导出并保存 V2.0.1 XML 配置文件,然后在目标产品环境中处理。
目标产品有 XSL 文件,该工具用这些文件将 XML 配置文件转换到目标版本。由此产生的 XML 配置文件根据对应的 XSD 文件进行验证,以保证模式更新到目标版本。迁移之后,转换后的 XML 配置文件保留 V2.0.1 文件中的配置。
尽管如此,仅因为目标系统的一些环境特定的数据在已转换的 XML 配置文件中不存在而转换模式还不够。迁移的所有 XML 配置文件都要经过下一阶段。
迁移之前,新的 V2.5 产品已部署为目标环境。此环境中的一些配置数据,如系统主机和数据库信息,由 Lotus Connections 2.5 安装程序根据用户在安装过程中的输入及从主机环境中收集的信息在默认的 XML 文件中设置。
这些默认的 V2.5 XML 配置文件此后会作为新安装的 XML 配置文件被引用。这些文件不包含源环境中的任何定制配置,因此迁移工具必须使用已转换的 XML 配置文件的定制配置来代替这些新安装文件中的相应配置。
要完成这个任务,要用包含 XPath 表达式的 TXT 文件来标记要被替代的 XML 配置的位置。对于每个要被替代的 V2.5 新安装 XML 文件,有且仅有一个相应的 TXT 文件。迁移工具可以使用此 TXT 文件替换成最终的迁移 XML 配置文件。
现在我们看看迁移过程的细节。
尽管迁移工具可用于不同过程,如升级、 试验到产品迁移、产品到产品迁移,不同过程中迁移工具的用法是相似的。因此,以从 2.0.1 升级到 2.5 为例。
在使用迁移工具的详细过程中,用到以下环境:
Lotus Connections 2.0.1 环境
- 操作系统:Red Hat Enterprise Linux® ES release 4 (Nahant Update 4)
- WebSphere Application Server V6.1.0.13
Lotus Connections 2.5 环境
- 操作系统:Red Hat Enterprise Linux ES release 4 (Nahant Update 7)
- WebSphere Application Server V6.1.0.23
然后:
- 是 WebSphere Application Server 安装主目录。
- 是 Lotus Connections 安装主目录。
- 是 Lotus Connections 数据目录。
注意: 所有命令都是与操作系统无关的。
此过程分三阶段。
导出 Lotus Connections 2.0.1 应用程序工件
首先,必须从 Lotus Connections 2.0 中导出以下应用程序工件。
XML 配置文件
- /profiles//config/cells//LotusConnections-config/oa-config.xml 导出到 migration/work/export/config/oa-config.xml。
- /profiles//config/cells//LotusConnections-config/LotusConnections-config.xml 导出到 migration/work/export/config/LotusConnections-config.xml。
- /profiles//config/cells//LotusConnections-config/notification-config.xml 导出到 migration/work/export/config/notification-config.xml。
- /profiles//config/cells//LotusConnections-config/oa-jobs.xml 导出到 migration/work/export/config/oa-jobs.xml。
- /profiles//config/cells//LotusConnections-config/contentreview-config.xml 导出到 migration/work/export/config/contentreview-config.xml。
- /profiles//config/cells//LotusConnections-config/communities-config.xml 导出到 migration/work/export/config/communities-config.xml。
- /profiles//config/cells//LotusConnections-config/forum-config.xml 导出到 migration/work/export/config/forum-config.xml。
- /profiles//config/cells//LotusConnections-config/dogear-config-cell.xml 导出到 migration/work/export/config/dogear-config-cell.xml。
- /profiles//config/cells//LotusConnections-config/profiles-config.xml 导出到 migration/work/export/config/profiles-config.xml。
- /profiles//config/cells//LotusConnections-config/widgets-config.xml 导出到 migration/work/export/config/widgets-config.xml。
- /profiles//config/cells//LotusConnections-config/search-config.xml 导出到 migration/work/export/config/search-config.xml。
属性
- /activities/activities/activities/activities.properties 导出到 migration/work/export/LC_HOME/activities/activities/activitiesactivities.properties。
- /blogs/blogs/blogs/blogs.properties 导出到 migration/work/export/LC_HOME/blogs/blogs/blogs/blogs.properties。
- /communities/communities/communities/communities.properties 导出到 migration/work/export/LC_HOME/communities/communities/communities.properties。
- /dogear/dogear/dogear/dogear.properties 导出到 migration/work/export/LC_HOME/dogear/dogear/dogear.properties。
- /profiles/profiles/profiles/profiles.properties 导出到 migration/work/export/LC_HOME/profiles/profiles/profiles/profiles.properties。
- /homepage/homepage/homepage/homepage.properties 导出到 migration/work/export/LC_HOME/homepage/homepage/homepage/homepage.properties。
migration/work/export 目录下还有其他属性。实际上,迁移工具导出 下所有属性,然后在导入过程中提取有用的属性。
数据文件
- /activities/content 导出到 migration/work/export/data/ACTIVITIES_CONTENT_DIR。
- /activities/statistic 导出到 migration/work/export/data/ACTIVITIES_STATS_DIR。
- /blogs/upload 导出到 migration/work/export/data/BLOGS_CONTENT_DIR。
- /communities/statistic 导出到 migration/work/export/data/COMMUNITIES_STATS_DIR。
- /dogear/favorite 导出到 migration/work/export/data/DOGEAR_FAVICON_DIR。
- /profiles/statistic 导出到 migration/work/export/data/PROFILES_STATS_DIR。
可以利用之前的资源清单验证导出过程。
要从 V2.0.1 环境中导出工件,执行以下步骤:
- 从 Lotus Connections 2.5 安装光盘中取得迁移工具。
- 复制整个 Lotus_Connections_Install/migration 文件夹到 V2.0.1 目录。
- 打开命令行,输入以下命令:
export WAS_HOME= - 将目录更改为 V2.5 迁移工具的迁移文件夹。
- 运行 migration lc-export 命令。此命令在 /migration/ 下创建一个名为 work 的子目录,保存 V2.0.1 应用程序工件。
图 4 显示的是导出后的迁移目录的示例。
在目标 WebSphere Application Server 上导入应用程序工件
在导出 V2.0.1 工件后,需要将有用的部分导入 V2.5 目标环境。请注意,不是所有导出工件都要导入。
要将 V2.0.1 工件导入 Lotus Connections 2.5 环境,执行以下步骤:
- 从 V2.0.1 目录将迁移文件夹和导出的 V2.0.1 工件复制到 V2.5 中同样的 目录。
- 打开命令行,切换到迁移文件夹。
- 运行命令:
Microsoft Windows: migration.bat lc-import
Linux/AIX: ./migration.sh lc-import
图 5 显示的是导入后迁移目录的示例。
如图所示,migration/work/import 目录在导入后包含三个临时文件夹:level10、level11 和 level12。这些文件夹包含迁移过程中的中间状态文件,它们能有助于诊断可能出现的问题。
level10 文件夹保存的是从 V2.0.1 源产品导出的 XML 配置文件;level11 保存的是新安装 V2.5 XML 配置文件;level2 保存的是中间状态的已转换的 XML 文件和最终迁移后的 XML 配置文件。
验证 Lotus Connections 2.5 环境中的结果
按以下步骤验证迁移:
- 检查导入日志,看是否有错误。参考 “故障排除” 一节,获得进一步信息。
- 按 “向目标 WebSphere Application Server 导入应用程序工件” 一节中的列表检查配置文件,确保 V2.0.1 环境中的定制配置成功导入。
- 按 “向目标 WebSphere Application Server 导入应用程序工件” 一节的描述检查数据目录,确保数据目录下的数据文件成功导入。
- 验证新产品的应用程序,确保成功开启和登录、用户界面正确,用户配置已迁移,例如,Activities 的上传文件限制、Blogs 的处理方法、Blogs 的上传图片。
我们现在看看关于故障排除的一些小提示。
迁移过程中,迁移工具输出执行,在 shell 窗口中追踪。这些输出消息描述了可能发生的大多数问题的产生原因及如何修复。由于输出太长,难以阅读,我们建议使用 shell 输出重定向将输出重定向到日志文件中:
migration lc-export > export_output.log
migration lc-import > import_output.log
利用包含所有输出消息的重定向日志文件来验证迁移结果。
首先,确保所有子任务完成。尽管命令看上去一样,整个迁移过程中却包含一系列的子任务。当所有子任务完成,日志底部显示 BUILD SUCCESSFUL 消息,如下所示:
action-post-config:
Thu Jul 30 22:11:46 CST 2009
[echo] executing post-configuration tasks
BUILD SUCCESSFUL
Total time: 33 seconds
uploading registry
CELL: fvt197Node01Cell
Websphere:_Websphere_Config_Data_Type=Registry,_Websphere_Config_Data_Id=cells/fvt197Node01Cell|
registry.xml#Registry_1248958817671,_WEBSPHERE_CONFIG_SESSION=anonymous1248963106375
Return Value: 0
1 file(s) moved.
1 file(s) moved.
1 file(s) moved.
其次,仔细查看日志。上一步只是告诉您所有迁移任务完成,但每个任务的结果并不明确,因此要更进一步。在这一步,通过在日志中搜索 “Exception” 和 “Error” 来确认迁移成功。
如果日志中没有错误,迁移应该是成功的。而且,如果搜索 “Warning” 和 “Skip” 也没看到任何有害信息,迁移过程基本就是成功的。
示例分析
我们现在利用输出消息来排除一个示例中的故障,其中从 V2.0.1 环境导出失败。如果在重定向日志文件中搜索 “Exception”,会显示 “NullPointerException” 错误,如下突出显示:
Load Version
[LoadVersion] Product set = All
[LoadVersion] java.lang.NullPointerException
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion.execute(Unknown Source)
[LoadVersion] at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:275)
[LoadVersion] at org.apache.tools.ant.Task.perform(Task.java:364)
[LoadVersion] at org.apache.tools.ant.Target.execute(Target.java:341)
[LoadVersion] at org.apache.tools.ant.Target.performTasks(Target.java:369)
[LoadVersion] at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1216)
[LoadVersion] at org.apache.tools.ant.Project.executeTarget(Project.java:1185)
[LoadVersion] at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:40)
[LoadVersion] at org.apache.tools.ant.Project.executeTargets(Project.java:1068)
... [LoadVersion] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
[LoadVersion] at java.lang.reflect.Method.invoke(Method.java:615)
[LoadVersion] at com.ibm.wps.config.launch.WpsConfigLauncher.process(WpsConfigLauncher.java:243)
[LoadVersion] at com.ibm.wps.config.launch.WpsConfigLauncher.main(WpsConfigLauncher.java:459)
The error means that the subtask to load the version failed because it was missing something. If you search for “skip” in the log, you get the following, in which the two lines containing “skip” are highlighted:
LoadLCWasVariable [LoadLCWasVariable] Server name = server1
[LoadLCWasVariable] Variables of profile AppSrv01 already loaded, skip...
[LoadLCWasVariable] Current feature = search
[LoadLCWasVariable] Feature folder search not installed, skip...
[LoadLCWasVariable] Current feature = mobile
[LoadLCWasVariable] Feature folder mobile not installed, skip...
[LoadLCWasVariable] Current feature = wikis
...
前面的追踪信息显示迁移工具找不到两个功能应用程序 Search 和 Mobile 的安装文件夹,因此 LoadLCWasVariable 子任务跳过这一步。
Lotus Connections Search 组件是两个基础架构组件之一,没了它,整个产品无法工作。Search 组件不可能没部署,因为导出来源的 V2.0.1 环境工作正常。
我们需要检查这个功能应用程序的注册信息。所有组件的注册信息保存在 /version 位置下名为 .product 的单独的 .product 文件中。
检查这些 .product 文件后,我们发现这些 Mobile 和 Search 不存在,这就是错误原因。迁移工具找不到 Search 和 Mobile,是因为它们的 .product 文件丢失。
本例中,我们在日志中发现了 Exception 错误和 Skip 警告,恰巧它们由同一问题引起,这说明在故障排除时应将他们结合起来考虑。
迁移命令看上去很简单,但过程中发生的问题会很复杂,难以解决。在此我们讲解一些您可能会遇到的常见问题及如何排除。
问题 1. 缺少必要的属性文件。 此问题在导出过程中发生。以下是日志片段:
Executing native2ascii with native encoding 'Cp1252': wkplc.properties -> wkplc_ascii.properties
java.lang.Exception: wkplc.properties could not be read.
ERROR: Native2ascii execution failed!
Executing native2ascii with native encoding 'Cp1252': wkplc_comp.properties -> wkplc_comp_ascii.properties
java.lang.Exception: wkplc_comp.properties could not be read.
...
[06/22/10 22:02:00.521 CST] WKSP0500
BUILD FAILED
C:\Program Files\IBM\WebSphere\LotusConnections\ConfigEngine\config\actions\util s.xml:872: CheckManagedNodeTask: ERROR: invalid input. "WpHome" property cannot be empty or null.
解决方案。 “java.lang.Exception: wkplc.properties could not be read” 异常在日志中显示了两次。wkplc.properties 和 wkplc_comp.properties 文件是后台引擎的配置文件,位于 /ConfigEngine/profiles/。
这些文件包含必需的配置,如 Lotus Connections 产品和 WebSphere Application Server 的路径,以及不同应用程序的配置文件路径。迁移过程也基于此后台引擎。如果一个或多个文件丢失,甚至配置设置错误,迁移过程就会失败。
要修复这些问题,通过引用同版本的工作正常的 Lotus Connections 环境来恢复文件或配置。然后运行迁移工具恢复步骤(见 “从失败的导入任务恢复” 一节),然后返回迁移命令。
问题 2. WebSphere Application Server 变量值错误。 这种情况下,会显示如下的关于数据文件路径的警告消息:
lc-export-data:
Tue Jun 22 22:58:45 CST 2010
...
[copy] Warning: C:\IBM\WebSphere\LotusConnections\Data\activities\content not found.
解决方案。 在 V2.5 产品中,每个应用程序的数据文件路径保存在 WebSphere Application Server 变量中,而不像 V2.0.1 保存在属性文件中。数据文件放在一个父目录中,而此目录作为安装向导的输入参数。
可以在 WebSphere Application Server Integrated Solution Console 的 Environment > WebSphere Variables 部分看到 WebSphere Application Server 变量,默认值如下:
http://:9060/ibm/console 这里 承载 WebSphere Application Server 的主机名。
此处错误发生在导出过程。警告消息中指出的目录是 activities/content,它属于 Activities 应用程序。路径信息放在 WebSphere Application Server 变量中,当查看 Integrated Solution Console 时,可以看到相关变量 ACTIVITIES_CONTENT_DIR 和它的值 C:\IBM\LotusConnections\Data\activities\content,这在之前的输出消息中已有。
Microsoft® Windows® 操作系统的默认路径与此不同,尽管如此,在文件系统中直接查找数据目录时,实际目录是 C:\Program Files\IBM\LotusConnections\Data\activities\content,而不是 WebSphere Application Server 变量值。
此问题会在 WebSphere Application Server 变量手工更改时发生。要修复此故障,将 WebSphere Application Server 变量值改正确,然后返回迁移命令。
问题 3. 错误:“不支持现有版本。” 如果源环境不匹配,会在导出日志中看到如下的错误消息:
lc-export-config:
[LoadVersion] Load product versions from C:\Program Files\IBM\WebSphere\LotusConnections\ConfigEngine\..\version
[LoadVersion] Prefix =
[LoadVersion] Product set = All
[LoadVersion] Current version is not supported.
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion$Product.fixLCVersion(Unknown Source)
[LoadVersion] at com.ibm.lconn.ant.task.LoadProductVersion$Product.(Unknown Source)
解决方案。 迁移工具对版本的要求很严格。V2.5 迁移工具值支持从 V2.0.1. 和以后的 / V2.5 迁移到 V2.5,并会在过程开始时验证源版本。这种情况下,“不支持现有版本” 错误意味着源环境无效。
要解决此错误,检查 /version 目录下不同应用程序的 .product 文件中的版本。如果低于 V2.0.1,首先用 V2.0.1 迁移工具将其升级到 V2.0.1。如果源环境不是用发布的 Gold 版本部署的,则无法支持迁移。
问题 4. WebSphere Application Server 配置文件在非默认路径下,构造失败。WebSphere Application Server 配置文件保存 WebSphere Application Server 应用程序的配置。可将配置文件部署在默认路径下,即 /profiles,也可部署在非默认路径下。本例中,非默认路径的错误消息如下所示:
lc-export-config:[copy]Warning:D:\LC25\WEBSPH~1\APPSER~1\profiles\lc_profile\config\cells\JVConnCell\LotusConnections-config not
found.[copy]Warning:D:\LC25\WEBSPH~1\APPSER~1\profiles\lc_profile\config\cells\JVConnCell\LotusConnections-config not
found.[copy]Warning:D:\LC25\WEBSPH~1\APPSER~1\profiles\lc_profile\config\cells\JVConnCell\LotusConnections-config not
found.[copy]Warning:D:\LC25\WEBSPH~1\APPSER~1\profiles\lc_profile\config\cells\JVConnCell\LotusConnections-config not found.
...
BUILD FAILED
D:\LC25\WebSphere\LotusConnections\ConfigEngine\config\actions\migrate_util.xml:391: The following error occurred while executing this line:
D:\LC25\WebSphere\LotusConnections\ConfigEngine\config\actions\migrate_util.xml:521:
D:\LC25\WebSphere\LotusConnections\migration\work\import\level2 not found.
解决方案。 在日志中,WebSphere Application Server 的路径是 D:\LC25\WebSphere\AppServer,而部署的应用程序的配置文件的路径是 D:\LC25\lc_profile,它是上文提到的非默认路径。
此问题是由 V2.5 迁移的软件限制导致,而不像其他环境问题。迁移工具不支持非默认配置文件路径,这意味着不能将配置文件放在这些路径下,否则迁移会失败。
迁移任务备份所有需要修改的文件,这使得恢复成为可能。
导出任务不需要恢复,因为它不会损坏 Lotus Connections 应用程序。如果发生错误,遵循故障排除步骤,再次运行导出任务。
相反,对于导入任务,导入后在迁移工具中有个备份文件夹。备份目录是 /migration/work/backup,它包含三个子目录:
- config。包含目标环境的所有新安装 XML 配置文件。在从失败的导入恢复时,将此子目录下的所有内容递归复制到 /AppServer/profiles//config/cells//LotusConnections-config。
- Data。包含目标环境导入前的所有数据文件。在从失败的导入恢复时,清空 /data,然后递归复制此目录下所有内容。
- LC_HOME。 无需恢复,因为它在迁移过程中未改变。
通过利用 XSLT 和 XPath 技术,Lotus Connections 迁移工具在 2.5 版本中大大改进。您现在应该清楚了解新迁移工具的架构和机制,以及如何使用。
通过前面的故障排除提示和案例分析,您可以更快诊断并解决问题,并且通过恢复指导,可以在导入失败后恢复环境。
原文链接:http://www.ibm.com/developerworks/cn/lotus/connections-migrate/index.html
来自 “ ITPUB博客 ” ,链接:http://blog.itpub.net/14751907/viewspace-673870/,如需转载,请注明出处,否则将追究法律责任。
转载于:http://blog.itpub.net/14751907/viewspace-673870/