Wiki Markup から XHTML ベース ストレージフォーマットへの移行
旧バージョン（Confluence 3.5.x 以前）から Confluence 4.0 以降へのアップグレードを行うと、アップグレードの間にコンテンツは自動的に移行されます。破壊的なプロセスではありません。既存のデータは上書きされません。代わりに、移行プロセスで各 wiki マークアップページの新しいバージョンを作成します。新しいバージョンは XHTML ベースのストレージフォーマットを使用するため、Confluence ページはリッチテクストエディターでの編集が可能になります。
また、旧バージョンからConfluence 4.3 以降へのアップグレードを行うと、アップグレードの間にテンプレートは自動的に移行されます。Wiki マークアップから XHTMLベース ストレージフォーマットへのテンプレートの移行を参照してください。「Wiki マークアップから XHTMLベース ストレージフォーマットへのテンプレートの移行」を参照してください。
注意：プロセスが破壊的ではないとはいえ、いかなるConfluence アップグレードにおいても推奨するように、新しいバージョンの Confluence を起動させる前にデータベースとホームディレクトリのバックアップを確実に行う必要があります。
移行のプロセス
インストールする Confluence のサイズ次第では、wiki マークアップから XHTML ベースのストレージフォーマットの移行の所要時間がわかることもあります。サイト特有の要因があり、移行の所要時間の正確な予測は困難です。おおよその目安として、全体で約 700 Mb、130,000 ページのテスト用データセットの移行の所要時間は 6 分間でした。
以下のプロパティを修正すると移行プロセスの管理が向上することがあります：
プロパティ | 目的 | 既定 |
|---|---|---|
confluence.wiki.migration.threads | コンテンツを移行する並列ワーカースレッドの数 | 4 |
confluence.wiki.migration.batch.size | 各ワークバッチに移行される項目数 | 500 |
confluence.wiki.migration.versioncomment | 新たに移行されたバージョンの各コンテンツに関連するコメント | "Confluence 4.0 へ移行しました" |
（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 ベースのストレージフォーマットに移行されますが、実際には XML 'unmigrated-wiki-markup' マクロにラップされた 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 はこのようなシナリオに対し、これ以上のレポートを提供せず、移行を再試行せずに通常通り Confluence を再起動させます。移行されなかったコンテンツを確認すると、以下のような例外が表示されます：
java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('Page Title') was 'WIKI' but was expected to be 'XHTML'
解決するには、再起動後にサイトの移行を手動で確実に再実行する必要があります。
移行の再実行 - 移行に失敗したコンテンツ向け
コンテンツの移行に失敗した場合、Confluence 管理者はサイトの移行を再起動できます（前述のセクションを参照）。まだ wiki マークアップのフォーマット状態のコンテンツのみが移行されるため、通常、最初の移行に比べ再移行の所要時間は短くなります。
移行を手動で再実行するには：
- ブラウザで次の URL を開きます:
<Confluence Address>/admin/force-upgrade.action - 実行するアップグレード タスクのドロップダウンリストからwikiToXhtmlMigrationUpgradeTaskを選択します。
- アップグレードを強制を選択します。
移行の再試行 - 'unmigrated-wiki-markup' マクロ内のコンテンツ向け
前述のセクションでは、特定のコンテンツが全く移行されずに残されている場合の、例外的な状況の処理についての説明です。移行時に発生する最も一般的な問題は、コンテンツは移行されたが、ページ上では wiki マークアップのフォーマットのまま、 'unmigrated-wiki-markup' マクロの本文にラップされてしまう場合です。移行レポートで参照されるコンテンツはこのような状態になっています。コンテンツは閲覧も編集も可能ですが、wiki マークアップの状態であるため、リッチテキストエディターの全機能を使用して編集することはできません。
このような状態になる最も頻度の高い理由は、ページに不明なマクロ、または、 Confluence 4.x と互換性のないマクロが含まれているためです。
このような場合は 2 通りの修正方法があります：
- Confluence 4.x と互換性のあるマクロをインストールする。4.0 についてのプラグイン開発アップグレード時 FAQ を参照してください。
- ページを編集し、問題のあるマクロを削除する。
どちらの方法を選択した場合でも、'unmigrated-wiki-markup' マクロに含まれたままのすべてのコンテンツ (テンプレート内のコンテンツも含む) の再移行を強制的に再移行できます。この機能は
にあります。<Confluence Address>/admin/unmigratedcontent.action
注意
Confluence の保存形式は、「XHTML ベース」といいます。正確を期すためには XML と呼ぶべきでしょう。というのも、Confluence の保存形式はXHTML 定義に準拠していないからです。特に、Confluence ではマクロなどにカスタム要素が含まれています。アトラシアンでは、保存形式で HTML が大部分を占めていることを示すために「XHTML ベース」という用語を使用しています。