プラグインの導入と設定

このページでは、Crowi 2.0 にプラグインを導入し、管理画面から設定する手順を説明します。プラグインの仕組み全体についてはプラグインアーキテクチャを先に読むことをおすすめします。

プラグインは 2 段階で有効になる

Crowi のプラグインは「導入 (load)」と「設定 (configure)」の 2 段階に分かれています。

導入 — どのプラグインを読み込むかを crowi.config.json で宣言する。これはコード変更ではなく運用者の設定変更です。
設定 — 各プラグインの設定値 (S3 バケット名、OAuth クライアント ID など) を管理画面 /admin/plugins から入力する。設定値は MongoDB の Config コレクションに plugin:<name>:* という名前空間で保存されます。

crowi.config.json には「どのプラグインを読むか」と「どのドライバを使うか」だけを書きます。バケット名やシークレットといった 設定値そのもの はこのファイルには書きません。

導入手順

1. runner プロジェクトの依存に追加

プラグインは通常の npm パッケージです。Crowi を動かしている runner プロジェクト (api を起動するプロジェクト) の package.json の依存関係にプラグインを加えます。

pnpm add @crowi/plugin-storage-aws-s3

開発リポジトリでは、ファーストパーティのプラグインは workspace 内にすでに存在するため、pnpm の hoisted な node_modules/ 経由で解決され、追加インストールは不要です。

2. crowi.config.json に列挙

runner プロジェクトの crowi.config.json の plugins 配列に、導入するプラグインの npm パッケージ名を追加します。

{
  "plugins": [
    "@crowi/plugin-storage-aws-s3",
    "@crowi/plugin-search-elasticsearch",
    "@crowi/plugin-renderer-plantuml",
    "@crowi/plugin-renderer-katex"
  ],
  "storage": {
    "driver": "s3"
  },
  "search": {
    "driver": "elasticsearch"
  }
}

ストレージ・検索・メールのように「ドライバ」を選択するプラグインの場合は、 storage.driver / search.driver / mail.driver で使用するドライバ名を指定します。省略すると、暗黙のデフォルトプラグインが提供する local / mongo / smtp が使われます (検索のデフォルトは Elasticsearch ではなく MongoDB です)。

Tip: crowi.config.json で列挙したプラグインが他プラグインを requires で必要としている場合、推移的な依存も自動で読み込まれます。例えば @crowi/plugin-storage-aws-s3 は @crowi/plugin-aws を要求するため、後者を明示的に列挙しなくても読み込まれます。

3. api の再起動

プラグインの読み込みは起動時に一度だけ行われます。crowi.config.json を変更したら api を再起動してください。プラグインの追加・削除に api イメージの再ビルドは不要です。

公式 Docker イメージでは、runner プロジェクトの crowi.config.json がイメージに焼き込まれています (有効ドライバを選択するだけでシークレットは含みません)。有効にするプラグイン/ドライバを変えたい場合は、自前のファイルを /app/crowi.config.json にマウントして上書きします。

管理画面からの設定

api が起動すると、読み込まれたプラグインは管理画面 /admin/plugins に一覧表示されます。各行には npm 名・バージョン・登録した拡張ポイントが表示され、クリックすると /admin/plugins/edit?name=<name> の設定フォームへ移動します。

設定不備の警告バナー

選択中のストレージ / 検索 / メール送信ドライバに、動作に必要な設定が欠けている場合 — S3 のバケット名、Elasticsearch / OpenSearch のクラスタ URL、SMTP のホスト名、Resend の API キーなど — 管理者にだけ警告バナーが表示されます。全ページのヘッダと /admin/plugins の両方に出て、該当する設定画面に直接リンクします。欠けている項目を保存すれば、次の再取得で消えます。

メールの送信元アドレス (mail:from) のように、プラグインではなく core 側の設定が対象になることもあります。この場合はメール設定画面 /admin/mail へのリンクになり、/admin/plugins の一覧には現れません (プラグインの行として表示されるのは、プラグイン自身の設定不備だけです)。

管理者以外にはバナーは出ず、判定のための問い合わせ自体も発生しません。判定に使われるのは どの設定が未入力かという情報だけで、実際の設定値・ URL・秘密情報は一切返しません。

プラグイン側でこの宣言を行う方法はプラグイン開発を参照してください。

スキーマ駆動の設定フォーム

設定フォームは、プラグインが宣言した設定項目から 自動生成 されます。プラグイン側が専用の画面を出荷する必要はありません。

各プラグインは管理サイドバーにも独自のエントリを追加します。表示位置はプラグイン自身が決め、セクション (storage / mail / notification / auth …) はそのプラグインが提供する拡張の種類から自動で導出されます。

どのセクションにも解決しなかった場合の既定は「設定」グループです。 独自のドライバを提供しない設定のみのベースプラグイン (@crowi/plugin-aws など) は「共通サービス」グループを選べますが、これはサイドバーに出すためではありません。選ばなくても「設定」に表示されます。同様に、サイドバーに見出しの無いセクションを指定したプラグインも「設定」へフォールバックするので、セクションの指定ミスで設定ページが辿れなくなることはありません。

機密の設定項目とアクションボタン

プラグインが機密と宣言した設定項目は、コアの機密設定と同じ鍵で保存時に自動暗号化され、管理 UI ではシークレット用の入力欄 (保存済みバッジ / 入力中のクリア / 取り消し) で表示されます。前提となる CROWI_ENCRYPTION_KEY については機密設定の暗号化を参照してください。

「接続テスト」「Google で認証」のようなアクションボタンも、プラグインが設定項目に宣言すると管理 UI に現れます。プラグイン側での宣言方法はプラグイン SDK にあります。

レンダーキャッシュのクリア

レンダラプラグイン (PlantUML など) は、レンダリング結果をキャッシュします。 /admin/plugins 画面には、全レンダーキャッシュをまとめてクリアするボタンがあります。プラグインの出力形が変わったときなどに利用してください。

1 プラグインの活性化失敗が起動全体を止めない

プラグインの活性化と、そのプラグインが提供する HTTP ルートの登録は、プラグインごとに独立して隔離されています。1 つのプラグインが起動時に例外を投げても、他のプラグインの読み込みやサーバ全体の起動は継続します。

活性化に失敗した場合: そのプラグインは「読み込み済み」の扱いから外れ、設定フォームやドライバ登録の対象になりません。サーバのログに [crowi:plugin:<name>] activation failed; plugin disabled: <エラー内容> という行が出力されます。/admin/plugins の一覧には引き続きこのプラグインが表示され、行に「起動失敗」バッジが付きます。バッジにカーソルを合わせると失敗理由を確認できます。
HTTP ルートの登録に失敗した場合: プラグイン自体の活性化は成功しているため一覧には通常どおり表示されますが、そのプラグインが提供する /api/plugins/<name>/... 配下のエンドポイントは登録されません。ログには [crowi:plugin:<name>] registerRoutes failed; this plugin's HTTP routes are not mounted: <エラー内容> という行が出力されます。

いずれの場合も、まずサーバログで実際のエラー内容を確認し、必要であれば crowi.config.json の plugins 配列から該当のプラグインを外して api を再起動してください。

Note: storage.driver / search.driver のように、crowi.config.json の既定値が指すドライバを提供するプラグインが活性化に失敗した場合でも、現状の実装では起動は継続します (該当ドライバは「未登録」として扱われ、 legacy な in-core 実装にフォールバックします)。

プラグインの削除

プラグインを外すには crowi.config.json の plugins から該当の名前を取り除いて api を再起動します。設定行 (plugin:<name>:*) は、運用者があとで再導入する可能性を考えて 既定では保持 されます。設定行も含めて完全に破棄したい場合のみ、削除時に明示的な purge 操作を行います。