Fessのクロール結果を調べるとき、障害URL、ログ、システム情報をそれぞれ管理画面で開くことがあります。fessctlの開発版では、これらをコマンドから確認できるようになりました。辞書、テーマ、プラグイン、ストレージ、検索文書を扱うコマンドも追加されています。
接続先と対象バージョンを明示する
開発ソースの実行にはPython 3.13以上が必要です。リポジトリを取得し、関連PRを含むリビジョンで依存関係を用意します。uvを使う場合の実行例です。
git clone https://github.com/codelibs/fessctl.git
cd fessctl
uv sync --no-dev
export FESS_ENDPOINT='https://fess.example.com'
export FESS_VERSION='15.9.0'
# FESS_ACCESS_TOKENには管理APIを利用できるトークンを設定する
uv run fessctl --help
以降のfessctlは、この作業ディレクトリではuv run fessctlとして実行できます。接続先の初期値はhttp://localhost:8080、対象バージョンは15.9.0、トークンは未設定です。FESS_VERSIONはサーバーのバージョンに合わせて指定してください。指定によって14系・15系のHTTPメソッド等が切り替わり、サーバー自体が更新されるわけではありません。
障害URLからログと稼働状態を調べる
fessctl failureurl list --error-count-min 3 --page 1 --size 100
fessctl failureurl get FAILURE_ID
fessctl stats --output json
fessctl systeminfo --output json
fessctl log list --output json
fessctl log download LOG_ID --dest ./fess.log
FAILURE_IDとLOG_IDには、それぞれの一覧で得たIDを指定します。障害URLの一覧は初期値が1ページ目・100件で、URLやエラー名でも絞り込めます。障害記録の削除は原因の修正や再クロールの代わりにはなりません。failureurl delete-allは絞り込み結果だけでなく全件を削除する操作です。
statsの終了コードが成功でも、検索エンジンへの接続失敗をengine.status=redとengine.exceptionで返すことがあります。監視では終了コードに加え、response.stats.engineの内容を確認します。systeminfoには環境変数や設定値が含まれるため、外部へ共有する前に内容を確認してください。
ログIDは一覧の値をそのまま使います。Fess 15.9.0ではIDに-や_が含まれるファイルを取得できない場合があります。本体のPR #3659はこれを修正していますが、15.9.0公開後のマージであり、15.9.0に含まれる修正としては扱えません。また、未知のログIDを検証エラーにするPR #3660は確認時点で未マージです。CLI側でも取得前にログ一覧とIDを照合します。
バックアップと辞書を別々に取得する
fessctl backup list
fessctl backup download fess_config.bulk --dest ./fess_config.bulk
fessctl dict list --type synonym --output json
fessctl dict synonym download DICT_ID --file ./synonym.txt
バックアップのIDはbackup listで確認します。ログとバックアップの取得では、保存先が既にある場合は--forceを指定しない限り上書きしません。途中のファイルは.partへ書き出し、成功時に保存先へ移す仕組みです。バックアップの読み取りタイムアウトはチャンクごとに60秒で、すべての規模の転送成功を保証するものではありません。
設定バックアップだけでは辞書ファイルまで揃わないため、必要な辞書も取得します。辞書APIにはCodeLibsの検索エンジンプラグインが必要で、プラグインなしのvanilla構成では利用できません。辞書IDには環境共通の初期値はありません。
辞書はsynonym、mapping、kuromoji、stopwords、protwords、stemmeroverrideに対応します。同義語の複数入力は、カンマで連結せずオプションを繰り返します。
fessctl dict synonym create DICT_ID \
--source 'ノートPC' --source 'ラップトップ' --target 'ノートパソコン'
辞書全体を置き換えるuploadは確認を求めます。Fess 15.6.1〜15.8.0ではサーバーのmultipart PUT処理に制限があり、CLIはアップロードを拒否します。15.9.0ではmultipart POSTを使います。辞書の項目IDはファイル内の位置に基づくため、別の利用者による削除で後続IDが変わります。更新・削除の直前に項目を確認してください。辞書の保存と、検索への反映に必要な解析設定・再インデクシング等も分けて確認します。
設定変更と追加コマンドの制限を押さえる
一般設定はgeneral getで取得し、変更するキーだけをgeneral update --set KEY=VALUEで指定できます。CLIは必須項目を読み戻して送信し、マスク済みの秘密情報をそのまま送り返さないようにします。空文字を送ることと管理画面で設定を削除することは同じではなく、秘密情報の消去にも制限があります。
テーマはtheme availableで候補を確認し、theme install NAME VERSIONで導入します。テーマAPIはFess 15.9.0以降が対象です。テーマ取得・導入の待ち時間は標準クライアントの5秒から60秒へ延長されています。サーバーから配布リポジトリへの通信も必要です。
plugin installed、plugin availableによる確認や、plugin install NAME VERSIONも利用できます。プラグインの導入・削除はバックグラウンド処理なので、コマンドの成功は受付を示します。導入済み一覧とログで結果を確認し、反映にはFessを再起動します。
文書を直接扱う場合は、次のコマンドを使えます。
fessctl searchlist search 'title:マニュアル' --start 0 --size 20
fessctl documents bulk ./documents.ndjson --output json
searchlistはdoc_idで文書を指定し、bulk応答のインデックス_idとは区別します。検索位置は0始まりの--startで、サーバーの取得サイズ上限は100件です。bulkはJSON配列、documents配列を持つJSON、NDJSONに対応し、一部文書の登録に失敗すると項目ごとの結果と終了コード9を返します。入力全体を一度に送信するため、大きなファイルは分割して使います。15.8以降のチャンク化された文書の本文変更にも制限があります。
ストレージはstorage listやstorage download PATH --file FILEで扱えますが、一覧は初期値1000件まででページングはありません。サジェストはsuggest infoで状態を確認できます。削除してもSuggest Indexerの実行で元データから再生成される点には注意してください。