Skip to end of metadata
Go to start of metadata

中文标题【从 WIKI 标记整合到基于 XHTML 的存储格式】

如果你现在正在将 Confluence 从一个老的版本升级到 Confluence 4.0 或者更新的版本 (例如从 Confluence 3.5.x 或者更老的版本),在升级的过程中一个内容整合过程也会进行。这个过程将不会对你的升级造成伤害,因为你已经存在内容是不会被重写的。作为替代,合并进程将会创为每一个 wiki 的页面创建一个新的版本。这个新版本将会使用一个新的 XHTML 的存储格式,所以你可以在 Confluence 的富文本编辑器中进行编辑。

另外,你现在正在将 Confluence 从一个老的版本升级到 Confluence 4.3 或者更新的版本,升级程序将会自动的合并你的页面模板,请参考 Migration of Templates from Wiki Markup to XHTML-Based Storage Format 页面中的内容。

注意:尽管这个合并过程是无害的,但是你还是必须要在升级的过程中对你的数据库进行备份,同时也需要对 home 目录中的内容进行备份,当你决定对 Confluence 进行任何的修改或者升级的时候,这个步骤必不可少。

合并进程

基于你 Confluence 安装的大小,从 Wiki 标记页面合并到新的 XHTML 页面的过程可能需要耗费比较多的时间。具体合并所需要的时间也比较难估计,多个因素都会对这个时间造成影响。基于一个大致的估算,一个有 130,000 页面,总计大致 700MB 的内容,合并需要耗费 6 分钟左右。

下面的配置属性可以进行修改以便以对升级的过程进行控制:

属性

用途

默认值

confluence.wiki.migration.threads

内容合并使用的线程数量

4

confluence.wiki.migration.batch.size

每个批量处理的数量

500

confluence.wiki.migration.versioncomment

关联到早期版本中的页面评论

"Migrated to Confluence 4.0"

(有关 Confluence 属性配置的内容,请参考 这篇文档)。

再次提示,针对 Confluence 的安装,每个系统的安装可能都不相同,所以我们很难给出一个通用的配置参数。一个基本的情况是,如果你增加使用线程的数量或者增加批量的数量,或者同时增加使用线程数量和批量的数量的话都会增加内存的消耗。如果内存使用是你需要考虑的问题的话,你可以选择增加一个,减少另一个。

另外一个需要避免的情况是,如果你修改了部署在你站点中的缓存数量设置,内容合并的过程可能会迅速使用了 Confluence 的某一个缓存设置,有关自定义缓存的设置请参考 Cache Performance Tuning 页面中的,很有可能会导致缓存被迅速占满使用。

在升级过程中查看合并日志

为了监控升级的过程,你应该查看 application log 日志中的输出。

通常日志经常将会显示多个日志实例,这个实例是定义在日志的 INFO 级别的,通常格式如下:

WikiToXhtmlMigrationThread-n - Migrated 2500 of 158432 pages, this batch migrated 500/500 without error

针对每一个独立的页面,可能会显示很多日志的消息,但是任何错误将会显示一个独立合并日志,一旦所有的内容都被处理完成后。下面是一个有关报表的基本显示内容:

Wiki to XHTML Exception Report:
Summary:
	0 settings values failed.
	0 PageTemplates failed.
	2 ContentEntityObjects failed.
Content Exceptions:
	1) Type: page, Id: 332, Title: Release Notes 1.0b3, Space: DOC - Confluence 4.0 Beta. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro link is unknown.. Message: The macro link is unknown.
	2) Type: comment, Id: 6919, Title: null, Global Scope. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro mymacro is unknown.. Message: The macro mymacro is unknown.

在报表中的每一部分定义了在合并过程中可能会导致异常的内容和显示的异常。

在绝大部分情况下,如果合并到新 XHTML 存储格式的错误内容将会显示在这里,通常主要原因是是 wiki 标记的内容中使用  'unmigrated-wiki-markup' 宏。这些内容在 Confluence 还是可见的,同时也是能够在新的 Confluence 中进行修改的。

然而,在一些情况下,批量合并处理的结果是完全失败了,这种情况主要是数据库的事务异常没有被处理,通常这种错误将会在日志中进行如下的显示:

Unable to start up Confluence. Fatal error during startup sequence: confluence.lifecycle.core:pluginframeworkdependentupgrades (Run all the upgrades that require the plugin framework to be available) - com.atlassian.confluence.content.render.xhtml.migration.exceptions.MigrationException: java.util.concurrent.ExecutionException: org.springframework.transaction.UnexpectedRollbackException: Transaction rolled back because it has been marked as rollback-only

Confluence 针对这种情况不能提供更多的报表,同时能够允许 Confluence 进行正常的启动而不再尝试重新合并内容。如果一个用户尝试查看任何没有合并的内容,这个用户将会有可能看类似下面的异常:

java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('Page Title') was 'WIKI' but was expected to be 'XHTML'

针对这个问题的解决方案就是在重启 Confluence 再次运行站点内容合并。

针对合并完全失败的内容重新运行合并

如果在系统合并的时候有任何内容的合并失败的话,一个 Confluence 的管理员可以再次重新启动内容合并(请参考前面页面的内容)。只有内容还是使用 wiki 格式的才会被合并,因此重新合并所需要的时间总是会少于原始内容合并所需要的时间的。

希望手动运行内容合并:

  1. 在你的浏览器中打开下面的链接: <Confluence Address>/admin/force-upgrade.action
  2. 运行的升级任务(Upgrade task to run) 下拉列表中,选择 wikiToXhtmlMigrationUpgradeTask 。
  3. 选择 强制升级(Force Upgrade)

针对 'unmigrated-wiki-markup' 宏重新尝试合并

在签名的章节中,我们主要是针对没有完全合并完成余下的为合并内容的异常处理。最常见的情况是内容以及被合并了,但是页面使用 wiki 标记的内容没有被合并,通常这些 wiki 标记的内容使用了 'unmigrated-wiki-markup' 宏。任何使用了这个宏的页面将会显示在合并报告中。这部分的内容还是可以查看和编辑的,但是因为使用了是 wiki 的标记,这部分的内容没有办法使用富文本编辑器的所有功能。

通常遇到这部分的情况的页面是页面中使用了未知的宏(unknown macro)或者使用的宏不能兼容 Confluence 4.x。

有下面 2 种办法可以修正这个问题:

  1. 安装一个与 Confluence 4.x 兼容的宏,请参考 Plugin Development Upgrade FAQ for 4.0 页面中的内容。
  2. 对页面进行编辑,删除使用不兼容宏的部分的内容。

不管你选择哪种解决方案,你可以尝试强制合并所有的内容(包括模板中的内容)以及使用 'unmigrated-wiki-markup' 宏,这个特性可以在 <Confluence Address>/admin/unmigratedcontent.action 中找到。

备注


我们将 Confluence 的存储格式定义为 'XHTML-based'。实际上,正确的说法应该是被称为 XML,因为 Confluence 存储的格式并不完全与 XHTML 的定义相同。

实际上 Confluence 在存储中还包括了有关宏的自定义元素以及更多。我们使用术语 'XHTML-based' 来进行定义,因为在我们的存储格式中 HTML 占了大部分的内容。



  • No labels