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

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

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

アーキテクチャ概要

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

Elasticsearch プラグインの有効化

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

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

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

Elasticsearch を用意する

Elasticsearch (または OpenSearch) は運用者が用意します。日本語のページを 検索する場合は、形態素解析プラグイン analysis-kuromoji を入れたクラスタが 必要です (後述の kuromoji アナライザーがこれを使います)。

Caution: sudachi アナライザーを使う場合は、 自前で analysis-sudachi プラグインと辞書を組み込んだ派生イメージを ビルドする必要があります。

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

接続情報を設定する

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

アナライザーの選択

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

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

インデックスの構築

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

crowi-admin rebuild search

このコマンドは:

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

crowi-admin は MongoDB に直接接続する運用者向け CLI です。@crowi/api がインストールされたディレクトリ (通常は runner プロジェクト) から実行 してください。オプションと終了コードは crowi-admin にあります。

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

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

検索ドライバの状態確認

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

トラブルシューティング

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