インデックスエクスポート機能

概要

インデックスエクスポート機能は、OpenSearch にインデックスされた検索ドキュメントを HTML または JSON ファイルとしてローカルファイルシステムにエクスポートします。この機能は以下の用途に便利です。

  • インデックスされたコンテンツの静的バックアップ作成

  • アーカイブ目的でのドキュメントのオフラインコピー生成

  • 静的検索結果ページの構築

  • 他システムへのコンテンツ移行

エクスポートされたファイルは、ソースドキュメントの元の URL パス構造を維持するため、エクスポートされたコンテンツの管理が容易です。

動作の仕組み

インデックスエクスポートジョブが実行されると、以下の処理が行われます。

  1. ドキュメント取得: スクロール API を使用して OpenSearch からドキュメントを効率的にバッチ取得

  2. コンテンツ処理: ドキュメントのフィールド（タイトル、コンテンツ、URL など）を抽出し、除外対象フィールドを取り除く

  3. ディレクトリ構造作成: ドキュメントの url フィールドに基づいてエクスポートディレクトリに URL パス構造を再現

  4. ファイル生成: ドキュメントのコンテンツを含むファイル（HTML または JSON）を作成

  5. 完了まで継続: インデックスが完全にエクスポートされるまでバッチ処理を継続

スクロール API により、メモリの問題なく大量のドキュメントセットを効率的に処理できます。

注釈

エクスポート対象となるのは検索インデックス（fess.search）のドキュメントです。url フィールドを持たないドキュメントはスキップされます。

設定プロパティ

fess_config.properties でインデックスエクスポート機能を設定します。

プロパティ デフォルト値 説明
index.export.path /var/lib/fess/export エクスポートファイルを保存するディレクトリ
index.export.exclude.fields cache エクスポートから除外するフィールド（カンマ区切り）
index.export.scroll.size 100 バッチあたりの処理ドキュメント数
index.export.format html エクスポートファイルのフォーマット（html または json）

設定例:

index.export.path=/data/fess/export
index.export.exclude.fields=cache,boost,role
index.export.scroll.size=200

ジョブの有効化

インデックスエクスポートジョブはスケジュールジョブとして登録されていますが、デフォルトでは無効です。

ジョブを有効にするには:

  1. Fess 管理コンソールにログイン

  2. システム > スケジューラ に移動

  3. ジョブ一覧から Index Exporter を探す

  4. クリックしてジョブ設定を編集

  5. cron 式でスケジュールを設定

  6. 設定を保存

cron 式の例:

  • 0 0 2 * * ? - 毎日午前2時に実行

  • 0 0 3 ? * SUN - 毎週日曜日の午前3時に実行

  • 0 0 0 1 * ? - 毎月1日の午前0時に実行

カスタムクエリフィルタリング

ジョブスクリプトを変更することで、特定のドキュメントのみをエクスポートするようにカスタマイズできます。

Index Exporter ジョブのデフォルトスクリプトは、すべてのドキュメントをエクスポートします:

return new org.codelibs.fess.job.IndexExportJob()
    .query(org.opensearch.index.query.QueryBuilders.matchAllQuery())
    .execute()

カスタムクエリフィルタを追加するには:

  1. システム > スケジューラ に移動

  2. Index Exporter を編集

  3. ジョブスクリプトを変更してクエリフィルタを追加

日付フィルタの例（直近7日間のドキュメントのみエクスポート）:

return new org.codelibs.fess.job.IndexExportJob()
    .query(org.opensearch.index.query.QueryBuilders.rangeQuery("created").gte("now-7d"))
    .execute()

サイトフィルタの例（特定サイトのドキュメントのみエクスポート）:

return new org.codelibs.fess.job.IndexExportJob()
    .query(org.opensearch.index.query.QueryBuilders.wildcardQuery("url", "*example.com*"))
    .execute()

JSON フォーマットでエクスポートする例:

return new org.codelibs.fess.job.IndexExportJob()
    .format("json")
    .execute()

エクスポートされたファイル構造

エクスポートされたファイルは、元の URL 構造を反映して整理されます。

例えば、URL が https://example.com/docs/guide/intro.html のドキュメントは以下のようにエクスポートされます:

/var/lib/fess/export/
└── example.com/
    └── docs/
        └── guide/
            └── intro.html

ファイルパスは、ドキュメントの url フィールドから以下のルールで決定されます:

  • ホスト名がトップレベルのディレクトリになります。URL にホスト名が含まれない場合は _local が使用されます。

  • パスがスラッシュで終わる場合やパスを持たない場合は、インデックスファイル（index.html または index.json）が作成されます。

  • パスにファイル拡張子が含まれない場合は、フォーマットに応じた拡張子（.html または .json）が付加されます。

  • ファイル名に使用できない文字（< > : " | ? * \）は _ に置換され、各パス構成要素は最大200文字に切り詰められます。

  • URL を解析できない場合やパストラバーサルが検出された場合は、_invalid ディレクトリに URL のハッシュ値をファイル名として保存されます。

HTML フォーマットの場合、各ファイルは以下の構造で生成されます:

  • title フィールド → <title> 要素

  • lang フィールド → <html> 要素の lang 属性

  • content フィールド → <body> 要素の本文

  • その他の除外されていないフィールド → <head> 内の <meta name="fess:フィールド名" content="値"> タグ

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>サンプルドキュメント</title>
<meta name="fess:url" content="https://example.com/docs/guide/intro.html">
<meta name="fess:last_modified" content="2024-01-01T00:00:00.000Z">
<meta name="fess:content_type" content="text/html">
</head>
<body>
ドキュメントの本文コンテンツ
</body>
</html>

JSON フォーマットの場合、各ファイルは除外されていない全フィールドを含む JSON オブジェクトになります:

{
  "url": "https://example.com/docs/guide/intro.html",
  "title": "サンプルドキュメント",
  "content": "ドキュメントの本文コンテンツ",
  "last_modified": "2024-01-01T00:00:00.000Z",
  "content_type": "text/html"
}

ベストプラクティス

ストレージの考慮事項

  • エクスポートディレクトリに十分なディスク容量を確保

  • 大量のドキュメントセットには専用ストレージの使用を検討

  • 定期エクスポートを実行する場合は古いエクスポートの定期的なクリーンアップを実装

パフォーマンスのヒント

  • ドキュメントサイズに応じて index.export.scroll.size を調整: - 小さいドキュメント: 大きなバッチサイズ（200-500） - 大きいドキュメント: 小さなバッチサイズ（50-100）

  • 利用が少ない時間帯にエクスポートをスケジュール

  • エクスポート操作中はディスク I/O を監視

セキュリティの推奨事項

  • エクスポートディレクトリに適切なファイルパーミッションを設定

  • エクスポートディレクトリを Web に直接公開しない

  • 機密情報を含むコンテンツはエクスポート後の暗号化を検討

  • エクスポートファイルへのアクセスを定期的に監査

トラブルシューティング

エクスポートジョブが実行されない

  1. スケジューラでジョブが有効になっているか確認

  2. cron 式の構文を確認

  3. Fess ログでエラーメッセージを確認:

tail -f /var/log/fess/fess.log | grep IndexExport

エクスポートディレクトリが空

  1. インデックスにドキュメントが存在することを確認

  2. エクスポートパスのパーミッションを確認

  3. クエリフィルタ（カスタム設定の場合）がドキュメントにマッチするか確認

# インデックスのドキュメント数を確認
curl -X GET "localhost:9201/fess.search/_count?pretty"

エクスポートが途中で失敗する

  1. 利用可能なディスク容量を確認

  2. メモリやタイムアウトのエラーがないかログを確認

  3. 大きなドキュメントの場合は scroll.size を小さくすることを検討

  4. OpenSearch のスクロールコンテキストのタイムアウト設定を確認

ファイルにアクセスできない

  1. ファイルパーミッションを確認: ls -la /var/lib/fess/export

  2. ディレクトリの所有者が Fess プロセスユーザーと一致するか確認

  3. SELinux や AppArmor のポリシーがアクセスを許可しているか確認

関連トピック