Delen via

Een Node.js-app configureren voor Azure App Service

  • Artikel

Node.js apps moeten worden geïmplementeerd met alle vereiste NPM-afhankelijkheden. De App Service-implementatie-engine wordt automatisch voor u uitgevoerd npm install --production wanneer u een Git-opslagplaats implementeert of een Zip-pakket waarvoor buildautomatisering is ingeschakeld. Als u uw bestanden echter implementeert met FTP/S, moet u de vereiste pakketten handmatig uploaden.

Deze handleiding bevat belangrijke concepten en instructies voor Node.js ontwikkelaars die implementeren in App Service. Als u Azure-app Service nog nooit hebt gebruikt, volgt u eerst de quickstart Node.js en Node.js met mongoDB-zelfstudie.

Node.js-versie weergeven

Als u de huidige Node.js-versie wilt weergeven, voert u de volgende opdracht uit in Cloud Shell:

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

Als u alle ondersteunde Node.js versies wilt weergeven, gaat u naar https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime of voert u de volgende opdracht uit in Cloud Shell:

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

Als u de huidige Node.js-versie wilt weergeven, voert u de volgende opdracht uit in Cloud Shell:

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

Als u alle ondersteunde Node.js-versies wilt weergeven, voert u de volgende opdracht uit in Cloud Shell:

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

Versie van Node.js instellen

Als u uw app wilt instellen op een ondersteunde Node.js versie, voert u de volgende opdracht uit in Cloud Shell om deze in te stellen WEBSITE_NODE_DEFAULT_VERSION op een ondersteunde versie:

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

Notitie

In dit voorbeeld wordt de aanbevolen 'tilde-syntaxis' gebruikt om de meest recente beschikbare versie van Node.js 16 runtime in App Service te gebruiken.

Omdat de runtime regelmatig wordt gepatcht en bijgewerkt door het platform, wordt het afgeraden om een specifieke secundaire versie/patch te richten, omdat deze niet gegarandeerd beschikbaar zijn vanwege mogelijke beveiligingsrisico's.

Notitie

U moet de Node.js versie instellen in de projectversie package.json. De implementatie-engine wordt uitgevoerd in een afzonderlijk proces dat alle ondersteunde Node.js versies bevat.

Als u uw app wilt instellen op een ondersteunde Node.js versie, voert u de volgende opdracht uit in Cloud Shell:

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

Met deze instelling geeft u de Node.js versie op die moet worden gebruikt, zowel tijdens runtime als tijdens het automatisch herstellen van pakketten in Kudu.

Notitie

U moet de Node.js versie instellen in de projectversie package.json. De implementatie-engine wordt uitgevoerd in een afzonderlijke container die alle ondersteunde Node.js versies bevat.

Poortnummer ophalen

Uw Node.js-app moet luisteren naar de juiste poort om binnenkomende aanvragen te ontvangen.

In App Service in Windows worden Node.js apps gehost met IISNode en moet uw Node.js-app luisteren naar de poort die is opgegeven in de process.env.PORT variabele. In het volgende voorbeeld ziet u hoe u dit doet in een eenvoudige Express-app:

App Service stelt de omgevingsvariabele PORT in de Node.js-container in en stuurt de binnenkomende aanvragen door naar uw container op dat poortnummer. Als u de aanvragen wilt ontvangen, moet uw app naar die poort luisteren met behulp van process.env.PORT. In het volgende voorbeeld ziet u hoe u dit doet in een eenvoudige Express-app:

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}`)
})

De automatisering van bouwbewerkingen aanpassen

Als u uw app implementeert met Git of zip-pakketten waarvoor buildautomatisering is ingeschakeld, doorloopt de App Service-buildautomatisering de volgende reeks:

  1. Voer aangepast script uit als dit is opgegeven door PRE_BUILD_SCRIPT_PATH.
  2. Uitvoeren npm install zonder vlaggen, die npm preinstall en postinstall scripts bevatten en ook worden geïnstalleerd devDependencies.
  3. Voer npm run build uit als er een buildscript is opgegeven in uw package.json.
  4. Voer npm run build:azure uit als een build:azure-script is opgegeven in uw package.json.
  5. Voer aangepast script uit als dit is opgegeven door POST_BUILD_SCRIPT_PATH.

Notitie

Zoals beschreven in npm-documenten, worden scripts genoemd prebuild en uitgevoerd vóór en postbuild na buildrespectievelijk, indien opgegeven. preinstall en postinstall worden respectievelijk vóór en na installuitgevoerd.

PRE_BUILD_COMMAND en POST_BUILD_COMMAND zijn omgevingsvariabelen die standaard leeg zijn. Als u vooraf gebouwde opdrachten wilt uitvoeren, definieert u PRE_BUILD_COMMAND. Als u achteraf gebouwde opdrachten wilt uitvoeren, definieert u POST_BUILD_COMMAND.

In het volgende voorbeeld worden de twee variabelen voor een reeks opdrachten opgegeven, gescheiden door komma's.

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"

Zie Oryx-configuratie voor aanvullende omgevingsvariabelen om bouwautomatisering aan te passen.

Zie de Documentatie van Oryx voor meer informatie over hoe App Service wordt uitgevoerd en bouwt Node.js apps in Linux: Hoe Node.js apps worden gedetecteerd en gebouwd.

Node.js-server configureren

De Node.js containers worden geleverd met PM2, een productieprocesmanager. U kunt uw app configureren om te beginnen met PM2, of met NPM, of met een aangepaste opdracht.

Hulpprogramma Doel
Uitvoeren met PM2 Aanbevolen : productie- of faseringsgebruik. PM2 biedt een volledig app-beheerplatform.
Npm starten uitvoeren Alleen ontwikkelingsgebruik.
Aangepaste opdracht uitvoeren Ontwikkeling of fasering.

Uitvoeren met PM2

De container start uw app automatisch met PM2 wanneer een van de algemene Node.js bestanden in uw project wordt gevonden:

  • bin/www
  • server.js
  • app.js
  • index.js
  • hostingstart.js
  • Een van de volgende PM2-bestanden: process.json en ecosystem.config.js

U kunt ook een aangepast startbestand configureren met de volgende extensies:

  • Een .js-bestand
  • Een PM2-bestand met de extensie .json, .config.js, .yaml of .yml

Notitie

Vanaf Node 14 LTS start de container uw app niet automatisch met PM2. Als u uw app wilt starten met PM2, stelt u de opstartopdracht in op pm2 start <.js-file-or-PM2-file> --no-daemon. Zorg ervoor dat u het --no-daemon argument gebruikt omdat PM2 op de voorgrond moet worden uitgevoerd om de container goed te laten werken.

Als u een aangepast startbestand wilt toevoegen, voert u de volgende opdracht uit in Cloud Shell:

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

Aangepaste opdracht uitvoeren

App Service kan uw app starten met behulp van een aangepaste opdracht, zoals een uitvoerbaar bestand zoals run.sh. Als u bijvoorbeeld wilt uitvoeren npm run start:prod, voert u de volgende opdracht uit in Cloud Shell:

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

Npm starten uitvoeren

Als u uw app wilt gaan gebruiken npm start, moet u ervoor zorgen dat een start script zich in het package.json bestand bevindt. Voorbeeld:

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

Als u een aangepaste package.json in uw project wilt gebruiken, voert u de volgende opdracht uit in Cloud Shell:

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

Foutopsporing op afstand

Notitie

Externe foutopsporing is momenteel beschikbaar als preview-versie.

U kunt fouten opsporen in uw Node.js-app op afstand in Visual Studio Code als u deze configureert voor uitvoering met PM2, behalve wanneer u deze uitvoert met behulp van een .config.js, .yml of .yaml.

In de meeste gevallen is er geen extra configuratie vereist voor uw app. Als uw app wordt uitgevoerd met een process.json bestand (standaard of aangepast), moet deze een script eigenschap hebben in de JSON-hoofdmap. Voorbeeld:

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

Installeer de App Service-extensie om Visual Studio Code in te stellen voor externe foutopsporing. Volg de instructies op de extensiepagina en meld u aan bij Azure in Visual Studio Code.

Zoek in Azure Explorer de app die u wilt opsporen, klik er met de rechtermuisknop op en selecteer Externe foutopsporing starten. Klik op Ja om deze in te schakelen voor uw app. App Service start een tunnelproxy voor u en koppelt het foutopsporingsprogramma. Vervolgens kunt u aanvragen naar de app indienen en het foutopsporingsprogramma bij onderbrekingspunten bekijken.

Als u klaar bent met foutopsporing, stopt u het foutopsporingsprogramma door Verbinding verbreken te selecteren. Wanneer u hierom wordt gevraagd, klikt u op Ja om externe foutopsporing uit te schakelen. Als u deze later wilt uitschakelen, klikt u opnieuw met de rechtermuisknop op uw app in Azure Explorer en selecteert u Externe foutopsporing uitschakelen.

Toegang tot omgevingsvariabelen

In App Service kunt u app-instellingen configureren buiten uw app-code. Vervolgens kunt u ze openen met behulp van het standaardpatroon Node.js. Voor toegang tot bijvoorbeeld de app-instelling NODE_ENV gebruikt u de volgende code:

process.env.NODE_ENV

Grunt/Bower/Gulp uitvoeren

App Service-buildautomatisering wordt standaard uitgevoerd npm install --production wanneer een Node.js app wordt geïmplementeerd via Git of via Zip-implementatie waarvoor buildautomatisering is ingeschakeld. Als uw app een van de populaire automatiseringsprogramma's vereist, zoals Grunt, Bower of Gulp, moet u een aangepast implementatiescript opgeven om het uit te voeren.

Als u wilt dat uw opslagplaats deze hulpprogramma's uitvoert, moet u deze toevoegen aan de afhankelijkheden in package.json. Bijvoorbeeld:

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

Wijzig vanuit een lokaal terminalvenster de map in de hoofdmap van uw opslagplaats en voer de volgende opdrachten uit:

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

De hoofdmap van de opslagplaats bevat nu twee extra bestanden: .deployment en deploy.sh.

Open deploy.sh en zoek de Deployment sectie, die er als volgt uitziet:

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

Deze sectie eindigt met uitvoeren npm install --production. Voeg de codesectie toe die u nodig hebt om het vereiste hulpprogramma aan het einde van de Deployment sectie uit te voeren:

Bekijk een voorbeeld in het MEAN.js voorbeeld, waarbij het implementatiescript ook een aangepaste npm install opdracht uitvoert.

Bower

Dit fragment wordt uitgevoerd 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

Slok

Dit fragment wordt uitgevoerd 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

Dit fragment wordt uitgevoerd grunt.

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

HTTPS-sessie detecteren

In App Service vindt TLS/SSL-beëindiging plaats bij de netwerktaakverdelers, zodat alle HTTPS-aanvragen uw app bereiken als niet-versleutelde HTTP-aanvragen. Inspecteer de header X-Forwarded-Proto als de app-logica moet controleren of de aanvragen van gebruikers al dan niet zijn versleuteld.

Populaire webframeworks bieden toegang tot de X-Forwarded-*-informatie in het patroon van de standaard-app. In Express kunt u vertrouwensproxy's gebruiken. Voorbeeld:

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

Toegang tot diagnostische logboeken

Als u toegang wilt tot de consolelogboeken die worden gegenereerd binnen uw toepassingscode in de App Service, schakelt u diagnostische logboekregistratie in door de volgende opdracht in de Cloud Shell uit te voeren:

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

Mogelijk waarden voor --level zijn: Error, Warning, Info en Verbose. Elk hoger niveau omvat het vorige niveau. Bijvoorbeeld: Error omvat alleen foutberichten en Verbose omvat alle berichten.

Nadat diagnostische logboekregistratie is ingeschakeld, voert u de volgende opdracht uit om de logboekstream te zien:

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

Als u de consolelogboeken niet meteen ziet, probeert u het opnieuw na 30 seconden.

Notitie

U kunt ook de logboekbestanden van de browser inspecteren op https://<app-name>.scm.azurewebsites.net/api/logs/docker.

U kunt op elk gewenst moment Ctrl+C typen om te stoppen met logboekstreaming.

U hebt vanuit de container toegang tot de consolelogboeken.

Schakel eerst logboekregistratie voor containers in door de volgende opdracht uit te voeren:

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

Vervang <app-name> en <resource-group-name> door de namen die van toepassing zijn op uw web-app.

Zodra logboekregistratie is ingeschakeld, voert u de volgende opdracht uit om de logboekstream te zien:

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

Als u de consolelogboeken niet meteen ziet, probeert u het opnieuw na 30 seconden.

U kunt op elk gewenst moment stoppen met logboekstreaming door Ctrl+C te typen.

U kunt ook de logboekbestanden in een browser inspecteren op https://<app-name>.scm.azurewebsites.net/api/logs/docker.

URL-herschrijven

Wanneer u Node.js-apps implementeert in Azure-app Service voor Linux, moet u mogelijk URL-herschrijven rechtstreeks in uw toepassing verwerken. Dit is met name handig om ervoor te zorgen dat specifieke URL-patronen worden omgeleid naar de juiste eindpunten zonder gebruik te maken van webserverconfiguraties. Er zijn verschillende manieren om URL-herschrijven uit te voeren in Node.js. Een voorbeeld is via het express-urlrewrite-pakket .

Controleren met behulp van Application Insights

Met Application Insights kunt u de prestaties, uitzonderingen en het gebruik van uw toepassing bewaken zonder codewijzigingen aan te brengen. Als u de App Insights-agent wilt koppelen, gaat u naar uw web-app in de portal en selecteert u Application Insights onder Instellingen en selecteert u Application Insights inschakelen. Selecteer vervolgens een bestaande App Insights-resource of maak een nieuwe resource. Selecteer tot slot Toepassen onderaan. Als u uw web-app wilt instrumenteren met behulp van PowerShell, raadpleegt u deze instructies

Met deze agent wordt uw Node.js toepassing aan de serverzijde bewaakt. Als u javaScript aan de clientzijde wilt bewaken, voegt u de JavaScript-SDK toe aan uw project.

Zie de releaseopmerkingen voor de Application Insights-extensie voor meer informatie.

Probleemoplossing

Wanneer een werkende Node.js app zich anders gedraagt in App Service of fouten bevat, probeert u het volgende:

  • Open de logboekstream.
  • Test de app lokaal in de productiemodus. App Service voert uw Node.js-apps uit in de productiemodus, dus u moet ervoor zorgen dat uw project werkt zoals verwacht in de productiemodus lokaal. Bijvoorbeeld:
    • Afhankelijk van uw package.json kunnen verschillende pakketten worden geïnstalleerd voor de productiemodus (dependencies vs. devDependencies).
    • Bepaalde webframeworks kunnen statische bestanden anders implementeren in de productiemodus.
    • Bepaalde webframeworks kunnen aangepaste opstartscripts gebruiken wanneer ze worden uitgevoerd in de productiemodus.
  • Voer uw app uit in App Service in de ontwikkelmodus. In MEAN.js kunt u uw app bijvoorbeeld instellen op de ontwikkelingsmodus in runtime door de NODE_ENV app-instelling in te stellen.

U bent niet gemachtigd om deze map of pagina weer te geven

Nadat u uw Node.js code hebt geïmplementeerd in een systeemeigen Windows-app in App Service, ziet u mogelijk het bericht You do not have permission to view this directory or page. in de browser wanneer u naar de URL van uw app navigeert. Dit komt waarschijnlijk doordat u geen web.config-bestand hebt (zie de sjabloon en een voorbeeld).

Als u uw bestanden implementeert met behulp van Git of door zip-implementatie te gebruiken waarvoor buildautomatisering is ingeschakeld, genereert de implementatie-engine automatisch een web.config in de webhoofdmap van uw app (%HOME%\site\wwwroot) als aan een van de volgende voorwaarden wordt voldaan:

  • De hoofdmap van uw project heeft een package.json waarmee een start script wordt gedefinieerd dat het pad van een JavaScript-bestand bevat.
  • De hoofdmap van uw project heeft een server.js of een app.js.

De gegenereerde web.config is aangepast aan het gedetecteerde startscript. Voor andere implementatiemethoden voegt u deze web.config handmatig toe. Zorg ervoor dat het bestand juist is opgemaakt.

Als u bijvoorbeeld ZIP-implementatie gebruikt (via Visual Studio Code), moet u buildautomatisering inschakelen omdat deze niet standaard is ingeschakeld. az webapp up maakt gebruik van ZIP-implementatie waarbij buildautomatisering is ingeschakeld.

robots933456 in logboeken

U ziet mogelijk het volgende bericht in de containerlogboeken:

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

U kunt dit bericht veilig negeren. /robots933456.txt is een dummy-URL-pad dat App Service gebruikt om te controleren of de container aanvragen kan verwerken. Een 404-antwoord geeft alleen aan dat het pad niet bestaat, maar laat App Service wel weten dat de container in orde is en klaar is om te reageren op aanvragen.

Volgende stappen

Zelfstudie: Node.js-app met MongoDB

Veelgestelde vragen over App Service Linux

Of zie aanvullende informatiebronnen:

Naslaginformatie over omgevingsvariabelen en app-instellingen