設定 | Crowi

Crowi 2.0 の設定は、大きく 3 つのレイヤーに分かれています。

環境変数 (.env / プロセス環境) — 接続先や暗号鍵など、起動時に必要な値。
crowi.config.json — どのプラグインを読み込み、どのドライバを有効にするか。
管理画面の設定 — アプリのタイトルや OAuth、メール、ストレージの詳細値。MongoDB の Config コレクションに保存されます。

このページでは 1 と 2 を扱います。3 の設定値については管理画面を参照してください。

環境変数

API は起動時に、起動した作業ディレクトリの .env を読み込みます。開発時のそのディレクトリは リポジトリルート です (pnpm dev の api スクリプトが明示的に読み込みます)。本番では runner プロジェクトのディレクトリ になるか、もしくはファイルの代わりに compose / オーケストレータから変数を注入します。.env.example をコピーして編集してください。

cp .env.example .env

API は起動時にこれらの環境変数をまとめて検証します。PORT / MONGO_URI (またはエイリアス) / REDIS_URL (またはエイリアス) / CROWI_ENCRYPTION_KEY の形式が不正な場合、検出できた問題をすべて含む 1 つのエラーメッセージとともに起動が即座に失敗します。CLIENT_URL / CROWI_MULTI_INSTANCE / NODE_ENV / JWT_ACCESS_TOKEN_TTL_SECONDS / JWT_REFRESH_TOKEN_TTL_SECONDS / COLLAB_MAX_EDITORS_PER_PAGE / MIGRATION_PREFLIGHT_UNAPPLIED_POLICY などの形式不正は起動を妨げず、起動ログに 1 箇所へまとめて warning として出力されます(CLIENT_URL が未設定の場合も、送信メール内のリンクが相対パスになってしまう旨の warning が同じレポートに含まれます)。

WS_TOKEN_SECRET は例外的に、NODE_ENV の値によって重大度が変わる 唯一の変数です。要件は環境変数の該当行を参照してください。

CROWI_ / WS_TOKEN_ / JWT_ / COLLAB_ / REDIS / MONGO / MIGRATION_ のいずれかの既知プレフィックスを持つものの、既知の変数名のどれとも完全一致しない環境変数は、タイポの疑いとして同じ warning レポートに含まれます。判定にはレーベンシュタイン距離(編集距離)を使い、既知の変数名のうち最も近いものとの距離が 2 以下であれば「もしかして XXX では?」という形で warning を出します(fail にはなりません — 誤検知を許容するヒューリスティックです)。PATH / CI / GITHUB_* / npm_* など上記プレフィックスを持たない一般的な OS/CI 環境変数は対象外です。

変数の一覧

変数名・既定値・意味の一覧は環境変数にあります。共同編集で使う変数の使い分けはリアルタイム共同編集の運用、構成ごとの NEXT_PUBLIC_API_URL / NEXT_PUBLIC_COLLAB_URL の選び方はデプロイ構成を参照してください。

Tip: WS_TOKEN_SECRET と CROWI_ENCRYPTION_KEY はどちらも openssl rand -base64 32 で生成できます。CROWI_ENCRYPTION_KEY は pnpm --filter @crowi/api crypto:gen-key でも生成できます。

MCP エンドポイント

AI クライアント向けの MCP エンドポイント /api/mcp は常に有効で、フィーチャーフラグはありません。運用者が気にする点は 3 つです。

認証は個人アクセストークンのみです。 web のセッションや OAuth アクセストークンでは接続できません。利用者側の手順は AI ツールから使う (MCP) を参照してください。
前段のプロキシは /api/* を api へ転送するだけで足ります。 MCP クライアントは wiki と同じ origin の /api/mcp に接続します。追加で公開するポートやプロセスはありません。
REDIS_URL を設定するとレート制限の予算がレプリカ間で共有されます。 未設定の場合は各レプリカがメモリ内で予算を持つため、レプリカ数だけ実効の上限が上がります。

サーバーはステートレス (リクエストごとに新しいセッション) なので、複数レプリカ構成でも sticky session は不要です。

Docker での環境変数

docker compose --profile app で全スタックを起動する場合、api サービスは .env を env_file として読み込みます。ただしコンテナネットワーク向けの URI (MONGO_URI / REDIS_URL / CLIENT_URL) は docker-compose.yml 側の environment 指定が .env の値を上書きします。機密値 (CROWI_ENCRYPTION_KEY / WS_TOKEN_SECRET など) は .env に書いておけばそのまま渡ります。

Tip: Web アプリ (@crowi/web) はプラグイン依存ゼロの 独立したデプロイ対象 です。api とは HTTP で通信し、どこにでもデプロイできます (Vercel・コンテナ・api と同居など)。一方 api は長寿命の Node サーバ (データベースへの持続的な接続・レプリカ間の pub/sub・常駐する WebSocket サーバ・起動時のプラグイン読み込み) であり、Node ランタイムが必須 です — Node ホストまたは Node コンテナ (ECS / EKS / Fly / Render / Cloud Run / Cloudflare Containers)。Cloudflare Workers のような edge/isolate 系のサーバレス基盤では動作しません。

レンダラ plugin アセットと CSP (Content-Security-Policy)

KaTeX のような一部のレンダラ plugin は、CSS / font などの静的アセットを自身の public route (/api/plugins/<plugin-name>/...) から配信します。 Web はどのレンダラ plugin が有効かを api に問い合わせ、そのスタイルシートを api origin に対する <link rel="stylesheet"> として読み込みます — plugin 名や CSS の存在を Web 側が事前に知る必要はありません。

Web と api が 同一オリジン (推奨のリバースプロキシ構成、上記参照) の deployment では追加の設定は不要です。既存の CORS policy (CLIENT_URL を許可オリジンとする) は CSS / font のクロスオリジンレスポンスにもそのまま適用されるため、CORS 側の追加設定も不要です。

Web と api を 別オリジン で運用し、かつ operator が Content-Security-Policy を付与している deployment では、style-src と font-src に api の origin を許可してください。例えば CLIENT_URL=https://wiki.example.com、api が https://api.example.com で動く構成では、Web が返す CSP ヘッダにおおよそ次のように追加します。

Content-Security-Policy: style-src 'self' https://api.example.com; font-src 'self' https://api.example.com; ...

許可を追加し忘れると、対象の plugin が有効でも CSS / font がブラウザにブロックされ、スタイルが当たらない状態になります (plugin 自体は正常に動作しているため、api / Web のログにはエラーが出ません — ブラウザのコンソールで CSP violation を確認してください)。

crowi.config.json

crowi.config.json は runner プロジェクトのルート に置く JSON ファイルです。どのプラグインを読み込み、どのドライバを有効にするか を宣言します。プラグインごとの設定値 (S3 のバケット名、OAuth クライアント ID、メール / ストレージの認証情報など) はここには書かず、MongoDB の Config コレクションに保存し、管理画面から編集します。

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

フィールドとドライバ名

キーの一覧・既定値と、指定できるドライバ名の一覧は crowi.config.json にあります。ファイルが存在しない場合や項目を省略した場合は既定値が使われ、スキーマに合わない内容は起動時に明示的なエラーで失敗します。

プラグインの解決方法

@crowi/api は プラグインを同梱しません。SDK (@crowi/plugin-api) とコアのみを出荷し、ドライバは同梱しません。プラグインは runner プロジェクトが所有します。plugins に挙げた名前は、起動時に runner プロジェクト自身の node_modules/ から解決されます。プラグインを追加するには、runner プロジェクトの package.json に依存として宣言したうえで crowi.config.json:plugins に名前を追加します。api パッケージ自体を再ビルドする必要はありません。

3 つのプラグインが 暗黙のデフォルトプラグイン として常に読み込まれ、設定不要で動作します: @crowi/plugin-storage-local、 @crowi/plugin-search-mongo、@crowi/plugin-mail-smtp。そのため、新規インストールは ローカルストレージ + MongoDB 検索 + SMTP メール がそのまま動きます — 必須のインフラは MongoDB だけです。

runner プロジェクトは package.json の "start": "crowi-api" スクリプト (@crowi/api が提供する crowi-api bin) で起動します。プラグインをそのプロジェクトの node_modules/ から解決させるため、プロジェクトディレクトリ自身から実行します。

プラグインが他のプラグインを requires で宣言している場合、その依存先も 自動で (transitive に) 解決・ロード されます。そのため、依存先を plugins に重ねて書く必要はありません。例えば @crowi/plugin-storage-aws-s3 と @crowi/plugin-mail-aws-ses は共通基盤の @crowi/plugin-aws を requires で宣言しているので、plugins には driver プラグインだけ を列挙すれば @crowi/plugin-aws は自動でロードされます。umbrella の @crowi/plugin-aws を明示列挙する必要はありません (重複ロードを避ける)。AWS 一式を使う通し手順は AWS Lightsail で動かすを参照してください。

プラグインの追加・有効化の詳しい手順はプラグインの導入と設定、プラグインの種類はプラグインアーキテクチャを参照してください。

ドライバを選ばないプラグイン

レンダラ系プラグイン (@crowi/plugin-renderer-katex / -plantuml / -mermaid / -crowi-legacy) は plugins に追加するだけで有効になり、 storage / search のようなドライバ選択は不要です。絵文字ショートコードとリンクカード (@[card](url)) はプラグインではなく Crowi コアの機能で、 plugins への追加なしに常時有効です(リンクカードの外部取得は管理画面「セキュリティ」の linkCardEnabled トグルで無効化できます)。

Tip: crowi.config.json でドライバ名を切り替えても、対応するプラグインが plugins に入っていなければ起動時に警告が出ます。ドライバを切り替えるときは、プラグインの追加とセットで行ってください。

次のステップ

機密設定の暗号化 — CROWI_ENCRYPTION_KEY の詳細
ストレージ設定 — storage.driver の切り替え手順
検索バックエンドのセットアップ — Elasticsearch の設定
プラグインの導入と設定 — プラグインの追加・有効化
環境変数 — 変数名・既定値・意味の一覧
crowi.config.json — フィールドとドライバ名の一覧

設定

On this page