Node.js: Pierwsze kroki

Dowiedz się, jak szybko i bezpiecznie wdrożyć usługę Node.js na Stackhero

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje gotowe do użycia rozwiązanie Node.js cloud, które zapewnia wiele korzyści, w tym:

Wdrażaj swoją aplikację w kilka sekund za pomocą prostego git push.

Używaj własnej nazwy domeny i korzystaj z automatycznej konfiguracji certyfikatów HTTPS dla zwiększonego bezpieczeństwa.

Ciesz się spokojem dzięki automatycznym kopiom zapasowym, aktualizacjom jednym kliknięciem oraz prostemu, przejrzystemu i przewidywalnemu cennikowi.

Uzyskaj optymalną wydajność i solidne zabezpieczenia dzięki prywatnej i dedykowanej VM.

Oszczędzaj czas i upraszczaj sobie życie: wypróbowanie rozwiązania Node.js cloud hosting Stackhero zajmuje tylko 5 minut!

Wdrażanie usługi Node.js na Stackhero zostało zaprojektowane tak, aby było szybkie, wydajne i niezawodne. W tym przewodniku przeprowadzimy Cię przez kluczowe kroki, które pozwolą uruchomić Twoją aplikację w zaledwie kilka minut, z zachowaniem bezpieczeństwa i wysokiej wydajności.

Uruchom usługę Node.js

Na początek utwórzmy usługę Node.js na Stackhero. Będzie to podstawa do wdrożenia Twojej aplikacji i zapewni dostęp do wszystkich korzyści chmury Stackhero.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz przygotowane następujące narzędzia:

Git: Możesz pobrać go ze strony https://git-scm.com/downloads.
Użytkownicy Windows: Dla wygodniejszej pracy zalecamy korzystanie z Windows Terminal, dostępnego w Microsoft Store.

Skonfiguruj swoją usługę

Głównym krokiem konfiguracyjnym jest zaktualizowanie klucza publicznego SSH. Klucz ten umożliwia Stackhero bezpieczny dostęp do Twojego repozytorium kodu.

Aby znaleźć swój klucz publiczny, uruchom jedno z poniższych poleceń w terminalu:

cat ~/.ssh/id_rsa.pub

lub

cat ~/.ssh/id_ed25519.pub

Jeśli nie masz jeszcze pary kluczy SSH, możesz ją wygenerować poleceniem ssh-keygen na Linuxie lub macOS, albo ssh-keygen.exe na Windows.

Gdy już masz swój klucz publiczny, zaloguj się do panelu Stackhero, wybierz swoją usługę Node.js, przejdź do sekcji konfiguracji i wklej klucz w odpowiednie pole.

Tip: Jeśli chcesz, aby Twój klucz publiczny SSH był dostępny dla wszystkich przyszłych usług, możesz ustawić go globalnie. Wystarczy, że przejdziesz do panelu Stackhero, klikniesz swoje zdjęcie profilowe (w prawym górnym rogu), wejdziesz w "Twój profil" i tam wkleisz klucz publiczny SSH.

Sklonuj przykład

Aby ułatwić rozpoczęcie pracy, udostępniamy przykładową aplikację Node.js, która pokazuje, jak działa wdrożenie na Stackhero. Repozytorium możesz sklonować za pomocą poniższych poleceń:

git clone https://github.com/stackhero-io/nodejsGettingStarted.git stackhero-nodejs-getting-started
cd stackhero-nodejs-getting-started

Skonfiguruj zdalne repozytorium

Wdrażanie aplikacji przez Git na Stackhero jest bardzo proste. Na głównej stronie swojej usługi znajdziesz polecenie do dodania zdalnego repozytorium Git, które wygląda mniej więcej tak:

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Skopiuj i wklej to polecenie do swojego terminala, aby skonfigurować zdalne repozytorium.

Wdróż swoją aplikację Node.js

Aby wdrożyć aplikację, po prostu wypchnij swój kod na Stackhero poleceniem:

git push stackhero main

Przy pierwszym wypchnięciu zostaniesz poproszony o potwierdzenie odcisku klucza. Wpisz "yes", aby kontynuować.

Po chwili Twoja aplikacja powinna być dostępna online. Status możesz sprawdzić, odwiedzając adres URL wyświetlony w panelu Stackhero (np. https://<XXXXXX>.stackhero-network.com).

To wszystko — Twoja aplikacja została wdrożona.

Jeśli chcesz wprowadzić zmiany, po prostu zaktualizuj plik app.js, zatwierdź i wypchnij modyfikacje:

git add -A .
git commit -m "Update app.js"
git push stackhero main

Wdróż istniejącą aplikację

Jeśli masz już aplikację Node.js, możesz dodać zdalne repozytorium Stackhero zgodnie z powyższym opisem i wdrożyć kod poleceniem:

git push stackhero main

Obsługa błędu "failed to push some refs to '[...]'"

Jeśli napotkasz taki błąd:

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
(e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Oznacza to, że Twoje lokalne repozytorium nie jest zsynchronizowane ze zdalnym. Możesz wymusić wypchnięcie poleceniem:

git push -f stackhero main

Obsługa błędu "src refspec main does not match any"

Jeśli podczas wypychania zobaczysz taki komunikat:

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

Zwykle oznacza to, że gałąź main nie istnieje. Spróbuj wtedy wypchnąć gałąź master:

git push stackhero master

Obsługa błędu "Everything up-to-date" podczas wypychania

Jeśli Git informuje Cię "Everything up-to-date", ale zmiany nie zostały wdrożone, prawdopodobnie zapomniałeś zatwierdzić zmiany. Spróbuj wykonać:

git add -A .
git commit -m "Twój opis commita"
git push stackhero main

Jeśli nie wprowadziłeś żadnych zmian, ale chcesz wymusić wdrożenie, możesz wykonać pusty commit:

git commit --allow-empty -m "Force update"
git push stackhero main

Wdróż inną gałąź niż main

Jeśli chcesz wdrożyć inną gałąź niż main, np. production, użyj polecenia:

git push stackhero production:main

Wdróż tag

Jeśli korzystasz z tagów i chcesz wdrożyć konkretny tag (np. v1.0), uruchom:

git push stackhero 'v1.0^{}:main'

Element ^{} zapewnia, że wypchnięty zostanie commit powiązany z tagiem.

Cofnij lub wdroż konkretny commit

Aby wdrożyć konkretny commit, najpierw znajdź jego hash za pomocą git log. Następnie wdroż go poleceniem:

git push -f stackhero <HASH>:main

Wdróż do wielu środowisk

Możesz chcieć mieć oddzielne środowiska produkcyjne i testowe (staging). Aby zmienić nazwę obecnego zdalnego repozytorium z stackhero na stackhero-staging, wykonaj:

git remote rename stackhero stackhero-staging

Następnie utwórz nową usługę Node.js w panelu Stackhero i dodaj ją jako stackhero-production:

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Teraz możesz wdrażać do wybranego środowiska poleceniem:

git push stackhero-production main

lub

git push stackhero-staging main

Zapisz hasło do klucza prywatnego SSH w pęku kluczy macOS

Na macOS możesz być proszony o hasło do klucza SSH przy każdym wypchnięciu kodu. Dla wygody i bezpieczeństwa możesz zapisać je w pęku kluczy macOS poleceniem:

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

To polecenie zapisuje hasło do klucza, dzięki czemu nie będziesz pytany o nie przy kolejnych wdrożeniach.

Zarządzanie sekretami

Pracując ze środowiskami staging i produkcyjnym, ważne jest, aby bezpiecznie zarządzać sekretami, takimi jak tokeny czy hasła. Zamiast przechowywać je w repozytorium, używaj zmiennych środowiskowych dla większego bezpieczeństwa.

Możesz dodać zmienne środowiskowe w panelu Stackhero i uzyskać do nich dostęp w kodzie Node.js. Na przykład, jeśli zdefiniujesz zmienną o nazwie mySecret, możesz odczytać ją w aplikacji w ten sposób:

process.env.mySecret

Otwieranie dodatkowych portów sieciowych

Jeśli Twoja aplikacja wymaga użycia innych protokołów niż HTTP, możesz otworzyć dodatkowe porty TCP lub UDP. Zrobisz to bezpośrednio w panelu Stackhero, określając publiczny port wejściowy, port docelowy na Twojej usłudze Node.js oraz protokół (TCP lub UDP).

Przechowywanie plików

Do przechowywania plików użytkowników, takich jak zdjęcia, najlepiej użyć rozwiązania typu object storage. Pozwala to współdzielić pliki między wieloma usługami i instancjami oraz oddzielić kod od danych. Polecamy MinIO jako szybkie, proste i wydajne rozwiązanie kompatybilne z protokołem Amazon S3.

Jeśli wolisz lokalne przechowywanie, możesz skorzystać z trwałego storage dostępnego w Twojej instancji Node.js. Znajdziesz go w katalogu /persistent/storage/.

UWAGA: Zawsze przechowuj dane w folderze /persistent/storage/.

Dane zapisane poza tym folderem mogą zostać utracone po restarcie instancji lub wypchnięciu zmian w kodzie.

Łagodne wyłączanie aplikacji (graceful shutdown)

Podczas wdrażania nowej wersji aplikacji, poprzednia wersja otrzymuje sygnał zakończenia przed zamknięciem. Dzięki temu aplikacja ma czas na zamknięcie połączeń z bazą danych i zatrzymanie innych usług w kontrolowany sposób.

Sygnał zakończenia SIGTERM jest wysyłany do Twojej aplikacji. Możesz obsłużyć ten sygnał w kodzie w następujący sposób:

process.on('SIGTERM', () => {
  // Ten log pojawi się w panelu Stackhero w zakładce "logs"
  console.info('SIGTERM signal received.');

  // Zamknij tutaj otwarte połączenia do bazy danych lub inne usługi
  // ...
});

Uruchamianie kodu na wielu rdzeniach CPU

Domyślnie Node.js używa jednego rdzenia i jednego wątku. Aby wykorzystać wszystkie dostępne rdzenie CPU, możesz użyć API cluster w Node.js. Oficjalną dokumentację znajdziesz tutaj: https://nodejs.org/api/cluster.html.

Oto prosty przykład tworzący serwer HTTP wykorzystujący wszystkie dostępne CPU:

const cluster = require('cluster');
const http = require('http');
const cpusCount = require('os').cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Tworzenie workerów
  for (let i = 0; i < cpusCount; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  // Workery współdzielą każde połączenie TCP, w tym przypadku serwer HTTP
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}