今日のひとこと

Fessに複数インスタンス間の分散協調機能を追加

Fessを複数インスタンスで運用している場合に、各インスタンスの状態を把握し、メンテナンス操作の競合を防止するための分散協調機能（CoordinatorHelper）を追加しました。

背景

Fessは同じOpenSearchクラスタに複数のインスタンスを接続して運用できますが、これまではインスタンス間で状態を共有する仕組みがなく、例えば複数のインスタンスから同時にリインデックスを実行してしまうといった問題が起こり得ました。この問題を解決するために、OpenSearchを利用した分散協調の仕組みを導入しました。

主な機能

インスタンスのハートビート管理

各Fessインスタンスは定期的にOpenSearchのfess_config.coordinatorインデックスにハートビートを送信します。ハートビートにはTTL（有効期限）が設定されており、期限切れのインスタンスは非アクティブとみなされます。これにより、現在稼働中のインスタンス一覧を取得できます。

メンテナンス操作の排他制御

リインデックス、設定インデックスの再構築、ドキュメントインデックスのリロード、クローラインデックスのクリアといったメンテナンス操作に対して、分散ロックの仕組みを導入しました。OpenSearchのop_type=createによる原子的なドキュメント作成を利用して排他制御を実現しています。

あるインスタンスが操作を開始すると、他のインスタンスからの同一操作の実行はブロックされ、どのインスタンスで実行中かを示すエラーメッセージが表示されます。ロックの解放にはif_seq_no/if_primary_termによる楽観的並行性制御を使用し、所有者のみがロックを解放できるようになっています。

また、ロックを保持しているインスタンスがダウンした場合は、TTLの期限切れやハートビートの不在を検知して、古いロックを自動的にクリーンアップします。

イベント通知

インスタンス間でイベントを通知する仕組みも用意しています。特定のインスタンスや全インスタンスに対してイベントを発行でき、定期的なポーリングで消費されます。将来的には、設定変更の通知や辞書の更新伝播などへの活用が予定されています。

設定

以下の設定項目が追加されています。

coordinator.poll.interval: ポーリング間隔（デフォルト60秒）
coordinator.heartbeat.ttl: ハートビートの有効期限
coordinator.operation.ttl: 操作ロックの有効期限
coordinator.event.ttl: イベントの有効期限

技術的なポイント

fess_config.coordinatorインデックスはnumber_of_shards: 1で作成されます。これは、op_type=createによる原子的なドキュメント作成が同一プライマリシャード上でのみ保証されるためです。

インスタンスIDはホスト名とPIDを組み合わせて生成されるため、同一ホスト上で複数のFessプロセスを実行している場合でも一意に識別できます。

Fess管理画面の検索結果編集でバリデーションとカスタムフィールド対応を改善

Fessの管理画面には、検索結果一覧からドキュメントを直接編集できる機能があります。今回、この編集画面のバリデーションメッセージの改善と、カスタムフィールドの編集対応を行いました。

背景

管理画面の検索結果編集画面（Admin Search List）では、ドキュメントのフィールドを編集する際にバリデーションが実行されます。しかし、いくつかの問題がありました。

バリデーションエラーのメッセージに doc. プレフィックスが表示され、ユーザーにとってわかりにくい表示になっていた
配列フィールドのバリデーションで、配列用ではなく必須チェック用のエラーメッセージが誤って使われていた
標準フィールド以外のカスタムフィールドが編集画面に表示されず、編集できなかった

バリデーションメッセージの修正

validateFields() メソッドでのエラーメッセージ生成を修正しました。従来は .map(s -> "doc." + s) でフィールド名にプレフィックスを付与した後、そのプレフィックス付きの名前をエラーメッセージの表示テキストとしても使っていました。

修正後は、"doc." プレフィックスはプロパティキー（JSPのバインディング用）にのみ使用し、表示テキストにはフィールド名そのものを使うようにしています。これにより、「doc.url is required.」ではなく「url is required.」と表示されるようになります。

// 修正前
.map(s -> "doc." + s)
.forEach(s -> messages.addErrorsPropertyRequired(s, s));

// 修正後
.forEach(s -> messages.addErrorsPropertyRequired("doc." + s, s));

配列フィールド用バリデーションメッセージの追加

配列フィールドのバリデーションでは、errors.property_required が誤って使用されていたため、専用の errors.property_type_array メッセージキーを新設しました。17言語すべてに翻訳を追加しています。

# 英語
errors.property_type_array={0} must be an array.

# 日本語
errors.property_type_array={0}は配列でなければなりません。

FessMessages クラスにも addErrorsPropertyTypeArray() メソッドを追加し、validateFields() メソッドから呼び出すようにしています。

カスタムフィールドの編集対応

編集画面では、URLやタイトルなどの標準フィールドはハードコードされた入力フォームで表示されますが、ユーザーが追加したカスタムフィールドは表示されていませんでした。

今回、registerExtraFields() メソッドを追加し、ドキュメントに含まれるフィールドのうち標準フィールド（STANDARD_EDIT_FIELDS）に含まれないものを動的に検出して編集画面に表示するようにしました。

フィールドの型は FessConfig の設定に基づいて自動判定されます。

配列フィールド → テキストエリア
日付フィールド → テキスト入力（日付フォーマットのバリデーション付き）
数値フィールド（integer、long、float、double） → 数値入力
その他 → テキスト入力

また、_id、_version、_seq_no、_primary_term などの内部メタデータフィールドは、セキュリティの観点から編集画面に表示されないよう除外しています。

カスタムフィールドの候補は、ドキュメントに含まれるキーだけでなく、FessConfig で定義されたフィールド定義からも取得されます。これにより、新規作成時やドキュメントにまだ値が設定されていないフィールドも編集画面に表示されます。

テストの追加

AdminSearchlistActionTest として27件のユニットテストを追加し、以下をカバーしています。

フォームの初期化とフィールドの割り当て
validateFields() の正常系・異常系（必須、float、long、日付）
バリデーションメッセージのプロパティキー形式
STANDARD_EDIT_FIELDS 定数の内容
registerExtraFields() のカスタムフィールド検出、型判定、ソート順、null処理
予約フィールドの除外

まとめ

この改善により、管理画面の検索結果編集画面がより使いやすくなりました。バリデーションメッセージがわかりやすくなり、カスタムフィールドも直接編集できるようになっています。詳細は PR #3102 を参照してください。

Fessの設定系インデックスの再構築機能

Fessをアップグレードする際、設定系インデックス（fess_config、fess_user、fess_log）のマッピングが変更されていることがあります。これまではマッピングの変更を手動で反映する必要がありましたが、管理画面のメンテナンス機能から簡単に再構築できるようにしました。

背景

Fessでは、検索ドキュメント用のインデックス（fess.YYYYMMDD）とは別に、設定情報を保存する設定系インデックスがあります。バージョンアップ時にマッピングの変更があった場合、設定系インデックスにも最新のマッピングを適用する必要があります。これまではOpenSearchの管理ツールなどを使って手動で対応する必要がありましたが、この作業を管理画面から実行できるようにしました。

再構築の仕組み

管理画面のメンテナンスページに「Rebuild Config Index」カードを追加しました。再構築は以下の手順で安全に実行されます。

バックアップの作成: 対象インデックスのデータをバックアップ用インデックスにリインデックス
インデックスの削除と再作成: 元のインデックスを削除し、最新のマッピングで再作成
データの復元: バックアップからデータをリインデックスして復元
エイリアスの再設定: エイリアスを再設定してサービスを継続
検証: ドキュメント数を検証し、不整合があれば自動でロールバック

再構築対象のインデックスは、fess_config、fess_user、fess_logの3種類から個別に選択できます。検索ドキュメント用のインデックス（DOC_INDEX）は対象外です。

デフォルトデータの読み込み

「Load Default Data」チェックボックスをオンにすると、再構築時にデフォルトのバルクデータを投入できます。この際、OpType.CREATEを使用しているため、既存のドキュメントは上書きされません。新規のデフォルトデータのみが追加されます。

利用方法

管理画面の「メンテナンス」ページにアクセスすると、「Rebuild Config Index」セクションが表示されます。再構築したいインデックスのチェックボックスを選択し、必要に応じて「Load Default Data」にチェックを入れて実行します。

この機能を利用するには、OpenSearchのreindexモジュールが必要です。Fessのmodule.xmlにreindexモジュールのインストール設定が追加されています。

詳細はPR #3097を参照してください。

背景