Atualização da v3 para a v4
Este guia explica como atualizar uma implantação do Casdoor v3 para a v4 e o que verificar após a atualização.
Resultados de aprendizagem
- Entenda o que mudou entre a v3 e a v4.
- Escolha uma versão da v4.
- Atualize uma implantação Docker, Helm ou por código-fonte.
- Verifique as partes da sua configuração que são afetadas pelo novo frontend.
- Volte para a v3 se necessário.
O que você precisa
- Uma implantação do Casdoor v3
- Uma maneira de fazer backup e restaurar seu banco de dados
Sobre a v4
O Casdoor v4.0.0 foi lançado em 1º de setembro de 2026. Ele substitui o console de administração e as páginas de login por um novo frontend. O backend, a REST API, o banco de dados e o conf/app.conf são compatíveis com a v3. A maioria das implantações é atualizada trocando a tag da imagem ou reconstruindo a partir do código-fonte.
A v3.164.0 é a última versão da v3. Correções de bugs e correções de segurança são publicadas apenas na 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 |
Escolher uma versão da v4
Atualize para a última versão da v4. Se você fixar uma versão, use a v4.6.0 ou posterior. As primeiras versões da v4 tinham regressões, que foram corrigidas nas seguintes versões:
| 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 |
A v4.5.0 também corrige CVE-2026-5469, CVE-2026-9091, CVE-2026-9093, CVE-2026-9096, CVE-2026-9097 e CVE-2026-9098.
Preparar a atualização
-
Verifique a versão que você está executando. Veja Informações sobre versões.
curl http://localhost:8000/api/get-version-info -
Faça backup do banco de dados. O Casdoor adiciona tabelas e colunas quando a v4 inicia. O backup é sua forma de voltar para a v3.
-
Se você personalizou uma página de login com CSS ou HTML, tire uma captura de tela dela, para que você possa comparar a página após a atualização.
Atualizar o Casdoor
Mantenha o mesmo app.conf e o mesmo banco de dados.
Atualizar uma implantação Docker
-
Baixe a nova imagem:
docker pull casbin/casdoor:latest -
Reinicie o container com a nova imagem.
Com Docker Compose, atualize image: e execute docker compose up -d. Com Helm, defina a nova tag da imagem e execute helm upgrade.
Atualizar uma implantação de código-fonte
Baixe o código, reconstrua o frontend e reinicie o servidor. Os comandos são os mesmos da v3. Node.js 20 e Yarn 1.x ainda são as versões obrigatórias.
git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor
Em desenvolvimento, yarn start ainda serve o frontend na porta 7001.
Verificar o resultado
Caminhos de arquivos estáticos
Os arquivos .js e .css com hash foram movidos de web/build/static/js e web/build/static/css para web/build/assets. Atualize tudo que se refere aos caminhos antigos:
- Regras de proxy reverso: Regras que fazem cache ou reescrevem
/static/js/ou/static/css/devem usar/assets/em vez disso. - CDN: Se um CDN hospeda os arquivos do frontend, execute o script de upload novamente após compilar a v4. Consulte Hospedar os arquivos do frontend em um CDN.
Personalização da página de login
O Casdoor v4 aplica o HTML personalizado, os itens de login e as configurações de tema de uma aplicação como antes.
Revise seu CSS personalizado. As páginas não são mais construídas a partir de componentes Ant Design, portanto seletores que visam nomes de classes do Ant Design, como .ant-btn ou .ant-input, não correspondem a nada. Abra as páginas de login, cadastro e recuperação de senha de cada aplicação personalizada e ajuste o CSS na aba UI Customization da aplicação.
Código de frontend modificado
Se você mantém um fork com alterações em web/, essas alterações não serão mantidas. O código da v3 está em web-old/, para que você possa ler suas alterações antigas ao lado do novo código, mas o Casdoor compila e serve apenas web/. Transfira suas alterações para os códigos-fonte TypeScript em web/src.
Aplicações que usam o Casdoor
Nada muda para suas aplicações. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP e a API REST funcionam como na v3, e os SDKs não precisam de atualização.
Voltar para a v3
- Pare o Casdoor.
- Restaure o backup do banco de dados.
- Inicie a imagem ou binário da v3 que você executava antes.
Obter ajuda
Se algo funcionava na v3 e não funciona na v4, abra uma issue com ambos os números de versão e o tipo do seu banco de dados.