Instalacja na istniejącym systemie

Wybierz tę metodę, gdy system docelowy jest już zainstalowany i możesz się do niego zalogować. Nie nagrywasz karty ponownie i nie uruchamiasz kreatora przygotowania karty. Jeśli wolisz pojedyncze polecenia, przejdź do ręcznej instalacji w Linuksie.

Pobierz i wybierz system docelowy

Rozpakuj cały folder nq2-installation. Zachowaj razem core, config.yaml i foldery platform. config.yaml jest wspólny dla wszystkich skryptów; ma angielskie komentarze, a kreator działa w EN lub PL.

Kontrola Linuksa dopuszcza arm64, amd64 i armhf; sprzęt musi też obsługiwać Node.js 24 oraz zależności aplikacji. Sama obecność architektury na liście nie gwarantuje działania każdej zależności natywnej. Dla Raspberry Pi użyj systemu 64-bit opisanego w instrukcji karty. Nie ma natywnego instalatora macOS.

Skrypty służą do nowej instalacji aplikacji. Sprawdzają zajęte porty i istniejące wybrane usługi. Jeśli masz już Nginx, Mosquitto lub Zigbee2MQTT, wybierz false dla tego komponentu, aby go zachować; istniejącą usługę skonfiguruj osobno. Skrypty nie aktualizują istniejącego NQ2. Konto Linuksa już używające PM2 zostanie odrzucone, aby nie zakłócić jego procesów; użyj innego istniejącego zwykłego konta przez --user.

Ubuntu lub Raspberry Pi OS przez SSH

System musi już mieć działającą sieć i SSH. Na komputerze rozpakuj ZIP, otwórz terminal w katalogu nadrzędnym nq2-installation i skopiuj cały folder przez SCP lub SFTP. Zastąp YOUR_USER i DEVICE_ADDRESS swoim kontem i IP/nazwą serwera:

scp -r nq2-installation YOUR_USER@DEVICE_ADDRESS:~/
ssh YOUR_USER@DEVICE_ADDRESS
cd ~/nq2-installation

Na urządzeniu docelowym uruchom jeden skrypt ze zwykłego konta:

# Ubuntu
bash ubuntu/install.sh

# Raspberry Pi OS / Debian
bash raspbian/install.sh

Skrypt poprosi o uprawnienia sudo. Oba pliki korzystają ze wspólnego core/install_linux.sh. Przy uruchamianiu przez Bash nie musisz wykonywać chmod +x. Jeśli jesteś zalogowany jako root, wskaż istniejące konto aplikacji, np. bash ubuntu/install.sh --user YOUR_USER.

Instalator zachowuje istniejące konto, hasło, hostname, sieć i SSH. Aplikacje działają z /opt/nq2 i /opt/zigbee2mqtt na wybranym koncie. Konfiguracja PM2 jest w katalogu domowym tego użytkownika, a prywatna konfiguracja instalatora w /etc/nq2-image/config.yaml.

Wi-Fi: wyłącz oszczędzanie energii

Jeśli Raspberry Pi lub serwer Linux korzysta z Wi-Fi, wyłącz oszczędzanie energii Wi-Fi, aby ograniczyć okresowe rozłączanie po bezczynności. Urządzenie może wtedy wyglądać na wyłączone, mimo że nadal działa. Aktualny instalator NQ2 ustawia to automatycznie w systemie z NetworkManagerem. Przy instalacji ręcznej lub starszym pakiecie wykonaj instrukcję ustawienia i kontroli Wi-Fi. Dla Ethernetu ta zmiana nie jest potrzebna.

Istniejący Windows

Uruchom windows\install.cmd z całego rozpakowanego pakietu. Instaluje to NQ2 na komputerze z Windows, a nie na karcie Raspberry Pi. Zaakceptuj UAC na tym samym koncie, które ma być właścicielem aplikacji. Kreator nie wymaga WSL ani osobnej instalacji Pythona. Niektóre zależności aplikacji mogą potrzebować narzędzi C++ i Pythona; jeśli npm install zgłosi błąd, uzupełnij wskazane wymagania przed ponowieniem.

Zachowaj domyślny katalog C:\ProgramData\NQ2. Użyj ścieżki bez spacji: wcześniej testowana paczka aplikacji miała błąd ścieżki UI w katalogach ze spacjami. Node.js i narzędzia PM2 należą do tej instalacji; Mosquitto jest instalowany jako usługa Windows w Program Files\mosquitto. Dla koordynatora Zigbee USB zainstaluj sterownik Windows i użyj jego portu COM, np. COM3.

Zadanie NQ2 Applications uruchamia aplikacje PM2 po zalogowaniu wybranego użytkownika Windows. Nie jest to start przed logowaniem. Mosquitto uruchamia się niezależnie jako automatyczna usługa Windows. Windows nie otrzymuje linuksowej konfiguracji hostname .local; użyj localhost lub IP komputera.

Pytania kreatora i kolejność instalacji

1. Wybierz EN lub PL.
2. Wybierz Nginx, lokalny Mosquitto i Zigbee2MQTT — domyślnie wszystkie są włączone.
3. Jeśli instalujesz Mosquitto, określ, czy inne komputery mają mieć dostęp. Domyślne false oznacza dostęp tylko lokalny.
4. Podaj login i hasło MQTT oraz e-mail i hasło administratora NQ2. Enter zachowuje wartości z config.yaml. Zmień przykładowe hasła na własne.
5. Jeśli wyłączysz Mosquitto, ale włączysz Zigbee2MQTT, podaj URL istniejącego brokera, np. mqtt://192.0.2.10:1883, oraz jego dane logowania. IP z przykładu należy zastąpić swoim.

Kolejność: wspólne zależności, Node.js 24, PM2 i narzędzia menedżera pakietów → pobranie NQ2 i npm install → opcjonalny Nginx → opcjonalny Mosquitto → na końcu pobranie Zigbee2MQTT, jego zależności, kompilacja i start. Nazwy procesów aplikacji to nq2 i zigbee2mqtt. Logi PM2 mają rotację: 10 MB i siedem skompresowanych archiwów.

mqtt_allow_remote: false ustawia nowy Mosquitto na 127.0.0.1. Ustaw true, aby nasłuchiwać na wszystkich interfejsach IPv4 pod 0.0.0.0; inne urządzenia łączą się z mqtt://IP_SERWERA:1883 i danymi MQTT. Uwierzytelnianie pozostaje włączone. Reguły zapory Linuksa nie są zmieniane. Windows dodaje regułę przychodzącą MQTT tylko dla sieci Prywatnej i po włączeniu tej opcji. Przekierowanie portów routera i dostęp przez internet nie są konfigurowane. Flaga nie zmienia konfiguracji zewnętrznego brokera ani już zainstalowanej usługi.

Sprawdź postęp i otwórz NQ2

W Linuksie instalacja działa w tle jako usługa systemd, również po rozłączeniu SSH:

sudo journalctl -u nq2-firstboot -f
sudo systemctl status nq2-firstboot --no-pager
pm2 list
pm2 logs nq2 --lines 100

Uruchamiaj pm2 z tego samego zwykłego konta, które jest właścicielem aplikacji; sudo pm2 pokazuje inną listę procesów. Ctrl+C kończy podgląd logów bez zatrzymywania instalacji.

W Windows poczekaj na komunikat zakończenia kreatora i użyj skryptu tej instalacji:

C:\ProgramData\NQ2\pm2.cmd list
C:\ProgramData\NQ2\pm2.cmd logs nq2 --lines 100

Z Nginxem otwórz http://IP_SERWERA (albo http://localhost na serwerze); bez niego użyj portu 8080. Wybrany Zigbee2MQTT używa portu 8090. Do NQ2 zaloguj się danymi administratora z kreatora, a następnie skonfiguruj integracje z właściwym adresem MQTT i danymi brokera. Sprawdź działanie ponownie po restarcie; w Windows najpierw zaloguj wybranego użytkownika.

Ponowienie po przerwaniu

• Linux: nieudane uruchomienia usługi są ponawiane po 120 sekundach. Popraw przyczynę z logów i użyj sudo systemctl restart nq2-firstboot. Nie uruchamiaj ponownie kreatora nad zapisaną konfiguracją. Błąd przygotowania może wystąpić, zanim powstanie usługa.
• Windows: ukończone etapy są zapisywane prywatnie. Uruchom ponownie install.cmd z tymi samymi opcjami i danymi logowania, aby wznowić. Nie ma automatycznego ponawiania instalatora co 120 sekund. Przy odrzuceniu zmienionej konfiguracji wróć do pierwotnych opcji.
• Po udanej instalacji aplikacja nie pobiera stale najnowszego NQ2. To nie jest narzędzie aktualizacji ani migracji.

Instalator ma testy automatyczne. Paczka była sprawdzana przez uruchomienie na Windows, co nie oznacza pełnego przetestowania każdej usługi na każdym docelowym systemie. Do instalacji bez kreatora służy ręczna instrukcja Linuksa.

Konfiguracja aplikacji w .env

Instalator tworzy /opt/nq2/.env w Linuksie lub C:\ProgramData\NQ2\apps\nq2\.env w Windows. Zapisuje tam NODE_ENV, PORT, ADMIN_EMAIL, ADMIN_PASSWORD, korzystając z danych kreatora / config.yaml. PM2 uruchamia NQ2 bezpośrednio (pm2 start index.js --name nq2 dla paczki z index.js), a Zigbee2MQTT dodaje osobno na końcu. pm2 save zapisuje listę do autostartu. Nie powstaje plik ecosystem. Zmiana dotyczy nowych instalacji; istniejąca instalacja nie jest automatycznie migrowana.

Usuń początkowe dane administratora po zalogowaniu

Po pierwszym uruchomieniu i udanym zalogowaniu do NQ2 usuń ADMIN_EMAIL i ADMIN_PASSWORD z pliku .env aplikacji. Są potrzebne tylko podczas pierwszego uruchomienia do utworzenia konta administratora. Pozostaw ustawienia działania aplikacji, na przykład:

NODE_ENV=production
PORT=8080

W Linuksie edytuj /opt/nq2/.env, a w domyślnej instalacji Windows C:\ProgramData\NQ2\apps\nq2\.env. Zrób to dopiero po potwierdzeniu, że logowanie administratora działa.