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

Artigo
09/13/2024

Node.js aplicativos devem ser implantados com todas as dependências npm necessárias. O mecanismo de implantação do Serviço de Aplicativo é executado npm install --production automaticamente quando você implanta um repositório Git ou quando implanta um pacote Zip com a automação de compilação habilitada. Se você implantar seus arquivos usando FTP / S, no entanto, você precisa carregar os pacotes necessários manualmente.

Este guia fornece conceitos-chave e instruções para Node.js desenvolvedores que implantam no Serviço de Aplicativo. Se você nunca usou o Serviço de Aplicativo do Azure, siga o Node.js tutorial de início rápido e Node.js com o MongoDB primeiro.

Mostrar versão 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 até 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 seu aplicativo 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 compatível:

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

Nota

Este exemplo usa a "sintaxe til" recomendada para direcionar a versão mais recente disponível do tempo de execução do Node.js 16 no Serviço de Aplicativo.

Como o tempo de execução é regularmente corrigido e atualizado pela plataforma, não recomendamos que você direcione uma versão/patch secundária específica, pois não é garantido que eles estejam disponíveis devido a possíveis riscos de segurança.

Nota

Você deve definir a versão Node.js no package.json. O mecanismo de implantação é executado em um processo separado que contém todas as versões de Node.js suportadas.

Para definir seu aplicativo para uma versão 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"

Essa configuração especifica a versão Node.js a ser usada, tanto em tempo de execução quanto durante a restauração automatizada de pacotes no Kudu.

Nota

Você deve definir a versão Node.js no package.json. O mecanismo de implantação é executado em um contêiner separado que contém todas as versões de Node.js suportadas.

Obter número da porta

Seu aplicativo Node.js precisa ouvir a porta certa para receber solicitações de entrada.

No Serviço de Aplicativo no Windows, Node.js aplicativos são hospedados com IISNode e seu aplicativo Node.js deve ouvir a porta especificada na process.env.PORT variável. O exemplo a seguir mostra como fazer isso em um aplicativo Express simples:

O Serviço de Aplicativo define a variável PORT de ambiente no contêiner Node.js e encaminha as solicitações de entrada para o contêiner nesse número de porta. Para receber as solicitações, seu aplicativo deve ouvir essa porta usando process.env.PORTo . O exemplo a seguir mostra como fazer isso em um aplicativo 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 você implantar seu aplicativo usando o Git ou pacotes zip com a automação de compilação habilitada, a automação de compilação do Serviço de Aplicativo percorrerá a seguinte sequência:

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

Nota

Como é observado nos documentos npm, scripts nomeados prebuild e postbuild executados antes e depois build, respectivamente, se especificado. preinstall e postinstall correr antes e depois install, respetivamente.

PRE_BUILD_COMMAND e POST_BUILD_COMMAND são variáveis de ambiente que estão vazias por padrã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 a seguir usa as duas variáveis para especificar 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 informações sobre variáveis de ambiente adicionais para personalizar a automação de compilação, consulte Configuração do Oryx.

Para obter mais informações sobre como o Serviço de Aplicativo executa e cria aplicativos Node.js no Linux, consulte a documentação do Oryx: Como Node.js aplicativos são detetados e criados.

Configurar Node.js servidor

Os contentores Node.js vêm com PM2, um gestor do processo de produção. Você pode configurar seu aplicativo para começar com PM2, com npm start ou com um comando personalizado.

Ferramenta	Propósito
Executar com PM2	Recomendado - Produção ou uso de preparação. O PM2 fornece uma plataforma de gerenciamento de aplicativos de serviço completo.
Executar com início npm	Apenas para uso de desenvolvimento.
Executar com um comando personalizado	Desenvolvimento ou encenação.

Executar com PM2

O contêiner inicia automaticamente seu aplicativo com PM2 quando um dos arquivos de Node.js comuns é encontrado em seu projeto:

BIN/WWW
server.js
app.js
index.js
hostingstart.js
Um dos seguintes ficheiros PM2: process.json ou ecosystem.config.js

Você também pode configurar um arquivo de início personalizado com as seguintes extensões:

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

Nota

A partir do Nó 14 LTS, o contêiner não inicia automaticamente seu aplicativo com PM2. Para iniciar seu aplicativo com PM2, defina o comando de inicialização como pm2 start <.js-file-or-PM2-file> --no-daemon. Certifique-se de usar o --no-daemon argumento porque o PM2 precisa ser executado em primeiro plano para que o contêiner funcione corretamente.

Para adicionar um arquivo 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 com um comando personalizado

O Serviço de Aplicativo pode iniciar seu aplicativo usando um comando personalizado, como um executável como run.sh. Por exemplo, para executar npm run start:prodo , 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 com início npm

Para iniciar seu aplicativo usando npm starto , basta verificar se um start script está no arquivo package.json . Por exemplo:

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

Para usar um package.json personalizado em 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

Você pode depurar seu aplicativo Node.js remotamente no Visual Studio Code se configurá-lo para ser executado com PM2, exceto quando executá-lo usando um .config.js..yml ou .yaml.

Na maioria dos casos, nenhuma configuração extra é necessária para seu aplicativo. Se seu aplicativo for executado com um arquivo process.json (padrão ou personalizado), ele deverá 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 do Serviço de Aplicativo. Siga as instruções na página de extensão e entre 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. Selecione Sim para habilitar a depuração remota para seu aplicativo. O Serviço de Aplicativo inicia um proxy de túnel para você e anexa o depurador. Em seguida, você pode fazer solicitações para o aplicativo e ver o depurador pausando nos pontos de interrupção.

Depois de concluir a depuração, pare o depurador selecionando Desconectar. Quando solicitado, você deve selecionar Sim para desativar a depuração remota. Para desativá-lo mais tarde, clique com o botão direito do mouse em seu aplicativo novamente no Azure Explorer e selecione Desabilitar 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, você pode acessá-los usando 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 padrão, a automação de compilação do Serviço de Aplicativo é executada npm install --production quando reconhece que um aplicativo Node.js é implantado por meio do Git ou por meio da implantação Zip com a automação de compilação habilitada. Se seu aplicativo requer qualquer uma das ferramentas de automação populares, como Grunt, Bower ou Gulp, você precisa fornecer um script de implantação personalizado para executá-lo.

Para permitir que seu repositório execute essas ferramentas, você precisa adicioná-las às dependências no package.json. Por exemplo:

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

Em 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 agora tem dois arquivos adicionais: .deployment e deploy.sh.

Abra deploy.sh e localize a seção, que tem esta Deployment aparência:

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

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

Bower
Gulp
Grunt

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

Bower

Este trecho é executado 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 trecho é executado 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 trecho é executado 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 Aplicativo, a terminação TLS/SSL acontece nos balanceadores de carga de rede, portanto, todas as solicitações HTTPS chegam ao seu aplicativo como solicitações HTTP não criptografadas. Se a lógica do seu aplicativo precisar verificar se as solicitações do usuário estão criptografadas, inspecione o X-Forwarded-Proto cabeçalho.

Estruturas da Web populares permitem que você acesse as X-Forwarded-* informações em seu padrão de aplicativo padrão. No Express, você pode usar 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.

Você pode acessar os logs do console gerados de dentro do contêiner.

Primeiro, ative o log de contêiner executando 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 apropriados para seu aplicativo Web.

Quando o log de contêiner estiver ativado, execute o seguinte comando para ver o fluxo de log:

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 interromper o streaming de logs a qualquer momento, digite Ctrl+C.

Você também pode inspecionar os arquivos de log em um navegador em https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Regravações de URL

Ao implantar aplicativos Node.js no Serviço de Aplicativo do Azure para Linux, talvez seja necessário lidar com regravações de URL diretamente em seu aplicativo. Isso é particularmente útil para garantir que padrões de URL específicos sejam redirecionados para os pontos de extremidade corretos sem depender das configurações do servidor Web. Há várias maneiras de realizar regravações de URL no Node.js. Um exemplo é através do pacote express-urlrewrite .

Monitorizar com o Application Insights

O Application Insights permite que você monitore o desempenho, as exceções e o uso do seu aplicativo sem fazer alterações no código. Para anexar o agente do Application Insights, vá para seu aplicativo Web no portal, selecione Application Insights em Configurações e selecione Ativar Application Insights. Em seguida, selecione um recurso existente do Application Insights ou crie um novo. Por fim, selecione Aplicar na parte inferior. Para instrumentar seu aplicativo Web usando o PowerShell, consulte estas instruções

Esse agente monitorará seu aplicativo Node.js do lado do servidor. Para monitorar seu JavaScript do lado do cliente, adicione o SDK JavaScript ao seu projeto.

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

Resolução de Problemas

Quando um aplicativo de Node.js em funcionamento se comportar de forma diferente no Serviço de Aplicativo ou tiver erros, tente o seguinte:

Acesse o fluxo de log.
Teste o aplicativo localmente no modo de produção. O Serviço de Aplicativo executa seus aplicativos Node.js no modo de produção, portanto, você precisa garantir que seu projeto funcione como esperado no modo de produção localmente. Por exemplo:
- Dependendo do seu package.json, pacotes diferentes podem ser instalados para o modo de produção (dependencies vs. devDependencies).
- Certas estruturas da Web podem implantar arquivos estáticos de forma diferente no modo de produção.
- Certas estruturas da Web podem usar scripts de inicialização personalizados quando executados no modo de produção.
Execute seu aplicativo no Serviço de Aplicativo no modo de desenvolvimento. Por exemplo, no MEAN.js, você pode definir seu aplicativo para o modo de desenvolvimento em tempo de execução definindo a configuração do NODE_ENV aplicativo.

Você não tem permissão para visualizar este diretório ou página

Depois de implantar seu código Node.js em um aplicativo nativo do Windows no Serviço de Aplicativo, você poderá ver a mensagem You do not have permission to view this directory or page no navegador ao navegar até a URL do seu aplicativo. Isso é provavelmente porque você não tem um arquivo web.config . (Veja o modelo e um exemplo.)

Se você implantar seus arquivos usando o Git ou usando a implantação ZIP com a automação de compilação habilitada, o mecanismo de implantação gerará um web.config na raiz da Web do seu aplicativo (%HOME%\site\wwwroot) automaticamente 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 arquivo JavaScript.
A raiz do seu 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 implantação, adicione este web.config manualmente. Verifique se o arquivo está formatado corretamente.

Se você usar a implantação ZIP (por meio do Visual Studio Code, por exemplo), certifique-se de habilitar a automação de compilação. Não está ativado por predefinição. az webapp up usa a implantação ZIP com a automação de compilação habilitada.

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.

Próximos passos

Tutorial: Node.js aplicativo com o MongoDB

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

Ou consulte recursos adicionais:

Referência de variáveis de ambiente e configurações de aplicativo

Partilhar via

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

Mostrar versão Node.js

Definir Node.js versão

Obter número da porta

Personalizar a automatização de compilação

Configurar Node.js servidor

Executar com PM2

Executar com um comando personalizado

Executar com início npm

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

Regravações de URL

Monitorizar com o Application Insights

Resolução de Problemas

Você não tem permissão para visualizar este diretório ou página

robots933456 nos registos

Próximos passos

Comentários

Recursos adicionais