Configurar uma aplicação Node.js para o Serviço de Aplicações do Azure

Artigo
06/01/2023

Node.js aplicações têm de ser implementadas com todas as dependências do NPM necessárias. O Serviço de Aplicações motor de implementação é executado npm install --production automaticamente quando implementa um repositório Git ou um pacote Zip com a automatização de compilação ativada. No entanto, se implementar os seus ficheiros com FTP/S, terá de carregar manualmente os pacotes necessários.

Este guia fornece conceitos e instruções fundamentais para Node.js programadores que implementam no Serviço de Aplicações. Se nunca utilizou Serviço de Aplicações do Azure, siga primeiro o Node.js início rápido e Node.js com o MongoDB.

Mostrar versão do Node.js

Para mostrar a versão atual do Node.js, execute o seguinte comando no Cloud Shell:

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

Para mostrar todas as versões de Node.js suportadas, navegue para https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime ou execute o seguinte comando no Cloud Shell:

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

Para mostrar a versão atual do Node.js, execute o seguinte comando no Cloud Shell:

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

Para mostrar todas as versões de Node.js suportadas, execute o seguinte comando no Cloud Shell:

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

Definir Node.js versão

Para definir a sua aplicação para uma versão de Node.js suportada, execute o seguinte comando no Cloud Shell para definir WEBSITE_NODE_DEFAULT_VERSION como uma versão suportada:

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

Nota

Este exemplo utiliza a "sintaxe tilada" recomendada para direcionar a versão mais recente disponível do runtime Node.js 16 no Serviço de Aplicações.

Uma vez que o runtime é regularmente corrigido e atualizado pela plataforma, não é recomendado direcionar uma versão/patch menor específico, uma vez que estes não estão garantidos para estarem disponíveis devido a potenciais riscos de segurança.

Nota

Deve definir a versão Node.js no package.json. O motor de implementação é executado num processo separado que contém todas as versões de Node.js suportadas.

Para definir a sua aplicação para uma versão de Node.js suportada, execute o seguinte comando no Cloud Shell:

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

Esta definição especifica a versão Node.js a utilizar, tanto no runtime como durante o restauro automatizado do pacote no Kudu.

Nota

Deve definir a versão Node.js no package.json. O motor de implementação é executado num contentor separado que contém todas as versões de Node.js suportadas.

Obter número de porta

A sua aplicação Node.js precisa de ouvir a porta certa para receber pedidos recebidos.

No Serviço de Aplicações no Windows, Node.js aplicações são alojadas com o IISNode e a sua aplicação Node.js deve escutar a porta especificada na process.env.PORT variável. O exemplo seguinte mostra como fazê-lo numa aplicação Express simples:

Serviço de Aplicações define a variável PORT de ambiente no contentor Node.js e reencaminha os pedidos recebidos para o contentor nesse número de porta. Para receber os pedidos, a sua aplicação deve ouvir essa porta com process.env.PORT. O exemplo seguinte mostra como fazê-lo numa aplicação Express simples:

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

Personalizar a automatização de compilação

Se implementar a sua aplicação com o Git ou pacotes zip com a automatização de compilação ativada, o Serviço de Aplicações compilar passos de automatização através da seguinte sequência:

Execute o script personalizado se especificado por PRE_BUILD_SCRIPT_PATH.
Execute npm install sem sinalizadores, que inclui npm preinstall e postinstall scripts e também instala devDependencies.
Execute npm run build se for especificado um script de compilação no package.json.
Execute npm run build:azure se for especificado um script build:azure no package.json.
Execute o script personalizado se especificado por POST_BUILD_SCRIPT_PATH.

Nota

Conforme descrito nos documentos do npm, os scripts com o nome prebuild e postbuild a execução antes e depois buildde , respetivamente, se especificado. preinstall e postinstall execute antes e depois installde , respetivamente.

PRE_BUILD_COMMAND e POST_BUILD_COMMAND são variáveis de ambiente que estão vazias por predefinição. Para executar comandos de pré-compilação, defina PRE_BUILD_COMMAND. Para executar comandos pós-compilação, defina POST_BUILD_COMMAND.

O exemplo seguinte especifica as duas variáveis para uma série de comandos, separados por vírgulas.

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"

Para obter variáveis de ambiente adicionais para personalizar a automatização de compilação, veja Configuração do Oryx.

Para obter mais informações sobre como Serviço de Aplicações executa e cria Node.js aplicações no Linux, veja Documentação do Oryx: Como as aplicações Node.js são detetadas e criadas.

Configurar Node.js servidor

Os contentores Node.js vêm com PM2, um gestor de processos de produção. Pode configurar a sua aplicação para começar com PM2, com o NPM ou com um comando personalizado.

Ferramenta	Objetivo
Executar com PM2	Recomendado – utilização de produção ou teste. O PM2 fornece uma plataforma de gestão de aplicações de serviço completo.
Executar npm start	Utilização de desenvolvimento apenas.
Executar comando personalizado	Desenvolvimento ou teste.

Executar com PM2

O contentor inicia automaticamente a sua aplicação com PM2 quando um dos ficheiros de Node.js comuns é encontrado no seu projeto:

bin/www
server.js
app.js
index.js
hostingstart.js
Um dos seguintes ficheiros PM2: process.json e ecosystem.config.js

Também pode configurar um ficheiro de início personalizado com as seguintes extensões:

Um ficheiro de.js
Um ficheiro PM2 com a extensão .json, .config.js, .yaml ou .yml

Nota

A partir do Nó 14 LTS, o contentor não inicia automaticamente a sua aplicação com PM2. Para iniciar a aplicação com PM2, defina o comando de arranque como pm2 start <.js-file-or-PM2-file> --no-daemon. Certifique-se de que utiliza o --no-daemon argumento porque o PM2 tem de ser executado em primeiro plano para que o contentor funcione corretamente.

Para adicionar um ficheiro de início personalizado, execute o seguinte comando no Cloud Shell:

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

Executar comando personalizado

Serviço de Aplicações pode iniciar a aplicação com um comando personalizado, como um executável como run.sh. Por exemplo, para executar npm run start:prod, execute o seguinte comando no Cloud Shell:

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

Executar npm start

Para iniciar a sua aplicação com npm starto , certifique-se de que um start script está no ficheiro package.json . Por exemplo:

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

Para utilizar um package.json personalizado no seu projeto, execute o seguinte comando no Cloud Shell:

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

Depurar remotamente

Nota

A depuração remota está atualmente em Pré-visualização.

Pode depurar a sua aplicação Node.js remotamente no Visual Studio Code se a configurar para ser executada com PM2, exceto quando a executar com um .config.js,.yml ou .yaml.

Na maioria dos casos, não é necessária nenhuma configuração adicional para a sua aplicação. Se a sua aplicação for executada com um ficheiro process.json (predefinido ou personalizado), tem de ter uma script propriedade na raiz JSON. Por exemplo:

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

Para configurar o Visual Studio Code para depuração remota, instale a extensão Serviço de Aplicações. Siga as instruções na página da extensão e inicie sessão no Azure no Visual Studio Code.

No explorador do Azure, localize a aplicação que pretende depurar, clique com o botão direito do rato na mesma e selecione Iniciar Depuração Remota. Clique em Sim para ativá-la para a sua aplicação. Serviço de Aplicações inicia um proxy de túnel automaticamente e anexa o depurador. Em seguida, pode fazer pedidos à aplicação e ver o depurador em pausa nos pontos de interrupção.

Depois de concluir a depuração, pare o depurador ao selecionar Desligar. Quando lhe for pedido, deve clicar em Sim para desativar a depuração remota. Para a desativar mais tarde, clique novamente com o botão direito do rato na sua aplicação no explorador do Azure e selecione Desativar Depuração Remota.

Aceder a variáveis de ambiente

No Serviço de Aplicações, pode configurar as definições da aplicação fora do código da aplicação. Em seguida, pode aceder aos mesmos com o padrão de Node.js padrão. Por exemplo, para aceder a uma definição da aplicação chamada NODE_ENV, utilize o seguinte código:

process.env.NODE_ENV

Executar Grunt/Bower/Gulp

Por predefinição, Serviço de Aplicações automatização de compilação é executada npm install --production quando reconhece que uma aplicação Node.js é implementada através do Git ou através da implementação zip com a automatização de compilação ativada. Se a sua aplicação precisar de alguma das ferramentas de automatização populares, como Grunt, Bower ou Gulp, tem de fornecer um script de implementação personalizado para executá-lo.

Para ativar o seu repositório para executar estas ferramentas, tem de adicioná-las às dependências em package.json. Por exemplo:

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

A partir de uma janela de terminal local, altere o diretório para a raiz do repositório e execute os seguintes comandos:

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

A raiz do repositório tem agora dois ficheiros adicionais: .deployment e deploy.sh.

Abra deploy.sh e localize a secção, que tem o Deployment seguinte aspeto:

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

Esta secção termina com a execução npm install --productionde . Adicione a secção de código de que precisa para executar a ferramenta necessária no final da Deployment secção:

Bower
Gulp
Grunt

Veja um exemplo no exemplo MEAN.js, em que o script de implementação também executa um comando personalizado npm install .

Bower

Este fragmento executa 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

Este fragmento executa 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

Este fragmento executa grunt.

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

Detetar sessão HTTPS

No Serviço de Aplicações, a terminação TLS/SSL ocorre nos balanceadores de carga de rede, pelo que todos os pedidos HTTPS chegam à sua aplicação como pedidos HTTP não encriptados. Se a lógica da aplicação precisar de verificar se os pedidos do utilizador estão encriptados ou não, inspecione o X-Forwarded-Proto cabeçalho.

As arquiteturas Web populares permitem-lhe aceder às X-Forwarded-* informações no seu padrão de aplicação padrão. No Express, pode utilizar proxies de confiança. Por exemplo:

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

Aceder aos registos de diagnósticos

Para aceder aos registos da consola gerados a partir do código da sua aplicação no Serviço de Aplicações, ative o registo de diagnósticos ao executar o seguinte comando no Cloud Shell:

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

Os valores possíveis para --level são: Error, Warning, Info e Verbose. Cada nível subsequente inclui o nível anterior. Por exemplo: Error inclui apenas mensagens de erro e Verbose inclui todas as mensagens.

Depois de ativar o registo de diagnósticos, execute o seguinte comando para ver o fluxo de registos:

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

Se não vir os registos da consola imediatamente, volte a consultar dentro de 30 segundos.

Nota

Também pode inspecionar os ficheiros de registo no browser em https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Para parar a transmissão de registos em qualquer altura, escreva Ctrl+C.

Pode aceder aos registos da consola gerados a partir do contentor.

Primeiro, ative o registo de contentores ao executar o seguinte comando:

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

Substitua <app-name> e <resource-group-name> pelos nomes adequados para a sua aplicação Web.

Assim que o registo de contentores estiver ativado, execute o seguinte comando para ver o fluxo de registos:

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

Se não vir os registos da consola imediatamente, volte a consultar dentro de 30 segundos.

Para parar a transmissão em fluxo de registos em qualquer altura, escreva Ctrl+C.

Também pode inspecionar os ficheiros de registo num browser em https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Monitorizar com o Application Insights

O Application Insights permite-lhe monitorizar o desempenho, as exceções e a utilização da sua aplicação sem efetuar alterações de código. Para anexar o agente do App Insights, aceda à sua aplicação Web no Portal e selecione Application Insights em Definições e, em seguida, selecione Ativar o Application Insights. Em seguida, selecione um recurso do App Insights existente ou crie um novo. Por fim, selecione Aplicar na parte inferior. Para instrumentar a sua aplicação Web com o PowerShell, veja estas instruções

Este agente irá monitorizar a sua aplicação de Node.js do lado do servidor. Para monitorizar o JavaScript do lado do cliente, adicione o JavaScript SDK ao projeto.

Para obter mais informações, veja as notas de versão da extensão do Application Insights.

Resolução de problemas

Quando uma aplicação Node.js funciona de forma diferente no Serviço de Aplicações ou tem erros, experimente o seguinte:

Aceda ao fluxo de registos.
Teste a aplicação localmente no modo de produção. Serviço de Aplicações executa as suas aplicações Node.js no modo de produção, pelo que tem de se certificar de que o projeto funciona conforme esperado no modo de produção localmente. Por exemplo:
- Consoante o package.json, podem ser instalados pacotes diferentes para o modo de produção (dependencies vs. devDependencies).
- Determinadas arquiteturas Web podem implementar ficheiros estáticos de forma diferente no modo de produção.
- Determinadas arquiteturas Web podem utilizar scripts de arranque personalizados quando são executados no modo de produção.
Execute a sua aplicação no Serviço de Aplicações no modo de desenvolvimento. Por exemplo, no MEAN.js, pode definir a aplicação para o modo de desenvolvimento no runtime ao definir a definição da aplicaçãoNODE_ENV.

Não tem permissão para ver este diretório ou página

Depois de implementar o código Node.js numa aplicação nativa do Windows no Serviço de Aplicações, poderá ver a mensagem You do not have permission to view this directory or page. no browser ao navegar para o URL da sua aplicação. Isto deve-se provavelmente ao facto de não ter um ficheiro web.config (veja o modelo e um exemplo).

Se implementar os seus ficheiros com o Git ou através da implementação ZIP com a automatização de compilação ativada, o motor de implementação gera automaticamente um web.config na raiz Web da sua aplicação (%HOME%\site\wwwroot) se uma das seguintes condições for verdadeira:

A raiz do projeto tem um package.json que define um start script que contém o caminho de um ficheiro JavaScript.
A raiz do projeto tem um server.js ou um app.js.

O web.config gerado é adaptado ao script de início detetado. Para outros métodos de implementação, adicione esta web.config manualmente. Certifique-se de que o ficheiro está formatado corretamente.

Se utilizar a implementação ZIP (por exemplo, através do Visual Studio Code), certifique-se de que ativa a automatização de compilação porque não está ativada por predefinição. az webapp up utiliza a implementação ZIP com a automatização de compilação ativada.

robots933456 nos registos

Pode ver a seguinte mensagem nos registos do contentor:

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

Pode ignorar esta mensagem. /robots933456.txt é um caminho de URL fictício que o Serviço de Aplicações utiliza para verificar se o contentor consegue satisfazer pedidos. Uma resposta 404 indica simplesmente que o caminho não existe, mas permite que o Serviço de Aplicações saiba que o contentor está em bom estado de funcionamento e pronto para responder aos pedidos.

Passos seguintes

Tutorial: Node.js aplicação com MongoDB

FAQ do Serviço de Aplicações no Linux

Em alternativa, veja recursos adicionais:

Referência de variáveis de ambiente e definições da aplicação

Partilhar via

Configurar uma aplicação Node.js para o Serviço de Aplicações do Azure

Mostrar versão do Node.js

Definir Node.js versão

Obter número de porta

Personalizar a automatização de compilação

Configurar Node.js servidor

Executar com PM2

Executar comando personalizado

Executar npm start

Depurar remotamente

Aceder a variáveis de ambiente

Executar Grunt/Bower/Gulp

Bower

Gulp

Grunt

Detetar sessão HTTPS

Aceder aos registos de diagnósticos

Monitorizar com o Application Insights

Resolução de problemas

Não tem permissão para ver este diretório ou página

robots933456 nos registos

Passos seguintes

Recursos adicionais