Dokumentacja

Ręczna instalacja NQ2 w Linuksie

Polecenia dla Ubuntu i Raspberry Pi OS: Node.js 24, NQ2, PM2, opcjonalny Nginx, MQTT i Zigbee2MQTT.

25 paź 2026 · Czas czytania: 9 min

Wykonaj kroki samodzielnie zamiast uruchamiania instalatora NQ2. Zestaw poleceń odpowiada aktualnej konfiguracji pakietu instalatora: NQ2 latest i Zigbee2MQTT 2.14.2.

Kolejność: zależności → NQ2 → Nginx → Mosquitto → Zigbee2MQTT. NQ2 i zależności są obowiązkowe. Nginx, Mosquitto i Zigbee2MQTT są opcjonalne, domyślnie włączone. Pomiń sekcję oznaczoną „opcjonalnie”, jeśli nie chcesz danego komponentu. Bez Nginx użyj portu 8080. Bez Mosquitto użyj istniejącego brokera i wpisz jego adres oraz dane w konfiguracji Zigbee2MQTT. Zależności wspólne (Node.js, PM2, Corepack i narzędzia kompilacji) instalujesz na początku; zależności npm i kompilację Zigbee2MQTT wykonujesz po jego pobraniu na końcu.

1. Sprawdź istniejący system

Ta instrukcja jest przeznaczona do nowej instalacji aplikacji na działającym Ubuntu 22.04/24.04 lub Raspberry Pi OS / Debian 12 lub 13 z systemd. Przykładem jest Raspberry Pi OS Lite 64-bit na Raspberry Pi 4. Wykonuj polecenia w Bash na urządzeniu docelowym jako zwykły użytkownik z sudo, nie jako root. Musisz mieć dostęp do internetu i działającą sieć; przez SSH zaloguj się swoim istniejącym kontem.

Jeśli systemu jeszcze nie ma, przygotuj go Imagerem zgodnie z krokami 1–13 instrukcji karty, ustaw konto, sieć i SSH, a następnie bez dodawania skryptu NQ2 uruchom Pi i wróć tutaj. Nie uruchamiaj raspianimager.cmd ani install.sh razem z tą metodą. Alternatywą jest instalator dla istniejącego systemu.

Sprawdź istniejące usługi i porty przed wykonaniem poleceń. To nie jest aktualizacja już działającego NQ2. Katalogi /opt/nq2 i (jeśli instalujesz Zigbee2MQTT) /opt/zigbee2mqtt muszą być wolne. Jeśli masz już Nginx lub Mosquitto, zachowaj ich konfigurację i pomiń odpowiednie sekcje; nie nadpisuj używanych plików. Wymagane są Python 3.10+ i platforma obsługiwana przez Node.js 24 oraz zależności aplikacji. Koordynator Zigbee jest potrzebny tylko przy korzystaniu z Zigbee2MQTT.

Jeżeli polecenie się nie powiedzie, zatrzymaj się i usuń przyczynę przed następnym krokiem. Ustaw własne hasła przed pierwszym uruchomieniem aplikacji. Najpierw sprawdź konto i architekturę:

whoami
dpkg --print-architecture
hostname

2. Zainstaluj pakiety i Node.js 24

Polecenia instalują zależności i pobierają skrypt repozytorium NodeSource. Przed uruchomieniem możesz go przeczytać w less (wyjście: q). Jest to skrypt zewnętrznego dostawcy, nie instalator NQ2. Wersja główna Node.js jest ustawiona na 24, tak jak w obecnym instalatorze. unzip i nano są dodatkowo potrzebne do kroków ręcznych.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg git make g++ gcc libsystemd-dev avahi-daemon libnss-mdns logrotate unzip nano openssl python3
curl -fsSL --retry 3 -o "$HOME/nodesource-setup-24.sh" https://deb.nodesource.com/setup_24.x
less "$HOME/nodesource-setup-24.sh"
sudo bash "$HOME/nodesource-setup-24.sh"
sudo apt-get install -y nodejs
sudo sh -c 'umask 022; npm install -g corepack pm2'
sudo corepack enable
corepack prepare [email protected] --activate
sudo systemctl enable --now avahi-daemon
node --version
pm2 --version

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.

3. Pobierz NQ2 latest i wykonaj npm install

ZIP latest jest dynamiczny, dlatego ta instrukcja nie przypina stałej sumy SHA. Po rozpakowaniu wykonujemy npm install jako zwykły użytkownik. Skrypt poniżej rozpoznaje katalog z package.json, także gdy paczka ma dodatkowy folder. Jeśli pobieranie zwróci 404, plik nie został jeszcze opublikowany — zatrzymaj instalację. /opt/nq2 nie powinien wcześniej istnieć.

mkdir "$HOME/nq2-manual-download"
cd "$HOME/nq2-manual-download"
curl -fL --retry 3 -o nq2.zip https://nq2.io/api/apps/nq2-local/download.zip
unzip nq2.zip -d unpack
sudo mkdir /opt/nq2
sudo chown "$(id -un):$(id -gn)" /opt/nq2
python3 - <<'PYCODE'
from pathlib import Path
import shutil
root = Path('unpack')
packages = [p.parent for p in root.rglob('package.json') if 'node_modules' not in p.relative_to(root).parts]
if not packages: raise SystemExit('No package.json in NQ2 ZIP')
depth = min(len(p.relative_to(root).parts) for p in packages)
packages = [p for p in packages if len(p.relative_to(root).parts) == depth]
if len(packages) != 1: raise SystemExit('Ambiguous NQ2 package root')
shutil.copytree(packages[0], '/opt/nq2', dirs_exist_ok=True)
PYCODE
cd /opt/nq2
npm install --no-audit --no-fund

4. Konfiguracja NQ2 w .env

Utwórz .env w katalogu aplikacji /opt/nq2. To format KLUCZ=wartość, bez klamer JSON i przecinków. NQ2 odczyta plik przy uruchomieniu. Konto administratora aplikacji jest niezależne od konta SSH i MQTT.

cd /opt/nq2
umask 077
cat > .env <<'EOF'
NODE_ENV=production
PORT=8080
[email protected]
ADMIN_PASSWORD=admin123
EOF
chmod 600 .env
nano .env

Przed pierwszym startem zmień e-mail i hasło administratora na własne. Zapisz plik w nano przez Ctrl+O, Enter, a następnie wyjdź przez Ctrl+X. Hasło zawierające # lub spacje zapisz w cudzysłowach. Nie udostępniaj tego pliku.

5. Uruchom NQ2 w PM2 i ustaw autostart

Polecenia PM2 wykonuj jako ten sam zwykły użytkownik. Uruchom aplikację z jej katalogu, zapisz listę procesów i dodaj PM2 do autostartu systemd:

cd /opt/nq2
pm2 start index.js --name nq2
pm2 save
sudo env PATH="$PATH" pm2 startup systemd -u "$(id -un)" --hp "$HOME"
sudo mkdir -p "/etc/systemd/system/pm2-$(id -un).service.d"
sudo tee "/etc/systemd/system/pm2-$(id -un).service.d/network.conf" > /dev/null <<'EOF'
[Unit]
Wants=network-online.target
After=network-online.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable "pm2-$(id -un)"
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7
pm2 set pm2-logrotate:compress true
pm2 set pm2-logrotate:workerInterval 30
pm2 save
pm2 list

PM2 zapamiętuje katalog roboczy aplikacji. Autostart konfigurujesz raz dla tego użytkownika; późniejsze pm2 save obejmie również dodany na końcu Zigbee2MQTT. Nie używaj sudo pm2 start ani sudo pm2 save. Autostart PM2.

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.

6. Ogranicz pozostałe logi

pm2-logrotate obsługuje logi aplikacji. Poniższe ustawienia dodają rotację własnego logu demona PM2 oraz limity dziennika systemowego.

sudo tee /etc/logrotate.d/nq2-pm2 > /dev/null <<EOF
$HOME/.pm2/pm2.log {
    su $(id -un) $(id -gn)
    daily
    maxsize 10M
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}
EOF
sudo mkdir -p /etc/systemd/journald.conf.d
sudo tee /etc/systemd/journald.conf.d/nq2.conf > /dev/null <<'EOF'
[Journal]
SystemMaxUse=100M
RuntimeMaxUse=50M
EOF
sudo systemctl restart systemd-journald

7. Nginx — port 80 do NQ2 na 8080 — opcjonalnie

Ten blok jest przeznaczony dla świeżego systemu bez innych witryn Nginx. proxy_pass przekazuje żądania do NQ2, bez zmiany adresu w przeglądarce. Wykonaj restart dopiero po udanym nginx -t. Avahi udostępnia nazwę hosta .local.

sudo apt-get install -y nginx
sudo tee /etc/nginx/sites-available/nq2 > /dev/null <<'EOF'
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
    }
}
EOF
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/nq2 /etc/nginx/sites-enabled/nq2
sudo nginx -t
sudo systemctl enable nginx avahi-daemon
sudo systemctl restart nginx avahi-daemon

8. Mosquitto — login i hasło MQTT — opcjonalnie

Poniższy przykład używa loginu nq2. Zmień go w poleceniu, jeśli chcesz. mosquitto_passwd zapyta o hasło dwukrotnie; wpisz własne lub nq2, aby zachować domyślne dane zestawu. Ten sam login i hasło wpiszesz w konfiguracji Zigbee2MQTT. Opcji -c używaj tylko do utworzenia pliku na świeżym systemie — nadpisuje istniejący plik haseł. Opis uwierzytelniania Mosquitto.

Domyślnie broker nasłuchuje tylko na 127.0.0.1:1883 i wymaga logowania, co odpowiada mqtt_allow_remote: false w config.yaml. Przy instalacji ręcznej, aby dopuścić inne komputery, zamień poniżej listener 1883 127.0.0.1 na listener 1883 0.0.0.0. Klienci używają IP serwera oraz loginu i hasła MQTT. Odpowiednikiem w instalatorze jest mqtt_allow_remote: true. Sama edycja config.yaml nie zmienia już zainstalowanego brokera. To nie ustawia publicznego IP, przekierowania portów routera ani reguł istniejącej zapory.

sudo apt-get install -y mosquitto mosquitto-clients
sudo mosquitto_passwd -c /etc/mosquitto/nq2.passwd nq2
sudo chown root:mosquitto /etc/mosquitto/nq2.passwd
sudo chmod 640 /etc/mosquitto/nq2.passwd
sudo tee /etc/mosquitto/conf.d/nq2.conf > /dev/null <<'EOF'
listener 1883 127.0.0.1
allow_anonymous false
password_file /etc/mosquitto/nq2.passwd
EOF
sudo systemctl enable mosquitto
sudo systemctl restart mosquitto
sudo systemctl is-active mosquitto
sudo tee "/etc/systemd/system/pm2-$(id -un).service.d/network.conf" > /dev/null <<'EOF'
[Unit]
Wants=network-online.target mosquitto.service
After=network-online.target mosquitto.service
EOF
sudo systemctl daemon-reload

9. Zainstaluj Zigbee2MQTT 2.14.2 — opcjonalnie

Dostęp do koordynatora Zigbee

Dodaj swoje konto do grupy dialout. Następnie zakończ sesję SSH i zaloguj się ponownie na to samo konto, aby nowe uprawnienia zaczęły działać.

sudo usermod -aG dialout "$(id -un)"
exit

Po ponownym połączeniu przez SSH kontynuuj instalację z tego samego konta. Jeśli używasz koordynatora sieciowego, pomiń grupę dialout.

Pobranie i zależności

Wersja 2.14.2 odpowiada obecnemu zestawowi. Polecenia pnpm wykonuj bez sudo, jako użytkownik z Imagera. Corepack odczyta wersję menedżera pakietów z repozytorium i przy pierwszym użyciu może poprosić o potwierdzenie pobrania. Dokumentacja instalacji Zigbee2MQTT.

sudo git clone --depth 1 --branch 2.14.2 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R "$(id -un):$(id -gn)" /opt/zigbee2mqtt
cd /opt/zigbee2mqtt
pnpm install --frozen-lockfile
pnpm run build
mkdir -p data
nano data/configuration.yaml

10. Konfiguracja Zigbee2MQTT — opcjonalnie

W otwartym edytorze wklej poniższą konfigurację. Dopasuj user i password do brokera z kroku 8. W nano zapisz przez Ctrl+O, Enter i wyjdź Ctrl+X. Jeśli hasło zawiera apostrof, w pojedynczym cudzysłowie YAML zapisz go podwójnie, np. 'hasło''z apostrofem'. Po zapisaniu wykonaj chmod 600 /opt/zigbee2mqtt/data/configuration.yaml.

onboarding: true pozwala wybrać koordynator podczas pierwszego uruchomienia. Użyj stabilnej ścieżki /dev/serial/by-id/... i właściwego typu adaptera (np. ember albo zstack, zależnie od sprzętu).

version: 5
onboarding: true
mqtt:
  server: mqtt://127.0.0.1:1883
  base_topic: zigbee2mqtt
  user: 'nq2'
  password: 'nq2'
frontend:
  enabled: true
  host: 0.0.0.0
  port: 8090
advanced:
  log_output: [console]
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

11. Uruchom Zigbee2MQTT w PM2 — opcjonalnie

Dopiero teraz dodaj Zigbee2MQTT do PM2 z tego samego konta co NQ2. Zmienna Z2M_ONBOARD_URL ustawia port ekranu pierwszej konfiguracji na 8090. Pomiń cały krok, jeśli nie instalujesz Zigbee2MQTT.

cd /opt/zigbee2mqtt
export Z2M_ONBOARD_URL="http://0.0.0.0:8090"
pm2 start index.js --name zigbee2mqtt
pm2 save
unset Z2M_ONBOARD_URL
pm2 list

NQ2 pozostaje uruchomione. Usługa autostartu PM2 z kroku 5 jest wspólna dla obu aplikacji; nie tworzysz jej ponownie. pm2 save zapisuje listę z nq2 i zigbee2mqtt, którą PM2 przywróci po starcie systemu.

12. Sprawdź działanie i restart

Jeśli pominąłeś Nginx, adres NQ2 to http://nq2.local:8080 (użyj własnego hostname). Jeśli pominąłeś Zigbee2MQTT, nie sprawdzaj portu 8090 ani koordynatora.

Jeśli hostname z Imagera to nq2, otwórz http://nq2.local (NQ2) i http://nq2.local:8090 (Zigbee2MQTT). Dla innej nazwy użyj jej zamiast nq2. Możesz też użyć adresu IP z routera. .local wymaga obsługi mDNS po stronie klienta. W panelu Zigbee2MQTT dokończ wybór koordynatora i ustaw MQTT z kroku 8. Brak koordynatora lub błędny typ adaptera może uniemożliwić uruchomienie Zigbee.

Poniżej sprawdzisz procesy i odpowiedź HTTP NQ2. Następnie zrestartuj Pi, zaloguj się ponownie i powtórz pm2 list oraz sprawdzenie obu stron WWW.

pm2 list
sudo systemctl is-active avahi-daemon
curl -I http://127.0.0.1:8080/
sudo reboot

13. Diagnostyka i zmiana ustawień

Logi aplikacji odczytasz poniższymi poleceniami; zakończ podgląd przez Ctrl+C. Po zmianie ustawień w /opt/nq2/.env wykonaj:

pm2 restart nq2
pm2 save

NQ2 ponownie odczyta .env. Dane ADMIN_EMAIL i ADMIN_PASSWORD ustaw przed pierwszym startem; ich późniejsza edycja nie jest procedurą resetowania istniejącego konta administratora. Po zmianie konfiguracji Zigbee2MQTT użyj pm2 restart zigbee2mqtt i pm2 save. Nie wykonuj sudo pm2 list: uruchomi widok procesów innego użytkownika.

Ta ręczna metoda nie tworzy usługi nq2-firstboot ani automatycznego ponawiania instalacji. Po przerwaniu instalacji wróć do nieukończonego kroku; nie powtarzaj bez sprawdzenia poleceń tworzących pliki haseł i katalogi. Przy przerwanym instalowaniu pakietów może być potrzebne sudo dpkg --configure -a i sudo apt-get -f install, a następnie ponowienie nieudanego kroku. Sieć i konto systemowe diagnozuj niezależnie — ta instrukcja ich nie konfiguruje. Nie udostępniaj plików z hasłami ani przygotowanej prywatnej karty klientom.

pm2 logs nq2 --lines 100
pm2 logs zigbee2mqtt --lines 100
sudo journalctl -u mosquitto -n 100 --no-pager
sudo journalctl -u nginx -n 100 --no-pager
sudo journalctl -u "pm2-$(id -un)" -n 100 --no-pager
Nq2Installation