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

Мақала
06/01/2023

Приложения 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 или пользовательской команды.

Инструмент	Назначение
Запуск с помощью 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.

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

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

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

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

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

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

Получите доступ к потоку журнала.
Протестируйте приложение локально в рабочем режиме. Служба приложений запускает приложения Node.js в рабочем режиме, поэтому вам необходимо убедиться в том, что проект работает надлежащим образом локально в рабочем режиме. Пример:
- В зависимости от содержимого файла package.json для рабочего режима могут быть установлены разные пакеты (dependencies или 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

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

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

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

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

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

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

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

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

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

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

Пользовательская команда

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

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

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

Запуск Grunt/Bower/Gulp

Bower

Gulp

Grunt

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

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

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

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

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

robots933456 в журналах

Дальнейшие действия

Қосымша ресурстар