v1 からの移行

このページは、Crowi v1 から v2 へ移行する際のデータ互換性の考え方と、 現状で利用できる移行パスを説明します。

v2 (Reignite) とは

Crowi v2 はフロントエンドを全面的にリビルドしたバージョンです。

• v1: Express + Swig (テンプレート) + jQuery のモノリス
• v2: Hono API (@hono/zod-openapi) + Next.js 16 (App Router) + React 19

UI とアプリケーション層は作り直されていますが、データ層 (MongoDB の データ形状) は v1 と互換性が保たれています。ページ、リビジョン、 ユーザー、コメントなどのドキュメント構造は v1 のものをそのまま読み込め ます。つまり、既存の Wiki のデータは v2 へ持ち越せる設計です。

データ互換性の現状

Note: v2 では機密 Config (OAuth secret、SMTP パスワードなど) を AES-256-GCM で暗号化する仕組みが入りました。v1 由来の平文の設定行は そのまま読み込めますが、暗号化を有効にした場合は管理画面の crypto 機能で再暗号化できます。詳細は 機密設定の暗号化 を 参照してください。

移行パスの現状

データ形状は互換ですが、v1 → v2 の 移行パスそのものはまだ整備中です。

• v1 の MongoDB をそのまま v2 で起動させる手順は技術的には可能ですが、 公式に検証・ドキュメント化された移行手順はまだ確立していません。
• 一部のデータには、v2 の新機能に合わせた変換が必要なものがあります (後述の wikilink 移行など)。
• 安定版リリースに向けて、移行手順とツールは順次整備されます。

このため、現時点では 本番データでの移行は行わず、v1 データのコピーを 使った検証環境での試用にとどめることを強くおすすめします。

機密設定の入れ直し

v1 のコア設定にあったストレージ・メールの認証情報 (crowi:upload:aws:* / crowi:mail:aws:* / crowi:mail:smtpPassword など) は v2 にはありません。 対応する プラグインを有効化して値を入力し直してください。入力した値は プラグインの名前空間に保存され、機密設定の暗号化 の設定が あれば自動で暗号化されます。旧データの自動移行やフォールバック参照は 行いません。

移行フレームワーク (crowi-admin migrate)

v1 → v2 のデータ移行は crowi-admin migrate plan | apply | status | list で実行します。crowi-admin は MongoDB に直接接続するため、@crowi/api が インストールされた runner プロジェクトのディレクトリから実行します。 モノレポでは pnpm migrate ラッパーが同じ CLI を実行します。

公式 Docker イメージでは crowi-admin が runner プロジェクトのツリー (/app がルート) に同梱されているため、コンテナ内で実行します。

# 起動中のコンテナ内で未適用の preflight 移行を適用
docker compose run --rm --entrypoint node api \
  node_modules/@crowi/admin-cli/dist/bin.js migrate apply

これは下記の preflight block ポリシーで特に重要です。デプロイで未適用の blocking preflight 移行が入ると api は起動を拒否するため、イメージ内から この方法で解除します。

移行は 2 つのレイヤーに分かれています。

• boot 移行は、api 起動時に自動で適用されます。
• preflight 移行は重い / 破壊的になりうるため、自動では適用されません。 起動のたびに probe され、未適用だったときの挙動は移行ごとの severity (重大度、下記参照) で決まります。blocking の移行は 起動を拒否 し (デフォルトの block ポリシー)、cosmetic の移行は 警告を出して起動を 継続 します。preflight 移行はメンテナンスウィンドウで crowi-admin migrate apply を使って明示的に適用します。

各移行は、未適用の preflight 移行が起動にどう影響するかを決める severity を 持ちます。

• blocking — インデックス・データ整合性に関わる移行 (user-unique-prepare と page-liker-seenusers-to-relations の 2 本)。未適用だとデフォルトの block ポリシー下で api は起動を拒否します。準備されていないデータに対して起動すると、一意インデックスの構築時に E11000 で失敗する恐れがあるためです。migrate plan / migrate list では [blocking] タグが付きます。
• cosmetic — 本文表示のみに関わる移行 (wikilink-format など)。未適用 でも api は 起動し、警告ログを出すだけです (block ポリシー下でも 同様)。cosmetic 移行はライブのコーパスを再スキャンするため、古い記法で 新しいページが書かれると再び未適用扱いになり続けます。これを起動拒否の 対象にするとクラスタがデッドロックします。migrate plan / migrate list では [cosmetic] タグが付きます。

# 未適用の移行をプレビュー (デフォルトは preflight)
crowi-admin migrate plan
# または、モノレポでは:
pnpm migrate plan

# 未適用の preflight 移行を適用
crowi-admin migrate apply

# 未適用の移行件数を表示
crowi-admin migrate status

Tip: crowi-admin の stdout はコマンド本来の出力だけです。boot 時の [crowi] Loaded N plugin(s) は開発時は stderr へ、NODE_ENV=production では 完全に抑制されるため、crowi-admin migrate plan --json | jq のような パイプが壊れません。Node 自体の非推奨警告 (DEP0169 など) も crowi-admin では常に出ません。ただし pnpm migrate plan 経由だと pnpm 自身のスクリプトバナー (> crowi@... migrate など) が stdout に 出ます — これはコード側からは消せない pnpm の挙動なので、パイプする ときは pnpm -s migrate plan --json | jq のように -s (silent) を 付けてください。

Tip: block ポリシーが効くのは blocking の移行だけです。そのため 本番ではデフォルトの block のままで問題ありません。cosmetic の移行 (表示のみに関わるもの) はポリシーに関係なく起動を拒否せず、起動を拒否 するのはデータ整合性に関わる blocking の移行だけだからです。いずれかの blocking の移行が未適用のまま起動したい場合 (たとえば単一インスタンスでの調査用) は、MIGRATION_PREFLIGHT_UNAPPLIED_POLICY=warn を設定すると、その起動拒否 を警告に格下げできます。

マルチインスタンスの注意: MIGRATION_PREFLIGHT_UNAPPLIED_POLICY (環境変数) は、管理画面の Config (migration.preflightUnappliedPolicy) より優先されます。環境変数を持つレプリカと Config だけに頼るレプリカが 混在すると、同一のデータベースに対して 異なる ポリシーが解決される 可能性があります。クラスタ全体で一致させるため、環境変数を 全レプリカに 一貫して 設定してください (例: Kubernetes の ConfigMap を全 Pod に注入)。

登録されている移行は以下のとおりです。

(severity は preflight 移行にのみ適用されます。boot 移行は自動適用され probe されないため、起動拒否の severity を持ちません。blocking は user-unique-prepare と page-liker-seenusers-to-relations の 2 本で、残りは cosmetic です。cosmetic が未適用でも警告は出ますが起動は拒否されません。)

boot 移行 (page-status-default / revisions-schema-unify) は api 起動時に 自動適用されるので、運用者の操作は不要です。以下では、明示的な適用が必要な preflight 移行を中心に説明します。

wikilink の移行

wikilink-format preflight 移行は、v1 時代の wikilink 記法を v2 の レンダラーに合わせて変換します。

# まず変更内容を確認 (新しいリビジョンは書き込まない)
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id wikilink-format

migrate plan は対象ページのスキャンとレポートだけを行い、実際の書き込みは 行いません。適用前に必ず影響範囲を確認してください。この移行は書き換えの 帰属先となる管理者ユーザーを必要とします — 管理者ユーザーが解決できない 場合は CROWI_MIGRATE_USER=<email> を設定してください。

この移行は コード領域を除外 します — フェンスコードブロックやインライン コードの中にある </…> や wikilink ふうの文字列は誤検知せず、そのまま残します。 また 適用してもページの最終更新日時と最終更新者は変わりません（移行に よる書き換えは保守オペレーションでありユーザー編集ではないため、ページ一覧の 並び順や「最終更新者」はそのままです）。

Tip: v1 由来の wikilink 記法は、@crowi/plugin-renderer-crowi-legacy プラグインによってレンダリング時にも解釈できます。データ自体を変換 したくない場合はこのプラグインを有効化するという選択肢もあります。 プラグインについては プラグインアーキテクチャ を参照して ください。

誤変換された HTML 終了タグの復旧 (wikilink-html-recover)

wikilink-format 移行を古い Crowi で実行した環境では、見出しなどで使われる 非推奨の HTML 終了タグ (</font> </center> </marquee> </blink> </applet>) が [[/font]] のような wikilink 記法に化けていることがあります。 現在の wikilink-format はこれらを書き換えませんが、既に化けた本文は移行が 再実行されないため自動では直りません。

wikilink-html-recover preflight 移行は、化けた [[/<x>]] を </x> へ 逆変換します。対象はこの 5 つの非推奨タグ (font / center / marquee / blink / applet) だけで、誤変換が 生み出しえた終了タグがこれらに限られるためです。それ以外の単一セグメント wikilink は、 たとえ名前が標準 HTML 要素であっても ([[/section]] [[/div]] [[/br]] など) 温存されます — これらは常に既知だったため wikilink-format が書き換えて おらず、本来の wikilink だからです。複数セグメント ([[/foo/bar]])・ alias 付き ([[/font|alias]])・大文字 ([[/Font]]) の形も温存されます。

# 復旧対象を事前確認 (本文は書き換えない)
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id wikilink-html-recover

Caution: [[/font]] が「化けた </font>」なのか「実在する /font ページへの本来の wikilink」なのかは、本文だけからは区別できません。この 移行は、/<x> と同名の実ページ (生きている公開ページ) が存在する [[/<x>]] は自動変換せず、migrate plan の結果に一覧として報告します (運用者が個別に判断してください)。一方、同名ページが存在しない [[/font]] (5 つの非推奨タグ) は 逆変換されます — 削除済み / 未作成のページへの dangling リンクも含みます。実際には /font /center /marquee /blink /applet という名前の実ページは非常に稀ですが、もし存在する場合は migrate plan の collision 一覧を確認し、まず dev / stg で検証してから 本番に適用してください。

この移行は冪等です — 逆変換後の </x> は復旧対象の検出にも wikilink-format の変換にも当たらないため、再実行しても二重には作用しません。

Note: コードフェンス (```) やインラインコード (`…`) の中に 書かれた [[/font]] などの記述は、この移行の 対象外 です — 移行の説明として コード例に書かれた [[/font]] は </font> へ逆変換されず、そのまま温存されます。 wikilink-format (</…>)・files-url-to-attachments (/files/<id>) と同じ コード除外挙動で、3 つの本文書き換え移行はいずれも同一です。このためコード内に しか対象トークンがないページが「移行未適用 (pending)」と誤検知されることもなく、 preflight + block ポリシー下で起動がブロックされ続けることはありません。

/api 名前空間の移設

v1 は API を /_api/*(アンダースコア付き)で提供していたため、/api/* (アンダースコアなし)は通常の wiki ページパスでした。v2 は /api を リバースプロキシ先のバックエンド(/api/*)用に予約するので、v1 で /api/* 配下に残っているページは行き場を失います — web アプリは予約名前 空間を 404 にし、同じパスはプロキシに完全に隠れます。

relocate-reserved-api-paths preflight 移行は、該当する全ページを /api-legacy/* へ移します(残りのパスは保持。移設先が既に存在する場合は -N サフィックスを付与)。旧パスにリダイレクトは残しません(予約名前空間内 のため)。/api/* ページが無い wiki では適用対象なしになります。

# 移動対象を事前確認
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id relocate-reserved-api-paths

ユーザーの一意性の準備 (user-unique-prepare)

v1 は username / email の一意性を厳密には強制していませんでした (大文字小文字違いの重複や、削除済みユーザーが元の identity を保持したまま 残るなど)。v2 は username / email に 大文字小文字を区別しない一意 インデックス を張る (起動時に autoIndex が構築) ため、衝突するデータが 残っているとインデックス構築が E11000 で失敗します。

user-unique-prepare preflight 移行は、インデックスが構築できるように データを整えます (インデックスの構築自体は行いません)。

• dedup-username — 大文字小文字を無視して衝突する現役ユーザーを 1 人に 統合し、所有権の参照を統合先に付け替えて残りを削除します。
• dedup-email — email についても同様に統合します。
• tombstone-deleted — 現役ユーザー (または別の削除済みユーザー) と衝突 する削除済みユーザーを、ランタイムの削除挙動と同じ deleted-<id> 形式の tombstone 名にリネームします。

# 統合 / 削除 / リネーム対象の件数をプレビュー
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id user-unique-prepare

Caution: この移行はユーザーの 統合・削除 を伴います。migrate plan で対象を必ず確認し、適用前に MongoDB のバックアップを取得してください。

liker / 閲覧済みユーザーの relation 化 (page-liker-seenusers-to-relations)

v1、および alpha.17 以前のすべての 2.0-alpha は、Like と「閲覧済み」利用者を pages.liker / pages.seenUsers という ObjectId 配列として pages document に直接保存していました。それ以降のバージョンはこれらを独立した likes / seens collection へ切り替え、Page schema から両 field を削除しましたが、MongoDB に保存済みの field と値はスキーマを変えただけでは消えません。page-liker-seenusers-to-relations preflight 移行は、このレガシー配列を一回限り likes / seens へコピーしてから pages 側の field を除去する、前進専用の移行です。

この移行は他の preflight 移行と異なり、停止窓 (メンテナンスウィンドウ) での適用が必須です。理由は 2 つあります。

1. likes / seens の {page,user} 一意インデックスは、この移行の最初の stage (prepare-target-index) が明示的に構築するまで存在しません。
2. 移行前は likes / seens に既存の Like / 閲覧済みデータが一件も無いため、新しい api を先に起動すると Like / 閲覧済み件数がすべて 0 に見えます。

以下の手順を 順番どおり に実行してください。

1. 対象が v1 および alpha.17 以前のすべての deployment であることを確認する。
2. メンテナンスモードに入り、新旧すべての writer とバックグラウンドワーカーを停止し、ロードバランサ / プロキシの in-flight トラフィックを drain する。
3. MongoDB のバックアップを取得し、復元可能であることを確認する。
4. 新しいイメージの admin CLI で crowi-admin migrate plan を実行し、page-liker-seenusers-to-relations の detect 件数と、pending なすべての blocking 移行を確認する。
5. crowi-admin migrate apply --id page-liker-seenusers-to-relations を実行する。
6. 再度 crowi-admin migrate plan を実行する。他に pending な blocking 移行が残っていれば、その ID を指定して crowi-admin migrate apply --id <id> を一本ずつ適用し、再度 plan を実行する。
7. 対象 ID と、他のすべての blocking 移行が pending でないことを plan 出力で確認する。この確認が取れない deployment は deploy しない。
8. 新しい binary を deploy し、起動と relation index の構築完了を確認する。
9. Like / unlike / 閲覧済みの記録と件数を smoke test する。
10. トラフィックを再開する。

# 移行対象と全 pending blocking migration を確認 (書き込みなし)
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id page-liker-seenusers-to-relations

# 残りの pending blocking migration を確認してから、それぞれ --id で適用
crowi-admin migrate plan
crowi-admin migrate apply --id <残りの blocking migration の ID>

Caution: この停止窓では --id を指定しない crowi-admin migrate apply を使わないでください。--id の無い apply は cosmetic を含む pending な preflight 移行をすべて適用します。とくに wikilink-format は本文を書き換える cosmetic 移行で、生きているコーパスを再スキャンする性質上、通常運用でも pending であり続けます。停止窓の目的でない大規模なリビジョン生成を巻き込んでしまうため、必ず対象 ID を指定してください。

適用が失敗したときの復旧

migrate apply が失敗すると、エラーメッセージに原因を特定できる情報 (件数と、page / user を特定できるサンプル最大 20 件) が含まれます。バックアップ全体への復元は最後の手段であり、最初の対応ではありません。

• duplicate レポート: likes / seens に重複行がある状態です。列挙された {page,user} について、重複行が 1 行になるまで削除してください。createdAt が非 null の行 (停止窓外で新 binary が作成したライブな行) があればそれを残し、無ければどれを残しても構いません。削除後に同じ apply --id を再実行してください。
• missing レポート: pages 側の legacy field はまだ $unset されておらず、元データは無傷です。原因 (接続断など) を解消し、同じ apply --id を再実行すれば copy と verify が最初からやり直され収束します。
• それ以外のエラー: メッセージが示す原因を解消し、同じ apply --id を再実行してください。

いずれの場合も、legacy field が残っている間は isPending が true のままなので、再実行は常に安全です。

Note: MIGRATION_PREFLIGHT_UNAPPLIED_POLICY=warn でこの移行を pending のまま起動した場合、その窓の間は移行前の Like / 閲覧済みが数えられません。また、その窓で利用者が unlike した Like は legacy 配列側に反映されないため、後で apply すると legacy 配列由来の Like が復活することがあります。$unset が完了したら旧 binary へは戻さず、問題があれば fix-forward するか、移行前のバックアップ全体へ復元してください。

Note: この移行は、無効な要素と Page 内の重複要素を除外して実在する relation 行数へ揃えるため、以前の配列の長さをそのまま数えていた場合と比べて likerCount / seenUsersCount が減ることがあります。非配列 (スカラ) で保存された値については、無効な値だけが除外されます — 有効な ObjectId (現在も 1 件の Like として数えられている状態) は除外されず、1 relation として移行され、この件数是正には含まれません。

検索インデックスの再構築

v1 から移行したデータで全文検索を使う場合、v2 側で検索インデックスを 作り直す必要があります。

crowi-admin rebuild search

詳細は 検索バックエンドのセットアップ を参照して ください。

ストレージの移行

添付ファイルの保存先を変える場合 (例: ローカルから S3 へ) は、 ストレージコピーコマンドを使います。

crowi-admin rebuild storage copy --from local --to s3 --dry-run
crowi-admin rebuild storage copy --from local --to s3

Note: v1 の AWS / S3 認証情報 (旧 upload:aws:* のコア設定) は 引き継がれません。@crowi/plugin-aws (および @crowi/plugin-storage-aws-s3) を有効化し、管理画面の Plugins で 認証情報を入力し直してください (プラグイン名前空間に保存され、暗号化 されます)。

ドメイン変更後の本文 URL 一括置換 (replace url)

v1 → v2 で 公開ドメイン (ホスト) を変更した 場合、ページ本文に埋め込まれた 絶対 URL (画像埋め込みやリンク。例: ![shot.png](https://old.example/files/<id>)) は旧ホストのまま残ります。ページ / ファイルの id は引き継がれるため、必要なのは ホスト (URL 接頭辞) の単純な置換 であって id の振り直しではありません。

crowi-admin replace url は、全ページ本文中の リテラル文字列 を --from から --to へ置換します (正規表現ではなく完全一致なので、/ . ? を含む URL でも安全です)。

# まず置換対象をプレビュー (書き込まない)
crowi-admin replace url --from https://old.example --to https://new.example --dry-run

# 実行 (置換件数を確認するプロンプトが出る)
crowi-admin replace url --from https://old.example --to https://new.example

この置換は エンドユーザーから見えない静かな書き換え として行われます。 ページごとに新しいリビジョンを積みますが、最終更新日時 / 最終更新者 / 公開範囲 は変更せず、ウォッチャーへの通知や自動ウォッチも行いません。一覧の 並びや通知が動かないので、ドメイン移行のクリーンアップに適しています。

オプションの一覧は crowi-admin にあります。--yes が無く TTY も無い環境では書き込みを拒否します。

Caution: --from に old.example のような スキームの無い裸のホスト を渡すと、old.example.com のような「接頭辞が一致するより長いホスト」まで 壊す恐れがあります。CLI は既定でこれを拒否し、--force が必要です。可能な 限り https://old.example のように完全なオリジンを指定してください。

置換後、ページのレンダリング済み HTML は新リビジョンとして再生成されるため 最新です。一方 検索インデックスは別途再構築が必要 です (crowi-admin rebuild search)。バックリンクは外部 URL が対象なので影響を 受けません。

Note: replace url はバージョン付きの移行ではなく (任意の from/to で 何度でも実行可能)、派生データの再構築でもない (本文を書き換える) ため、 migrate でも rebuild でもない独立した名前空間です。

ファイル URL の v2 化 (files-url-to-attachments)

v1 はページ本文の添付ファイル / 画像を v1 のファイル URL で参照していました (![shot.png](/files/<id>) の相対形、またはエディタがフル URL を貼り付けた ![shot.png](https://wiki.example/files/<id>) の絶対形)。Crowi 2.0 は添付を 専用のストリームエンドポイント /api/attachments/<id> で配信し、レガシーの /files/<id> 互換ルートは削除されたため、v1 形式の URL は 404 = 画像が壊れます。id は v1 / v2 で同一の 24-hex の添付 ID なので、必要なのは URL の書き換えだけ (id の振り直しは不要) です。

files-url-to-attachments preflight 移行は、公開ページ (+ レガシーの null ステータス) の現リビジョン本文を走査し、Markdown 画像 ![alt](url) / リンク [text](url) の URL を次のルールで書き換えます (生 HTML の <img> / <a> は 対象外)。

• 相対 /files/<id> → /api/attachments/<id> (無条件。ルート相対パスは 常に自サイト)。
• 自サイトの絶対 URL https://<CLIENT_URL のホスト>/files/<id> → /api/attachments/<id> (ホストを落として相対化し、ホスト非依存にする)。 自サイト判定は CLIENT_URL / BASE_URL のオリジンとの一致のみです。
• 外部ホストの絶対 URL → 触りません (無関係な第三者の /files/<id> 画像を誤って書き換えないため)。

# まず書き換え対象をプレビュー (書き込まない)
crowi-admin migrate plan

# この移行だけを適用
crowi-admin migrate apply --id files-url-to-attachments

この移行は冪等で、書き換え後の /api/attachments/<id> は再適用しても二重に 変換されません。書き換えの帰属先となる管理者ユーザーを必要とするため、解決 できない場合は CROWI_MIGRATE_USER=<email> を設定してください。

Tip: ドメインを変更した 場合は、先に replace url で旧ホスト → 新ホストを揃えてから本移行を適用してください。replace url で 自サイトの絶対 URL が CLIENT_URL のホストに揃うと、本移行がそれらを相対化 できます。逆順だと旧ホストの絶対 URL が「外部」と判定され書き換えられません。

Note: 移行漏れや未変換の本文への保険として、API には /files/<id> → 302 /api/attachments/<id> のリダイレクトが復活して います。実行時に相対 /files/<id> へアクセスがあっても正規の形式へ転送される ため、本文の書き換えが間に合わなくても画像が壊れたままにはなりません (ただし外部ホストを指す絶対 URL はリダイレクトでは救えないため、本文の 書き換えが本筋です)。

Note: コードフェンス (```) やインラインコード (`…`) の中に 書かれた /files/<id> URL は、この移行の 対象外 です — コード例として 書かれた ![pic](/files/<id>) は書き換えられず、そのまま温存されます。 wikilink-format (</…>)・wikilink-html-recover ([[/font]]) と同じ コード除外挙動で、3 つの本文書き換え移行はいずれも同一です。このためコード内に しか対象 URL がないページが「移行未適用 (pending)」と誤検知されることもなく、 preflight + block ポリシー下で起動がブロックされ続けることはありません。

移行前に必ず行うこと

実際に移行を試す前に、以下を済ませてください。

1. v1 データの完全なバックアップを取得する — mongodump で MongoDB を、 ストレージドライバの保存先を添付ファイルごとバックアップします。 手順は バックアップ を参照してください。
2. 検証環境を用意する — v1 データのコピーを使い、本番とは隔離された 環境で v2 を立ち上げます。
3. CROWI_ENCRYPTION_KEY を準備する — v2 で機密設定の暗号化を使う 場合は鍵を生成し、安全に保管します。
4. 移行をまずプレビューする — crowi-admin migrate plan で未適用の preflight 移行を、rebuild storage copy ... --dry-run で対象を確認してから、 実際の適用を行います。

まとめ

• v2 のデータ形状は v1 と互換で、既存の Wiki データは持ち越せます。
• crowi-admin migrate フレームワーク (plan / apply と preflight-block の起動ガード) と、rebuild search / rebuild storage copy、ドメイン変更後の 本文 URL 置換 replace url が提供されています。適用前にいずれもプレビュー (migrate plan / --dry-run) してください。
• 移行の各コマンドの詳細と既知の注意点はリリースノートにも記載されます。