跳到主内容

从 v3 升级到 v4

本指南说明如何将 Casdoor v3 部署升级到 v4,以及升级后需要检查什么。


学习目标​

  • 了解 v3 和 v4 之间发生了什么变化。
  • 选择一个 v4 版本。
  • 升级 Docker、Helm 或源码部署。
  • 检查新前端会影响的设置部分。
  • 如有必要,回退到 v3。

前提条件​

  • 一个 Casdoor v3 部署
  • 一种备份和恢复其数据库的方法

关于 v4​

Casdoor v4.0.0 于 2026 年 9 月 1 日发布。它用一个新的前端替换了管理控制台和登录页面。后端、REST API、数据库和 conf/app.conf 与 v3 兼容。大多数部署可以通过切换镜像标签或通过源码重新构建来升级。

v3.164.0 是最后一个 v3 版本。错误修复和安全修复仅在 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

选择 v4 版本​

升级到 最新的 v4 版本。如果你固定了版本,请使用 v4.6.0 或更高版本。最初的几个 v4 版本存在回归问题,这些问题在后续版本中已修复:

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 还修复了 CVE-2026-5469、CVE-2026-9091、CVE-2026-9093、CVE-2026-9096、CVE-2026-9097 和 CVE-2026-9098。

准备升级​

  1. 检查你运行的版本。参见 版本信息。

    curl http://localhost:8000/api/get-version-info
  2. 备份数据库。Casdoor 在 v4 启动时会添加表和列。备份是你回退到 v3 的途径。

  3. 如果您使用 CSS 或 HTML 自定义了登录页面,请对其进行截图,以便在升级后进行比较。

Upgrade Casdoor​

保持相同的 app.conf 和相同的数据库。

Upgrade a Docker deployment​

  1. 拉取新镜像:

    docker pull casbin/casdoor:latest
  2. 使用新镜像重启容器。

对于 Docker Compose,更新 image: 并运行 docker compose up -d。对于 Helm,设置新的镜像标签并运行 helm upgrade。

Upgrade a source deployment​

拉取代码,重新构建前端,并重启服务器。命令与 v3 相同。Node.js 20 和 Yarn 1.x 仍然是所需的版本。

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

在开发环境中,yarn start 仍然在端口 7001 上提供前端服务。

Check the result​

Static file paths​

带哈希值的 .js 和 .css 文件已从 web/build/static/js 和 web/build/static/css 移动到 web/build/assets。更新所有引用旧路径的内容:

  • Reverse proxy rules:缓存或重写 /static/js/ 或 /static/css/ 的规则必须改用 /assets/。
  • CDN:如果 CDN 托管前端文件,请在构建 v4 后再次运行上传脚本。参见 Host the frontend files on a CDN。

Sign-in page customization​

Casdoor v4 像以前一样应用自定义 HTML、登录项和主题设置。

检查您的自定义 CSS。页面不再由 Ant Design 组件构建,因此针对 Ant Design 类名的选择器(如 .ant-btn 或 .ant-input)将不再匹配任何内容。打开每个自定义应用的登录、注册和忘记密码页面,并在应用的 UI Customization 选项卡中调整 CSS。

Modified frontend code​

如果您维护了一个包含 web/ 下更改的 fork,这些更改不会自动迁移。v3 代码位于 web-old/ 中,以便您可以对照新代码查看旧的更改,但 Casdoor 仅构建和服务 web/。请将您的更改移植到 web/src 中的 TypeScript 源代码。

Applications that use Casdoor​

您的应用没有任何变化。OAuth 2.0、OpenID Connect (OIDC)、SAML、CAS、LDAP 和 REST API 的行为与 v3 相同,SDK 也不需要更新。

Roll back to v3​

  1. 停止 Casdoor。
  2. 恢复数据库备份。
  3. 启动之前运行的 v3 镜像或二进制文件。

Get help​

如果某些功能在 v3 中正常而在 v4 中不正常,请提交 issue,并提供两个版本号和您的数据库类型。

另请参阅​