Wiki マークアップから XHTML への移行

2011-10-12 (Wed)  •  By 伊藤  •  ドキュメント  •  Confluence 翻訳

旧バージョンから Confluence 4.0 にアップグレードする場合、アップグレードの一環としてサイトの自動移行が行われます。これは害のないプロセスです。既存のコンテンツが上書きされることはありません。代わりに、各 wiki マークアップ ページの新しい XHTML バージョンが作成されます。とはいえ、Confluence の新しいバージョンを開始する前にデータベースとホーム ディレクトリのバックアップを必ず実行してください。当然、これが任意の Confluence アップグレード での標準の推奨事項です。

移行プロセス

Confluence インストールの規模により、wiki マークアップから XHTML への移行には時間がかかることがあります。サイト固有の要因によるため、移行にかかる時間の予測は困難です。参考までに、弊社が移行したテスト データセットは 130,000 ページで約 700 MB でしたが、6 分かかりました。

移行プロセスをより細かく制御するための以下のようなプロパティがあります。

(Confluence のシステム プロパティの設定については、こちらのドキュメント を参照してください。)

前に説明したように Confluence インストールは非常に多岐にわたるため、上記の設定に対して具体的な推奨設定を提示することは困難です。ただし、バッチ サイズとスレッド数を両方とも増やすことで、移行に必要なピーク メモリが増えることに留意してください。メモリに問題がある場合は、これらの設定の一方を増やしてもう一方を減らすようにします。

これらの既定値を変更する際に留意すべき別の要素として、サイトで使用されるキャッシュ設定が挙げられます。移行により一定の Confluence キャッシュがすぐに満たされてしまうため、ここで説明 されているようにキャッシュをカスタマイズした場合は、最大容量に達した場合に備えてサーバーに十分なメモリがあるかどうかを確認してください。

サイト移行の進捗を監視するには、アプリケーション ログ の出力内容を確認してください。

移行のログ記録

通常のログの進行状況はフォーマットの INFO レベルで複数のログ エントリによって示されます。

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

個々のページからログ記録される多様なメッセージがありますが、エラーがあれば収集され、全コンテンツの処理が終わった後に 1 つの移行レポートに表示されます。レポートの典型例を以下に示します。

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 に移行されますが、実際には XHTML 固有の ‘未移行の wiki マークアップ’ マクロに内包された wiki マークアップ コンテンツで構成されます。このコンテンツは 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 4.0 の現行バージョンではこの状況について それ以上のレポート は出力されず、移行を再試行することなく通常どおり Confluence が再起動されます。そのような移行されないコンテンツをユーザーが表示しようとすると、以下のような例外が表示されます。

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

ここでは、再起動後にサイト移行を手動で再実行する方法について記載します。

移行の再実行

移行に失敗したコンテンツがある場合、Confluence 管理者はサイト移行を再度実行できます。通常、wiki マークアップの書式のままのコンテンツが移行されるため、再移行処理には最初の移行ほどの時間はかかりません。

移行を再度手動で実行するには、以下の操作を行います。

1. <site>/admin/force-upgrade.action を開きます。
2. [実行するアップグレード タスク (Upgrade task to run)] の一覧から、[wikiToXhtmlMigrationUpgradeTask] を選択します。
3. [アップグレードを強制 (Force Upgrade)] をクリックします。

移行の再試行

前のセクションは、特定のコンテンツが完全に未移行になるという特殊な場合に対処するためのものでした。移行時に最もありがちな問題は、コンテンツは移行されたが ‘未移行の wiki マークアップ’ マクロの本文内に wiki マークアップが残ることです。これが移行レポートで言及されるコンテンツが見つかる状態です。このようなコンテンツは引き続き表示や編集が可能ですが、wiki マークアップであるため新しいエディターの全機能セットを使用して編集することはできません。 コンテンツがこうした状態になる一番の理由は、4.0 との互換性がないマクロ (または不明なマクロ) がページで見つかったためです。

この状況を解決するには 2 つの方法があります。

1. そのマクロの 4.0 互換バージョンをインストールします。「4.0 向けプラグイン開発のよくある質問 」を参照してください。
2. 問題のマクロを使用しないようにページを編集します。

どちらの解決方法を選択したかにかかわらず、’未移行の wiki マークアップ’ マクロに内包されたままの全コンテンツの再移行を強制できます。この機能は <site>/admin/unmigratedwikicontent.action にあります。