Actualización de v3 a v4
Esta guía explica cómo actualizar una implementación de Casdoor v3 a v4 y qué verificar después de la actualización.
Resultados del aprendizaje
- Entender qué cambió entre v3 y v4.
- Elegir una versión de v4.
- Actualizar una implementación de Docker, Helm o código fuente.
- Verificar las partes de su configuración que afectan al nuevo frontend.
- Volver a v3 si es necesario.
Lo que necesita
- Una implementación de Casdoor v3
- Una forma de hacer copias de seguridad y restaurar su base de datos
Acerca de v4
Casdoor v4.0.0 fue lanzado el 1 de septiembre de 2026. Reemplaza la consola de administración y las páginas de inicio de sesión con un nuevo frontend. El backend, la API REST, la base de datos y conf/app.conf son compatibles con v3. La mayoría de las implementaciones se actualizan cambiando la etiqueta de la imagen o reconstruyendo desde el código fuente.
v3.164.0 es la última versión de v3. Las correcciones de errores y de seguridad se publican solo en 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 |
Elige una versión de v4
Actualiza a la última versión de v4. Si fijas una versión, usa v4.6.0 o posterior. Las primeras versiones de v4 tenían regresiones, que se corrigen en las siguientes versiones:
| 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 también corrige CVE-2026-5469, CVE-2026-9091, CVE-2026-9093, CVE-2026-9096, CVE-2026-9097 y CVE-2026-9098.
Prepara la actualización
-
Comprueba la versión que ejecutas. Consulta Información de versión.
curl http://localhost:8000/api/get-version-info -
Haz una copia de seguridad de la base de datos. Casdoor añade tablas y columnas cuando inicia v4. La copia de seguridad es tu forma de volver a v3.
-
Si personalizaste una página de inicio de sesión con CSS o HTML, toma una captura de pantalla para poder comparar la página después de la actualización.
Actualiza Casdoor
Mantén el mismo app.conf y la misma base de datos.
Actualiza una implementación con Docker
-
Extrae la nueva imagen:
docker pull casbin/casdoor:latest -
Reinicia el contenedor con la nueva imagen.
Con Docker Compose, actualiza image: y ejecuta docker compose up -d. Con Helm, establece la nueva etiqueta de imagen y ejecuta helm upgrade.
Actualiza una implementación desde código fuente
Extrae el código, recompila el frontend y reinicia el servidor. Los comandos son los mismos que en v3. Node.js 20 y Yarn 1.x siguen siendo las versiones requeridas.
git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor
En desarrollo, yarn start sigue sirviendo el frontend en el puerto 7001.
Comprueba el resultado
Rutas de archivos estáticos
Los archivos .js y .css con hash se movieron de web/build/static/js y web/build/static/css a web/build/assets. Actualiza todo lo que haga referencia a las rutas antiguas:
- Reglas de proxy inverso: Las reglas que almacenan en caché o reescriben
/static/js/o/static/css/deben usar/assets/en su lugar. - CDN: Si una CDN aloja los archivos del frontend, ejecuta el script de carga de nuevo después de compilar v4. Consulta Alojar los archivos del frontend en una CDN.
Personalización de la página de inicio de sesión
Casdoor v4 aplica el HTML personalizado, los elementos de inicio de sesión y la configuración del tema de una aplicación como antes.
Revisa tu CSS personalizado. Las páginas ya no están construidas con componentes de Ant Design, por lo que los selectores que apuntan a nombres de clase de Ant Design, como .ant-btn o .ant-input, ya no coinciden con nada. Abre las páginas de inicio de sesión, registro y recuperación de contraseña de cada aplicación personalizada y ajusta el CSS en la pestaña UI Customization de la aplicación.
Código frontend modificado
Si mantienes un fork con cambios bajo web/, esos cambios no se conservan. El código de v3 está en web-old/, para que puedas leer tus antiguos cambios junto al nuevo código, pero Casdoor compila y sirve solo web/. Migra tus cambios a los fuentes de TypeScript en web/src.
Aplicaciones que usan Casdoor
No cambia nada para tus aplicaciones. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP y la REST API se comportan igual que en v3, y los SDKs no necesitan una actualización.
Volver a v3
- Detenga Casdoor.
- Restaurar la copia de seguridad de la base de datos.
- Inicie la imagen o el binario v3 que ejecutaba antes.
Obtener ayuda
Si algo funcionaba en v3 y no funciona en v4, abra un issue con ambos números de versión y su tipo de base de datos.