Konfigurowanie aplikacji Node.js dla usługi Azure App Service

Artykuł
09/13/2024

Node.js aplikacje muszą być wdrażane ze wszystkimi wymaganymi zależnościami npm. Aparat wdrażania usługi App Service jest uruchamiany npm install --production automatycznie podczas wdrażania repozytorium Git lub wdrażania pakietu Zip z włączoną automatyzacją kompilacji. Jeśli jednak wdrażasz pliki przy użyciu protokołu FTP/S, musisz ręcznie przekazać wymagane pakiety.

Ten przewodnik zawiera kluczowe pojęcia i instrukcje dla deweloperów Node.js, którzy wdrażają w usłudze App Service. Jeśli nigdy nie używasz usługi aplikacja systemu Azure Service, najpierw postępuj zgodnie z przewodnikiem Szybki start Node.js i Node.js z samouczkiem bazy danych MongoDB.

Pokaż wersję Node.js

Aby wyświetlić bieżącą wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

Aby wyświetlić wszystkie obsługiwane wersje Node.js, przejdź do https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime lub uruchom następujące polecenie w usłudze Cloud Shell:

az webapp list-runtimes --os windows | grep NODE

Aby wyświetlić bieżącą wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

Aby wyświetlić wszystkie obsługiwane wersje Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp list-runtimes --os linux | grep NODE

Ustawianie wersji Node.js

Aby ustawić aplikację na obsługiwaną wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell , aby ustawić WEBSITE_NODE_DEFAULT_VERSION obsługiwaną wersję:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"

Uwaga

W tym przykładzie użyto zalecanej składni "tyldy", aby kierować do najnowszej dostępnej wersji środowiska uruchomieniowego Node.js 16 w usłudze App Service.

Ponieważ środowisko uruchomieniowe jest regularnie poprawiane i aktualizowane przez platformę, nie zalecamy określania docelowej wersji pomocniczej/poprawki, ponieważ nie są one gwarantowane ze względu na potencjalne zagrożenia bezpieczeństwa.

Uwaga

Należy ustawić wersję Node.js w projekcie package.json. Aparat wdrażania działa w osobnym procesie zawierającym wszystkie obsługiwane wersje Node.js.

Aby ustawić aplikację na obsługiwaną wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"

To ustawienie określa Node.js wersję do użycia, zarówno w czasie wykonywania, jak i podczas automatycznego przywracania pakietu w kudu.

Uwaga

Należy ustawić wersję Node.js w projekcie package.json. Aparat wdrażania działa w oddzielnym kontenerze zawierającym wszystkie obsługiwane wersje Node.js.

Uzyskiwanie numeru portu

Aplikacja Node.js musi nasłuchiwać odpowiedniego portu w celu odbierania żądań przychodzących.

W usłudze App Service w systemie Windows aplikacje Node.js są hostowane w programie IISNode, a aplikacja Node.js powinna nasłuchiwać portu określonego w zmiennej process.env.PORT . W poniższym przykładzie pokazano, jak to zrobić w prostej aplikacji Express:

Usługa App Service ustawia zmienną środowiskową PORT w kontenerze Node.js i przekazuje żądania przychodzące do kontenera pod tym numerem portu. Aby otrzymywać żądania, aplikacja powinna nasłuchiwać tego portu przy użyciu polecenia process.env.PORT. W poniższym przykładzie pokazano, jak to zrobić w prostej aplikacji Express:

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

Dostosowywanie automatyzacji kompilacji

Jeśli wdrażasz aplikację przy użyciu usługi Git lub przy użyciu pakietów zip z włączoną automatyzacją kompilacji, procedura automatyzacji kompilacji usługi App Service przebiega przez następującą sekwencję:

Uruchom skrypt niestandardowy, jeśli został określony przez PRE_BUILD_SCRIPT_PATHelement .
Uruchom polecenie npm install bez żadnych flag, które obejmują narzędzie npm preinstall i postinstall skrypty, a także instaluje program devDependencies.
Uruchom polecenie npm run build , jeśli skrypt kompilacji został określony w package.json.
Uruchom polecenie npm run build:azure , jeśli skrypt build:azure został określony w package.json.
Uruchom skrypt niestandardowy, jeśli jest określony przez POST_BUILD_SCRIPT_PATHpolecenie .

Uwaga

Jak wspomniano w dokumentacji npm, skrypty o nazwie prebuild i postbuild uruchamiane przed i po build, odpowiednio, jeśli określono. preinstall i postinstall uruchom odpowiednio przed i po install, .

PRE_BUILD_COMMAND i POST_BUILD_COMMAND są zmiennymi środowiskowymi, które są domyślnie puste. Aby uruchomić polecenia przed kompilacją, zdefiniuj polecenie PRE_BUILD_COMMAND. Aby uruchomić polecenia po kompilacji, zdefiniuj polecenie POST_BUILD_COMMAND.

W poniższym przykładzie użyto dwóch zmiennych, aby określić serię poleceń rozdzielonych przecinkami.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Aby uzyskać informacje o dodatkowych zmiennych środowiskowych w celu dostosowania automatyzacji kompilacji, zobacz Konfiguracja Oryx.

Aby uzyskać więcej informacji na temat sposobu uruchamiania i kompilowania aplikacji Node.js w systemie Linux, zobacz dokumentację Oryx: Jak wykrywać i kompilować aplikacje Node.js.

Konfigurowanie serwera Node.js

Kontenery Node.js są dostarczane z pm2, menedżerem procesów produkcyjnych. Aplikację można skonfigurować tak, aby rozpoczynała się od pm2, z uruchamianiem narzędzia npm lub za pomocą polecenia niestandardowego.

Narzędzie	Purpose
Uruchamianie za pomocą funkcji PM2	Zalecane — użycie produkcyjne lub przejściowe. Pm2 zapewnia platformę zarządzania aplikacjami w pełnej usłudze.
Uruchamianie przy użyciu narzędzia npm start	Tylko do użytku programistycznego.
Uruchamianie za pomocą polecenia niestandardowego	Programowanie lub przemieszczanie.

Uruchamianie za pomocą funkcji PM2

Kontener automatycznie uruchamia aplikację z pm2, gdy w projekcie znajduje się jeden z typowych plików Node.js:

bin/www
server.js
app.js
index.js
hostingstart.js
Jeden z następujących plików PM2: process.json lub ecosystem.config.js

Można również skonfigurować niestandardowy plik startowy z następującymi rozszerzeniami:

Plik .js
Plik PM2 z rozszerzeniem .json, .config.js, yaml lub .yml

Uwaga

Począwszy od środowiska Node 14 LTS, kontener nie uruchamia automatycznie aplikacji z pm2. Aby uruchomić aplikację z pm2, ustaw polecenie uruchamiania na pm2 start <.js-file-or-PM2-file> --no-daemon. Pamiętaj, aby użyć argumentu --no-daemon , ponieważ pm2 musi działać prawidłowo na pierwszym planie kontenera.

Aby dodać niestandardowy plik startowy, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

Uruchamianie za pomocą polecenia niestandardowego

Usługa App Service może uruchomić aplikację przy użyciu polecenia niestandardowego, takiego jak plik wykonywalny, taki jak run.sh. Aby na przykład uruchomić npm run start:prodpolecenie , uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

Uruchamianie przy użyciu narzędzia npm start

Aby uruchomić aplikację przy użyciu polecenia npm start, upewnij się, że start skrypt znajduje się w pliku package.json . Na przykład:

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

Aby użyć niestandardowego package.json w projekcie, uruchom następujące polecenie w usłudze Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

Debugowanie zdalne

Możesz debugować aplikację Node.js zdalnie w programie Visual Studio Code , jeśli skonfigurujesz ją do uruchamiania przy użyciu funkcji PM2, z wyjątkiem sytuacji, gdy jest uruchamiana przy użyciu .config.js, .yml lub yaml.

W większości przypadków nie jest wymagana żadna dodatkowa konfiguracja aplikacji. Jeśli aplikacja jest uruchamiana z plikiem process.json (domyślnym lub niestandardowym script ), musi mieć właściwość w katalogu głównym JSON. Na przykład:

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

Aby skonfigurować program Visual Studio Code na potrzeby zdalnego debugowania, zainstaluj rozszerzenie usługi App Service. Postępuj zgodnie z instrukcjami na stronie rozszerzenia i zaloguj się do platformy Azure w programie Visual Studio Code.

W Eksploratorze platformy Azure znajdź aplikację, którą chcesz debugować, kliknij ją prawym przyciskiem myszy i wybierz polecenie Rozpocznij debugowanie zdalne. Wybierz pozycję Tak , aby włączyć zdalne debugowanie dla aplikacji. Usługa App Service uruchamia dla Ciebie serwer proxy tunelu i dołącza debuger. Następnie możesz wysyłać żądania do aplikacji i zobaczyć wstrzymanie debugera w punktach przerwania.

Po zakończeniu debugowania zatrzymaj debuger, wybierając pozycję Rozłącz. Po wyświetleniu monitu wybierz pozycję Tak , aby wyłączyć debugowanie zdalne. Aby wyłączyć ją później, ponownie kliknij aplikację prawym przyciskiem myszy w eksploratorze platformy Azure i wybierz polecenie Wyłącz debugowanie zdalne.

Uzyskiwanie dostępu do zmiennych środowiskowych

W usłudze App Service można określić ustawienia aplikacji poza kodem aplikacji. Następnie możesz uzyskać do nich dostęp przy użyciu standardowego wzorca Node.js. Aby na przykład uzyskać dostęp do ustawienia aplikacji o nazwie NODE_ENV, użyj następującego kodu:

process.env.NODE_ENV

Run Grunt/Bower/Gulp

Domyślnie automatyzacja kompilacji usługi App Service jest uruchamiana npm install --production po rozpoznaniu, że aplikacja Node.js jest wdrażana za pośrednictwem usługi Git lub za pośrednictwem wdrożenia zip z włączoną automatyzacją kompilacji. Jeśli aplikacja wymaga dowolnego z popularnych narzędzi automatyzacji, takich jak Grunt, Bower lub Gulp, musisz podać niestandardowy skrypt wdrożenia, aby go uruchomić.

Aby umożliwić repozytorium uruchamianie tych narzędzi, należy dodać je do zależności w package.json. Na przykład:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

W lokalnym oknie terminalu zmień katalog na katalog główny repozytorium i uruchom następujące polecenia:

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

Katalog główny repozytorium ma teraz dwa dodatkowe pliki: .deployment i deploy.sh.

Otwórz deploy.sh i znajdź sekcję Deployment , która wygląda następująco:

##################################################################################################################################
# Deployment
# ----------

Ta sekcja kończy się uruchomieniem polecenia npm install --production. Dodaj sekcję kodu, którą musisz uruchomić wymagane narzędzie na końcu Deployment sekcji:

Bower
Gulp
Grunt

Zobacz przykład w przykładzie MEAN.js, w którym skrypt wdrażania uruchamia również polecenie niestandardowenpm install.

Bower

Ten fragment kodu uruchamia polecenie bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

Ten fragment kodu uruchamia polecenie gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

Ten fragment kodu uruchamia polecenie grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

Wykrywanie sesji protokołu HTTPS

W usłudze App Service kończenie żądań PROTOKOŁU TLS/SSL odbywa się w modułach równoważenia obciążenia sieciowego, więc wszystkie żądania HTTPS docierają do aplikacji jako niezaszyfrowane żądania HTTP. Jeśli logika aplikacji musi sprawdzić, czy żądania użytkownika są szyfrowane, sprawdź X-Forwarded-Proto nagłówek.

Popularne platformy internetowe umożliwiają dostęp do informacji X-Forwarded-* w standardowym wzorcu aplikacji. W programie Express można używać serwerów proxy zaufania. Na przykład:

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

Uzyskiwanie dostępu do dzienników diagnostycznych

Aby uzyskać dostęp do dzienników konsoli wygenerowanych wewnątrz kodu aplikacji w usłudze App Service, włącz rejestrowanie diagnostyczne, uruchamiając następujące polecenie w usłudze Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Możliwe wartości parametru --level to: Error, Warning, Info i Verbose. Każdy kolejny poziom obejmuje poprzedni poziom. Na przykład poziom Error obejmuje tylko komunikaty o błędach, a poziom Verbose obejmuje wszystkie komunikaty.

Po włączeniu rejestrowania diagnostycznego uruchom następujące polecenie, aby wyświetlić strumień dziennika:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Jeśli nie widzisz dzienników konsoli, sprawdź ponownie w ciągu 30 sekund.

Uwaga

Pliki dzienników można także sprawdzać w przeglądarce pod adresem https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Aby w dowolnym momencie zatrzymać przesyłanie strumieniowe dzienników, naciśnij kombinację klawiszy Ctrl+C.

Dostęp do dzienników konsoli wygenerowanych z poziomu kontenera można uzyskać.

Najpierw włącz rejestrowanie kontenerów, uruchamiając następujące polecenie:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Zastąp <app-name> wartości i <resource-group-name> nazwami odpowiednimi dla aplikacji internetowej.

Po włączeniu rejestrowania kontenerów uruchom następujące polecenie, aby wyświetlić strumień dziennika:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Jeśli nie widzisz dzienników konsoli, sprawdź ponownie w ciągu 30 sekund.

Aby zatrzymać przesyłanie strumieniowe dzienników w dowolnym momencie, wpisz Ctrl+C.

Możesz również sprawdzić pliki dziennika w przeglądarce pod adresem https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Ponowne zapisywanie adresów URL

Podczas wdrażania aplikacji Node.js w usłudze aplikacja systemu Azure Service dla systemu Linux może być konieczne obsługiwanie ponownego zapisywania adresów URL bezpośrednio w aplikacji. Jest to szczególnie przydatne w przypadku zapewnienia przekierowania określonych wzorców adresów URL do poprawnych punktów końcowych bez polegania na konfiguracjach serwera internetowego. Istnieje kilka sposobów na ponowne zapisywanie adresów URL w Node.js. Przykładem jest pakiet express-urlrewrite .

Monitorowanie za pomocą usługi Application Insights

Usługa Application Insights umożliwia monitorowanie wydajności, wyjątków i użycia aplikacji bez wprowadzania żadnych zmian w kodzie. Aby dołączyć agenta usługi Application Insights, przejdź do aplikacji internetowej w portalu, wybierz pozycję Application Insights w obszarze Ustawienia, a następnie wybierz pozycję Włącz usługę Application Insights. Następnie wybierz istniejący zasób usługi Application Insights lub utwórz nowy. Na koniec wybierz pozycję Zastosuj u dołu. Aby instrumentować aplikację internetową przy użyciu programu PowerShell, zapoznaj się z tymi instrukcjami

Ten agent będzie monitorować aplikację Node.js po stronie serwera. Aby monitorować kod JavaScript po stronie klienta, dodaj zestaw SDK języka JavaScript do projektu.

Aby uzyskać więcej informacji, zobacz informacje o wersji rozszerzenia usługi Application Insights.

Rozwiązywanie problemów

Jeśli działająca aplikacja Node.js działa inaczej w usłudze App Service lub ma błędy, spróbuj wykonać następujące czynności:

Uzyskaj dostęp do strumienia dziennika.
Przetestuj aplikację lokalnie w trybie produkcyjnym. Usługa App Service uruchamia aplikacje Node.js w trybie produkcyjnym, dlatego należy upewnić się, że projekt działa zgodnie z oczekiwaniami w trybie produkcyjnym lokalnie. Na przykład: .
- W zależności od package.json różne pakiety mogą być instalowane w trybie produkcyjnym (dependencies a devDependencies).
- Niektóre struktury internetowe mogą wdrażać pliki statyczne inaczej w trybie produkcyjnym.
- Niektóre struktury internetowe mogą używać niestandardowych skryptów uruchamiania podczas uruchamiania w trybie produkcyjnym.
Uruchom aplikację w usłudze App Service w trybie programowania. Na przykład w MEAN.js możesz ustawić aplikację na tryb programowania w czasie wykonywania, ustawiając NODE_ENV ustawienie aplikacji.

Nie masz uprawnień do wyświetlania tego katalogu lub strony

Po wdrożeniu kodu Node.js w natywnej aplikacji systemu Windows w usłudze App Service może zostać wyświetlony komunikat You do not have permission to view this directory or page w przeglądarce podczas przechodzenia do adresu URL aplikacji. Jest to najprawdopodobniej spowodowane tym, że nie masz pliku web.config . (Zobacz szablon i przykład).

Jeśli pliki są wdrażane przy użyciu usługi Git lub przy użyciu wdrożenia ZIP z włączoną automatyzacją kompilacji, aparat wdrażania generuje plik web.config w katalogu głównym sieci Web aplikacji (%HOME%\site\wwwroot), jeśli jeden z następujących warunków jest spełniony:

Katalog główny projektu ma package.json , który definiuje start skrypt zawierający ścieżkę pliku JavaScript.
Katalog główny projektu ma server.js lub app.js.

Wygenerowany plik web.config jest dostosowany do wykrytego skryptu uruchamiania. W przypadku innych metod wdrażania dodaj tę konfigurację web.config ręcznie. Upewnij się, że plik jest poprawnie sformatowany.

Jeśli używasz wdrożenia ZIP (na przykład za pomocą programu Visual Studio Code), pamiętaj, aby włączyć automatyzację kompilacji. Nie jest ona domyślnie włączona. az webapp up używa wdrożenia ZIP z włączoną automatyzacją kompilacji.

robots933456 w dziennikach

W dziennikach kontenera może zostać wyświetlony następujący komunikat:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Możesz bezpiecznie zignorować ten komunikat. /robots933456.txt jest fikcyjną ścieżką adresu URL, za pomocą której usługa App Service sprawdza, czy kontener jest w stanie obsługiwać żądania. Odpowiedź 404 oznacza po prostu, że ścieżka nie istnieje, ale pozwala usłudze App Service sprawdzić, czy kontener jest w dobrej kondycji i jest gotowy do reagowania na żądania.

Następne kroki

Samouczek: Node.js aplikacji z bazą danych MongoDB

Azure App Service on Linux FAQ (Usługa Azure App Service w systemie Linux — często zadawane pytania)

Możesz też zapoznać się z dodatkowymi zasobami:

Dokumentacja zmiennych środowiskowych i ustawień aplikacji

Udostępnij za pośrednictwem

Konfigurowanie aplikacji Node.js dla usługi Azure App Service

Pokaż wersję Node.js

Ustawianie wersji Node.js

Uzyskiwanie numeru portu

Dostosowywanie automatyzacji kompilacji

Konfigurowanie serwera Node.js

Uruchamianie za pomocą funkcji PM2

Uruchamianie za pomocą polecenia niestandardowego

Uruchamianie przy użyciu narzędzia npm start

Debugowanie zdalne

Uzyskiwanie dostępu do zmiennych środowiskowych

Run Grunt/Bower/Gulp

Bower

Gulp

Grunt

Wykrywanie sesji protokołu HTTPS

Uzyskiwanie dostępu do dzienników diagnostycznych

Ponowne zapisywanie adresów URL

Monitorowanie za pomocą usługi Application Insights

Rozwiązywanie problemów

Nie masz uprawnień do wyświetlania tego katalogu lub strony

robots933456 w dziennikach

Następne kroki

Opinia

Dodatkowe zasoby