アップグレード手順

このページでは、 Fess を以前のバージョンから最新版にアップグレードする手順について説明します。

警告

アップグレード前の重要な注意事項

• アップグレード前に必ずバックアップを取得してください

• テスト環境で事前にアップグレードを検証することを強く推奨します

• アップグレード中はサービスが停止するため、適切なメンテナンス時間を設定してください

• バージョンによっては、設定ファイルの形式が変更されている場合があります

対応バージョン

このアップグレード手順は、以下のバージョン間のアップグレードに対応しています：

• Fess 14.x → Fess 15.9

• Fess 15.x → Fess 15.9

重要

Fess 14.x は OpenSearch 2.x 系、Fess 15.9 は OpenSearch 3.9.0 に対応しています。 Fess 用の OpenSearch プラグインは OpenSearch のバージョンと完全に一致している必要があるため、 14.x からアップグレードする場合は OpenSearch のメジャーバージョンアップも必須です。 ステップ 4: OpenSearch のアップグレード を参照してください。

注釈

さらに古いバージョン（13.x 以前）からアップグレードする場合は、段階的なアップグレードが必要な場合があります。 詳細はリリースノートを確認してください。

アップグレード前の準備

バージョン互換性の確認

アップグレード先のバージョンと現在のバージョンの互換性を確認してください。

• リリースノート

• システム要件 - Fess 15.9 の動作環境（Java、OpenSearch のバージョン）

ダウンタイムの計画

アップグレード作業には、システムの停止が必要です。以下を考慮してダウンタイムを計画してください：

• バックアップ時間: 10分 〜 数時間（データ量による）

• アップグレード時間: 10 〜 30分

• 動作確認時間: 30分 〜 1時間

• 予備時間: 30分

推奨メンテナンス時間: 合計 2 〜 4時間

ステップ 1: データのバックアップ

アップグレード前に、すべてのデータをバックアップしてください。

設定データのバックアップ

1. 管理画面からのバックアップ

   管理画面にログインし、「システム情報」→「バックアップ」をクリックします。

   バックアップページには、以下の設定データが項目ごとに一覧表示されます。 各行をクリックしてダウンロードします（単一の ZIP ファイルではなく、項目ごとの個別ファイルです。 一括ダウンロードの機能はないため、必要な項目を 1 つずつダウンロードします）。

   • fess_basic_config.bulk - 設定インデックス（クロール設定、スケジューラー、ラベル、 キーマッチ、ロール、Web/ファイル認証など 19 インデックス）

   • fess_config.bulk - 上記 19 インデックスに加えて、クロール情報、障害 URL、ジョブログ、 サムネイルキューなどの実行時データを含む 25 インデックス（15.8 まで。15.9 ではユーザータグを 保持する tag_type インデックスが加わり 26 インデックス）

   • fess_user.bulk - ユーザー、ロール、グループ

   • system.properties - 全般設定を含むシステム設定

   • fess.json - インデックスの設定（シャード数、index.knn など）

   • doc.json - ドキュメントのマッピング（フィールド定義）

   注釈

   fess_config.bulk は fess_basic_config.bulk を包含しています。アップグレード前の 設定バックアップとしては、fess_basic_config.bulk、fess_user.bulk、 system.properties の 3 つで十分です。ただし、バックアップ元が 15.9 以降でユーザータグを使っている場合は、ユーザータグを保持する tag_type インデックスが fess_basic_config.bulk には含まれないため、fess_config.bulk も取得してください（ タグ を参照）。

   注釈

   検索ログやクリックログなどのログデータ（search_log.ndjson、click_log.ndjson、 favorite_log.ndjson、user_info.ndjson。15.9 では chat_log.ndjson も表示されます）も 同じページからダウンロードできます。 設定のみをバックアップする場合は不要です。なお、これらの *.ndjson ファイルは バックアップページからアップロードして復元することはできません （「ロールバック手順」を参照）。

2. 設定ファイルのバックアップ

   ZIP 版:

   $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/
   $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/
   $ cp /path/to/fess/bin/fess.in.sh /backup/
   

   RPM 版:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/sysconfig/fess /backup/
   

   DEB 版:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/default/fess /backup/
   

   注釈

   /etc/sysconfig/fess（RPM 版）と /etc/default/fess（DEB 版）は、 FESS_PORT、FESS_HEAP_SIZE、SEARCH_ENGINE_HTTP_URL、 FESS_DICTIONARY_PATH などを指定する環境変数ファイルです。 ZIP 版でこれらに相当する設定は bin/fess.in.sh にあります。

3. カスタマイズした設定ファイル

   カスタマイズした設定ファイルがある場合、それらもバックアップします:

   $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/
   $ cp /path/to/fess/lib/classes/tomcat_config.properties /backup/
   

   注釈

   app/WEB-INF/classes/log4j2.xml は Fess 本体（Web）プロセスのログ設定です。 クローラーなどの子プロセスは別々のファイル （app/WEB-INF/env/crawler/resources/log4j2.xml など、crawler、suggest、 thumbnail、chunk の 4 つ）を使用するため、これらを変更している場合は あわせてバックアップしてください。

インデックスデータのバックアップ

OpenSearch のインデックスデータをバックアップします。

方法 1: スナップショット機能を使用（推奨）

OpenSearch のスナップショット機能を使用して、インデックスをバックアップします。

注釈

ファイルシステムリポジトリ（fs）を登録するには、事前に OpenSearch の opensearch.yml の path.repo にバックアップ先ディレクトリを指定し、OpenSearch を再起動しておく必要があります。

1. リポジトリの設定:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d'
   {
     "type": "fs",
     "settings": {
       "location": "/backup/opensearch/snapshots"
     }
   }'
   

2. スナップショットの作成:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true"
   

3. スナップショットの確認:

   $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1"
   

方法 2: ディレクトリごとバックアップ

OpenSearch を停止してから、データディレクトリをバックアップします。

$ sudo systemctl stop opensearch
$ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data
$ sudo systemctl start opensearch

Docker 版のバックアップ

OpenSearch のデータは Docker ボリュームに保存されます。compose-opensearch3.yaml では、 インデックスデータ用の search01_data と、辞書ファイル用の search01_dictionary の 2 つのボリュームが定義されています。

注釈

実際のボリューム名には、Compose のプロジェクト名（既定では Compose ファイルを配置した ディレクトリ名）が接頭辞として付与されます。正確な名前は次のコマンドで確認してください:

$ docker volume ls

コンテナーを停止してから、ボリュームをバックアップします。docker run の -v には、 接頭辞を含む実際のボリューム名を指定します:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data
$ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data
$ docker compose -f compose.yaml -f compose-opensearch3.yaml start

警告

-v に接頭辞なしの search01_data を指定すると、Docker は既存のボリュームを参照せず、 同名の空のボリュームを新規作成します。コマンドはエラーにならず中身が空のアーカイブが 作成されるため、バックアップが取得できたように見えてしまいます。

注釈

Fess 本体（fess01）のコンテナーには専用のボリュームがないため、バックアップ対象は 上記の 2 つのみです。ただし、管理画面から変更した全般設定や、管理画面からインストールした プラグインはコンテナー内にのみ保存され、コンテナーを再作成すると失われます。 これらは Compose ファイルの FESS_JAVA_OPTS や FESS_PLUGINS で指定して永続化してください。

ステップ 2: 現在のバージョンの停止

Fess と OpenSearch を停止します。

ZIP 版には停止用のスクリプトは同梱されていません。bin/fess を -p オプション付きで 起動していた場合は、PID ファイルを使って停止します:

$ kill $(cat /path/to/fess/fess.pid)
$ kill <opensearch_pid>

-p を指定せずに起動していた場合は、プロセス ID を確認して kill します （-d だけでは PID ファイルは作成されません）。

RPM/DEB 版 (systemd):

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Docker 版:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down

警告

ステップ 3 を始める前に Fess が停止していることを確認してください。起動中の Fess のパッケージや ファイルを入れ替えないでください。起動中の 15.8 の Fess で DEB パッケージを 15.9 のものに 入れ替えたところ、Fess を再起動するまで検索画面が 404 を返しました。パッケージ版では systemctl status fess.service で確認できます。

ステップ 3: 新しいバージョンのインストール

インストール方法により、手順が異なります。

ZIP 版

1. 新しいバージョンをダウンロードして展開:

   $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.zip
   $ unzip fess-15.9.0.zip
   

   注釈

   Fess のアーカイブ版は ZIP 形式でのみ配布されています（fess-15.9.0.tar.gz は 提供されていません）。

2. 古いバージョンの設定をコピー:

   $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.9.0/app/WEB-INF/conf/
   $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/
   $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/
   

   警告

   fess_config.properties と fess.in.sh をそのままコピーすると、15.9 で既定値が変わった 値も含めて、旧バージョンの値が引き継がれます。たとえば、アップグレード後に作成したジョブの 既定は Groovy になります。後の 2 つのコマンドを実行する前に、各ファイルを fess-15.9.0 のファイルと比較し、自分で変更した値だけを移してください。確認すべき項目は 15.8 から引き継いだ設定ファイル を参照してください。

3. カスタマイズしている場合は、以下もコピーします:

   # Tomcat の設定（SAML で必要な tomcat.sameSiteCookies=none もここにあります）
   $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.9.0/lib/classes/
   # インストール済みプラグイン
   $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.9.0/app/WEB-INF/plugin/
   # 自分でアップロードした静的テーマ（テーマごとのディレクトリ。bootstrap は除く）
   $ cp -r /path/to/old-fess/app/themes/<your-theme> /path/to/fess-15.9.0/app/themes/
   

   警告

   旧バージョンの tomcat_config.properties をコピーしないと、 tomcat.sameSiteCookies は 何も知らせずに既定値の lax に戻り、SAML ログインが動作しなくなります （ SAML 認証（SSO）を利用していた場合 を参照）。このファイルの同梱の内容は 15.8.0 と 15.9 で同じなので、 そのままコピーできます。

   警告

   log4j2.xml を 15.9 のファイルに上書きコピーしないでください。15.9 のファイルは RequestLoggingFilter のロガーを warn に固定しており、15.8 のファイルをコピーすると この設定が失われます。ログレベルを DEBUG にすると、リクエストヘッダー（ Authorization を含む）と リクエストパラメーター（ログインフォームに入力したパスワードを含む）がログに書き出されます。 2 つのファイルを diff で比較し、自分で変更した内容だけを 15.9 のファイルに再適用してください。

   警告

   app/themes/ ディレクトリ全体はコピーしないでください。このディレクトリには Fess に 同梱のテーマ bootstrap も入っており、15.9 のものに上書きすると、15.9 の検索画面が 15.8 版のテーマに置き換わります。コピーするのは自分で作成したテーマのディレクトリだけにして ください。 Fess プロジェクトが公開しているテーマは、 bin/fess-setup install theme <name> で 15.9 向けのビルドをインストールしてください（ fess-setup コマンド を参照）。

   警告

   管理画面「デザイン」で編集した JSP（app/WEB-INF/view/）はコピーしないでください。 15.9 の検索画面は静的テーマで、これらの JSP を使いません。変更内容の移し先は 検索画面は静的テーマに を参照してください。

   注釈

   app/WEB-INF/plugin/ からコピーしたプラグインは、旧バージョン向けにビルドされています。 コピーした後、 fess-15.9.0 で bin/fess-setup upgrade plugins を実行し、15.9 向けに ビルドされたバージョンに入れ替えてください（ プラグインのバージョン更新 を参照）。

4. 設定差分を確認し、必要に応じて調整します

RPM/DEB 版

新しいバージョンのパッケージをインストール:

# RPM
$ sudo rpm -Uvh fess-15.9.0.rpm

# DEB
$ sudo dpkg -i fess-15.9.0.deb

注釈

RPM 版では /etc/fess/* の設定ファイルは %config(noreplace) として登録されているため、 アップグレード時も保持されます（新しい既定のファイルは .rpmnew として併置されます）。 新しい設定オプションが追加されている場合は、手動で調整が必要です。変更を加えた /etc/fess/fess_config.properties は、ZIP 版の手順でコピーしたファイルと同様に、15.9 でも 旧バージョンの値のまま使われます。 15.8 から引き継いだ設定ファイル を参照してください。

警告

DEB 版では、 /etc/fess 以下のファイル（ fess_config.properties や tomcat_config.properties など）は、 /etc/default/fess、/etc/init.d/fess、 /usr/lib/systemd/system/fess.service と同様に conffile として登録されています。15.8 からの 最初のアップグレードでは、 dpkg は次のように扱います。

• 編集していないファイルは、確認なしに 15.9 のファイルへ置き換えられます。

• 編集したファイルについては、 dpkg が確認を求めます。自分のファイルを残す場合（既定の回答、または --force-confold ）は、15.9 のファイルが <ファイル名>.dpkg-dist として併置されます。新しいファイルを インストールする場合（ Y または --force-confnew ）は、自分のファイルが <ファイル名>.dpkg-old として保存されます。

• 回答する人がいないとき、 dpkg -i と apt-get install -y は最初の確認で停止します。 無人でアップグレードする場合は --force-confold を指定してください（ --force-confdef でも確認は 出なくなります）。たとえば sudo dpkg --force-confold -i fess-15.9.0.deb や sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.9.0.deb です。

いずれの場合も、事前に /etc/fess をバックアップしてください（ステップ 1）。残したファイルは 15.8 の値の ままなので、そのまま使わず .dpkg-dist のファイルと比較してください（ 15.8 から引き継いだ設定ファイル を参照）。なお /etc/fess/system.properties はパッケージに 含まれない実行時生成ファイルのため、上書きされません。

Docker 版

1. 新しいバージョンの Compose ファイルを取得:

   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose.yaml
   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose-opensearch3.yaml
   

2. 新しいイメージを取得:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull
   

ステップ 4: OpenSearch のアップグレード

Fess 15.9 は OpenSearch 3.9.0 に対応しています。接続先の OpenSearch がこれより古い場合は、 以下の手順でアップグレードしてください。

注釈

この手順は ZIP 版および RPM/DEB 版で OpenSearch を手動運用している場合の手順です。 Docker 版では、ステップ 3 で新しいイメージを取得すると OpenSearch とプラグインも まとめて更新されるため、本ステップは不要です。

重要

Fess 15.9 は、チャンクベクトル検索（セマンティック検索）の利用有無にかかわらず、 検索インデックスの設定に index.knn を、マッピングに content_chunk_vector（knn_vector 型）を常に含めます。そのため、接続先の OpenSearch には k-NN プラグインが必須 です。

• 標準配布の OpenSearch および Docker 版のイメージには同梱されています。

• minimal 配布には含まれないため、インデックスの新規作成に失敗し、|Fess| が起動できません。

• インデックス設定には knn.derived_source.enabled も常に送信されます。これを認識できない 古い OpenSearch では、k-NN プラグインの有無にかかわらずインデックスの作成に失敗します。

詳細は セマンティック検索（コンテンツチャンク＋ベクトル検索） の「前提条件」を参照してください。

警告

OpenSearch のメジャーバージョンアップグレードは慎重に行ってください。 インデックスの互換性に問題が発生する可能性があります。 Fess 14.x は OpenSearch 2.x 系のため、14.x からのアップグレードでは必ずこのケースに該当します。

OpenSearch 3.9.0 で取得したスナップショットは、3.8.0 以前の OpenSearch には復元できません。切り戻しに備えて、アップグレード前に取得したスナップショットを残しておいてください。

1. 新しいバージョンの OpenSearch をインストール

2. プラグインを再インストール:

   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip
   

   注釈

   これらのプラグインのバージョンは、使用する OpenSearch のバージョンと一致させる必要があります。 Fess 15.9 は OpenSearch 3.9.0 に対応しています。バージョンが一致しない場合、 プラグインのインストールに失敗します。

   Fess 用の 4 つのプラグインは maven.codelibs.org で公開しているため、URL で指定します。 opensearch-plugin install の groupId:artifactId:version 形式は Maven Central だけを参照します。

3. 辞書ディレクトリを OpenSearch の設定ディレクトリの下へ移動

   OpenSearch 3.8.0 以降は、辞書ファイルが OpenSearch の設定ディレクトリの外にあるとインデックスの作成を拒否します。 以前の手順どおり configsync.config_path に /var/lib/opensearch/data/config/ （ZIP 版では /path/to/opensearch/data/config/）など設定ディレクトリの外を指定している場合、 Fess はインデックスを作成できず、起動しません。 RPM/DEB 版では、次のように辞書ファイルを /etc/opensearch/dictionary/ へコピーします:

   $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary
   $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/
   $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary
   

   そのうえで、 /etc/opensearch/opensearch.yml の configsync.config_path と、 Fess の FESS_DICTIONARY_PATH （RPM 版は /etc/sysconfig/fess 、DEB 版は /etc/default/fess）を、どちらも /etc/opensearch/dictionary/ に変更します。 ZIP 版では、OpenSearch の config/dictionary/ を使用します。詳細は Linux へのインストール (詳細手順) を参照してください。

4. OpenSearch を起動:

   $ sudo systemctl start opensearch.service
   

ステップ 5: 新しいバージョンの起動

ZIP 版:

$ cd /path/to/fess-15.9.0
$ ./bin/fess -d -p /path/to/fess-15.9.0/fess.pid

注釈

-p を指定すると PID ファイルが作成され、次回の停止時に kill $(cat /path/to/fess-15.9.0/fess.pid) で停止できます。

RPM/DEB 版:

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Docker 版:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

ステップ 6: 動作確認

1. ログの確認

   エラーがないことを確認します。

   ZIP 版:

   $ tail -f /path/to/fess/logs/fess.log
   

   RPM/DEB 版:

   $ sudo tail -f /var/log/fess/fess.log
   

   Docker 版:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01
   

   注釈

   同じログディレクトリーに、クロール処理の fess-crawler.log、認証や管理操作の audit.log、検索リクエストの searchlog.log も出力されます。

2. Web インターフェースへのアクセス

   ブラウザーで http://localhost:8080/ にアクセスします。

3. 管理画面へのログイン

   http://localhost:8080/admin にアクセスし、管理者アカウントでログインします。

4. バージョンの確認

   管理画面で「システム情報」→「設定情報」をクリックし、「システムのプロパティ」に表示される fess.version が新しいバージョンになっていることを確認します。

5. 検索の動作確認

   検索画面で検索を実行し、正常に結果が返されることを確認します。

ステップ 7: インデックスの再作成（推奨）

メジャーバージョンアップの場合、インデックスを再作成することを推奨します。

注釈

以下の手順はクロールの再実行であり、インデックスのマッピング（フィールド定義）自体は 更新されません。チャンクベクトル検索（セマンティック検索）を新たに有効にする場合など、 マッピングの更新を伴う再インデックスが必要な場合は、管理画面 > システム情報 > メンテナンス の 「再インデクシング」を別途実行してください。詳細は 15.7 以前からアップグレードする場合の移行（セマンティック検索（コンテンツチャンク＋ベクトル検索））を 参照してください。

15.8 以前で作成した文書インデックスを引き続き使う場合は、 既存の文書インデックスへの新しいフィールドとかなの正規化の反映 も参照してください。

警告

15.8 が受け付けた辞書のエントリーのうち、OpenSearch 3.9.0 が拒否するものがあります。たとえば 同じ mapping のエントリーを 2 回保存している場合や、 kuromoji のトークンに空白が含まれる 場合です。そのようなエントリーがあると「再インデクシング」は新しい文書インデックスを作成しません。 fess.log には Failed to create index としか出力されず、古いインデックスが検索を提供し続けます。 「システム」→「辞書」で辞書をダウンロードし、重複または不正な行を削除してから再度アップロードし、 「再インデクシング」をもう一度実行してください。15.9 が保存しなくなったエントリーは API が拒否するようになったリクエスト を参照してください。

1. 既存のクロールスケジュールを確認

2. 「システム」→「スケジューラ」から「Default Crawler」を実行

3. クロールが完了するまで待機

4. 検索結果を確認

警告

再インデクシングでは新しいマッピングでインデックスが作り直されるため、k-NN プラグインの ない OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。

15.8 から 15.9 へのアップグレード

15.8 からアップグレードする場合、以下が互換性のない変更です。15.7 以前からアップグレードする場合も これらがすべて当てはまります。「組み込み OpenSearch の廃止」から「既存の文書インデックスへの新しい フィールドとかなの正規化の反映」までの各節（組み込み OpenSearch、スクリプトエンジン、S3 と SSO の プラグイン、Index Exporter ジョブなど）と、このページの最後にある「15.9 固有の移行作業」をすべて 読んでください。

組み込み OpenSearch の廃止

15.8 までは SEARCH_ENGINE_HTTP_URL を設定せずに bin/fess を起動すると、Fess が自身の JVM 内で OpenSearch ノードを起動していました。15.9 ではこの構成がなくなり、検索エンジンは常に 別のサーバーになります。

bin/fess.in.sh は既定で SEARCH_ENGINE_HTTP_URL=http://localhost:9200 を設定します。 接続先の OpenSearch がない場合、Fess は起動に失敗します。 bin/fess-setup install opensearch で導入できます（Linux と Windows のみ。macOS には OpenSearch の公式配布がないため、Homebrew か Docker を使用してください）。

また、 FESS_DICTIONARY_PATH をその OpenSearch の opensearch.yml にある configsync.config_path と一致させる必要があります。設定されていないか一致していないと、 Fess はインデックスを作成できません。15.9 の bin/fess.in.sh （Windows では bin\fess.in.bat ）は、 Fess のディレクトリの opensearch/ に bin/fess-setup install opensearch で導入した OpenSearch が 1 つだけある場合に、これを自動で設定します。それ以外の OpenSearch を使う場合は、 Linux へのインストール (詳細手順) または Windows へのインストール (詳細手順) のとおりに設定してください。

あわせて次が廃止されました。

• es/ ディレクトリ（ es/modules 、 es/plugins 、 es/data ）

• -Dfess.es.dir と SEARCH_ENGINE_HOME

• bin/module.xml と bin/plugin.xml

• 旧 elasticsearch.* 設定キーのフォールバック

また、OpenSearch 3 より前のバージョンに接続した場合、15.8 まではエラーログを出して起動を続行して いましたが、15.9 では起動に失敗します。これらのバージョンは全文書を走査する処理が使う _shard_doc ソートを実装しておらず、HTTP 経由では失敗せずに応答が返らなくなるためです。

警告

組み込み OpenSearch で運用していた場合、インデックスデータは引き継げません。外部の OpenSearch サーバーを新しく構築し、管理画面「バックアップ」で設定を移したうえで 再クロールしてください。バックアップに含まれるのはクロール設定・ユーザー・ログで、 クロール済みの文書は含まれません。

注釈

15.8 のバックアップを新しい 15.9 のサーバーへ復元するときは、次の 2 点に注意してください。

• ジョブは、サーバー上のものより新しい場合にだけ復元されます。そのため、15.8 で編集していない同梱ジョブは 15.9 の JavaScript 版のまま残ります。15.8 で編集または作成したジョブは、保存されたスクリプトエンジン （同梱ジョブなら groovy）のまま復元され、 fess-script-groovy プラグインがないと groovy is not found で失敗します。プラグインを導入するか、そのジョブを JavaScript に切り替えてください。 どちらも 標準のスクリプトエンジンが Groovy から JavaScript に変更 で説明しています。

• Web 認証、クロール設定、データストア設定のパラメーターに保存されたパスワードやシークレットは app.cipher.key で暗号化されています。新しいサーバーの fess_config.properties に、旧環境の値を 設定してください（ 15.8 から引き継いだ設定ファイル を参照）。そうしないと復号できません。

Playwright クローラをプラグインへ移動

Playwright クローラと、それが使用する Node.js の実行ファイルは、配布物に含まれなく なりました。 fess-15.8.0.zip（457.1 MiB）では、Node.js の実行ファイルを収めた Playwright のドライバーバンドルが 204.3 MiB を占めていました。

クロール設定の設定パラメータで client.crawlerClients=playwright:http://.* のように Playwright クライアントを指定している場合は、プラグインと Node.js の両方を導入してください。 プラグインは管理画面の「システム > プラグイン」ページからも導入できます。 bin/fess.in.sh が Node.js の導入先を検出し、 PLAYWRIGHT_NODEJS_PATH を設定します。

$ bin/fess-setup install plugin fess-crawler-playwright
$ bin/fess-setup install nodejs

プラグインがない場合でも、そのような設定はクロールされますが、通常の HTTP クライアントが 使われるため、JavaScript によって生成されるテキストはインデックスされません。クロールジョブは 正常に終了し、障害 URL も記録されません。クロールのたびに、 fess-crawler.log にはクロール設定 ごとに 1 件、プラグイン名と上記の 2 つのコマンドを示す警告が記録されます。

Playwright で HTML ページのサムネイルを生成する fess-thumbnail-playwright プラグインも Node.js で動作します。このプラグインを使用している場合も、 bin/fess-setup install nodejs で Node.js を導入してください。導入した Node.js は 2 つのプラグインで共用されます。

Playwright クローラも fess-thumbnail-playwright プラグインも使用していない場合、対応は不要です。

Google Cloud Storage をプラグインへ移動

Google Cloud Storage の SDK は配布物に含まれなくなり、 gcs:// のクロールと gcs ストレージタイプは fess-storage-gcs プラグインから提供されます。管理画面の 「システム > プラグイン」ページ、または次のコマンドで導入してください。

$ bin/fess-setup install plugin fess-storage-gcs

crawler.file.protocols の既定値からも gcs が外れ、 file,smb,smb1,ftp に なりました。プラグインを導入すると再び追加されます。導入前は、パスが gcs: で始まる ファイルクロール設定について警告がログに記録されるだけで、何も取得できません。 アップグレードした既存インストールでは crawler.file.protocols がそのまま残るため、 パスは受け付けられますが、対応するクローラクライアントがありません。新規インストールでは gcs: が設定済みのプロトコルではないため、管理画面はそのパスの保存を拒否し、以前に 保存されたパスはローカルファイルパスとして扱われます。ストレージ画面も警告をログに記録し、 導入すべきプラグイン名を含むエラーを表示します。以前は空のファイル一覧を表示するだけでした。

Google Cloud Storage を使用していない場合、対応は不要です。Amazon S3 と MinIO などの S3 互換ストレージも同じようにプラグインへ移動しました。次の節を参照してください。

Amazon S3 をプラグインへ移動

AWS SDK は配布物に含まれなくなり、 s3:// のクロールと s3 および s3_compat の ストレージタイプは fess-storage-s3 プラグインから提供されます。管理画面の 「システム > プラグイン」ページ、または次のコマンドで導入してください。

$ bin/fess-setup install plugin fess-storage-s3

crawler.file.protocols の既定値からも s3 が外れ、 file,smb,smb1,ftp に なりました。プラグインを導入すると再び追加されます。 storage.type の既定値は auto のままで、エンドポイントが未設定なら S3 に解決されるため、 s3 を明示していなくても プラグインを導入するまで管理画面のストレージは機能しません。 storage.* の設定値は WEB-INF/conf/system.properties にあるため残り、既存の crawler.file.protocols も アップグレードで置き換わりません。

Amazon S3 と MinIO などの S3 互換ストレージを使用していない場合、対応は不要です。

SSO 認証をプラグインへ移動

4 種類の SSO 認証はいずれも配布物に含まれなくなり、 sso.type の値ごとに専用の プラグインから提供されます。プラグインには必要な認証ライブラリも含まれます。 saml は fess-sso-saml 、 spnego は fess-sso-spnego 、 entraid （旧名の aad も 同じ）は fess-sso-entraid 、 oic は fess-sso-oidc です。最後の組み合わせに 注意してください。プラグイン名は fess-sso-oidc ですが sso.type の値は oic の ままで、両者が異なるのはここ 1 か所だけです。使用するものを管理画面の 「システム > プラグイン」ページ、または次のコマンドで導入してください。

$ bin/fess-setup install plugin fess-sso-saml

sso.type と saml.* 、 spnego.* 、 entraid.* 、 aad.* 、 oic.* の各キーは WEB-INF/conf/system.properties にあるため、設定値はそのまま残ります。管理画面 「システム」→「全般」も 4 種類すべてを選択肢として表示し、設定欄も残ります。プラグインから JSP を提供できないためで、この画面はプラグインが未導入であることを知らせません。

プラグインを導入するまで、 /sso/ へのリクエストは SSO ログインの失敗を表示する ログインページへリダイレクトされ、SSO でログインできません。15.9 では探した コンポーネント名と提供元のプラグイン名を含む警告が fess.log に記録されます。 15.8 まではどのログレベルでも何も出力されませんでした。

oic プラグインは、15.8 の認証機能より検証が厳しくなっています。 oic.token.server.url は HTTPS である必要があり（ http が使えるのは localhost 、 127.x.x.x 、 ::1 のみです）、ID Token の aud と exp を検証します。新しいキー oic.issuer を設定した場合は iss も検証します。詳しくは OpenID ConnectによるSSO設定 を参照してください。

15.8 では oic.token.server.url に http のURLを指定でき、ホスト名の制限もありませんでした。15.9 では、Docker Composeのサービス名（http://keycloak:8080/... など）や社内のホスト名への http は、同じマシンを指していても拒否されます。拒否されるとログインに失敗し、 fess.log に Failed to process the OpenID Connect callback: oic.token.server.url must be https で始まる警告が出力されます。更新する前に、トークンエンドポイントを HTTPS のURLに変更してください。

あわせて oic.issuer に、OPのDiscoveryドキュメントの issuer の値を設定することをお勧めします。設定しない場合、 iss は検証されず、起動後の最初のログインで警告が出力されます。 oic.issuer を設定しても HTTPS の規則は緩和されません。

SSO を使用していない場合、つまり sso.type が none または未設定の場合、 対応は不要です。

標準のスクリプトエンジンが Groovy から JavaScript に変更

15.8 までは標準のスクリプトエンジンが Groovy で、 job.default.script の既定値も groovy でした。15.9 では標準のエンジンが JavaScript になり、既定値は javascript です。Groovy は 標準では組み込まれなくなり、 fess-script-groovy プラグインで提供されます。 scriptType に groovy を指定するには、このプラグインをインストールしておく必要があります。

アップグレードでは、各設定に保存されたスクリプトエンジンは変更されません。また、15.9 より前に 保存され、エンジンを記録していない設定は groovy として扱われます。プラグインがない場合、 次の設定が動作しなくなります。

• groovy として保存されたスケジュールジョブ。 15.8 が自動で登録したジョブもこれに該当します。Default Crawler、Suggest Indexer、 Config Reloader、Log Aggregator、Doc Purger などの同梱ジョブはすべて groovy として保存されて おり、15.9 は起動時にまだ存在しない同梱ジョブだけを追加するため、これらは書き換えられません。 各ジョブはスケジュールで起動されるたびに失敗し、Default Crawler によるクロールも行われなく なります。同梱ジョブの多くは「ロギング」が無効なため、失敗はジョブログには残らず、 fess.log に Failed to execute job の警告として出力されるだけです。

• 「設定パラメーター」にフィールドスクリプト（ field.script.<フィールド名> ）を書いた Web クロール設定とファイルクロール設定。その設定のドキュメントはすべて ScriptEngineException で失敗して障害 URL に記録されますが、クロールジョブ自体は正常に終了します。

• 「スクリプト」を設定したデータストア設定。パラメーター名そのもの以外の値は評価できません。 データストアコネクタの概要 を参照してください。

• ドキュメントブーストのルール。そのルールは何もブーストしません。

• 「置換」が groovy: で始まるパスマッピング。そのマッピングは適用されず、URL は変更されません。

最初の起動後、 fess.log で Settings use the script engine groovy, which is not registered で始まる警告を確認して ください。Fess は起動時に上記の設定を一度確認し、どのプラグインも提供していないエンジンを 使う設定の数を種類ごとに出力します。15.8 から引き継いだ fess_config.properties に job.default.script=groovy が残っている場合はそれも示され、この場合はアップグレード後に作成した ジョブも Groovy を使います（ 15.8 から引き継いだ設定ファイル を参照）。次のいずれかで 対応してください。

• プラグインをインストールして Fess を再起動します。保存済みの Groovy スクリプトはそのまま 動作し、警告も出力されなくなります。プラグインは管理画面「システム」→「プラグイン」からも インストールできます。

  $ bin/fess-setup install plugin fess-script-groovy
  

• 各設定を JavaScript に移行します。Groovy だけが受け付ける構文を先に書き換えてから、 JavaScript を選択します。

  • スケジュールジョブ: 管理画面「システム」→「スケジューラ」で「実行方法」を javascript にします。同梱ジョブのスクリプトは、次の 2 つを除いてそのまま JavaScript として有効です。 Thumbnail Purger は Groovy の long リテラル 1000L を使っており、JavaScript では 構文エラーになります（ 1000 と書きます）。Index Exporter には Index Exporter ジョブが削除されたパッケージを参照 の変更が必要です。JavaScript では配列リテラルが Java の String[] へ自動的に変換されるため、Groovy 形式の as String[] は不要です。

    return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor);
    

  • Web クロール設定とファイルクロール設定: 「設定パラメーター」に config.script.type=javascript を追加します。

  • データストア設定: 「パラメーター」に script_type=javascript を追加します。

  • ドキュメントブーストのルール: 「スクリプト種別」を javascript にします。

  • パスマッピング: 「置換」の先頭を groovy: から javascript: に変えます。

  • job.default.script: 15.8 から引き継いだ fess_config.properties で javascript に設定します。

crawler.default.script の削除

crawler.default.script は fess_config.properties から削除されました。設定に残していても 効果はないため、削除してください。

クロールプロトコル storage の削除

crawler.file.protocols で storage は指定できなくなりました。同梱の値は file,smb,smb1,ftp です。代わりに s3 を使用し、 storage: で始まるパスを 指定しているファイルクロール設定は s3: のパスへ変更してください。 s3 には fess-storage-s3 プラグインが必要です。

Index Exporter ジョブが削除されたパッケージを参照

15.9 には org.opensearch のクラスが含まれなくなり、ジョブのスクリプトで使用するクエリビルダーは org.codelibs.fesen.opensearch の下に移りました。15.8 が Index Exporter ジョブに保存した スクリプトは org.opensearch.index.query.QueryBuilders を参照しており、アップグレードでも 置き換えられないため、 fess-script-groovy をインストールしてもこのジョブは失敗します。 このジョブは無効かつスケジュールなしの状態で同梱されているため、影響があるのは実行している 場合だけです。管理画面「システム」→「スケジューラ」でジョブを開き、スクリプトのパッケージを 15.9 のものに変更してください。

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

独自に作成したスクリプトで org.opensearch.index.query を参照している場合も、同じように 変更してください。クエリの例は インデックスエクスポート機能 を参照してください。

15.8 から引き継いだ設定ファイル

ステップ 3 の ZIP 版の手順では、旧バージョンの fess_config.properties と bin/fess.in.sh をコピーします。RPM 版のアップグレードでは、変更を加えた /etc/fess/fess_config.properties がそのまま残ります（15.9 のファイルは fess_config.properties.rpmnew として併置されます）。 DEB 版でも、確認で自分のファイルを残した場合は同様です（15.9 のファイルは fess_config.properties.dpkg-dist として併置されます）。 いずれの場合も 15.9 は 15.8 の値のまま動作し、15.9 で同梱の値が変わったキーも例外ではありません。 少なくとも次のキーを確認してください。

キー	15.8.0	15.9	15.8 の値が残った場合の影響
job.default.script	groovy	javascript	管理画面「システム」→「スケジューラ」で作成するジョブの既定が groovy になり、 fess-script-groovy プラグインがないと失敗します。
job.template.script	as String[] を含む Groovy 形式	JavaScript 形式	クロール設定から作成したジョブのスクリプトが Groovy 形式になります。
crawler.file.protocols	file,smb,smb1,ftp,storage,s3,gcs	file,smb,smb1,ftp	s3: や gcs: で始まるパスがプラグインなしでも受け付けられ、クロール時に警告を 出して処理されません。 storage はサポートされなくなりました。
search_engine.http.url	http://localhost:9201	http://localhost:9200	SEARCH_ENGINE_HTTP_URL が設定されていない場合に使われます。15.8 からコピーした bin/fess.in.sh で設定していなかった場合がこれに当たり、Fess は 15.9 で廃止された 組み込み OpenSearch のポートである 9201 で OpenSearch を探します。
jvm.crawler.options、jvm.thumbnail.options	-Djcifs.smb.client.*、-Djcifs.smb1.smb.client.*	-Djcifs.client.*	SMB のタイムアウトが jcifs の既定値のままになります。 SMB のタイムアウトは jcifs 3 のプロパティ名を使用 を 参照してください。
response.headers	text/html=Content-Security-Policy: reflected-xss block の行を含む	その行なし	ログイン画面や管理画面など、Fess 自身が描画するページのレスポンスに、ブラウザーが認識しない Content-Security-Policy: reflected-xss block ヘッダーが付き、ブラウザーのコンソールに Unrecognized Content-Security-Policy directive 'reflected-xss' が出ます。このヘッダーは 何も制限しません。次の段落のとおり、その行を削除してください。
app.encrypt.property.pattern	.*password|.*key|.*token|.*secret	.*password|.*passphrase|.*key|.*token|.*secret	名前が passphrase で終わるパラメーター（たとえばデータストア設定の ssh.passphrase）が 平文で保存されます。すでに保存されている値は、15.9 のパターンで設定を保存し直すまで平文のままです。
index.backup.log.targets	click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson	chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson	「システム情報」→「バックアップ」ページに chat_log.ndjson が表示されません。
index.export.exclude.fields	cache	cache,tag	ユーザータグを保持する tag フィールドが、Index Export ジョブが書き出すファイルから 除外されなくなります。
crawler.default.script、theme.allowed.archive.extensions、 theme.assets.cache.max.age、theme.assets.precompressed、 rag.chat.message.max.length、supported.uploaded.js.extentions、 supported.uploaded.css.extentions、supported.uploaded.media.extentions、 supported.uploaded.files、online.help.name.design	あり	削除	効果はありません。削除してください。

response.headers の同梱の値には、15.0 から 15.8 まで text/html=Content-Security-Policy: reflected-xss block の行があります。 reflected-xss は Content-Security-Policy の初期の草案にあったディレクティブで、現在の ブラウザーは認識しないため、このヘッダーは何も制限せず、コンソールにエラーを出すだけです。15.9 は同梱の値から この行を削除しました。 X-XSS-Protection と X-Frame-Options の行は変わりません。15.8 から引き継いだ response.headers にはこの行が残るため、 fess_config.properties の response.headers から、次の行だけを 削除してください。各行の末尾の \n\ は値が次の行に続くことを表すため、行ごと削除すれば、ほかの行はそのまま 使えます:

text/html=Content-Security-Policy: reflected-xss block\n\

response.headers を -Dfess.config.response.headers で指定している場合は、その値から同じ項目を削除してください。

15.8 からコピーした bin/fess.in.sh には、15.9 のファイルにある次の 2 点もありません。 15.9 は SEARCH_ENGINE_HTTP_URL に http://localhost:9200 を設定しますが、15.8 のファイルは 自分で設定しない限り未設定のままです。また、 bin/fess-setup install nodejs で導入した Node.js を検出しないため、 PLAYWRIGHT_NODEJS_PATH を自分で設定しない限り、Playwright 系のプラグインは Node.js を見つけられません。

どちらのファイルも丸ごとコピーするのではなく、15.9 に同梱のファイルを元にして、変更した値を 再適用してください。変更した値は diff で確認できます:

$ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/fess_config.properties
$ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/fess.in.sh

RPM 版では、同じように /etc/fess/fess_config.properties と /etc/fess/fess_config.properties.rpmnew を、DEB 版では /etc/fess/fess_config.properties.dpkg-dist を比較してください。DEB 版のアップグレードでは、 編集していない fess_config.properties は 15.9 のファイルに置き換えられるため（ステップ 3 を参照）、 15.9 の値から始まります。

app.cipher.key は、15.9 で変わっていなくても必ず引き継ぐ必要がある値です。Web 認証、クロール設定、 データストア設定のパラメーターに保存されたパスワードやシークレットを暗号化する鍵だからです。新しい 環境が、それらを保存したときとは別の鍵で動作していると（同梱の fess_config.properties を使った場合や、 バックアップを新しいサーバーへ復元した場合など）復号できず、 fess-crawler.log に CipherFailureException が記録され、そのような設定を含むクロールは何も索引できないことがあります。

注釈

15.9 の Fess は、Web 認証とファイル認証の password も app.cipher.key で暗号化して保存するため、 バックアップの fess_basic_config.bulk と fess_config.bulk には暗号化された値が含まれます。 別のインストールに復元するときは同じ app.cipher.key を引き継いでください。鍵が異なると、これらの認証情報を使う クロールはエラーで失敗します。15.9 より前のバックアップには平文で含まれており、そのまま使えます （詳細は バックアップ を参照）。

SMB のタイムアウトは jcifs 3 のプロパティ名を使用

SMB ファイルサーバーのクロールに Fess が使用する jcifs は、バージョン 3 でプロパティ名を 変更しました。 jcifs.smb.client.* は jcifs.client.* になり、SMB1 用の jcifs.smb1.smb.client.* も同じプロパティに統合されました。15.8 までの jvm.crawler.options と jvm.thumbnail.options は旧名を渡しており、jcifs はそれを読まないため、SMB のクロールは jcifs の既定値で動作していました。15.9 は新しい名前を渡します。

-Djcifs.client.responseTimeout=30000
-Djcifs.client.soTimeout=35000
-Djcifs.client.connTimeout=60000
-Djcifs.client.sessionTimeout=60000

そのため、接続タイムアウトとセッションタイムアウトが初めて有効になり、jcifs の既定値の 35 秒から 60 秒に延びます。応答しない SMB サーバーに対して、クロールは最大 60 秒待つようになります。 応答タイムアウトとソケットタイムアウトは jcifs の既定値と同じ値のため、変わりません。

これらのタイムアウトを変更していた場合は、両方のオプションで名前を変更してください。旧名のままでは 15.8 でも効果はありませんでした。15.8 から引き継いだ fess_config.properties には旧名が残り、 jcifs の既定値のままになります。

効果のなかった 4 つのプロパティの削除

次のキーは fess_config.properties から削除されました。Fess はこれらをこのファイルから 読み込んでいなかったため、これまでと同様、この名前で残した値に効果はありません。

• theme.allowed.archive.extensions

• theme.assets.cache.max.age

• theme.assets.precompressed

• rag.chat.message.max.length

rag.chat.message.max.length による上限は引き続き有効ですが、システムプロパティとして 読み込まれます。 AI検索モード機能の設定 のとおり、 app/WEB-INF/conf/system.properties または -Dfess.system.rag.chat.message.max.length で設定してください。

検索画面は静的テーマに

別のテーマを選んでいない限り、検索画面は Fess に同梱の静的テーマ bootstrap で表示されます。 対象は / 、 /search 、 /advance 、 /help 、 /profile 、 /cache 、 /chat と エラーページです。15.8 までは、既定のテーマを設定していなければ、これらのページは JSP でした。

この切り替えはアップグレードでも起こります。既定のテーマを設定したことのない 15.8 の環境では system.properties に theme.default が無いため、アップグレード後は静的テーマで表示されます。 設定ファイルには何も書き込まれず、ログにも何も出ません。JSP の検索画面に戻す設定はありません。 15.8 で既定のテーマを設定していた場合、その設定は引き継がれます。そのテーマは 15.9 向けのビルドを インストールしてください（ bin/fess-setup install theme <name> ）。インストールされていないテーマを 既定に指定していると、 fess.log に警告を出して bootstrap で表示します。

管理画面の「ページのデザイン」や JAR テーマプラグインで検索画面の JSP、CSS、画像を変更していた場合、 その変更は表示されなくなります。変更は静的テーマで行ってください。同梱のテーマを複製して変更するか （ 同梱テーマのカスタマイズ を参照）、公開されているテーマを管理画面の「システム」>「テーマ」または bin/fess-setup install theme <name> でインストールします。仮想ホストごとの見た目は、仮想ホスト名と 同じ名前の静的テーマで変えます（ 仮想ホスト を参照）。

次の 2 つも無くなりました。

• 仮想ホストごとのログイン画面。15.8 までは「システム」>「全般」を保存すると、ログイン画面を含む JSP が WEB-INF/view/<仮想ホスト名>/ にコピーされ、仮想ホストごとに編集できました。15.9 は このコピーを作りません。ログイン画面（ /login/ ）は引き続き JSP ですが、すべての仮想ホストで 共通の WEB-INF/view/admin/login/ のものが表示されます。以前にコピーされた JSP は使われません。

• JAR テーマプラグイン（ fess-theme-* ）。インストールしても種類 jar の汎用 JAR として 置かれるだけで、画面は変わりません。残っている JAR は「システム」>「プラグイン」ページ、または bin/fess-setup remove plugin <name> で削除できます（ テーマ開発ガイド を参照）。

15.8 で JSP の検索結果に独自のフィールドを表示していた場合は、 query.additional.response.fields に加えて query.additional.api.response.fields にも同じフィールドを追加してください。静的テーマは 検索結果を /api/v2/search から取得します。 query.additional.response.fields は検索エンジンから 取得するフィールドを追加するだけで、この API が応答に含めるのは query.additional.api.response.fields に列挙されたフィールドだけです（ 検索関連の設定 を参照）。そのフィールドを表示するように テーマも変更してください。

クライアントから見た変化

エラーは、要求された URL のまま、実際の HTTP ステータスで返るようになりました。ブラウザ （ Accept ヘッダーに text/html を含むリクエスト）にはテーマのエラーページを、それ以外の クライアントには Not Found. のような 1 行の text/plain を返します。15.8 までは、ほとんどの エラーが /error/... のページへの 302 リダイレクトになり、そのページが 200 を返していました。 監視、ヘルスチェック、 Location ヘッダーをたどるクライアントや /error/ の URL を前提とする クライアントを見直してください。

リクエスト	15.8 まで	15.9
パラメーターが欠けた、または存在しない文書に対する /go/	200 、または /error/ への 302	400 または 404
パラメーターが欠けた、未知の文書に対する、またはサムネイルの無い /thumbnail/	200 または 302	400 または 404
設定した SSO の種類が扱わない /sso/metadata と /sso/logout	/error/badrequest/ への 302	400
/api/v1/* 、 /json 、および存在しない URL	/error/notfound/ への 302	404
捕捉されない例外（管理 API を含む）	/error/systemerror/ への 302	500 。本文は System Error. （JSON ではありません）
/error/notfound/ 、 /error/badrequest/ 、 /error/systemerror/ そのもの	200	404 、 400 、 500

login.required=true のとき、検索系のページは未ログインのユーザーをリダイレクトしなくなりました。 ページはテーマとともに 200 を返してログインを求め、その裏のデータの方を拒否します。 /health 、 /auth/* 、 /ui/config 以外の /api/v2/ のエンドポイントは、 /api/v2/search を含め、ログインするまで 401 を返します。 /go/ 、 /thumbnail/ 、 /osdd は従来どおりログインへ リダイレクトします。未ログインで / にアクセスしたときのリダイレクトを確認している監視は、 /api/v2/search が 401 を返すことを確認するように変えてください。

検索画面は /api/v2/search を使って検索するため、検索ログは /search へのリクエストではなく この API の呼び出しで記録されます。JavaScript を実行しないクライアントには、検索結果の無いページが 返ります。

検索画面の HTML には X-Frame-Options: DENY と、 frame-ancestors 'none' を含む Content-Security-Policy が付き、他のページのフレームには表示されません。15.8 の JSP の検索画面は response.headers の既定値により X-Frame-Options: SAMEORIGIN で、同じオリジンのページの iframe に表示できました。検索画面を同じオリジンの iframe に埋め込んでいる場合は、 fess_config.properties の theme.index.frame.ancestors （既定値 'none' ）に 'self' を設定してください。別のオリジンから埋め込むときは、そのオリジンを指定します（ テーマ開発ガイド を参照）。

管理画面の「ページのデザイン」を削除

管理画面の [システム > ページのデザイン] を削除しました。検索画面の JSP、CSS、画像を管理画面から 編集することはできません。検索画面の見た目は静的テーマで変更してください（ 同梱テーマのカスタマイズ を参照）。

次のキーも fess_config.properties から削除しました。この名前で残した値は使われません。

• supported.uploaded.js.extentions

• supported.uploaded.css.extentions

• supported.uploaded.media.extentions

• supported.uploaded.files

• online.help.name.design

admin-design と admin-design-view のロールは、何の権限も与えなくなりました。これらのロールだけを 持つユーザーは、ログインすると管理画面ではなく検索画面に移動します。

api.access.token.required の削除

api.access.token.required は fess_config.properties から削除されました。15.8 から引き継いだ fess_config.properties に残っている場合も含め、この名前の値は効果がありません。 true にすると、 ログインしていないユーザーからの API リクエストをすべて拒否していました。検索画面は /api/v2/search を使って検索するようになったため、この設定では匿名ユーザーに結果のない検索画面が 表示されることにもなります。

true に設定していた環境では、匿名ユーザーからの API リクエストにも、検索画面と同じくゲストのロールで 応答するようになります。匿名ユーザーに検索させない場合は login.required=true を設定してください。 アクセストークンの動作は変わりません。登録済みのアクセストークンを付けたリクエストにはそのトークンの 権限が与えられ、未登録または期限切れのトークンを付けたリクエストは拒否されます。

API が拒否するようになったリクエスト

15.8 では受け付けられていた次のリクエストを、15.9 は拒否します。15.8 向けに作ったクライアントやスクリプトが送っていないか確認してください。管理 API の拒否は HTTP 400 で、本文の status は 1 です。

リクエスト	15.8	15.9
/api/v2/search に facet.field または facet.query と一緒に、 0 以下の facet.size 、または整数でない facet.size ・ facet.minDocCount を指定する	200 。ただし record_count が 0 で partial が true の空の結果	400 （ invalid_request ）。 facet.size は 1 以上です
track_total_hits=false を指定する。 query.track.total.hits を false にしている場合はすべての検索が対象です	200 。ただし検索結果が 0 件	検索が拒否されます（ /api/v2/search は 400 で invalid_request ）。 true と正の整数は従来どおりです
管理 API の辞書（ mapping ・ kuromoji ）に、既にある項目と重複する項目を登録・更新する	保存されます。辞書を読み込むときに失敗し、検索できなくなる原因になります	400
管理 API の kuromoji 辞書に、 token が空白を含む項目や、 segmentation と reading で空白区切りの語の数が異なる項目を登録・更新する	保存されます。上と同じく、辞書を読み込むときに失敗します	400
DELETE /api/admin/searchlist/doc/{doc_id} で、何も削除されなかった場合（存在しない doc_id 、または文書一覧が返す _id のように doc_id でない値）	200 （ status は 0 ）。文書は削除されません	400
管理 API のユーザーの roles ・ groups に、ロール名・グループ名を指定する	保存されますが、指定した名前はロールとして働きません。名前によっては、そのユーザーの読み込みに失敗します	400 。ロール・グループの ID（ GET /api/admin/role/settings ・ GET /api/admin/group/settings の id ）を指定します
管理 API のユーザーに、パスワードポリシー（ password.min.length の既定値 8 など）に反するパスワードを設定する。作成時にパスワードを省略する。 confirm_password を送り、 password と一致しない	保存され、そのパスワードでログインできます	400

/api/v2/documents/all の各行から score がなくなりました。15.8 では各文書に検索スコアが付いていましたが、 15.9 は全件の取得を point in time と search_after で行うため、スコアは付きません。旧 API プラグインの /json?type=scroll ・ /api/v1/documents/all も同じです。 score を読むスクリプトは、値がない場合を扱えるようにしてください。

管理 API のファイルのアップロード（辞書 6 種類、 badword 、 elevateword 、 storage ）は、 POST で受け付けます。15.8 の文書は PUT を案内していましたが、 multipart/form-data の PUT ではファイルが届かず、15.8 でも 15.9 でも「ファイルが必要です」という検証エラーになります。 PUT のエンドポイントは残っていますが、アップロードには POST を使ってください。

search_engine.type の cloud は非推奨

15.9 では、CodeLibs のプラグインを含まない素の OpenSearch 用に、 search_engine.type の値として vanilla が追加されました（ 検索エンジンの種別 を参照）。 cloud は vanilla の非推奨の別名になりました。引き続き動作しますが、起動時に警告をログに出力します。15.9 で運用するようになったら、 vanilla に変更してください。 aws はこれまでどおり動作します。

• vanilla は 15.9 以降で使えます。15.8 以前の Fess はこの値を認識しません。15.8 に戻す可能性がある間は cloud のままにしてください。

• aws と cloud のインデックス定義は fess_indices/_vanilla/ から読み込まれます。同梱されていた fess_indices/_aws/ と fess_indices/_cloud/ はなくなりました。独自に追加した fess_indices/_aws/ または fess_indices/_cloud/ は読み込まれなくなるため、変更内容を fess_indices/_vanilla/ に移してください。作成済みのインデックスは変更されません。

• 15.8 が検索エンジンに保存したサジェストの設定は、自動的に移行されます。対応は不要です。

CSV データストアが引用符で囲まれたフィールドを解釈

15.9 の fess-ds-csv プラグインは、既定で引用符を解釈します。 "山田, 太郎" のようなフィールドは 1 つの列になります。15.8.0 のプラグインはカンマの位置で分割していました。 bin/fess-setup upgrade plugins の実行後は、引用符で囲まれたフィールドを含む CSV ファイルを読む データストア設定を確認してください。15.8 の動作を維持するには、「パラメーター」に quote_disabled=true を追加します。対応する引用符がない場合の動作も含め、 CSVコネクタ を参照してください。

既存の文書インデックスへの新しいフィールドとかなの正規化の反映

15.9 は起動時に、設定・ログ・ユーザーのインデックスへ新しいフィールドを追加します。文書の インデックスに追加するのは、ユーザータグを保持する tag フィールド（ keyword ）だけで、 マッピングのそれ以外の部分と解析の設定は変更しません。15.8 以前で作成した文書インデックスを そのまま使うと、次の 15.9 の変更が効きません。

• ファイルの所有者と最終更新者（owner・last_modifier）: ファイルシステム・SMB・FTP の クロールで新たに索引されるフィールドです。既存の文書インデックスには定義がないため、最初に クロールした値から text 型として自動でマッピングされ、owner:alice のような検索や facet.field=owner が期待どおりに動きません。

• ETag（etag）: クロールしたページの ETag を保存するフィールドです。15.9 はこれを If-None-Match として送り返し、変更のないページを再取得しません。既存の文書インデックスにはこれも 定義がないため、同梱の「索引されない keyword」ではなく text 型として自動でマッピングされます。 このマッピングでも条件付きリクエストは動作します。

• かなの表記ゆれと、長音符の代わりに書かれたダッシュの正規化（例: サ―バ－ を サーバー と 同じ語として扱う）: 規則は文書インデックスの解析の設定と辞書 mapping.txt にあるため、 既存のインデックスには反映されません。

両方を反映するには、管理画面の「システム情報」→「メンテナンス」で「エイリアスの更新」と 「辞書の初期化」を有効にして「再インデクシング」を実行します。再インデクシングは既存の文書を 新しいインデックスへコピーするため、クロールし直す必要はありません。

警告

「辞書の初期化」は、同梱の辞書ファイルで OpenSearch 側の辞書を上書きします。管理画面の「辞書」で 同義語などを編集している場合は、事前にダウンロードしておき、再インデクシングの後に反映し直して ください。ダウンロードしたファイルから重複または不正なエントリーを削除し（ステップ 7 を参照）、 アップロードしたうえで、「システム情報」→「メンテナンス」の「ドキュメントインデックスのリロード」で [リロード] をクリックしてください。リロードするまで、文書インデックスのアナライザーは同梱の辞書を 使い続けるため、復元した同義語は、どれだけ待っても一致しません。インデックス時に効く辞書は、さらに 文書の再クロールが必要です。 辞書の変更を反映する を参照してください。

注釈

15.8 以前に索引したファイルには、所有者と最終更新者の値がありません。差分クロールでは変更のない ファイルは取得し直されないため、値を付けるには「システム」→「全般」の「最終更新日時の確認」を 一時的に無効にしてクロールしてください。

15.9 固有の移行作業

15.7 以前から 15.9 へアップグレードする場合、利用している機能に応じて以下の作業が必要です。

セマンティック検索を利用していた場合

15.7 以前でセマンティック検索を提供していた fess-webapp-semantic-search プラグインは、 15.9 でコアに統合されたため不要になりました（非推奨）。プラグインの削除、-Dfess.semantic_search.* および -Drank.fusion.searchers=default,semantic の削除、旧 ingest pipeline のデタッチが 必要です。手順は 15.7 以前からアップグレードする場合の移行（セマンティック検索（コンテンツチャンク＋ベクトル検索））を 参照してください。

AI 検索モード（RAG チャット）を利用していた場合

15.9 から、AI 検索モード（RAG チャット）の機能は fess-llm-ollama、fess-llm-openai、 fess-llm-gemini などのプラグインとして分離されました。利用しているプロバイダーに対応する プラグインを管理画面「システム」→「プラグイン」からインストールしてください。 また、15.9 では Amazon Bedrock 用の fess-llm-bedrock が追加されています。

SPNEGO（Windows 統合認証）を利用していた場合

15.9 から、クライアントのプリンシパルの Kerberos レルムがサーバーのレルムと異なる場合、 SPNEGO ログインは拒否されます。AD のドメインツリーの子ドメインや信頼関係を結んだフォレストの ユーザーがログインする構成では、管理画面「システム」→「全般」または app/WEB-INF/conf/system.properties の spnego.allowed.realms に該当するレルムを カンマ区切りで列挙してください。列挙しない場合、15.7 まではログインできていたユーザーが Kerberos realm is not allowed として拒否されます。 詳細は Windows統合認証によるSSO設定 を参照してください。

また、15.9 では spnego.allow.unsecure.basic と spnego.allow.localhost のコード上の 既定値が true から false へ変更されました。これらのキーが app/WEB-INF/conf/system.properties に存在しない環境では、アップグレードによって より厳格な挙動が適用されます。特に spnego.allow.unsecure.basic=false では、SPNEGO ライブラリは HttpServletRequest#isSecure() が true を返すリクエストにのみ Basic 認証を提示するため、 TLS をリバースプロキシで終端して HTTP で転送している構成では、これまで Basic 認証へ フォールバックしていたクライアントがログインできなくなります。その場合は tomcat_config.properties で tomcat.secure=true を設定してください。 詳細は Windows統合認証によるSSO設定 を参照してください。

警告

コード上の既定値は、キーが存在しない場合にのみ適用されます。管理画面「システム」→「全般」は 保存のたびにすべての spnego.* キーを書き込むため、15.7 でこの画面から一度でも更新した環境には spnego.allow.unsecure.basic=true と spnego.allow.localhost=true が保存されたままです。 この場合、15.9 へアップグレードしても設定は強化されず、緩い挙動が黙って引き継がれます。 15.9 は SPNEGO の初期化時に fess.log へ警告を出力するだけです。管理画面「システム」→「全般」 または system.properties で、両方を明示的に無効化してください。特に spnego.allow.localhost=true は危険です。SPNEGO ライブラリが同一ホストからのリクエストを Kerberos の検証なしにサーバーの OS ユーザーとして認証するため、同一ホスト上にリバースプロキシを 置く構成では安全ではありません。

SAML 認証（SSO）を利用していた場合

15.9 から、Fess は送信した AuthnRequest の ID と SAML レスポンスを対応付けて検証するため、 IdP-Initiated（未承諾・unsolicited）SSO は動作しなくなりました。IdP のポータル（Okta の ダッシュボードや Microsoft Entra ID の「マイアプリ」など）に置いたタイルから開始したログインは、 対応付ける AuthnRequest が存在せず拒否されます。15.7 では、Fess が対応付けできないレスポンスを IdP へ差し戻し、IdP が即座に SP-Initiated のアサーションを返していたため動作していました。 IdP 側にタイルを配置する場合は、リンク先を Fess の /sso/ に変更し、SP-Initiated の ログインにしてください。

また、IdP はアサーションをクロスサイトの POST で返すため、tomcat_config.properties の tomcat.sameSiteCookies に none を設定する必要があります。同梱の既定値 lax のままでは セッション Cookie がこのリクエストに送信されず、SAML ログインが完了しません。このファイルは ZIP 版では lib/classes/、DEB/RPM 版では /etc/fess/ に配置されており、変更後は Fess の再起動が必要です。none はブラウザーが Secure 属性付きの Cookie に対してのみ 受け入れるため、Fess を HTTPS で提供する必要があります。15.7 までは同じ設定不備が明確な エラーにならず、IdP への再リダイレクトが繰り返されるループになっていたため、動作しているように 見えていた環境でも設定を確認してください。15.9 ではループせずに 1 回で失敗します。 詳細は SAML認証によるSSO設定 を参照してください。

Microsoft Entra ID（Azure AD）を利用していた場合

15.9 から、認可エンドポイントに要求するレスポンスモードの既定値が form_post から query に変わりました。15.7 まではコールバックがクロスサイトの POST で返るため、Fess の既定値である tomcat.sameSiteCookies = lax ではセッションクッキーが送信されず、none への変更が必要で した。この回避策のためだけに none を設定していた場合は、既定値に戻せます。従来どおり form_post を使う場合は entraid.response.mode=form_post を指定し、 tomcat.sameSiteCookies = none を維持してください。none はブラウザーが Secure 属性付きの Cookie に対してのみ受け入れるため、この場合も Fess を HTTPS で提供する必要があります。

また 15.9 からは、ログイン完了後にユーザーのグループ・ロール権限をバックグラウンドで解決するように なり、ログインがMicrosoft Graphの応答を待って止まることはなくなりました。解決が完了するまでの間、 または解決が完全には成功しなかった場合、ユーザーが保持するのは、ユーザー自身のユーザーレベルの 権限と、entraid.default.groups・entraid.default.rolesに設定したグループ・ロール だけです。どちらも未設定（同梱の既定値）の場合、この間の検索は1件もヒットしません。同梱の既定値の まま作成したクロール設定でクロールした文書には {role}guest が付与されますが、 ログイン済みユーザーはこのロールを持たないためです。解決中は検索画面にその旨のメッセージが表示され、 完全には成功しなかった場合は別のメッセージが表示されます（直接所属の取得とネストしたグループの 探索の両方が成功しない限り、解決は失敗として扱われます）。アクセストークンが更新されるたびに解決が 再実行され、その後成功すればメッセージは消えるため、トークンの有効期間を超えて続くセッションでは 失敗が最終的なものになるとは限りません。すぐに再試行したい場合は、いったんログアウトしてから ログインし直してください。 詳細は Microsoft Entra IDによるSSO設定 を参照してください。

バックグラウンドで解決することの副作用として、解決が完了するまでの間は、解決済みの ロールがまだ分かりません。そのため、管理者は管理ダッシュボードではなく検索画面にリダイレクトされ、 その間に管理画面を開いても検索画面に戻されます。この時間は、最大で約1秒のスケジューリング遅延に 加えて、Microsoft Graphの呼び出しそのもの（直接所属の取得で1回、さらにネストしたグループをたどる ために直接所属グループごとに1回ずつを順番に実行。キャッシュが未作成の場合）だけかかるため、 ユーザーが所属するグループ数に応じて長くなります。この間にアクセスが許可されてしまうことはなく、 拒否されるだけです。また、この時間帯をなくすための設定は必要ありません。認可は同じセッションの リクエストごとに評価し直されるため、解決の完了後に開き直せば、ログインし直さなくても管理画面に 正常にアクセスできます。

警告

この時間帯を短くするために、Fess の管理者ロールを entraid.default.rolesに設定してはいけません。この設定は単一のグローバル設定で、Fess はログイン時にすべてのEntra IDユーザーへ適用し、その後の解決のたびに再適用します。 テナント内のすべてのユーザーに、永続的な Fess の管理者権限を与えてしまいます。

LDAP / Active Directory 連携を利用していた場合

15.9 から、グループやロールの権限名はエントリーの DN をテキストとして切り出すのではなく、 RDN として解析した値になりました。DN の中でエスケープされる文字（一般的にはカンマ）を CN に含む グループは、15.7 までとは異なる権限名になります。

グループのエントリー DN	15.7 までの権限名	15.9 の権限名
CN=Sales\, EMEA,CN=Users,...	2Sales	2Sales, EMEA
CN=Sales\, APAC,CN=Users,...	2Sales	2Sales, APAC

15.7 までは、カンマの手前までが一致する複数のグループが同じ権限名に潰れていたため、Sales, EMEA と Sales, APAC の所属者は互いの文書と Sales グループの文書を 読めていました。 15.9 ではそれぞれ別の権限名になり、この横断的なアクセスは発生しません。

その代わり、旧来の権限名でインデックスされた文書は、該当グループの利用者から見えなくなります。 クロール設定の「パーミッション」に旧来の権限名を設定していた場合は、新しい権限名に更新して 再クロール（または再インデクシング）してください。CN にカンマなどを含むグループを使っていない場合、 権限名は変わりません。

ldap.role.search.user.enabled の挙動変更

15.7 までは、ldap.role.search.user.enabled=false を設定していても、ユーザー名から導出した 権限（role.search.user.prefix ＋ ユーザー名）は付与されていました。15.9 からはこの設定が 実際に反映され、false の場合は付与されません。

false を設定している環境では、アップグレード後にユーザーが自分自身の権限を失うため、 個々のユーザーに対して設定した権限を持つ文書が検索できなくなります。従来の挙動を維持する場合は、 同梱の既定値である true に戻してください。

/api/v2 の設定キーを変更していた場合

15.8.0 から、4 つの設定キーが api.v2. の接頭辞を失いました。値・既定値・挙動は変わりませんが、後方互換のための別名は用意されていません。古い名前のまま残した設定は警告もなく無視され、同梱の既定値が使われます。

15.7 まで	15.8.0 以降	既定値
api.v2.chat.stream.keepalive.interval.ms	api.chat.stream.keepalive.interval.ms	15000
api.v2.param.max.length	api.param.max.length	1000
api.v2.param.max.array.size	api.param.max.array.size	100
api.v2.click.max.rt	api.click.max.timestamp	9999999999999

fess_config.properties または -Dfess.config.<キー> の JVM 引数でこれらを設定していた場合は、新しい名前に変更してください。影響を受けるのは明示的に設定していた場合だけで、変更していなかった環境で対応は不要です。

1 つ目のキーは POST /api/v2/chat/stream がモデルの応答を待つあいだに送出する keep-alive の間隔を決めるため、設定が失われたことに気づくのは AI 検索モードの利用時になります。最後のキーは名前の正確さのためにも変更されました。これはクリックログが持てる rt の値の上限で、応答時間ではなくタイムスタンプを指します。

プラグインのバージョン更新

app/WEB-INF/plugin/ にインストールされているプラグインは、Fess のバージョンに対応した ものへ入れ替えが必要です。 bin/fess-setup upgrade plugins は、インストール済みのすべての プラグインについて、この Fess 向けにビルドされたバージョンをインストールし、古いものを 削除します。その後 Fess を再起動してください。 bin/fess-setup check は、OpenSearch と そのプラグイン、インストール済みの Fess プラグインの状態を報告し、問題がある場合は終了コード 1 で終了します。 bin/fess.in.sh、/etc/sysconfig/fess、/etc/default/fess は読み込まないため、 OpenSearch が http://localhost:9200 にない場合は、 --url を指定するか、実行するシェルで SEARCH_ENGINE_HTTP_URL を設定してください。そうしないと、エンジンに接続できないと報告されます。

$ bin/fess-setup upgrade plugins
$ bin/fess-setup check

upgrade plugins が対象にするのはインストール済みのプラグインだけです。 fess-script-groovy など、15.9 で配布物から外れた部分を補うプラグインは、前述の各節のとおり bin/fess-setup install plugin でインストールしてください。

Docker 版で FESS_PLUGINS を指定している場合は、 fess-ds-wikipedia:15.9.0 のようにバージョン部分を更新してください。

ロールバック手順

アップグレードに失敗した場合、以下の手順でロールバックできます。

ステップ 1: 新しいバージョンの停止

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

ステップ 2: 古いバージョンの復元

バックアップから設定ファイルとデータを復元します。

RPM/DEB 版の場合:

$ sudo rpm -Uvh --oldpackage --nodeps fess-<old-version>.rpm

または:

$ sudo dpkg -i fess-<old-version>.deb

注釈

RPM では --nodeps が必要です。15.8.0 のパッケージは fess と opensearch のユーザーとグループを 必須としているため、指定しないと rpm は Failed dependencies: group(fess) is needed by fess-15.8.0 でダウングレードを拒否します。

警告

15.8.0 の DEB パッケージは /etc/fess/* を conffile として登録していないため、 dpkg -i は、 編集した /etc/fess/fess_config.properties などを、コピーを残さずに上書きします。ステップ 1 で 取ったバックアップから戻してください。

ステップ 3: データの復元

スナップショットから復元します。OpenSearch を起動し、 Fess は停止したままにしてください。

1. OpenSearch を起動します:

   $ sudo systemctl start opensearch.service
   

2. スナップショットは、存在するインデックスの上には復元できません。そのため、アップグレード後に （再インデクシングなどで）作成されたものと、OpenSearch のプラグインが作成する configsync インデックスを含め、Fess のインデックスをすべて先に削除します。スナップショットに含まれる インデックスだけを削除すると、再インデクシングで作られたインデックスが残り、 fess.search が 2 つのインデックスを指して、15.8.0 が起動しません:

   $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index"
   $ curl -X DELETE "http://localhost:9200/<index name>"
   

   2 つ目のコマンドは、1 つ目が表示したインデックスごとに実行します。

3. スナップショットを復元します:

   $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true"
   

注釈

辞書ディレクトリ（ configsync.config_path 。辞書ファイルを含む）は、以前と同じように存在している 必要があります。失われたマシンでは、復元は完了しても、辞書を使うインデックスは red のままになります。

または、バックアップからディレクトリを復元（ステップ 1 で作成したアーカイブの名前を指定します）:

$ sudo systemctl stop opensearch
$ sudo rm -rf /var/lib/opensearch/data/*
$ sudo tar xzf /backup/opensearch-data-<YYYYMMDD>.tar.gz -C /
$ sudo systemctl start opensearch

Docker 版では、旧バージョンの Compose ファイルに戻したうえで、ボリュームの内容を復元します:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \
    sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /"
$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

注釈

管理画面からダウンロードした設定データは、Fess の起動後に「システム情報」→「バックアップ」 ページのアップロード機能から再度インポートして復元できます。アップロードできるのは *.bulk、system で始まる *.properties、gsa で始まる *.xml、 fess で始まる *.json、doc で始まる *.json のみで、1 回の操作につき 1 ファイルです。 検索ログなどの *.ndjson ファイルは受け付けられず、エラーになります。

警告

fess.json と doc.json のアップロードは、Fess に同梱されているインデックス定義 ファイルそのものを上書きします。アップグレード後に旧バージョンの fess.json や doc.json をアップロードすると、新しいバージョンのインデックス設定・マッピングが失われます。 ロールバックの目的以外ではアップロードしないでください。

注釈

アップロードされた system.properties はメモリー上にのみ読み込まれ、ファイルには 書き出されません。そのため system.properties の内容は Fess を再起動すると失われます。 確実に復元するには、バックアップしたファイルを所定の場所（ZIP 版は app/WEB-INF/conf/、RPM/DEB 版は /etc/fess/）へ直接配置してから起動してください。

注釈

インポートは非同期で実行され、画面には開始した旨のみが表示されます。 実際に成功したかどうかは fess.log を確認してください。

ステップ 4: サービスの起動と確認

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

動作を確認し、正常に戻ったことを確認します。

よくある質問

Q: ダウンタイムなしでアップグレードできますか？

A: Fess のアップグレードには、サービスの停止が必要です。ダウンタイムを最小限にするには、以下を検討してください：

• 事前にテスト環境で手順を確認する

• バックアップを事前に取得しておく

• メンテナンス時間を十分に確保する

Q: OpenSearch もアップグレードする必要がありますか？

A: Fess のバージョンごとに対応する OpenSearch のバージョンが決まっています。 Fess 15.9 は OpenSearch 3.9.0 に対応しています。 opensearch-analysis-fess などの Fess 用 OpenSearch プラグインは OpenSearch のバージョンと 完全に一致している必要があるため、OpenSearch をアップグレードする場合は、 対応するバージョン（3.9.0）のプラグインに更新してください。

なお Fess 15.9 は k-NN プラグインを必須とし、インデックス設定に knn.derived_source.enabled を常に送信します。古い OpenSearch のままでは新しいインデックスの作成に失敗するため、 実質的に OpenSearch のアップグレードが必要です。詳細はステップ 4 を参照してください。

Q: インデックスを再作成する必要がありますか？

A: Fess のマイナーバージョンアップ（15.x → 15.9）で、チャンクベクトル検索を利用しない場合は 通常不要です。既存インデックスはそのまま利用でき、content_chunker.enabled などは既定で 無効のため挙動は変わりません。

次の場合は再作成・再インデクシングが必要です。

• 新たにチャンクベクトル検索（セマンティック検索）を有効にする場合: 既存インデックスには 新しいマッピングが反映されないため、再インデクシングが必須です。詳細は 15.7 以前からアップグレードする場合の移行（セマンティック検索（コンテンツチャンク＋ベクトル検索））を参照してください。

• 14.x からアップグレードする場合: OpenSearch が 2.x から 3.x へメジャーバージョンアップ するため、インデックスの再作成を推奨します。

• 15.8 以前で作成した文書インデックスで、所有者での検索やかなの正規化を使う場合: 再インデクシングが 必要です。詳細は 既存の文書インデックスへの新しいフィールドとかなの正規化の反映 を参照してください。

警告

インデックスを新規に作成する操作（再インデクシングを含む）は、k-NN プラグインのない OpenSearch では失敗します。ステップ 4 の注意事項を確認してください。

Q: アップグレード後、検索結果が表示されません

A: 以下を確認してください：

1. OpenSearch が起動しているか確認

2. インデックスが存在するか確認（curl http://localhost:9200/_cat/indices）

3. クロールを再実行

次のステップ

アップグレードが完了したら：

• 起動、停止、初期設定 - 起動と初期設定の確認

• セキュリティ設定 - セキュリティ設定の見直し

• セマンティック検索（コンテンツチャンク＋ベクトル検索） - チャンクベクトル検索（セマンティック検索）の設定と移行手順

• リリースノートで新機能を確認