Configurare un'app Node.js per il Servizio app di Azure

Node.js le app devono essere distribuite con tutte le dipendenze NPM necessarie. Il motore di distribuzione servizio app viene eseguito npm install --production automaticamente quando si distribuisce un repository Git o un pacchetto ZIPcon l'automazione della compilazione abilitata. Se si distribuiscono i file usando FTP/S, tuttavia, è necessario caricare manualmente i pacchetti necessari.

Questa guida fornisce i concetti chiave e le istruzioni per Node.js sviluppatori che distribuiscono in servizio app. Se non si è mai usato Servizio app di Azure, seguire prima l'esercitazione introduttivaNode.js e Node.js con MongoDB.

Mostra versione Node.js

Per visualizzare la versione corrente Node.js, eseguire il comando seguente nel Cloud Shell:

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

Per visualizzare tutte le versioni di Node.js supportate, passare a https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime o eseguire il comando seguente nel Cloud Shell:

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

Per visualizzare la versione corrente Node.js, eseguire il comando seguente nel Cloud Shell:

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

Per visualizzare tutte le versioni di Node.js supportate, eseguire il comando seguente in Cloud Shell:

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

Impostare la versione Node.js

Per impostare l'app su una versione supportata Node.js, eseguire il comando seguente nel Cloud Shell per impostare WEBSITE_NODE_DEFAULT_VERSION su una versione supportata:

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

Nota

In questo esempio viene usata la "sintassi tilde" consigliata per specificare la versione più recente disponibile di Node.js runtime 16 in servizio app.

Poiché il runtime viene regolarmente sottoposto a patch e aggiornato dalla piattaforma, non è consigliabile specificare come destinazione una versione o una patch secondaria specifica perché non è garantito che siano disponibili a causa di potenziali rischi per la sicurezza.

Nota

È consigliabile impostare la versione Node.js nel progetto.package.json Il motore di distribuzione viene eseguito in un processo separato che contiene tutte le versioni supportate Node.js.

Per impostare l'app su una versione di Node.js supportata, eseguire il comando seguente nel Cloud Shell:

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

Questa impostazione specifica la versione Node.js da usare, sia in fase di esecuzione che durante il ripristino automatico dei pacchetti in Kudu.

Nota

È consigliabile impostare la versione Node.js nel progetto.package.json Il motore di distribuzione viene eseguito in un contenitore separato che contiene tutte le versioni di Node.js supportate.

Ottenere il numero di porta

L'app Node.js deve essere in ascolto della porta corretta per ricevere le richieste in ingresso.

In servizio app in Windows le app Node.js sono ospitate con IISNode e l'app Node.js deve essere in ascolto della porta specificata nella process.env.PORT variabile. L'esempio seguente illustra come eseguire questa operazione in una semplice app Express:

servizio app imposta la variabile PORT di ambiente nel contenitore Node.js e inoltra le richieste in ingresso al contenitore in corrispondenza di tale numero di porta. Per ricevere le richieste, l'app deve restare in ascolto di tale porta usando process.env.PORT. L'esempio seguente illustra come eseguire questa operazione in una semplice app 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}`)
})

Personalizzare l'automazione della compilazione

Se si distribuisce l'app usando Git o i pacchetti ZIP con l'automazione della compilazione abilitata, la procedura di automazione della compilazione servizio app seguire questa sequenza:

  1. Esegue lo script personalizzato se specificato da PRE_BUILD_SCRIPT_PATH.
  2. Eseguire npm install senza alcun flag, che include npm preinstall e postinstall script e installa devDependenciesanche .
  3. Eseguire npm run build se viene specificato uno script di compilazione nel file package.json.
  4. Eseguire npm run build:azure se viene specificato uno script build:azure nel file package.json.
  5. Esegue lo script personalizzato se specificato da POST_BUILD_SCRIPT_PATH.

Nota

Come descritto nella documentazione di npm, gli script denominati prebuild ed postbuild eseguiti rispettivamente prima e dopo build, se specificato. preinstall e postinstall vengono eseguiti rispettivamente prima e dopo install.

PRE_BUILD_COMMAND e POST_BUILD_COMMAND sono variabili di ambiente vuote per impostazione predefinita. Per eseguire comandi pre-compilazione, definire PRE_BUILD_COMMAND. Per eseguire comandi post-compilazione, definire POST_BUILD_COMMAND.

Nell'esempio seguente vengono specificate le due variabili, separate da virgole, per una serie di comandi.

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"

Per altre variabili di ambiente per personalizzare l'automazione della compilazione, vedere Configurazione Oryx.

Per altre informazioni su come servizio app vengono eseguite e compilate app Node.js in Linux, vedere la documentazione di Oryx: Come vengono rilevate e compilate le app Node.js.

Configurare Node.js server

I contenitori Node.js sono dotati di PM2, un responsabile dei processi di produzione. È possibile configurare l'app per iniziare con PM2 o con Monitoraggio prestazioni rete o con un comando personalizzato.

Strumento Scopo
Eseguire con PM2 Consigliato : uso di produzione o gestione temporanea. PM2 offre una piattaforma di gestione delle app completa.
Eseguire npm start Solo uso dello sviluppo.
Eseguire un comando personalizzato Sviluppo o gestione temporanea.

Eseguire con PM2

Il contenitore avvia automaticamente l'app con PM2 quando uno dei file di Node.js comuni si trova nel progetto:

  • bin/www
  • server.js
  • app.js
  • index.js
  • hostingstart.js
  • Uno dei file PM2 seguenti: process.json e ecosystem.config.js

È anche possibile configurare un file di avvio personalizzato con le estensioni seguenti:

  • Un file di.js
  • File PM2 con estensione json, .config.js, yaml o .yml

Nota

A partire dal nodo 14 LTS, il contenitore non avvia automaticamente l'app con PM2. Per avviare l'app con PM2, impostare il comando di avvio su pm2 start <.js-file-or-PM2-file> --no-daemon. Assicurarsi di usare l'argomento --no-daemon perché PM2 deve essere eseguito in primo piano perché il contenitore funzioni correttamente.

Per aggiungere un file di avvio personalizzato, eseguire il comando seguente nel Cloud Shell:

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

Eseguire un comando personalizzato

servizio app possibile avviare l'app usando un comando personalizzato, ad esempio un eseguibile come run.sh. Ad esempio, per eseguire npm run start:prod, eseguire il comando seguente nel Cloud Shell:

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

Eseguire npm start

Per avviare l'app usando npm start, assicurarsi che uno start script si trova nel file package.json . Ad esempio:

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

Per usare un file package.json personalizzato nel progetto, eseguire il comando seguente nel Cloud Shell:

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

Eseguire il debug in modalità remota

Nota

Il debug remoto è attualmente in anteprima.

È possibile eseguire il debug dell'app Node.js in modalità remota in Visual Studio Code se la si configura per l'esecuzione con PM2, tranne quando viene eseguita usando un file con estensione config.js,. yml o yaml.

Nella maggior parte dei casi non è necessaria alcuna configurazione aggiuntiva per l'app. Se l'app viene eseguita con un file process.json (impostazione predefinita o personalizzata), deve avere una script proprietà nella radice JSON. Ad esempio:

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

Per configurare Visual Studio Code per il debug remoto, installare l'estensione servizio app. Seguire le istruzioni nella pagina dell'estensione e accedere ad Azure in Visual Studio Code.

In Azure Explorer individuare l'app di cui si vuole eseguire il debug, fare clic con il pulsante destro del mouse e scegliere Avvia debug remoto. Fare clic su per abilitarla per l'app. servizio app avvia un proxy di tunnel per l'utente e collega il debugger. È quindi possibile effettuare richieste all'app e visualizzare il debugger sospeso in corrispondenza dei punti di interruzione.

Al termine del debug, arrestare il debugger selezionando Disconnetti. Quando richiesto, fare clic su per disabilitare il debug remoto. Per disabilitarla in un secondo momento, fare di nuovo clic con il pulsante destro del mouse sull'app in Esplora azure e scegliere Disabilita debug remoto.

Accedere alle variabili di ambiente

Nel servizio app è possibile configurare le impostazioni dell'app al di fuori del codice dell'app. È quindi possibile accedervi usando il modello di Node.js standard. Ad esempio, per accedere a un'impostazione dell'app denominata NODE_ENV, usare il codice seguente:

process.env.NODE_ENV

Eseguire Grunt/Bower/Gulp

Per impostazione predefinita, servizio app l'automazione della compilazione viene eseguita npm install --production quando riconosce che un'app Node.js viene distribuita tramite Git o tramite la distribuzione Zip con automazione della compilazione abilitata. Se l'app richiede uno degli strumenti di automazione più diffusi, ad esempio Grunt, Bower o Gulp, è necessario fornire uno script di distribuzione personalizzato per eseguirlo.

Per abilitare il repository per eseguire questi strumenti, è necessario aggiungerli alle dipendenze in package.json. Per esempio:

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

Da una finestra del terminale locale modificare la directory nella radice del repository ed eseguire i comandi seguenti:

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

La radice del repository include ora due file aggiuntivi: distribuzione e deploy.sh.

Aprire deploy.sh e trovare la sezione, simile alla Deployment seguente:

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

Questa sezione termina con l'esecuzione npm install --productiondi . Aggiungere la sezione codice necessario per eseguire lo strumento necessario alla fine della Deployment sezione:

Vedere un esempio nell'esempio di MEAN.js, in cui lo script di distribuzione esegue anche un comando personalizzato npm install .

Bower

Questo frammento di codice esegue 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

Questo frammento di codice esegue 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

Questo frammento di codice esegue grunt.

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

Rilevare una sessione HTTPS

In servizio app la terminazione TLS/SSL si verifica nei servizi di bilanciamento del carico di rete, quindi tutte le richieste HTTPS raggiungono l'app come richieste HTTP non crittografate. Se la logica dell'app deve controllare se le richieste degli utenti sono crittografate o meno, esaminare l'intestazione X-Forwarded-Proto.

I framework Web più diffusi consentono di accedere alle informazioni X-Forwarded-* nel modello di app standard. In Express è possibile usare proxy di attendibilità. Ad esempio:

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

Accedere ai log di diagnostica

Per accedere ai log della console generati dall'interno del codice dell'applicazione nel servizio app, attivare la registrazione diagnostica eseguendo il comando seguente in Cloud Shell:

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

I valori possibili per --level sono: Error, Warning, Info e Verbose. Ogni livello successivo include il livello precedente. Ad esempio, Error include solo i messaggi di errore, mentre Verbose include tutti i messaggi.

Dopo aver attivato la registrazione diagnostica, eseguire il comando seguente per visualizzare il flusso di registrazione:

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

Se i log di console non sono immediatamente visibili, controllare nuovamente dopo 30 secondi.

Nota

È anche possibile esaminare i file di log nel browser all'indirizzo https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Per interrompere lo streaming dei log in qualsiasi momento, digitare Ctrl+C.

È possibile accedere ai log della console generati dall'interno del contenitore.

Prima di tutto attivare la registrazione del contenitore eseguendo questo comando:

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

Sostituire <app-name> e <resource-group-name> con i valori appropriati per l'app Web.

Dopo che la registrazione del contenitore è attivata, eseguire il comando seguente per visualizzare il flusso di registrazione:

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

Se i log di console non sono immediatamente visibili, controllare nuovamente dopo 30 secondi.

Per interrompere lo streaming dei log in qualsiasi momento, premere CTRL+C.

È anche possibile ispezionare i file di log in un browser all'indirizzo https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Monitorare con Application Insights

Application Insights consente di monitorare le prestazioni, le eccezioni e l'utilizzo dell'applicazione senza apportare modifiche al codice. Per collegare l'agente di App Insights, passare all'app Web nel portale e selezionare Application Insights in Impostazioni, quindi selezionare Attiva Application Insights. Selezionare quindi una risorsa di App Insights esistente o crearne una nuova. Infine, selezionare Applica nella parte inferiore. Per instrumentare l'app Web con PowerShell, vedere queste istruzioni

Questo agente monitorerà l'applicazione Node.js lato server. Per monitorare JavaScript lato client, aggiungere JavaScript SDK al progetto.

Per altre informazioni, vedere le note sulla versione dell'estensione di Application Insights.

Risoluzione dei problemi

Quando un'app Node.js funzionante si comporta in modo diverso in servizio app o ha errori, provare quanto segue:

  • Accedere al flusso di log.
  • Testare l'app in locale nella modalità di produzione. Il servizio app esegue le app Node.js in modalità di produzione, quindi è necessario assicurarsi che il progetto funzioni come previsto in modalità di produzione in locale. Ad esempio:
    • A seconda del pacchetto.json, è possibile installare pacchetti diversi per la modalità di produzione (dependencies vs. devDependencies).
    • Alcuni framework Web possono distribuire i file statici in modo diverso in modalità di produzione.
    • Alcuni framework Web possono usare script di avvio personalizzati durante l'esecuzione in modalità di produzione.
  • Eseguire l'app in servizio app in modalità di sviluppo. Ad esempio, in MEAN.jsè possibile impostare l'app sulla modalità di sviluppo in runtime impostando l'impostazione dell'appNODE_ENV.

Non si dispone dell'autorizzazione per visualizzare questa directory o pagina

Dopo aver distribuito il codice Node.js in un'app di Windows nativa in servizio app, è possibile visualizzare il messaggio You do not have permission to view this directory or page. nel browser quando si passa all'URL dell'app. Questo è più probabile perché non si dispone di un file diweb.config (vedere il modello e un esempio).

Se si distribuiscono i file usando Git o usando la distribuzione ZIP con automazione della compilazione abilitata, il motore di distribuzione genera un web.config nella radice Web dell'app (%HOME%\site\wwwroot) se una delle condizioni seguenti è true:

  • La radice del progetto ha un file package.json che definisce uno start script che contiene il percorso di un file JavaScript.
  • La radice del progetto ha un server.js o un app.js.

Il web.config generato è personalizzato per lo script di avvio rilevato. Per altri metodi di distribuzione, aggiungere questa web.config manualmente. Assicurarsi che il file sia formattato correttamente.

Se si usa la distribuzione ZIP (tramite Visual Studio Code, ad esempio), assicurarsi di abilitare l'automazione della compilazione perché non è abilitata per impostazione predefinita. az webapp up usa la distribuzione ZIP con automazione della compilazione abilitata.

robots933456 nei log

È possibile che nei log del contenitore venga visualizzato il messaggio seguente:

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

È possibile ignorare tale errore. /robots933456.txt è un percorso URL fittizio usato dal servizio app per verificare se il contenitore è in grado di gestire le richieste. Una risposta 404 indica semplicemente che il percorso non esiste, ma consente al servizio app di capire che il contenitore è integro e pronto per rispondere alle richieste.

Passaggi successivi

In alternativa, vedere altre risorse:

Informazioni di riferimento sulle variabili di ambiente e sulle impostazioni dell'app