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

2024-09-13

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, выполните следующую команду в 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.

Что происходит с устаревшими средами выполнения в сервисе приложений?

Устаревшие среды выполнения сняты с поддержки поддерживающей организацией или имеют значительные уязвимости. Соответственно, они удаляются из страниц создания и настройки на портале. Если устаревшая среда выполнения скрыта на портале, любое приложение, которое по-прежнему используется этой средой выполнения, продолжает выполняться.

Если вы хотите создать приложение с устаревшей версией среды выполнения, которая больше не отображается на портале, используйте Azure CLI, шаблон ARM или Bicep. Эти варианты развертывания позволяют создавать устаревшие среды выполнения, которые были удалены на портале, но по-прежнему поддерживаются.

Если среда выполнения полностью удалена из платформы службы приложений, владелец подписки Azure получает уведомление по электронной почте перед удалением.

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

Приложение 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:

Бельведер
Gulp;
Хрюкать

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

Беседка

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

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 секунд.

Чтобы прекратить потоковую передачу журнала в любое время, нажмите 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.

Перезаписи 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-файла с включенной автоматизацией сборки.

Игнорировать сообщение робота933456 в журналах

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

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

Беседка

Глотать

Ворчание

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

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

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

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

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

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

Игнорировать сообщение робота933456 в журналах

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

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

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