ストレージドライバ

Crowi にアップロードされた添付ファイルは、ストレージドライバ を通じて保存されます。Crowi 2.0 では、どのドライバを使うかをランナープロジェクトの crowi.config.json (storage.driver) で選択し、ドライバの実体は対応する @crowi/plugin-storage-* プラグインが提供します。

Note: Crowi v1 にあった FILE_UPLOAD 環境変数は廃止されました。ストレージの選択は crowi.config.json の storage.driver と、対応する @crowi/plugin-storage-* パッケージの組み合わせで行います。

利用できるドライバ

ドライバ名	提供プラグイン	保存先
`local`	`@crowi/plugin-storage-local` (デフォルトで常に有効)	サーバのローカルファイルシステム
`s3`	`@crowi/plugin-storage-aws-s3`	Amazon S3 (互換ストレージ含む)

@crowi/plugin-storage-local は 暗黙のデフォルトプラグイン として常に読み込まれます。crowi.config.json に何も書かなければ、local ドライバが使われます。

ローカルストレージ (local)

ローカルストレージは、アップロードファイルをサーバのファイルシステムに保存します。最小構成では設定は不要で、crowi.config.json を省略するか次のように書くだけで有効になります。

{
  "storage": {
    "driver": "local"
  }
}

保存先ディレクトリのデフォルトは data/uploads です (crowi.config.json を置いたディレクトリからの相対パス)。

Tip: コンテナで運用する場合は、保存先ディレクトリを永続ボリュームにマウントしてください。コンテナを作り直すとローカルファイルは失われます。 S3 を使えばこの心配はなくなります。

S3 ストレージ (s3)

Amazon S3 (または S3 互換ストレージ) にファイルを保存するには、 @crowi/plugin-storage-aws-s3 プラグインを使います。

1. プラグインを有効化する

crowi.config.json の plugins に S3 ストレージプラグインを追加し、 storage.driver を s3 にします。

{
  "plugins": [
    "@crowi/plugin-storage-aws-s3"
  ],
  "storage": {
    "driver": "s3"
  }
}

@crowi/plugin-storage-aws-s3 は AWS の共通クレデンシャル基盤である @crowi/plugin-aws に依存しているため、依存プラグインは自動で読み込まれます。プラグインの解決方法の詳細はプラグインの管理を参照してください。

2. バケットとクレデンシャルを設定する

S3 のバケット名と AWS のクレデンシャルは、管理画面から設定します。

バケット名 — @crowi/plugin-storage-aws-s3 自身の設定。管理画面のプラグイン設定 (/admin/plugins) から「AWS S3」の設定を開いて入力します。
リージョン / アクセスキー / シークレットキー — @crowi/plugin-aws の設定。同じくプラグイン設定から入力します。

アクセスキー ID とシークレットアクセスキーは機密扱いとして登録されており、CROWI_ENCRYPTION_KEY が設定されていれば自動で暗号化されて保存されます。詳細は機密設定の暗号化を参照してください。

Tip: EC2 / ECS のインスタンスロールや IRSA を使う場合は、アクセスキーを空のままにしておけば、AWS SDK のデフォルトのクレデンシャル解決 (環境変数やインスタンスメタデータ) が使われます。

3. 設定の即時反映

プラグインの設定を管理画面から保存すると、S3 ドライバは reconfigure により サーバ再起動なしで 新しいバケット / クレデンシャルを反映します。

ストレージの現在の状態を確認する

管理画面のストレージ画面 (/admin/storage) を開くと、登録されているドライバの一覧と、現在アクティブなドライバが表示されます。内部的には GET /api/v2/admin/storage が呼ばれ、各ドライバについて以下が返ります。

driverName — ドライバ名 (local / s3 など)
pluginName — そのドライバを登録したプラグイン名
isActive — crowi.config.json で選択中のドライバかどうか

ドライバの切り替えとファイル移行

ドライバを切り替える (例: local → s3) と、crowi.config.json を書き換えた時点で 新規アップロードは新しいドライバに保存 されます。しかし、既存のファイルは自動では移動しません。古いドライバに残ったファイルは、crowi-admin CLI で新しいドライバへコピーします。

crowi-admin rebuild storage copy

crowi-admin はサーバ内 (ssh / kubectl exec) での実行を想定した運用者用 CLI です。rebuild storage copy サブコマンドで、あるドライバから別のドライバへ全オブジェクトをコピーできます。

# local から s3 へ全ファイルをコピー
crowi-admin rebuild storage copy --from local --to s3

# まず対象キーだけを確認する (コピーは行わない)
crowi-admin rebuild storage copy --from local --to s3 --dry-run

ポイント:

コピー元・コピー先の 両方のドライバが、いずれかのプラグインで読み込まれている 必要があります。crowi.config.json の storage.driver が指す「アクティブなドライバ」とは無関係なので、s3 をアクティブにする前に local から s3 へデータを先にコピーしておけます。
--dry-run を付けると、コピー対象のキーを列挙するだけで実際の書き込みはしません。件数の事前確認に使えます。
添付ファイルの行は MongoDB のカーソルで逐次処理されるため、ファイル数が非常に多くてもメモリ使用量は一定です。
1 件単位のエラーはイテレーションを止めず、failed カウントに加算されます。再実行は安全です (local / S3 ドライバはキー単位で上書きします)。

終了コードは次のとおりです。

終了コード	意味
`0`	全件コピー成功 (または dry-run 完了)
`1`	致命的エラー (初期化失敗、または処理開始前の例外)
`2`	部分的失敗 (コピーは走ったが 1 件以上失敗 — 再実行を推奨)

推奨される移行手順

local から s3 へ移行する場合の安全な手順:

@crowi/plugin-storage-aws-s3 を crowi.config.json:plugins に追加し、管理画面で S3 バケット / クレデンシャルを設定する (storage.driver はまだ local のまま)。
crowi-admin rebuild storage copy --from local --to s3 --dry-run で対象件数を確認する。
crowi-admin rebuild storage copy --from local --to s3 で実際にコピーする。 failed が出た場合は再実行する。
crowi.config.json の storage.driver を s3 に変更し、API を再起動する。
新しいアップロードとダウンロードが S3 経由で動くことを確認する。

Tip: 手順 1 で先に S3 へデータをステージングしておけば、ドライバを切り替えた瞬間からダウンタイムなしで S3 が使えます。

経路	1 ファイルあたりの上限
画像の貼り付け (paste)	10 MB
ドラッグ&ドロップ	50 MB

ドラッグ&ドロップは 1 回の操作で 最大 5 ファイル まで扱えます。これを超えてドロップした場合はアップロードされず、トーストで通知されます。

ファイル種別の許可リスト

エディタからアップロードできるファイル種別は許可リストで制限されています。既定の許可リストは次のとおりです。

分類	受け付けるもの
画像	`image/png` / `image/jpeg` / `image/gif` / `image/webp` / `image/svg+xml`
文書	`.pdf` / `.txt` / `.md` / `.csv`
アーカイブ	`.zip`

許可リストにない種別は拒否され、エディタ側には拒否された種別名を添えたトーストが表示されます。許可リストはインスタンス全体に対するグローバル設定です(ユーザーグループ単位の設定はありません)。

Note: これらの制限はエディタからの直接アップロード経路に対するものです。ページフッターの添付ファイルセクションからのアップロードやストレージドライバ自体の設定とは独立しています。

次のステップ

設定 — crowi.config.json の全体像
機密設定の暗号化 — S3 クレデンシャルの暗号化
プラグインの管理 — プラグインの追加・有効化
バックアップ — データのバックアップ