Pular para o conteúdo principal

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.

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

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:

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

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​

  1. Verifique a versão que você está executando. Veja Informações sobre versões.

    curl http://localhost:8000/api/get-version-info
  2. 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.

  3. 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​

  1. Baixe a nova imagem:

    docker pull casbin/casdoor:latest
  2. 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​

  1. Pare o Casdoor.
  2. Restaure o backup do banco de dados.
  3. 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.

Veja também​