プラグインの導入と設定

このページでは、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 パッケージ名を追加します (モノレポでは apps/crowi-runner/crowi.config.json。セルフホストする運用者は自分の runner プロジェクトのファイルを編集します)。

{
  "plugins": [
    "@crowi/plugin-storage-aws-s3",
    "@crowi/plugin-search-elasticsearch",
    "@crowi/plugin-renderer-plantuml",
    "@crowi/plugin-renderer-emoji",
    "@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> の設定フォームへ移動します。

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

設定フォームは、プラグインが宣言した configSchema (Zod スキーマ) をランタイムが辿って 自動生成 します。プラグイン側が React コンポーネントを出荷する必要はありません。

各プラグインは管理サイドバーにも独自のエントリを追加します。表示位置はプラグインの adminPlacement で決まり、register* フックの種類からセクション (storage / mail / notification / auth …) が自動で導出されます。 register* を持たない設定のみのベースプラグイン (@crowi/plugin-aws など) は、サイドバーに出すために section: 'shared' を宣言します。

`@sensitive` マーカー

configSchema のフィールドの説明文が @sensitive で始まる場合、そのフィールドは 機密扱い になります。

z.string().describe('@sensitive AWS secret access key')

機密フィールドは、コアの機密 Config と同じ KeyProvider を使って保存時に自動暗号化され、読み取り時に復号されます。管理 UI ではシークレット用の入力欄 (<SecretField>: 保存済みバッジ / 入力中のクリア / 取り消し) でレンダリングされます。暗号化の前提となる CROWI_ENCRYPTION_KEY の設定については設定の暗号化を参照してください。

`@action` マーカー

フィールドの説明文が @action で始まる場合、そのフィールドの隣にアクションボタンが描画されます。

z.string().describe('@action "Test connection" POST /test')

書式は @action "<ラベル>" <メソッド> <パス> です。ボタンを押すと、プラグインが registerRoutes で提供したエンドポイント (/api/v2/plugins/<name>/... に対する相対パス) が呼び出されます。「接続テスト」「Google で認証」といった操作を、プラグインが専用 UI を書かずに提供できます。

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

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

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

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

活性化 (activate()) が失敗した場合: そのプラグインは「読み込み済み」の扱いから外れ、設定フォームやドライバ登録の対象になりません。サーバのログに [crowi:plugin:<name>] activation failed; plugin disabled: <エラー内容> という行が出力されます。/admin/plugins の一覧には引き続きこのプラグインが表示され、行に「起動失敗」バッジが付きます。バッジにカーソルを合わせると失敗理由を確認できます。
HTTP ルート登録 (registerRoutes) が失敗した場合: プラグイン自体の活性化は成功しているため一覧には通常どおり表示されますが、そのプラグインが提供する /api/v2/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 実装にフォールバックします)。今後、この種の implicit-default なドライバに限って起動を止める判定ロジックの追加を検討する可能性があります。

プラグインの削除

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