从 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 中发布。
| 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 |
选择 v4 版本
升级到 最新的 v4 版本。如果你固定了版本,请使用 v4.6.0 或更高版本。最初的几个 v4 版本存在回归问题,这些问题在后续版本中已修复:
| 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 还修复了 CVE-2026-5469、CVE-2026-9091、CVE-2026-9093、CVE-2026-9096、CVE-2026-9097 和 CVE-2026-9098。
准备升级
-
检查你运行的版本。参见 版本信息。
curl http://localhost:8000/api/get-version-info -
备份数据库。Casdoor 在 v4 启动时会添加表和列。备份是你回退到 v3 的途径。
-
如果您使用 CSS 或 HTML 自定义了登录页面,请对其进行截图,以便在升级后进行比较。
Upgrade Casdoor
保持相同的 app.conf 和相同的数据库。
Upgrade a Docker deployment
-
拉取新镜像:
docker pull casbin/casdoor:latest -
使用新镜像重启容器。
对于 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
- 停止 Casdoor。
- 恢复数据库备份。
- 启动之前运行的 v3 镜像或二进制文件。
Get help
如果某些功能在 v3 中正常而在 v4 中不正常,请提交 issue,并提供两个版本号和您的数据库类型。