検索バックエンドのセットアップ

Crowi の全文検索バックエンド (Elasticsearch) のセットアップとインデックス構築

Crowi の全文検索は 検索ドライバ という差し替え可能な仕組みで提供されます。デフォルトのドライバは mongo で、MongoDB の $regex を使った検索です。暗黙のデフォルトプラグイン @crowi/plugin-search-mongo として実装されており、追加のインフラを必要としないため、新規インストールでも MongoDB だけですぐに検索できます。

より大規模な構成向けには、Elasticsearch を opt-in で選択 できます。 @crowi/plugin-search-elasticsearch プラグインとして実装されており、大量の文書でもスケールしやすく、日本語解析 (analysis-kuromoji) にも対応します。このページは運用者向けに、Elasticsearch ドライバのセットアップとインデックス構築の手順を説明します。利用者向けの検索の使い方は検索を参照してください。

Note: Crowi 2.0 (Reignite) は alpha 開発中で、Elasticsearch バックエンドはまだ調整中です (ES のバージョン更新と、検索ドライバのプラグイン化)。本ページの手順は現行の dev 環境に基づいていますが、詳細は今後変わる可能性があります。最新状況は TODO.md を参照してください。

アーキテクチャ概要

検索ドライバはプラグイン経由で SearchRegistry に登録されます。
どのドライバを使うかは crowi.config.json の search.driver で指定します (デフォルトは mongo)。
Elasticsearch ドライバの接続情報は、Mongo の Config 名前空間 plugin:@crowi/plugin-search-elasticsearch:* に保存されます。設定は管理画面のプラグイン設定画面からのみ行います (環境変数からの自動移行は行いません)。

Elasticsearch プラグインの有効化

デフォルトの mongo ドライバから Elasticsearch に切り替えるには、ランナープロジェクトの依存に @crowi/plugin-search-elasticsearch を宣言し、crowi.config.json の plugins 配列にプラグイン名を加え、 search.driver を elasticsearch に設定します。

{
  "plugins": [
    "@crowi/plugin-search-elasticsearch"
  ],
  "search": {
    "driver": "elasticsearch"
  }
}

設定後に api を再起動すると、プラグインがロードされ検索ドライバが登録されます。プラグインの導入手順全般はプラグインの管理を参照してください。

Elasticsearch を起動する

開発環境では docker-compose.yml に Elasticsearch サービスが含まれています。

docker compose up -d

dev 用の Elasticsearch イメージ (elasticsearch.Dockerfile) は、素の Elasticsearch に analysis-kuromoji プラグインをプリインストールしたカスタムイメージです。これにより、後述の kuromoji アナライザーが追加設定なしで使えます。

Caution: dev イメージには日本語形態素解析の analysis-sudachi プラグインは 含まれていません。sudachi アナライザーを使う場合は、自前で analysis-sudachi プラグインと辞書を組み込んだ派生イメージをビルドする必要があります。

本番環境では、マネージドの Elasticsearch (Elastic Cloud、Bonsai など) か、自前で運用する Elasticsearch クラスタを用意してください。

接続情報を設定する

接続情報は管理画面のプラグイン設定画面 (/admin/plugins/edit?name=@crowi/plugin-search-elasticsearch) から設定します。

設定キー	説明
`url`	Elasticsearch のエンドポイント。`https://[user:pass@]host[:port][/indexName]` 形式。URL にパスワードを含められるため、機密値として暗号化されます。空文字のときはドライバは登録されますが無効化されます。
`indexName`	ベースとなるインデックス名 (デフォルト `crowi`)。URL のパスで指定しない場合に使われます。
`requestTimeout`	リクエストタイムアウト (ミリ秒、デフォルト `5000`)。
`analyzer`	マッピングの種類。`default` / `kuromoji` / `sudachi` から選択。

アナライザーの選択

analyzer 設定で、全文検索のトークナイズ方式を選びます。

アナライザー	クラスタ要件
`default`	追加の ES プラグイン不要。
`kuromoji`	`analysis-kuromoji` プラグインが必要。dev イメージにはプリインストール済み。
`sudachi`	サードパーティの `analysis-sudachi` プラグイン + 辞書が必要。dev イメージには含まれないため、派生イメージのビルドが必須。

日本語コンテンツが主体の Wiki では kuromoji が無難な選択です。プラグイン未導入のクラスタで kuromoji / sudachi を選ぶと、後述のインデックス再構築 (rebuild()) が失敗します。

インデックスの構築

検索インデックスの全件再構築は、Web の管理画面からではなく crowi-admin CLI で行います。長時間かかる処理を管理リクエストに紐付けないための設計です。

crowi-admin rebuild search

このコマンドは:

.env を読み込み、MONGO_URI などを Crowi のブート時と同じ経路で解決します。
アクティブな検索ドライバを解決し、その rebuild() を呼び出します。
Elasticsearch ドライバの場合、タイムスタンプ付きの新しいインデックスを作成し、全ページを bulk indexing したうえで <indexName>-current エイリアスを新インデックスへ切り替えます。古いインデックスは削除されます。

crowi-admin は MongoDB に直接接続する運用者向け CLI です。@crowi/api がインストールされたディレクトリ (通常は runner パッケージ) から実行してください。

Tip: エイリアス方式により、再構築中もダウンタイムなく既存インデックスへの検索が継続できます。新インデックスの構築完了後に一括でエイリアスが切り替わります。

ドライバが永続インデックスを持たない場合 (rebuild() を実装しない場合)、管理画面の Search セクションには再構築のヒントは表示されません。

検索ドライバの状態確認

管理画面の Search セクション (/admin/search) は read-only で、現在アクティブな検索ドライバとインストール済みドライバの一覧を表示します。ドライバの切り替えは crowi.config.json の search.driver 変更 + api 再起動で行います。管理画面全般については管理画面を参照してください。

トラブルシューティング

url が空でドライバが無効: 接続情報が未設定です。管理画面のプラグイン設定で url を設定してください。url が空のときは query() がエラーを投げ、index() は no-op になります。
rebuild が失敗する: kuromoji / sudachi を選んでいるのに対応する ES プラグインがクラスタに入っていない可能性があります。crowi-admin rebuild search はエラー時に ES クラスタのレスポンス本文を出力するので、その内容を確認してください。
検索結果が古い / 出てこない: ページ更新時の差分インデックスは反映されますが、過去データやマッピング変更を取り込むには crowi-admin rebuild search での全件再構築が必要です。

検索バックエンドのセットアップ

On this page