Настройка приложения Node.js для Службы приложений Azure

Статья
09/13/2024

Node.js приложения должны быть развернуты со всеми необходимыми зависимостями npm. Подсистема развертывания Служба приложений автоматически запускается npm install --production при развертывании репозитория Git или при развертывании zip-пакета с включенной автоматизацией сборки. Но при развертывании файлов с помощью FTP/S нужные пакеты необходимо загрузить вручную.

Это руководство содержит сведения об основных понятиях и инструкции для разработчиков, использующих Node.js и Службу приложений. Если вы раньше не использовали Службу приложений Azure, сначала ознакомьтесь со статьями Краткое руководство по Node.js и Руководство по использованию Node.js с MongoDB.

Просмотр версии Node.js

Чтобы просмотреть сведения о текущей версии Node.js, выполните следующую команду в Cloud Shell:

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

Чтобы отобразились сведения обо всех поддерживаемых версиях Node.js, перейдите по адресу https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime или выполните следующую команду в Cloud Shell:

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

Чтобы просмотреть сведения о текущей версии Node.js, выполните следующую команду в Cloud Shell:

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

Чтобы отобразились сведения обо всех поддерживаемых версиях Node.js, выполните следующую команду в Cloud Shell:

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

Выбор версии Node.js

Чтобы настроить для приложения поддерживаемую версию Node.js, выполните приведенную ниже команду в Cloud Shell. С ее помощью для WEBSITE_NODE_DEFAULT_VERSION устанавливается поддерживаемая версия.

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

Примечание.

В этом примере используется рекомендуемый синтаксис "тильда" для последней доступной версии среды выполнения Node.js 16 в Службе приложений.

Так как среда выполнения регулярно обновляется и обновляется платформой, мы не рекомендуем использовать конкретную дополнительную версию или исправление, так как они не гарантируют доступность из-за потенциальных рисков безопасности.

Примечание.

Необходимо задать версию Node.js в package.json проекта. Подсистема развертывания выполняется в отдельном процессе, который содержит все поддерживаемые версии Node.js.

Чтобы настроить для приложения поддерживаемую версию Node.js, выполните следующую команду в Cloud Shell:

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

Этот параметр указывает версию Node.js для использования как во время выполнения, так и во время автоматического восстановления пакета в Kudu.

Примечание.

Необходимо задать версию Node.js в package.json проекта. Подсистема развертывания выполняется в отдельном контейнере, который содержит все поддерживаемые версии Node.js.

Получение номера порта группы

Приложение Node.js должно прослушивать правильный порт для получения входящих запросов.

В Службе приложений в Windows приложения Node.js размещаются с помощью IISNode. Ваше приложение Node.js должно ожидать передачи данных в порте, указанном в переменной process.env.PORT. В следующем примере показано, как это сделать в простом приложении Express:

Служба приложений устанавливает переменную среды PORT в контейнере Node.js и перенаправляет входящие запросы в контейнер по этому номеру порта. Чтобы получать запросы, приложение должно ожидать передачи данных в этом порте с использованием process.env.PORT. В следующем примере показано, как это сделать в простом приложении 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}`)
})

Настройка автоматизации сборки

При развертывании приложения с помощью Git или с помощью zip-пакетов с включенной автоматизацией сборки Служба приложений выполняется следующая последовательность.

Запустите пользовательский скрипт, если он указан.PRE_BUILD_SCRIPT_PATH
Запустите npm install без флагов. Будут включены скрипты npm preinstall и postinstall, а также выполнена установка devDependencies.
Выполните npm run build, если в package.json выбран скрипт build.
Выполните npm run build:azure, если в package.json выбран скрипт build:azure.
Запустите пользовательский скрипт, если он указан POST_BUILD_SCRIPT_PATH.

Примечание.

Как отмечается в документации npm, скрипты с именем prebuild и postbuild выполнением до и после buildних соответственно, если задано. preinstall и postinstall выполняются до и после install соответственно.

PRE_BUILD_COMMAND и POST_BUILD_COMMAND являются переменными среды, которые по умолчанию пустые. Чтобы выполнить команды перед сборкой, определите PRE_BUILD_COMMAND. Чтобы выполнить команды после сборки, определите POST_BUILD_COMMAND.

В следующем примере используются две переменные для указания ряда команд, разделенных запятыми.

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"

Сведения о дополнительных переменных среды для настройки автоматизации сборки см. в разделе "Конфигурация Oryx".

Дополнительные сведения о том, как Служба приложений выполняет и создает приложения Node.js в Linux, см. в статье документации по Oryx "Обнаружение и создание приложений Node.js".

Настройка сервера Node.js

Контейнеры Node.js поставляются с PM2, диспетчером рабочих процессов. Вы можете настроить приложение для запуска с PM2, с помощью npm start или с помощью настраиваемой команды.

Средство	Характер использования
Запуск с помощью PM2	Рекомендуется для рабочей или промежуточной среды. PM2 предоставляет платформу для управления рабочими приложениями.
Запуск с помощью npm start	Только для разработки.
Запуск с помощью настраиваемой команды	Для разработки или промежуточной среды.

Запуск с помощью PM2

Контейнер автоматически запускает приложение с помощью PM2, когда в проекте обнаруживается один из распространенных файлов Node.js:

bin/www;
server.js
app.js
index.js
hostingstart.js;
Один из следующих файлов PM2: process.json или ecosystem.config.js

Кроме того, вы можете настроить пользовательский файл запуска со следующими расширениями:

файл .js;
файл PM2 с расширением .json, .config.js, .yamlили .yml.

Примечание.

Начиная с версии Node 14 LTS контейнер не запускает приложение автоматически с помощью PM2. Чтобы запустить приложение с помощью PM2, задайте для команды startup значение pm2 start <.js-file-or-PM2-file> --no-daemon. Используйте аргумент --no-daemon, так как служба PM2 должна выполняться на переднем плане для правильной работы контейнера.

Чтобы добавить пользовательский файл запуска, выполните следующую команду в Cloud Shell:

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

Запуск с помощью настраиваемой команды

Служба приложений может запустить приложение с помощью пользовательской команды, такой как исполняемый файл, например run.sh. Например, чтобы запустить npm run start:prod, выполните следующую команду в Cloud Shell:

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

Запуск с помощью npm start

Чтобы запустить приложение с помощью npm start, просто убедитесь, что сценарий start находится в файле package.js. Например:

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

Чтобы использовать в проекте настраиваемый файл package.js, выполните следующую команду в Cloud Shell:

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

Удаленная отладка

Вы можете выполнить удаленную отладку приложения Node.js в Visual Studio Code, настроив этот инструмент для работы с PM2, если вы не используете для запуска .config.js, .yml или .yaml.

В большинстве случаев для приложения дополнительная настройка не требуется. Если приложение запускается с файлом process.json (по умолчанию или настраиваемым), оно должно иметь свойство script в корне JSON. Например:

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

Чтобы настроить Visual Studio Code для удаленной отладки, установите расширение Службы приложений. Следуйте инструкциям на странице расширения и войдите в Azure в Visual Studio Code.

В обозревателе Azure найдите приложение, которое нужно отладить, щелкните его правой кнопкой мыши и выберите команду Start Remote Debugging (Запустить удаленную отладку). Выберите "Да", чтобы включить удаленную отладку для приложения. Служба приложений запустит прокси-сервер туннеля и присоединит отладчик. Затем можно выполнить запросы к приложению и увидеть, что отладчик приостанавливается в точках останова.

После отладки закройте отладчик, выбрав команду Отключить. При появлении запроса необходимо выбрать "Да" , чтобы отключить удаленную отладку. Чтобы отключить ее позже, снова щелкните свое приложение в Azure Explorer и выберите команду Disable Remote Debugging (Отключить удаленную отладку).

Доступ к переменным среды

В Службе приложений можно задать параметры приложения вне кода приложения. Затем вы сможете получать к ним доступ, используя стандартный шаблон Node.js. Например, для доступа к параметру приложения с именем NODE_ENV используйте следующий код:

process.env.NODE_ENV

Запуск Grunt/Bower/Gulp

По умолчанию Служба приложений автоматизация сборки выполняется npm install --production при распознавании того, что приложение Node.js развертывается через Git или с помощью развертывания Zip с включенной автоматизацией сборки. Если приложению требуются какие-либо популярные средства автоматизации, такие как Grunt, Bower или Gulp, вам необходимо предоставить пользовательский скрипт развертывания для запуска приложения.

Чтобы разрешить репозиторию запускать эти средства, необходимо добавить их в зависимости в файле package.json. Например:

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

В окне локального терминала измените каталог в корневой каталог репозитория и выполните следующие команды:

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

Корень репозитория теперь содержит два дополнительных файла: .deployment и deploy.sh.

Откройте файл deploy.sh и найдите раздел Deployment, который выглядит следующим образом:

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

В конце этого раздела запускается npm install --production. Добавьте раздел кода для запуска необходимого инструмента в конец раздела Deployment:

Bower
Gulp;
Grunt

См. пример MEAN.js, где скрипт развертывания также выполняет пользовательскую команду npm install.

Bower

Этот фрагмент кода отвечает за запуск 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

Этот фрагмент кода отвечает за запуск 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

Этот фрагмент кода отвечает за запуск grunt.

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

Обнаружение сеанса HTTPS

В Службе приложений завершение TLS/SSL-запросов происходит в подсистеме балансировки нагрузки сети, поэтому все HTTPS-запросы достигают вашего приложения в виде незашифрованных HTTP-запросов. Если логика приложения должна проверить, шифруются ли запросы пользователей, проверьте X-Forwarded-Proto заголовок.

Популярные веб-платформы позволяют получить доступ к информации X-Forwarded-* в стандартном шаблоне приложения. В Express можно использовать доверенные прокси-серверы. Например:

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

Доступ к журналам диагностики

Чтобы получить доступ к журналам консоли, созданным в коде приложения в Службе приложений, включите ведение журнала диагностики, выполнив следующую команду в Cloud Shell:

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

Возможные значения для --level: Error, Warning, Info и Verbose. Каждый последующий уровень включает предыдущий уровень. Например: Error включает только сообщения об ошибках, а Verbose включает все сообщения.

Включив ведение журнала диагностики, выполните следующую команду, чтобы просмотреть поток данных журнала:

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

Если журналы консоли не отображаются, проверьте еще раз через 30 секунд.

Примечание.

Вы также можете проверить файлы журнала в браузере на странице https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Чтобы остановить потоковую передачу журналов, нажмите клавиши Ctrl+C.

Можно получить доступ к журналам консоли, которые были созданы в контейнере.

Сначала включите ведение журнала контейнера, выполнив следующую команду:

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

Замените <app-name> и <resource-group-name> именами, подходящими для вашего веб-приложения.

После включения ведения журнала контейнера, выполните следующую команду, чтобы просмотреть поток данных журнала.

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

Если журналы консоли не отображаются, проверьте еще раз через 30 секунд.

Чтобы остановить потоковую передачу журналов, нажмите клавиши CTRL+C.

Вы также можете проверить файлы журнала в браузере на странице https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Перезаписи URL-адресов

При развертывании приложений Node.js в службе приложение Azure для Linux может потребоваться обрабатывать перезаписи URL-адресов непосредственно в приложении. Это особенно полезно для обеспечения перенаправления определенных шаблонов URL-адресов на правильные конечные точки без использования конфигураций веб-сервера. Существует несколько способов выполнения перезаписи URL-адресов в Node.js. Одним из примеров является пакет express-urlrewrite .

Мониторинг с помощью Application Insights

Application Insights позволяет отслеживать производительность, исключения и использование приложения без внесения изменений в код. Чтобы подключить агент Application Insights, перейдите к веб-приложению на портале, выберите Application Insights в разделе "Параметры" и нажмите кнопку "Включить Application Insights". Затем выберите существующий ресурс Application Insights или создайте новый ресурс. Наконец, нажмите кнопку Применить в нижней части страницы. Инструкции по инструментированию веб-приложения с помощью PowerShell

Этот агент отслеживает приложение Node.js на стороне сервера. Чтобы отслеживать JavaScript на стороне клиента, добавьте в проект пакет SDK для JavaScript.

Дополнительные сведения см. в статье Заметки о выпуске расширения Application Insights.

Устранение неполадок

Если рабочее приложение Node.js неправильно функционирует в Службе приложений или его работа сопровождается ошибками, попробуйте сделать следующее:

Получите доступ к потоку журнала.
Протестируйте приложение локально в рабочем режиме. Служба приложений запускает приложения Node.js в рабочем режиме, поэтому вам необходимо убедиться в том, что проект работает надлежащим образом локально в рабочем режиме. Например:
- В зависимости от package.json различные пакеты могут быть установлены в рабочем режиме (dependencies vs. devDependencies).
- Некоторые веб-платформы могут развертывать статические файлы по-разному в рабочем режиме.
- Некоторые веб-платформы могут использовать пользовательские скрипты запуска при выполнении в рабочем режиме.
Запустите свое приложение в Службе приложений в режиме разработки. Например, в MEAN.js можно задать режим разработки приложения во время выполнения, задав NODE_ENV параметр приложения.

У вас нет разрешения на просмотр этого каталога или страницы

После развертывания кода Node.js в собственном приложении Windows в Служба приложений вы можете увидеть сообщение You do not have permission to view this directory or page в браузере при переходе по URL-адресу приложения. Скорее всего, у вас нет файла web.config . (См. шаблон и пример.)

При развертывании файлов с помощью Git или при использовании развертывания на основе ZIP-файла с включенной автоматизацией сборки подсистема развертывания автоматически создает файл web.config в корневом веб-каталоге приложения (%HOME%\site\wwwroot) при соблюдении одного из следующих условий:

Корневой каталог проекта содержит файл package.json, который определяет скрипт start, содержащий путь к файлу JavaScript.
Корневой каталог проекта содержит файл server.js или app.js.

Созданный файл web.config адаптирован к обнаруженному скрипту запуска. Для других методов развертывания добавьте этот файл web.config вручную. Убедитесь, что файл правильно отформатирован.

Если вы используете развертывание ZIP (например, с помощью Visual Studio Code), обязательно включите автоматизацию сборки. По умолчанию она отключена. az webapp up использует развертывание на основе ZIP-файла с включенной автоматизацией сборки.

robots933456 в журналах

В журналах контейнера может отобразиться следующее сообщение:

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

Это сообщение можно проигнорировать. /robots933456.txt — это фиктивный URL-путь, с помощью которого Служба приложений проверяет, может ли контейнер обслуживать запросы. Ответ 404 означает, что путь не существует. При этом он информирует Службу приложений о том, что контейнер работоспособен и готов отвечать на запросы.

Следующие шаги

Руководство по Node.js приложению с MongoDB

Служба приложений Azure на платформе Linux: вопросы и ответы

Дополнительные ресурсы:

Справка по переменным среды и параметрам приложений

Поделиться через

Настройка приложения Node.js для Службы приложений Azure

Просмотр версии Node.js

Выбор версии Node.js

Получение номера порта группы

Настройка автоматизации сборки

Настройка сервера Node.js

Запуск с помощью PM2

Запуск с помощью настраиваемой команды

Запуск с помощью npm start

Удаленная отладка

Доступ к переменным среды

Запуск Grunt/Bower/Gulp

Bower

Gulp

Grunt

Обнаружение сеанса HTTPS

Доступ к журналам диагностики

Перезаписи URL-адресов

Мониторинг с помощью Application Insights

Устранение неполадок

У вас нет разрешения на просмотр этого каталога или страницы

robots933456 в журналах

Следующие шаги

Обратная связь

Дополнительные ресурсы