v3 から v4 へのアップグレード
このガイドでは、Casdoor v3 デプロイメントを v4 にアップグレードする方法と、アップグレード後に確認すべき内容を説明します。
学習目標
- v3 と v4 の変更点を理解する。
- v4 リリースを選択する。
- Docker、Helm、またはソースからのデプロイメントをアップグレードする。
- 新しいフロントエンドの影響を受けるセットアップ部分を確認する。
- 必要に応じて v3 にロールバックする。
前提条件
- Casdoor v3 デプロイメント
- データベースのバックアップと復元の方法
v4 について
Casdoor v4.0.0 は 2026 年 9 月 1 日にリリースされました。管理コンソールとサインイン ページが新しいフロントエンドに置き換えられます。バックエンド、REST API、データベース、および conf/app.conf は v3 と互換性があります。ほとんどのデプロイメントは、イメージ タグの切り替えまたはソースからの再ビルドによりアップグレードできます。
v3.164.0 は最後の v3 リリースです。バグ修正とセキュリティ修正は v4 のみで公開されます。
| Area | v3 | v4 |
|---|---|---|
| Frontend UI | Ant Design | shadcn/ui and Tailwind CSS |
| Frontend build | create-react-app (craco), JavaScript | Vite, TypeScript |
| Build output | web/build/static/js, web/build/static/css | web/build/assets |
| Frontend source | web/ | web/ (the v3 frontend is kept in web-old/ for reference and is not built) |
| Backend, API, SDKs | No change needed | |
| Database | New tables and columns are created automatically on startup | |
conf/app.conf | aiAssistantUrl was removed and is ignored if still present |
v4 リリースの選択
最新の v4 リリース にアップグレードしてください。バージョンを固定する場合、v4.6.0 以降を使用してください。初期の v4 リリースにはリグレッションがあり、以下のバージョンで修正されています:
| Problem | Affected | Fixed in |
|---|---|---|
| No Docker image was published | v4.1.0 | v4.2.0 |
| Sign-in and sign-up page customization (custom HTML, sign-in items, custom CSS) was ignored | v4.0.0 – v4.1.0 | v4.2.0 |
Sign-in through an OIDC provider failed with Unknown column 'oidc' | v4.0.0 – v4.1.0 | v4.2.0 |
Startup failed with MySQL Error 1118 on MySQL 8.0.46, 8.4.9 – 8.4.10 and 9.7.0 – 9.7.2 | v4.4.0 | v4.5.0 |
| The UI was always in English instead of following the browser language | up to v4.5.0 | v4.6.0 |
v4.5.0 でも CVE-2026-5469、CVE-2026-9091、CVE-2026-9093、CVE-2026-9096、CVE-2026-9097、および CVE-2026-9098 が修正されています。
アップグレードの準備
-
実行中のバージョンを確認します。バージョン情報 を参照してください。
curl http://localhost:8000/api/get-version-info -
データベースをバックアップします。v4 の起動時に Casdoor はテーブルと列を追加します。バックアップは v3 に戻すための唯一の手段です。
-
CSS や HTML を使用してサインイン ページをカスタマイズした場合、アップグレード後にページを比較できるようにスクリーンショットを撮っておいてください。
Casdoor のアップグレード
同じ app.conf と同じデータベースを維持します。
Docker デプロイメントのアップグレード
-
新しいイメージをプルします:
docker pull casbin/casdoor:latest -
新しいイメージでコンテナを再起動します。
Docker Compose を使用している場合は、image: を更新して docker compose up -d を実行します。Helm を使用している場合は、新しいイメージタグを設定して helm upgrade を実行します。
ソースデプロイメントのアップグレード
コードを取得し、フロントエンドを再ビルドしてサーバーを再起動します。コマンドは v3 と同じです。Node.js 20 と Yarn 1.x が引き続き必要なバージョンです。
git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor
開発環境では、yarn start は依然としてポート 7001 でフロントエンドを提供します。
結果の確認
静的ファイルパス
ハッシュ化された .js および .css ファイルが web/build/static/js および web/build/static/css から web/build/assets に移動しました。古いパスを参照しているすべてのものを更新してください:
- リバースプロキシルール:
/static/js/または/static/css/をキャッシュまたは書き換えるルールは、代わりに/assets/を使用する必要があります。 - CDN: フロントエンドファイルを CDN でホストしている場合、v4 のビルド後にアップロードスクリプトを再度実行してください。フロントエンドファイルを CDN でホストするを参照してください。
サインインページのカスタマイズ
Casdoor v4 では、アプリケーションのカスタム HTML、サインイン項目、およびテーマ設定が以前と同様に適用されます。
カスタム CSS を確認してください。ページは Ant Design コンポーネントから構築されなくなったため、Ant Design クラス名(.ant-btn や .ant-input など)を対象とするセレクタは一致しなくなりました。各カスタマイズ済みアプリケーションのサインイン、サインアップ、パスワード紛失ページを開き、アプリケーションの UI Customization タブで CSS を調整してください。
変更されたフロントエンドコード
web/ 配下に変更を加えたフォークを維持管理している場合、それらの変更は引き継がれません。v3 のコードは web-old/ にあります。これにより、新しいコードの横で以前の変更を確認できますが、Casdoor は web/ のみをビルドして提供します。変更内容を web/src の TypeScript ソースに移植してください。
Casdoor を使用しているアプリケーション
アプリケーションには何も変化はありません。OAuth 2.0、OpenID Connect (OIDC)、SAML、CAS、LDAP、および REST API の動作は v3 と同じままで、SDK のアップデートも不要です。
v3 へのロールバック
- Casdoor を停止します。
- データベースバックアップを復元します。
- 以前実行していた v3 のイメージまたはバイナリを起動します。
ヘルプを得る
v3 で機能していたものが v4 で機能しない場合は、両方のバージョン番号とデータベースタイプを記載して issue を作成してください。