CONVIRO
Engineering

Instalacja modułu Magento 2 przez Composer: instrukcja krok po kroku

Praktyczny przewodnik po instalacji modułu Magento 2 przez Composer: prywatne repozytoria, auth.json, setup:upgrade, kroki w trybie produkcyjnym, aktualizacje, odinstalowanie i…

Conviro
19 listopada 20267 min czytania
Instalacja modułu Magento 2 przez Composer: instrukcja krok po kroku
W tym artykule

Instalacja modułu Magento 2 przez Composer wygląda tak: dodajesz repozytorium dostawcy (a jeśli jest prywatne, także dane uwierzytelniające), uruchamiasz composer require, włączasz moduł, uruchamiasz bin/magento setup:upgrade, kompilujesz kod i wdrażasz pliki statyczne, jeśli sklep działa w trybie produkcyjnym, a na koniec czyścisz cache. To tylko kilka poleceń, ale kolejność i tryb wdrożenia mają znaczenie.

Ten przewodnik przeprowadza przez całą sekwencję na przykładzie darmowego modułu Conviro for Magento, a potem omawia aktualizację, odinstalowanie i błędy, na które najprawdopodobniej trafisz.

Najważniejsze wnioski

  • Każde polecenie uruchamiaj z katalogu głównego Magento jako właściciel plików, po wykonaniu kopii zapasowej i najpierw na stagingu.
  • W trybie deweloperskim wystarczą setup:upgrade i wyczyszczenie cache; tryb produkcyjny wymaga też kompilacji i wdrożenia plików statycznych.
  • Odinstalowuj w odwrotnej kolejności: najpierw rozłącz integrację, potem wyłącz moduł, usuń pakiet i uruchom setup:upgrade.

Zanim zaczniesz: wymagania

Sprawdź te punkty, zanim dotkniesz produkcji:

  • Dostęp SSH i Composer na serwerze. Instalacji przez Composer nie da się przeprowadzić z panelu administracyjnego.
  • Świeża kopia zapasowa kodu i bazy danych, a najlepiej także kopia testowa (staging), na której możesz testować.
  • Właściwy użytkownik. Uruchamiaj polecenia jako właściciel plików, a nie jako root, inaczej narobisz sobie problemów z uprawnieniami.
  • Twój tryb wdrożenia. Sprawdzisz go poleceniem bin/magento deploy:mode:show.
  • Okno serwisowe na produkcji: bin/magento maintenance:enable przed instalacją, bin/magento maintenance:disable po niej.

W przypadku modułu Conviro potrzebujesz też Magento Open Source 2.4.4 lub nowszego z PHP 7.4 lub 8.1–8.4, adresu sklepu z HTTPS, działającego crona Magento i wychodzącego ruchu HTTPS do api.conviro.io. Instalację modułu (w chwili pisania w wersji 1.4.1) przetestowano na:

Magento PHP Motyw
2.4.4-p13 8.1 Luma
2.4.7-p4 8.3 Luma
2.4.9 8.4 Luma i Hyvä 1.5.2

Adobe Commerce działa na tym samym frameworku, ale nie zostało jeszcze przetestowane, Hyvä Checkout nie był testowany, a sklepy na wersjach 2.4.0–2.4.3 pozostają przy wersji modułu 1.3.5.

Instalacja modułu Magento 2 przez Composer krok po kroku

Krok 1: dodaj repozytorium Composera i dane uwierzytelniające

Prywatne moduły są udostępniane z własnego repozytorium Composera dostawcy. W katalogu głównym Magento:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <CONVIRO_API_KEY>

Pierwsze polecenie dodaje repozytorium do pliku composer.json. Drugie zapisuje dane uwierzytelniające w pliku auth.json obok niego. W przypadku Conviro nazwa użytkownika to api, a hasłem jest klucz API z sekcji Developers → API Keys w panelu Conviro. Więcej o API Conviro znajdziesz na stronie dla deweloperów.

Nie dodawaj pliku auth.json do systemu kontroli wersji. W tym samym pliku zwykle są też twoje klucze do repo.magento.com.

Krok 2: uruchom composer require i setup:upgrade

composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade

Te trzy polecenia to podstawa instalacji każdego modułu Magento 2:

  1. composer require pobiera pakiet do katalogu vendor/ i zapisuje go w plikach composer.json i composer.lock. Commituj oba pliki, żeby każde środowisko instalowało tę samą wersję.
  2. module:enable rejestruje moduł w pliku app/etc/config.php.
  3. setup:upgrade wprowadza zmiany schematu bazy danych i patche danych modułu oraz aktualizuje rejestr modułów.

Krok 3: kompilacja, wdrożenie i czyszczenie cache

W trybie produkcyjnym wygenerowany kod i pliki statyczne nie są budowane na żądanie, więc uruchom:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f

W trybie deweloperskim pomiń oba polecenia. W obu trybach zakończ poleceniem:

bin/magento cache:flush

Następnie sprawdź, czy moduł jest aktywny, i wyłącz tryb konserwacji:

bin/magento module:status Conviro_AiChat
bin/magento maintenance:disable

Krok 4: połącz moduł w panelu administracyjnym

Większość modułów wymaga konfiguracji po instalacji. W przypadku Conviro otwórz Stores › Settings › Conviro Setup. Siedmiokrokowy kreator sprawdza środowisko, a potem klikasz Connect to Conviro, zatwierdzasz sklep w panelu Conviro i wracasz do Magento. Do Magento nie kopiujesz żadnego klucza API ani tokena.

Kreator tworzy integrację Magento z minimalnymi uprawnieniami (OAuth 1.0a), pozwala wybrać widoki sklepu, zakres synchronizacji i dozwolone akcje AI, a na koniec weryfikuje wszystko zdarzeniem testowym. Potem karta Integration Health w Stores › Configuration › Conviro › AI Chat sprawdza połączenie, uwierzytelnianie, webhooki, katalog, zamówienia, crona, wersję i środowisko oraz podaje instrukcje naprawy. Każdy krok opisują strona instalacji i dokumentacja instalacji. Do połączenia potrzebny jest plan Conviro z dostępem do API, czyli Pro lub wyższy (zobacz cennik).

Aktualizacja i odinstalowanie modułu Magento 2

Aktualizacja

composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Tak jak wcześniej, kompilację i wdrożenie plików statycznych wykonuj tylko w trybie produkcyjnym. Gdy pojawi się nowa wersja, panel administracyjny Magento wyświetli powiadomienie z dokładnym poleceniem, a twoja konfiguracja, klucz API i integracja zostaną zachowane.

Odinstalowanie

Kolejność ma znaczenie: rozłączenie odbywa się w kreatorze konfiguracji, który znika po usunięciu modułu.

  1. Rozłącz sklep w kreatorze konfiguracji Conviro.
  2. Wyłącz moduł: bin/magento module:disable Conviro_AiChat
  3. Usuń pakiet: composer remove conviro/module-aichat
  4. Uruchom bin/magento setup:upgrade.

W trybie produkcyjnym jak zwykle ponownie skompiluj kod, wdróż pliki statyczne i wyczyść cache. Conviro usuwa dane sklepu 30 dni po rozłączeniu albo od razu, jeśli tak wybierzesz. Wszystkie kroki znajdziesz w dokumentacji odinstalowania.

Typowe błędy i jak je naprawić

Objaw Prawdopodobna przyczyna Rozwiązanie
„Allowed memory size exhausted” podczas działania Composera Limit pamięci PHP Uruchom COMPOSER_MEMORY_LIMIT=-1 composer require ...
Kompilacji brakuje pamięci Limit pamięci w CLI Uruchom php -d memory_limit=2G bin/magento setup:di:compile
Błąd 401 lub prośba o dane logowania z repozytorium Zły klucz lub nazwa użytkownika Uruchom ponownie polecenie http-basic; nazwa użytkownika to api
„Permission denied” w generated/, var/ lub pub/static/ Polecenia uruchomione jako root lub niewłaściwy użytkownik Popraw właściciela plików, a potem uruchom polecenia ponownie jako właściciel plików
„Please upgrade your database” Nie uruchomiono setup:upgrade Uruchom bin/magento setup:upgrade
Dane przestają się synchronizować, karta Integration Health zgłasza crona Cron nie działa Uruchom bin/magento cron:install i sprawdź crontab -l

Cron ma większe znaczenie, niż się wydaje. Conviro zapisuje zdarzenia finalizacji zamówienia, rejestracji i zapisu produktu w lokalnej kolejce, którą cron Magento dostarcza w tle. Moduł jest też zaprojektowany tak, by strony sklepu nie wywoływały Conviro z poziomu PHP, a zamówienia były realizowane nawet wtedy, gdy Conviro jest niedostępne. Najpierw przetestuj cały proces na stagingu; po instalacji przyda się nasza checklista testów chatbota AI.

Najczęściej zadawane pytania

Czy w trybie deweloperskim trzeba uruchamiać setup:di:compile?

Nie. Tryb deweloperski generuje kod na żądanie, więc po instalacji modułu wystarczą setup:upgrade i cache:flush. W trybie produkcyjnym uruchom też setup:di:compile i setup:static-content:deploy, bo inaczej sklep i panel administracyjny mogą przestać działać z powodu brakującego wygenerowanego kodu i plików statycznych.

Gdzie Composer przechowuje dane logowania do prywatnego repozytorium?

composer config http-basic.<host> <user> <password> zapisuje je w pliku auth.json w katalogu głównym projektu, obok composer.json. Dodaj --global, żeby zamiast tego zapisać je w katalogu domowym Composera twojego użytkownika. W obu przypadkach nie dodawaj auth.json do systemu kontroli wersji, żeby klucze nie wyciekły.

Jak sprawdzić, czy moduł Magento 2 jest włączony?

Uruchom bin/magento module:status, aby wyświetlić listę włączonych i wyłączonych modułów, albo dodaj nazwę modułu, np. bin/magento module:status Conviro_AiChat. Jeśli moduł jest wyłączony, uruchom module:enable, potem setup:upgrade i wyczyść cache.

Czy można zainstalować moduł Magento bez dostępu SSH?

Nie przez Composer. Moduł Conviro wymaga dostępu SSH lub CLI oraz Composera na serwerze. Jeśli twój hosting tego nie zapewnia, poproś dostawcę hostingu lub agencję o przeprowadzenie instalacji. W planie Enterprise zespół Conviro instaluje moduł bez dodatkowych opłat.

Kolejne kroki

Przeprowadź instalację na stagingu, przejdź przez kreator konfiguracji i sprawdź kartę Integration Health, zanim powtórzysz wszystko na produkcji. Pełny przegląd tego, co moduł robi po połączeniu, znajdziesz w naszym omówieniu modułu czatu AI dla Magento 2. Chcesz połączyć sklep? Załóż konto Conviro.

Udostępnij:

Opublikowane przez

Conviro

Dzieli się wiedzą o obsłudze klienta opartej na AI, automatyzacji chatbotów i strategiach wzrostu SaaS.

Buduj na bazie Conviro

Połącz przepływy konwersacyjne ze swoim stosem technologicznym

Przejrzyj zasoby dla deweloperów i wzorce integracji, zanim zaprojektujesz wdrożenie.

Powiązane artykuły

Więcej wpisów