Оновлення з v3 до v4
Цей посібник пояснює, як оновити розгортання Casdoor v3 до v4 та що перевірити після оновлення.
Результати навчання
- Зрозуміти, що змінилося між v3 та v4.
- Вибрати реліз v4.
- Оновити розгортання Docker, Helm або з вихідного коду.
- Перевірити частини вашої системи, на які впливає новий фронтенд.
- Повернутися до v3, якщо це необхідно.
Необхідне для початку
- Розгортання Casdoor v3
- Спосіб резервного копіювання та відновлення бази даних
Про v4
Casdoor v4.0.0 був випущений 1 вересня 2026 року. Він замінює адмін-консоль та сторінки входу новим фронтендом. Бекенд, 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, зробіть скріншот, щоб порівняти вигляд сторінки після оновлення.
Оновлення Casdoor
Залиште той самий app.conf і ту саму базу даних.
Оновлення розгортання Docker
-
Завантажте новий образ:
docker pull casbin/casdoor:latest -
Перезапустіть контейнер з новим образом.
У Docker Compose оновіть image: і виконайте docker compose up -d. У Helm встановіть новий тег образу та виконайте helm upgrade.
Оновлення розгортання з вихідного коду
Отримайте код, перебудуйте фронтенд і перезапустіть сервер. Команди такі ж, як у v3. Node.js 20 та Yarn 1.x залишаються обов'язковими версіями.
git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor
Під час розробки yarn start все ще обслуговує фронтенд на порту 7001.
Перевірте результат
Шляхи до статичних файлів
Хешовані файли .js та .css переміщено з web/build/static/js та web/build/static/css до web/build/assets. Оновіть усе, що посилається на старі шляхи:
- Правила реверс-проксі: Правила, які кешують або переписують
/static/js/або/static/css/, мають використовувати/assets/. - CDN: Якщо CDN розміщує файли фронтенду, запустіть скрипт завантаження знову після збірки v4. Див. Розміщення файлів фронтенду на CDN.
Налаштування сторінки входу
Casdoor v4 застосовує власний HTML, елементи входу та налаштування теми для додатків так само, як і раніше.
Перегляньте ваш власний CSS. Сторінки більше не будуються на компонентах Ant Design, тому селектори, що вказують на класи Ant Design, такі як .ant-btn або .ant-input, більше нічого не знаходять. Відкрийте сторінки входу, реєстрації та відновлення пароля для кожного налаштованого додатка та скоригуйте CSS на вкладці UI Customization додатка.
Модифікований код фронтенду
Якщо ви підтримуєте форк зі змінами в web/, ці зміни не перенесуться автоматично. Код v3 знаходиться в web-old/, щоб ви могли переглядати свої старі зміни поруч із новим кодом, але Casdoor збирає та обслуговує лише web/. Перенесіть ваші зміни в TypeScript-вихідні файли в web/src.
Додатки, що використовують Casdoor
Для ваших додатків нічого не змінюється. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP та REST API працюють так само, як у v3, а SDK не потребують оновлення.
Повернення до v3
- Зупиніть Casdoor.
- Відновіть резервну копію бази даних.
- Запустіть образ або бінарний файл v3, який ви використовували раніше.
Отримати допомогу
Якщо щось працювало у v3, але не працює у v4, створіть issue з обома номерами версій та типом вашої бази даних.