Настройка приложения 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, перейдите по адресу 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.

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

Замените #D0 и #D1 именами, подходящими для веб-приложения.

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

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

Игнорировать сообщение робота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

Bower

Gulp

Ворчание

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

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

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

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

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

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

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

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

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

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