Instalacja NQ2

Wybierz ścieżkę pasującą do urządzenia. Pakiet instalatora zawiera skrypty dla różnych platform i wspólny config.yaml. ZIP aplikacji zawiera samo NQ2 — to dwa różne pliki do pobrania.

Ścieżka 1: świeża karta Raspberry Pi

Skorzystaj z instrukcji Raspberry Pi z 16 zrzutami ekranu. Nagraj Raspberry Pi OS Lite (64-bit) w Raspberry Pi Imagerze, ustaw tam konto i sieć, a następnie na komputerze z Windows uruchom windows/raspianimager.cmd, aby dodać instalator pierwszego uruchomienia. Dopiero potem wysuń kartę i włącz Raspberry Pi.

To najprostsza ścieżka dla nowego Raspberry Pi. Instalator pobiera NQ2 i wybrane komponenty na samym Pi. Pakiet nie jest gotowym obrazem .img i przy pierwszym uruchomieniu wymaga internetu.

Ścieżka 2: istniejący system operacyjny

Zachowaj zainstalowany system i wybierz:

• Instalator dla swojej platformy: Ubuntu lub Raspberry Pi OS przez SSH albo instalację bezpośrednio w Windows. Kreator przygotuje zależności, NQ2, autostart i opcjonalne komponenty.
• Ręczną instalację w Linuksie: samodzielnie sprawdzasz i wykonujesz polecenia. Instrukcja obejmuje Node.js, PM2, Nginx, uwierzytelnianie MQTT i Zigbee2MQTT. Nie uruchamiasz instalatora NQ2.

Użyj jednej metody dla nowej instalacji aplikacji. Skrypty nie aktualizują istniejącego NQ2 ani nie łączą konfiguracji już działających usług.

Który plik uruchomić?

Pakiet nie ma obecnie instalatora natywnego dla macOS ani skryptu raspianimager dla macOS/Linuksa. Imager jest dostępny na tych komputerach, ale przygotowanie karty skryptem .cmd wymaga Windows. Skrypty linuksowe uruchamiasz na docelowym systemie Linux, a nie na karcie podłączonej do komputera.

Pobierz i skonfiguruj

Rozpakuj cały folder nq2-installation. Zachowaj razem core, katalogi platform i config.yaml. Kreator Windows nie wymaga osobnej instalacji Pythona. W Linuksie potrzebny jest Python 3.10+.

Kreator zaczyna od wyboru EN/PL i pobiera wartości domyślne z config.yaml, którego komentarze są po angielsku:

install_nginx: true
install_mqtt: true
install_zigbee2mqtt: true
mqtt_allow_remote: false
mqtt_user: "nq2"
mqtt_password: "nq2"
admin_email: "admin@admin.local"
admin_password: "admin123"
nq2_url: "https://nq2.io/api/apps/nq2-local/download.zip"

Aktualny instalator domyślnie korzysta z adresu API aplikacji podanego powyżej. Jeśli używasz wcześniej rozpakowanego instalatora, ustaw nq2_url na ten adres przed uruchomieniem.

Przed pierwszym uruchomieniem ustaw własne hasła MQTT i administratora. Konto Linux/SSH, konto MQTT i administrator NQ2 są niezależne. Sieć Raspberry Pi, nazwa hosta i konto Linuksa pochodzą z Imagera; kreator NQ2 ich nie zmienia.

Kolejność instalacji to zależności i Node.js 24 → NQ2 i PM2 → opcjonalny Nginx → opcjonalny Mosquitto → opcjonalny Zigbee2MQTT. Ostatnie trzy komponenty mają domyślnie true; narzędzia potrzebne przed końcowym pobraniem Zigbee2MQTT są przygotowane wcześniej. Dla NQ2 wykonywane jest npm install na docelowym urządzeniu. Rotacja logów aplikacji PM2 ogranicza pojedynczy plik do 10 MB i zachowuje siedem skompresowanych archiwów.

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.

Adresy i dostęp do MQTT

Adres IP przydziela sieć/router; 192.168.1.100 nie jest wpisany na sztywno. Użyj swojej nazwy hosta. .local wymaga obsługi mDNS po stronie klienta; natywny instalator Windows nie ogłasza tej nazwy.

Domyślnie MQTT jest dostępny tylko lokalnie. Aby połączyć inne komputery lub urządzenia, odpowiedz tak na pytanie o dostęp MQTT albo przed instalacją ustaw mqtt_allow_remote: true. Mosquitto zacznie nasłuchiwać na 0.0.0.0 zamiast 127.0.0.1, nadal wymagając ustawionego loginu i hasła. Klienci łączą się z mqtt://IP_URZADZENIA:1883; 0.0.0.0 jest adresem nasłuchu, a nie adresem do wpisania w kliencie. Istniejąca zapora Linuksa może wymagać dopuszczenia portu. Windows dodaje regułę MQTT tylko dla profilu sieci Prywatna i tylko po włączeniu dostępu z innych urządzeń. To nie konfiguruje przekierowania portów routera ani dostępu przez internet.

Pobieranie aplikacji i aktualizacje

Każda nowa instalacja pobiera paczkę NQ2 dostępną pod download.zip. W config.yaml nie używamy stałego nq2_sha256. Pliki sum kontrolnych na stronie opisują opublikowane pliki do pobrania i są niezależne od ustawień instalatora.

Skrypty nie aktualizują automatycznie zainstalowanego NQ2. W sekcji Aplikacje znajdziesz wydanie aplikacji, a na stronie instalatora pakiet automatyzacji.

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.