Перейти до основного вмісту

Оновлення з 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.

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, зробіть скріншот, щоб порівняти вигляд сторінки після оновлення.

Оновлення Casdoor​

Залиште той самий app.conf і ту саму базу даних.

Оновлення розгортання Docker​

  1. Завантажте новий образ:

    docker pull casbin/casdoor:latest
  2. Перезапустіть контейнер з новим образом.

У 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​

  1. Зупиніть Casdoor.
  2. Відновіть резервну копію бази даних.
  3. Запустіть образ або бінарний файл v3, який ви використовували раніше.

Отримати допомогу​

Якщо щось працювало у v3, але не працює у v4, створіть issue з обома номерами версій та типом вашої бази даних.

Див. також​