Passer au contenu principal

Passage de v3 à v4

Ce guide explique comment mettre à niveau un déploiement Casdoor v3 vers v4 et quoi vérifier après la mise à niveau.


Objectifs d'apprentissage​

  • Comprendre ce qui a changé entre v3 et v4.
  • Choisir une version v4.
  • Mettre à niveau un déploiement Docker, Helm ou source.
  • Vérifier les parties de votre configuration affectées par le nouveau frontend.
  • Revenir à v3 si nécessaire.

Prérequis​

  • Un déploiement Casdoor v3
  • Une méthode pour sauvegarder et restaurer sa base de données

À propos de v4​

Casdoor v4.0.0 a été publié le 1er septembre 2026. Il remplace la console d'administration et les pages de connexion par un nouveau frontend. Le backend, l'API REST, la base de données et conf/app.conf sont compatibles avec v3. La plupart des déploiements se mettent à niveau en changeant le tag de l'image ou en reconstruisant à partir du code source.

v3.164.0 est la dernière version de v3. Les corrections de bugs et de sécurité sont publiées uniquement dans v4.

Areav3v4
Frontend UIAnt Designshadcn/ui and Tailwind CSS
Frontend buildcreate-react-app (craco), JavaScriptVite, TypeScript
Build outputweb/build/static/js, web/build/static/cssweb/build/assets
Frontend sourceweb/web/ (the v3 frontend is kept in web-old/ for reference and is not built)
Backend, API, SDKsNo change needed
DatabaseNew tables and columns are created automatically on startup
conf/app.confaiAssistantUrl was removed and is ignored if still present

Choisir une version v4​

Effectuez la mise à niveau vers la dernière version v4. Si vous épinglez une version, utilisez v4.6.0 ou ultérieure. Les premières versions v4 contenaient des régressions, corrigées dans les versions suivantes :

ProblemAffectedFixed in
No Docker image was publishedv4.1.0v4.2.0
Sign-in and sign-up page customization (custom HTML, sign-in items, custom CSS) was ignoredv4.0.0 – v4.1.0v4.2.0
Sign-in through an OIDC provider failed with Unknown column 'oidc'v4.0.0 – v4.1.0v4.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.2v4.4.0v4.5.0
The UI was always in English instead of following the browser languageup to v4.5.0v4.6.0

v4.5.0 corrige également CVE-2026-5469, CVE-2026-9091, CVE-2026-9093, CVE-2026-9096, CVE-2026-9097 et CVE-2026-9098.

Préparer la mise à niveau​

  1. Vérifiez la version que vous exécutez. Voir Informations sur la version.

    curl http://localhost:8000/api/get-version-info
  2. Sauvegardez la base de données. Casdoor ajoute des tables et des colonnes au démarrage de v4. La sauvegarde est votre moyen de retour vers v3.

  3. Si vous avez personnalisé une page de connexion avec du CSS ou du HTML, prenez-en une capture d'écran afin de pouvoir comparer la page après la mise à niveau.

Mettre à niveau Casdoor​

Conservez le même app.conf et la même base de données.

Mettre à niveau un déploiement Docker​

  1. Téléchargez la nouvelle image :

    docker pull casbin/casdoor:latest
  2. Redémarrez le conteneur avec la nouvelle image.

Avec Docker Compose, mettez à jour image: et exécutez docker compose up -d. Avec Helm, définissez la nouvelle balise d'image et exécutez helm upgrade.

Mettre à niveau un déploiement depuis les sources​

Téléchargez le code, reconstruisez le frontend et redémarrez le serveur. Les commandes sont les mêmes que pour v3. Node.js 20 et Yarn 1.x restent les versions requises.

git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor

En développement, yarn start sert toujours le frontend sur le port 7001.

Vérifier le résultat​

Chemins des fichiers statiques​

Les fichiers .js et .css hachés ont été déplacés de web/build/static/js et web/build/static/css vers web/build/assets. Mettez à jour tout ce qui fait référence aux anciens chemins :

  • Règles de reverse proxy : Les règles qui mettent en cache ou réécrivent /static/js/ ou /static/css/ doivent utiliser /assets/ à la place.
  • CDN : Si un CDN héberge les fichiers du frontend, exécutez à nouveau le script de téléchargement après avoir construit v4. Voir Héberger les fichiers du frontend sur un CDN.

Personnalisation de la page de connexion​

Casdoor v4 applique le HTML personnalisé, les éléments de connexion et les paramètres de thème d'une application comme auparavant.

Passez en revue votre CSS personnalisé. Les pages ne sont plus construites à partir des composants Ant Design, donc les sélecteurs qui ciblent les noms de classes Ant Design, tels que .ant-btn ou .ant-input, ne correspondent plus à rien. Ouvrez les pages de connexion, d'inscription et de récupération de mot de passe de chaque application personnalisée et ajustez le CSS dans l'onglet UI Customization de l'application.

Code frontend modifié​

Si vous maintenez un fork avec des modifications sous web/, ces modifications ne sont pas conservées. Le code v3 se trouve dans web-old/, afin que vous puissiez lire vos anciennes modifications à côté du nouveau code, mais Casdoor construit et sert uniquement web/. Portez vos modifications vers les sources TypeScript dans web/src.

Applications utilisant Casdoor​

Rien ne change pour vos applications. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP et l'API REST fonctionnent comme dans v3, et les SDK n'ont pas besoin d'être mis à jour.

Revenir à v3​

  1. Arrêtez Casdoor.
  2. Restaurez la sauvegarde de la base de données.
  3. Démarrez l'image ou le binaire v3 que vous utilisiez auparavant.

Obtenir de l'aide​

Si quelque chose fonctionnait dans v3 et ne fonctionne pas dans v4, ouvrez un problème indiquant les deux numéros de version et le type de votre base de données.

Voir aussi​