Upgrade von v3 auf v4
Dieser Leitfaden erklärt, wie man eine Casdoor-v3-Bereitstellung auf v4 aktualisiert und was nach dem Upgrade überprüft werden sollte.
Lernziele
- Verstehen, was sich zwischen v3 und v4 geändert hat.
- Eine v4-Version auswählen.
- Eine Docker-, Helm- oder Quellcode-Bereitstellung aktualisieren.
- Überprüfen der Teile Ihrer Einrichtung, die vom neuen Frontend betroffen sind.
- Zurückkehren zu v3, falls erforderlich.
Voraussetzungen
- Eine Casdoor-v3-Bereitstellung
- Eine Möglichkeit, deren Datenbank zu sichern und wiederherzustellen
Über v4
Casdoor v4.0.0 wurde am 1. September 2026 veröffentlicht. Es ersetzt die Admin-Konsole und die Anmeldeseiten durch ein neues Frontend. Das Backend, die REST-API, die Datenbank und conf/app.conf sind mit v3 kompatibel. Die meisten Bereitstellungen aktualisieren durch Wechseln des Image-Tags oder durch Neukompilierung aus dem Quellcode.
v3.164.0 ist die letzte v3-Version. Fehlerbehebungen und Sicherheitskorrekturen werden nur noch in v4 veröffentlicht.
| 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 |
Eine v4-Version auswählen
Aktualisieren Sie auf die neueste v4-Version. Wenn Sie eine Version festlegen, verwenden Sie v4.6.0 oder höher. Die ersten v4-Versionen hatten Regressionen, die in den folgenden Versionen behoben wurden:
| 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 behebt außerdem CVE-2026-5469, CVE-2026-9091, CVE-2026-9093, CVE-2026-9096, CVE-2026-9097 und CVE-2026-9098.
Das Upgrade vorbereiten
-
Prüfen Sie die Version, die Sie ausführen. Siehe Versionsinformationen.
curl http://localhost:8000/api/get-version-info -
Sichern Sie die Datenbank. Casdoor fügt Tabellen und Spalten hinzu, wenn v4 startet. Das Backup ist Ihr Weg zurück zu v3.
-
Wenn Sie eine Anmeldeseite mit CSS oder HTML angepasst haben, erstellen Sie einen Screenshot davon, damit Sie die Seite nach dem Upgrade vergleichen können.
Casdoor aktualisieren
Behalten Sie dieselbe app.conf und dieselbe Datenbank bei.
Upgrade einer Docker-Bereitstellung
-
Ziehen Sie das neue Image:
docker pull casbin/casdoor:latest -
Starten Sie den Container mit dem neuen Image neu.
Bei Verwendung von Docker Compose aktualisieren Sie image: und führen Sie docker compose up -d aus. Bei Helm setzen Sie das neue Image-Tag und führen Sie helm upgrade aus.
Upgrade einer Quellcode-Bereitstellung
Laden Sie den Code herunter, bauen Sie das Frontend neu und starten Sie den Server neu. Die Befehle sind identisch zu v3. Node.js 20 und Yarn 1.x sind weiterhin die erforderlichen Versionen.
git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor
In der Entwicklung stellt yarn start das Frontend weiterhin auf Port 7001 bereit.
Ergebnis überprüfen
Pfade für statische Dateien
Die gehashten .js- und .css-Dateien wurden von web/build/static/js und web/build/static/css in web/build/assets verschoben. Aktualisieren Sie alles, was sich auf die alten Pfade bezieht:
- Reverse-Proxy-Regeln: Regeln, die
/static/js/oder/static/css/cachen oder umschreiben, müssen stattdessen/assets/verwenden. - CDN: Wenn ein CDN die Frontend-Dateien hostet, führen Sie das Upload-Skript erneut aus, nachdem Sie v4 gebaut haben. Siehe Frontend-Dateien auf einem CDN hosten.
Anpassung der Anmeldeseite
Casdoor v4 wendet das benutzerdefinierte HTML, die Anmeldesegmente und die Theme-Einstellungen einer Anwendung wie zuvor an.
Überprüfen Sie Ihr benutzerdefiniertes CSS. Die Seiten werden nicht mehr aus Ant Design-Komponenten erstellt, daher passen Selektoren, die auf Ant Design-Klassennamen abzielen, wie .ant-btn oder .ant-input, nicht mehr auf irgendetwas. Öffnen Sie die Anmelde-, Registrierungs- und Passwort-vergessen-Seiten jeder angepassten Anwendung und passen Sie das CSS im Tab UI Customization der Anwendung an.
Geänderter Frontend-Code
Wenn Sie einen Fork mit Änderungen unter web/ pflegen, werden diese Änderungen nicht übernommen. Der v3-Code befindet sich in web-old/, sodass Sie Ihre alten Änderungen neben dem neuen Code lesen können, aber Casdoor baut und stellt nur web/ bereit. Übertragen Sie Ihre Änderungen in die TypeScript-Quellen in web/src.
Anwendungen, die Casdoor nutzen
Für Ihre Anwendungen ändert sich nichts. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP und die REST-API verhalten sich wie in v3, und die SDKs benötigen kein Update.
Rollback auf v3
- Stoppen Sie Casdoor.
- Stellen Sie die Datenbank-Sicherung wieder her.
- Starten Sie das v3-Image oder die Binary, die Sie vorher ausgeführt haben.
Hilfe erhalten
Wenn etwas in v3 funktioniert hat und in v4 nicht funktioniert, öffnen Sie ein Issue mit beiden Versionsnummern und Ihrem Datenbanktyp.