Migracja z SuiteCRM 7.x do 8.x: kiedy przejść, co się zepsuje i jak się przygotować
Migracja z SuiteCRM 7 do SuiteCRM 8 nie jest aktualizacją wersji. To przeniesienie instancji do nowej architektury: Symfony na backendzie, Angular na froncie i dotychczasowy kod 7.x zamknięty w warstwie legacy. Dla jednych firm oznacza to kilka tygodni pracy, dla innych przepisanie customizacji budowanych latami. Seria SuiteCRM 7.15 ESR daje czas na decyzję, ale z niej nie zwalnia. Poniżej opisujemy, kiedy migracja ma sens, co najczęściej przestaje działać i jak przygotować projekt.
Czym migracja do SuiteCRM 8 różni się od zwykłej aktualizacji?
Migracja do SuiteCRM 8 wymaga nowej instalacji docelowej i dedykowanej paczki migracyjnej. Nie da się jej przeprowadzić przez Upgrade Wizard na istniejącej instancji SuiteCRM 7. Dokumentacja SuiteCRM wprost rozdziela dwa pojęcia. Upgrade odbywa się w obrębie 7.x i jest łatką nakładaną na istniejącą instalację. Migracja to zmiana głównej wersji na nowej instancji. Różnica ma praktyczne konsekwencje: wycofanie migracji oznacza odtworzenie kopii zapasowej, a nie odinstalowanie paczki.
SuiteCRM 8 dodaje warstwę aplikacyjną Symfony i interfejs oparty na Angularze. Kod SuiteCRM 7 trafia do katalogu public/legacy i działa jako warstwa legacy wewnątrz nowej aplikacji. Dane i większość logiki biznesowej przechodzą bez zmian. Problem dotyczy wszystkiego, co zależało od sposobu renderowania widoków w SuiteCRM 7: własnych klas widoków, skryptów JavaScript i szablonów Smarty. Nowy frontend po prostu ich nie wywołuje.
Technicznie migracja SuiteCRM 7 do 8 przebiega według stałego schematu. Najpierw rozpakowuje się paczkę migracyjną (nazwa według wzorca SuiteCRM-8.x-7.x-migration). Następnie kopiuje się instancję SuiteCRM 7 do katalogu public/ i zmienia jej nazwę na legacy. Potem uruchamia się trzy komendy CLI:
- ./bin/console suitecrm:app:setup-legacy-migration
- ./bin/console suitecrm:app:upgrade -t <wersja>
- ./bin/console suitecrm:app:upgrade-finalize
Od wersji 8.7 (Symfony 6.4) przed uruchomieniem skryptów trzeba dodatkowo ręcznie podmienić katalogi vendor i include oraz plik deprecated.php wersjami z paczki.
Kiedy warto przejść na SuiteCRM 8, a kiedy zostać na SuiteCRM 7.15 ESR?
Pozostanie na SuiteCRM 7.15 ESR jest w 2026 roku decyzją racjonalną, a nie zaniedbaniem, pod warunkiem że to świadomy wybór z planowaną datą końcową. SalesAgility zapowiedziało, że wydanie 7.15 jako Extended Support Release wydłuża życie serii 7.x o co najmniej dwa lata i dodaje wsparcie PHP do wersji 8.4. Obie linie są aktywnie rozwijane: 31 lipca 2026 roku ukazały się równolegle SuiteCRM 7.15.2 i SuiteCRM 8.10.2.
Za migracją do SuiteCRM 8 przemawia kierunek rozwoju platformy. Nowe mechanizmy rozszerzeń (front-end extensions, Process API, save handlery, zadania asynchroniczne) istnieją wyłącznie w linii 8.x. Każda nowa customizacja budowana dziś w SuiteCRM 7 zwiększa przyszły koszt przejścia. Po drugiej stronie wagi leży cykl wydań. Wersje minor SuiteCRM 8 mają krótkie okna wsparcia: aktywne wsparcie dla 8.6 trwało od kwietnia do lipca 2024 roku. Przejście na 8.x oznacza więc regularne aktualizacje.
Jednego scenariusza nie rekomendujemy w żadnym wariancie: pozostawania na niewspieranych wersjach 7.10, 7.11 czy 7.12. Przykładem ryzyka jest podatność CVE-2024-36411 z oceną CVSS 9.6 (Critical, 2024), czyli SQL Injection w kontrolerze EmailUIAjax. Poprawiono ją dopiero w wersjach 7.14.4 i 8.6.1. Starsze wydania nie otrzymały poprawki.
| Kryterium | Raczej migrować teraz | Raczej zostać na 7.15 ESR |
| Customizacje UI (widoki, JS, Smarty) | Nieliczne lub brak | Liczne i krytyczne dla procesu sprzedaży lub obsługi |
| Wtyczki firm trzecich | Dostawcy mają wersje dla 8.x | Kluczowe wtyczki nie mają wersji dla 8.x |
| Serwer | Linux, Apache 2.4, PHP 8.2+ | Windows Server / IIS bez możliwości zmiany stosu |
| Zasoby IT | Zespół gotowy na regularne aktualizacje minor 8.x | Brak zasobów na częste aktualizacje |
| Plany rozwoju systemu | Nowe moduły i integracje w najbliższym roku | System stabilny, zmiany minimalne |
| Horyzont | Chęć uniknięcia migracji pod presją końca wsparcia 7.x | Planowana zmiana platformy CRM w ciągu 2 lat |
Najdroższy scenariusz, jaki widzimy w projektach, to migracja odkładana do ostatnich miesięcy wsparcia SuiteCRM 7. Wtedy audyt, testy i przepisywanie customizacji odbywają się pod presją czasu, a decyzje o tym, co porzucić, zapadają bez analizy.
Co przestanie działać po migracji z SuiteCRM 7 do 8?
Najbardziej narażone są customizacje warstwy prezentacji. Chodzi o własne klasy widoków (view.detail.php, view.edit.php), modyfikacje JavaScript, szablony Smarty oraz logic hooki ingerujące w wyświetlanie, takie jak process_record. Logika backendowa, czyli hooki before_save i after_save, Workflow i vardefy, zwykle przechodzi, bo działa w warstwie legacy. Zgłoszenia na forum społeczności SuiteCRM potwierdzają ten wzorzec. Hook process_record wyświetla w SuiteCRM 8 surowy kod HTML, a view.detail.php przestaje być wywoływany.
| Obszar | Ryzyko | Co sprawdzić przed migracją |
| Własne widoki (custom/modules/*/views) | Wysokie | Nowy interfejs ich nie renderuje. Opcje: tryb legacy modułu w module_routing.yaml albo przepisanie na front-end extension |
| Logic hooki UI (np. process_record) | Wysokie | Lista hooków ingerujących w listy i widoki. Do przepisania lub do trybu legacy |
| Logic hooki backendowe (before_save, after_save) | Niskie–średnie | Zgodność kodu z PHP 8.2+ (minimum w aktualnej matrycy SuiteCRM 8) |
| Metadane widoków (custom/modules/*/metadata) | Średnie | Wybór trybu scalania metadanych. Tryb nadpisania usuwa pliki customizacji |
| Pliki spoza core w public/legacy | Średnie | Inwentaryzacja plików dodanych poza custom/. Proces migracji może je usunąć |
| Wtyczki firm trzecich | Wysokie | Potwierdzenie u dostawcy, że istnieje wersja dla SuiteCRM 8 |
| Modyfikacje motywu SuiteP i CSS | Wysokie | Zmiany w motywie SuiteCRM 7 nie przenoszą się na interfejs SuiteCRM 8 |
| Integracje i adresy URL | Średnie | Nowa struktura katalogów, site_url i RewriteBase. Test wszystkich integracji na stagingu |
Tryb legacy dla modułu to obejście, a nie rozwiązanie docelowe. Ustawienie modułu w module_routing.yaml sprawia, że wyświetla się on w starym interfejsie osadzonym w nowym. Pozwala to przeprowadzić migrację SuiteCRM 7 do 8 bez blokowania projektu przez kilka problematycznych modułów. Użytkownicy pracują jednak wtedy w dwóch interfejsach naraz, a dług techniczny tylko zmienia adres.
Jakie wymagania infrastrukturalne stawia SuiteCRM 8?
Aktualna matryca kompatybilności SuiteCRM 8 obejmuje PHP 8.2, 8.3 i 8.4, serwer Apache 2.4, MariaDB 10.6, 10.11, 11.4 i 11.8 oraz MySQL 8.0 i 8.4. Platformy to Linux, Unix i macOS. Od wersji 8.7 SuiteCRM nie działa na PHP 7.4. Najczęściej przeoczana zmiana dotyczy jednak Windows: matryca SuiteCRM 7.14 obejmowała Windows Server 2019+ i IIS 10, a aktualna matryca SuiteCRM 8 ich nie wymienia.
| Element | SuiteCRM 7.14.x | SuiteCRM 8 (aktualna matryca) |
| Platforma | Linux, Unix, macOS, Windows Server 2019+ | Linux, Unix, macOS |
| Serwer WWW | Apache 2.4, IIS 10 | Apache 2.4 |
| PHP | 8.1, 8.2 (w 7.15 ESR do 8.4) | 8.2, 8.3, 8.4 |
| MariaDB | 10.4, 10.5, 10.6, 10.10, 10.11 | 10.6, 10.11, 11.4, 11.8 |
| MySQL | według matrycy 7.x | 8.0, 8.4 (MySQL 5.7 był jeszcze wspierany w 8.8) |
| Node.js / Angular CLI | nie dotyczy | Tylko do budowy front-end extensions, niewymagane na produkcji |
Dla instancji działających na Windows i IIS migracja do SuiteCRM 8 oznacza więc w praktyce dwa projekty: zmianę serwera i zmianę wersji CRM. Warto je rozdzielić w czasie. Najpierw przenosi się SuiteCRM 7.15 na Linux i Apache, potem przeprowadza migrację do SuiteCRM 8. Każdy problem da się wtedy przypisać do jednej zmiany.
Jak przygotować się do migracji SuiteCRM 7 do 8 krok po kroku?
Przygotowanie do migracji SuiteCRM 7 do 8 zaczyna się od inwentaryzacji, a nie od pobrania paczki. Poniższa sekwencja to schemat, który stosujemy w projektach migracyjnych. Kroki 1–3 można wykonać na długo przed decyzją o terminie migracji.
- Inwentaryzacja customizacji. Należy spisać zawartość custom/, moduły z Module Buildera, wszystkie logic hooki, pliki dodane poza custom/ oraz zainstalowane wtyczki. Każdy element trzeba sklasyfikować: backend (zwykle przechodzi) czy UI (wymaga decyzji).
- Aktualizacja SuiteCRM 7 do wymaganej wersji. Dokumentacja migracji wymaga najnowszego wydania 7.14.x. Dla linii 7.15 SuiteCRM udostępnia paczkę „8.10.2 Migrate from 7.15.x”. Po drodze trzeba wykonać manualne kroki z release notes każdej wersji.
- Środowisko zgodne z matrycą. Obejmuje to PHP 8.2+, Apache 2.4 i wspieraną wersję bazy danych. Trzeba też sprawdzić, czy kod customizacji działa na minimalnej wersji PHP z matrycy.
- Kopia zapasowa plików instancji i bazy danych.
- Próbna migracja na stagingu. W pliku .env.local należy ustawić APP_ENV=prod. Komendy warto uruchamiać z flagą -vvv (pełne raportowanie błędów E_ALL). Trzeba też świadomie wybrać tryb scalania metadanych widoków.
- Porządki po komendach. Należy przywrócić uprawnienia plików dla użytkownika serwera WWW. Przy błędzie „Invalid CSRF token” wystarczy wyczyścić ciasteczka przeglądarki.
- Testy procesowe. Testować należy pełne scenariusze (lead → szansa → oferta, obsługa zgłoszenia), integracje, raporty, Workflow i harmonogramy. Logi znajdują się w public/legacy/upgradeWizard.log i public/legacy/suitecrm.log.
- Decyzja per moduł i go-live. Każdy moduł trafia do jednej z trzech kategorii: natywny interfejs SuiteCRM 8, tymczasowy tryb legacy albo przepisanie. Ostatnim elementem jest plan regularnych aktualizacji minor 8.x po wdrożeniu.
Listę rozszerzeń SuiteCRM od eVolpe znajdziesz w sklepie eVolpe.
Tryby scalania metadanych to decyzja, której nie warto zostawiać domyślnej konfiguracji bez zrozumienia. Tryb domyślny zachowuje istniejące customizacje metadanych i pomija scalanie. Tryb merge próbuje połączyć customizacje z nowymi metadanymi core i tworzy kopię zapasową. Tryb override zastępuje customizacje metadanymi core i usuwa pliki w public/legacy/custom/<Module>/metadata.
Jak może wyglądać migracja SuiteCRM 7 do 8 w praktyce?
Scenariusz hipotetyczny. Firma dystrybucyjna ma 60 użytkowników SuiteCRM 7.14 na Windows Server z IIS. Instancja zawiera 14 logic hooków (w tym 3 typu process_record), 2 moduły z Module Buildera, własny widok szczegółów szansy sprzedaży (Opportunities) oraz 3 wtyczki firm trzecich. Liczby i harmonogram w tej sekcji są ilustracyjne. Nie opisują konkretnego wdrożenia eVolpe.
Audyt w tym scenariuszu daje jasny podział:
- 11 hooków backendowych przechodzi do SuiteCRM 8 po weryfikacji zgodności z PHP 8.2.
- 3 hooki process_record i własny widok Opportunities trafiają na start do trybu legacy. Ich przepisanie na front-end extensions zaplanowano w drugiej fazie.
- Jedna z trzech wtyczek nie ma wersji dla SuiteCRM 8. Jej funkcję przejmuje natywny moduł Workflow.
- Infrastruktura: wymiana serwera na Linux z Apache to osobny etap, wykonany przed migracją.
Harmonogram fazy pierwszej w takim scenariuszu może wyglądać następująco:
| Etap | Szacowany czas |
| Audyt | 2 tygodnie |
| Zmiana serwera na SuiteCRM 7.15 | 2 tygodnie |
| Próbna migracja i poprawki | 3 tygodnie |
| Testy akceptacyjne z użytkownikami | 2 tygodnie |
Kluczowy wniosek ze scenariusza: o koszcie migracji SuiteCRM 7 do 8 nie decyduje liczba użytkowników ani rekordów, tylko liczba customizacji warstwy UI i wtyczek bez wersji dla 8.x. Firma z 300 użytkownikami i czystą instancją może migrować szybciej niż firma z 30 użytkownikami i rozbudowanymi widokami.
Jakie błędy najczęściej popełnia się przy migracji SuiteCRM 7 do 8?
Najczęstszy błąd to potraktowanie migracji jak upgrade’u: bez audytu, bez stagingu, z założeniem, że „wszystko przejdzie”. Pozostałe błędy wynikają zwykle z pośpiechu lub niewiedzy o różnicach architektonicznych:
- Migracja z nieaktualnej wersji 7.x. Pominięcie kroku aktualizacji do wymaganej wersji 7.x i manualnych kroków z release notes.
- Zła paczka. Użycie paczki instalacyjnej SuiteCRM 8 zamiast migracyjnej. Objawem jest brak komendy suitecrm:app:setup-legacy-migration.
- Tryb override „żeby było czysto”. Wybór nadpisania metadanych bez kopii customizacji usuwa układy widoków budowane latami.
- Założenie, że wtyczki przejdą bez zmian. Przykładem jest wtyczka Security Suite, niekompatybilna z SuiteCRM 8.x. Bez wersji od dostawcy wtyczka to element do zastąpienia, nie do przeniesienia.
- Tryb legacy jako stan docelowy. Moduły „tymczasowo” w legacy po dwóch latach wciąż blokują korzyści z nowego interfejsu.
- Brak planu na cykl wydań SuiteCRM 8. API front-end extensions zmieniało się między wersjami: dokumentacja zawiera osobne przewodniki migracji rozszerzeń do 8.5+ i 8.8+. Każde rozszerzenie trzeba więc testować przy aktualizacjach minor.
- Komendy jako root bez przywrócenia uprawnień. Serwer WWW traci dostęp zapisu do nowo utworzonych plików.
Podsumowanie
Migracja z SuiteCRM 7 do 8 to projekt architektoniczny, którego koszt wyznacza liczba customizacji UI i wtyczek, a nie wielkość bazy. SuiteCRM 7.15 ESR daje czas, ale ten czas warto wykorzystać na inwentaryzację, nie na odkładanie decyzji. Audyt customizacji można przeprowadzić w tym kwartale, niezależnie od terminu migracji, i od niego zależy realny budżet całego przejścia.
Ile customizacji w Waszej instancji SuiteCRM 7 dotyka warstwy wyświetlania? Czy ktoś w zespole potrafi dziś odpowiedzieć na to pytanie bez otwierania katalogu custom/?
Jeśli zainteresował Cię ten temat, skontaktuj się z nami. Chętnie odpowiemy na twoje pytania.
Najczęściej zadawane pytania
Nie. Przejście z SuiteCRM 7 na 8 to migracja: wymaga nowej instalacji docelowej, dedykowanej paczki migracyjnej i komend CLI uruchamianych na instancji SuiteCRM 8. Upgrade Wizard obsługuje wyłącznie aktualizacje w obrębie linii 7.x.
SalesAgility zapowiedziało, że wydanie SuiteCRM 7.15 ESR przedłuża życie serii 7.x o co najmniej dwa lata. Aktualne daty wsparcia aktywnego i bezpieczeństwa publikowane są na stronie Supported Versions w dokumentacji SuiteCRM.
Hooki backendowe, takie jak before_save i after_save, zwykle działają, bo wykonują się w warstwie legacy. Problemy dotyczą hooków ingerujących w wyświetlanie, zwłaszcza process_record. Każdy hook trzeba przetestować na stagingu i sprawdzić zgodność z PHP 8.2+.
Aktualna matryca kompatybilności SuiteCRM 8 wymienia tylko Linux, Unix i macOS z serwerem Apache 2.4. Windows Server i IIS, wspierane w SuiteCRM 7.14, nie figurują na liście. Instancje na Windows wymagają zmiany serwera przed migracją.
Tak. Kod i dane SuiteCRM 7 są przenoszone do struktury SuiteCRM 8 i stają się warstwą legacy. Przed migracją obowiązkowa jest jednak pełna kopia zapasowa plików i bazy, bo wycofanie migracji oznacza odtworzenie backupu.
Dokumentacja migracji wymaga najnowszego wydania 7.14.x. Dla linii 7.15 SuiteCRM udostępnia osobną paczkę, np. „8.10.2 Migrate from 7.15.x”. Starsze wersje (7.10–7.13) trzeba najpierw zaktualizować w obrębie linii 7.x.
Tryb legacy, ustawiany w pliku module_routing.yaml wyświetla moduł w interfejsie SuiteCRM 7 osadzonym w SuiteCRM 8. Pozwala zachować działanie starych widoków i hooków UI, ale jest rozwiązaniem przejściowym, nie docelowym.
Źródła
- SuiteCRM Documentation – Migration (Upgrading vs migrating): https://docs.suitecrm.com/admin/migration/
- SuiteCRM Documentation – Moving to SuiteCRM 8: https://docs.suitecrm.com/admin/migration/to-suitecrm-8/
- SuiteCRM Documentation – Running the Migration (8.7.0+): https://docs.suitecrm.com/8.x/admin/migration/running-the-migration/
- SuiteCRM Documentation – Compatibility Matrix 8.x: https://docs.suitecrm.com/8.x/admin/compatibility-matrix/
- SuiteCRM – Extended Support for SuiteCRM 7.x: https://suitecrm.com/extended-support-for-suitecrm-7-x/
- SuiteCRM – Releases: https://suitecrm.com/releases/
- OSV – CVE-2024-36411: https://osv.dev/vulnerability/CVE-2024-3641



