Руководство. Создание веб-приложения Quarkus с помощью Службы приложений Azure в Linux и PostgreSQL

  • Статья

В этом руководстве показано, как создать, настроить и развернуть безопасное приложение Quarkus в службе приложение Azure, подключенной к базе данных PostgreSQL (с помощью База данных Azure для PostgreSQL). Служба приложений Azure — это высокомасштабируемая веб-служба с поддержкой самостоятельного исправления, которая позволяет легко развертывать приложения в Windows или Linux. По завершении вы получите приложение Quarkus, работающее в службе приложение Azure в Linux.

Screenshot of Quarkus application storing data in PostgreSQL.

Чтобы завершить работу с этим руководством, вам потребуется:

1. Запустите пример

Для удобства пример репозитория Hibernate ORM с Panache и RESTEasy включает конфигурацию контейнера разработки. Контейнер разработки имеет все необходимое для разработки приложения, включая базу данных, кэш и все переменные среды, необходимые образцу приложения. Контейнер разработки может выполняться в пространстве кода GitHub, что означает, что вы можете запустить пример на любом компьютере с веб-браузером.

Шаг 1. В новом окне браузера:

  1. Войдите в свою учетную запись GitHub.
  2. Перейдите к https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app.
  3. Выберите Создать вилку.
  4. Щелкните Создать вилку.

A screenshot showing how to create a fork of the sample GitHub repository.

Шаг 2. В вилке GitHub выберите пространство кода Create codespace>on main.

A screenshot showing how create a codespace in GitHub.

Шаг 3. В терминале пространства кода:

  1. Запустите mvn quarkus:dev.
  2. Когда появится уведомление Your application running on port 8080 is available., нажмите кнопку "Открыть в браузере". Если вы видите уведомление с портом 5005, пропустите его. Пример приложения должен отображаться на новой вкладке браузера. Чтобы остановить сервер разработки Quarkus, введите Ctrl+C.

A screenshot showing how to run the sample application inside the GitHub codespace.

Дополнительные сведения о создании примера приложения Quarkus см. в документации Quarkus по упрощению Hibernate ORM с помощью Panache и настройке источников данных в Quarkus.

2. Создание Служба приложений и PostgreSQL

Сначала вы создадите ресурсы Azure. Действия, используемые в этом руководстве, создают набор безопасных ресурсов по умолчанию, включающих Служба приложений и База данных Azure для PostgreSQL. В процессе создания вы укажете следующее:

  • Имя веб-приложения. Это имя используется в составе DNS-имени вашего веб-приложения в виде https://<app-name>.azurewebsites.net.
  • Регион для физического запуска приложения.
  • Стек среды выполнения для приложения. Здесь вы выбираете версию Java, используемую для вашего приложения.
  • План размещения для приложения. Это ценовая категория, которая включает набор функций и емкость масштабирования для вашего приложения.
  • Группа ресурсов для приложения. Группа ресурсов позволяет группировать (в логическом контейнере) все ресурсы Azure, необходимые для приложения.

Войдите на портал Azure и выполните следующие действия, чтобы создать ресурсы Службы приложений Azure.

Шаг 1. В портал Azure:

  1. Введите "веб-приложение база данных" в строке поиска в верхней части портала Azure.
  2. Выберите элемент с меткой Веб-приложение и база данных под заголовком Marketplace. Вы также можете перейти напрямую к мастеру создания.

A screenshot showing how to use the search box in the top tool bar to find the Web App + Database creation wizard.

Шаг 2. На странице "Создание веб-приложения + база данных " заполните форму следующим образом.

  1. Группа ресурсов → Выбрать создать и использовать имя msdocs-quarkus-postgres-tutorial.
  2. Регион → любой ближайший к вам регион Azure.
  3. Имя → msdocs-quarkus-postgres-XYZ, где XYZ является тремя случайными символами. Это имя должно быть уникальным в Azure.
  4. Стек среды выполнения → Java 17.
  5. Стек веб-серверов Java → Java SE (внедренный веб-сервер).
  6. База данных → PostgreSQL — гибкий сервер. Имя сервера и имя базы данных задаются по умолчанию соответствующими значениями.
  7. План размещения — Базовый. Позже, когда все будет готово, вы сможете вертикально увеличить масштаб до рабочей ценовой категории.
  8. Выберите Review + create (Просмотреть и создать).
  9. После завершения проверки щелкните Создать.

A screenshot showing how to configure a new app and database in the Web App + Database wizard.

Шаг 3. Развертывание занимает несколько минут. После завершения развертывания нажмите кнопку Перейти к ресурсу. Вы перейдете непосредственно в приложение Службы приложений, но будут созданы следующие ресурсы:

  • Группа ресурсов — Контейнер для всех созданных ресурсов.
  • План службы приложений — определяет вычислительные ресурсы для Службы приложений. Создается план Linux на уровне Базовый.
  • Служба приложений — представляет приложение и выполняется в плане службы приложений.
  • Виртуальная сеть — интегрирована с приложением Службы приложений и изолирует внутренний сетевой трафик.
  • База данных Azure для PostgreSQL гибкий сервер → доступен только из виртуальной сети. База данных и пользователь создаются на этом сервере.
  • Частная зона DNS зона → включает разрешение DNS сервера PostgreSQL в виртуальной сети.

A screenshot showing the deployment process completed.

3. Проверка параметров подключения

Мастер создания создал переменные подключения для вас уже в качестве параметров приложения. Параметры приложения — это один из способов сохранения секретов подключения из репозитория кода. Когда вы будете готовы переместить секреты в более безопасное расположение, вы можете использовать ссылки На Key Vault.

Шаг 1. На странице Служба приложений в меню слева выберите "Конфигурация".

A screenshot showing how to open the configuration page in App Service.

Шаг 2. На вкладке "Параметры приложения" на странице "Конфигурация" убедитесь, что AZURE_POSTGRESQL_CONNECTIONSTRING он присутствует. Он внедряется во время выполнения в качестве переменной среды.

A screenshot showing how to see the autogenerated connection string.

Шаг 4. На вкладке "Параметры приложения" на странице "Конфигурация" выберите новый параметр приложения. Присвойте параметру PORT имя и задайте для нее значение 8080, которое является портом по умолчанию приложения Quarkus. Нажмите ОК.

A screenshot showing how to set the PORT app setting in the Azure portal.

Шаг 5. Выберите "Сохранить".

A screenshot showing how to save the PORT app setting in the Azure portal.

Возникли проблемы? Ознакомьтесь с разделом "Устранение неполадок".

4. Развертывание примера кода

На этом шаге вы настроите развертывание GitHub с помощью GitHub Actions. Это всего лишь один из множества способов развертывания в Службе приложений, но это также отличный способ обеспечения непрерывной интеграции в процессе развертывания. По умолчанию каждая команда git push из репозитория GitHub запускает действие сборки и развертывания.

Обратите внимание на следующее:

  • Развернутый пакет Java должен быть Uber-Jar.
  • Для простоты руководства вы отключите тесты во время процесса развертывания. GitHub Actions runners не имеют доступа к базе данных PostgreSQL в Azure, поэтому все тесты интеграции, требующие доступа к базе данных, завершаются сбоем, например с примером приложения Quarkus.

Шаг 1. Вернитесь на страницу Служба приложений в меню слева выберите Центр развертывания.

A screenshot showing how to open the deployment center in App Service.

Шаг 2. На странице Центра развертывания:

  1. В поле Источник выберите GitHub. По умолчанию в качестве поставщика сборки выбрано GitHub Actions.
  2. Войдите в свою учетную запись GitHub и следуйте инструкциям по авторизации Azure.
  3. В поле Организация выберите свою учетную запись.
  4. В репозитории выберите msdocs-quarkus-postgresql-sample-app.
  5. В поле Ветвь выберите main.
  6. В типе проверки подлинности выберите назначаемое пользователем удостоверение (предварительная версия).
  7. В меню сверху выберите Сохранить. Служба приложений фиксирует файл рабочего процесса в выбранном репозитории GitHub в каталоге .github/workflows.

A screenshot showing how to configure CI/CD using GitHub Actions.

Шаг 3. Вернитесь в пространство кода GitHub примера вилки, выполните команду git pull origin main. Это извлекает только что зафиксированный файл рабочего процесса в пространство кода.

A screenshot showing git pull inside a GitHub codespace.

Шаг 4.

  1. Откройте src/main/resources/application.properties в обозревателе. Quarkus использует этот файл для загрузки свойств Java.
  2. Добавьте производственное свойство %prod.quarkus.datasource.jdbc.url=${AZURE_POSTGRESQL_CONNECTIONTRING}. Это свойство задает URL-адрес источника данных рабочей среды для параметра приложения, созданного мастером создания.

A screenshot showing a GitHub codespace and the application.properties file opened.

Шаг 5.

  1. Откройте github/workflows/main_msdocs-quarkus-postgres-XYZ.yml в обозревателе. Этот файл был создан мастером создания Служба приложений.
  2. На шаге измените Build with Maven команду mvn clean install -DskipTests -Dquarkus.package.type=uber-jarMaven на . -DskipTestsпропускает тесты в проекте Quarkus и -Dquarkus.package.type=uber-jar создает Uber-Jar, который Служба приложений потребностей.

A screenshot showing a GitHub codespace and a GitHub workflow YAML opened.

Шаг 6.

  1. Выберите расширение Система управления версиями.
  2. В текстовом поле введите сообщение фиксации, например Configure DB and deployment workflow.
  3. Нажмите кнопку "Зафиксировать", а затем подтвердите значение "Да".
  4. Нажмите кнопку "Синхронизировать изменения 2", а затем нажмите кнопку "ОК".

A screenshot showing the changes being committed and pushed to GitHub.

Шаг 7. Назад на странице Центра развертывания в портал Azure:

  1. Выберите Журналы. Новый запуск развертывания уже запущен из зафиксированных изменений.
  2. В элементе журнала для запуска развертывания выберите запись "Сборка и развертывание журналов " с последней меткой времени.

A screenshot showing how to open deployment logs in the deployment center.

Шаг 8. Вы перейдете в репозиторий GitHub и увидите, что действие GitHub выполняется. Файл рабочего процесса определяет два отдельных этапа: сборку и развертывание. Дождитесь, пока в выполнении действия GitHub не будет показано состояние Завершено. Это занимает около 5 минут.

A screenshot showing a GitHub run in progress.

Возникли проблемы? Ознакомьтесь с разделом "Устранение неполадок".

5. Перейдите к приложению

Шаг 1. На странице Служба приложений:

  1. В меню слева выберите Обзор.
  2. Выберите URL-адрес своего приложения. Также можно перейти непосредственно по адресу https://<app-name>.azurewebsites.net.

A screenshot showing how to launch an App Service from the Azure portal.

Шаг 2. Добавьте несколько фруктов в список. Поздравляем, вы запускаете веб-приложение в службе приложение Azure с безопасным подключением к База данных Azure для PostgreSQL.

A screenshot of the Quarkus web app with PostgreSQL running in Azure showing a list of fruits.

6. Потоковая передача журналов диагностики

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

private static final Logger LOGGER = Logger.getLogger(FruitEntityResource.class.getName());

@GET
public List<FruitEntity> get() {
    LOGGER.info("In FruitEntityResource.get()");
    return FruitEntity.listAll(Sort.by("name"));
}

Шаг 1. На странице Служба приложений:

  1. В меню слева выберите Журналы службы приложений.
  2. Под элементом Ведение журнала приложения выберите Файловая система.
  3. В меню сверху выберите Сохранить.

A screenshot showing how to enable native logs in App Service in the Azure portal.

Шаг 2. В меню слева выберите поток журналов. Вы увидите журналы для своего приложения, включая журналы платформы и журналы из контейнера.

A screenshot showing how to view the log stream in the Azure portal.

Узнайте больше о ведении журнала в приложениях Java в серии о включении Azure Monitor OpenTelemetry для приложений .NET, Node.js, Python и Java.

7. Очистка ресурсов

По завершении работы можно удалить все ресурсы из вашей подписки Azure, удалив соответствующую группу ресурсов.

Шаг 1. В строке поиска в верхней части портал Azure:

  1. Введите имя группы ресурсов.
  2. Выберите группу ресурсов.

A screenshot showing how to search for and navigate to a resource group in the Azure portal.

Шаг 2. На странице группы ресурсов выберите "Удалить группу ресурсов".

A screenshot showing the location of the Delete Resource Group button in the Azure portal.

Шаг 3.

  1. Введите имя группы ресурсов для подтверждения удаления.
  2. Выберите команду Удалить.
  3. Подтвердите еще раз с помощью удаления .

A screenshot of the confirmation dialog for deleting a resource group in the Azure portal. :

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

Я вижу журнал ошибок "ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource] (vert.x-eventloop-thread-0) Не удалось обработать запрос: jakarta.ws.rs.NotFoundException: HTTP 404 Not Found.

Это ошибка Vert.x (см . quarkus Reactive Architecture), указывающая, что клиент запрашивал неизвестный путь. Эта ошибка возникает при каждом запуске приложения, так как Служба приложений проверяет, начинается ли приложение, отправляя GET запрос /robots933456.txtв .

Приложение не удалось запустить и отображает следующую ошибку в журнале: "Классы моделей определены для единицы сохраняемости <по умолчанию по умолчанию> , но настроенный источник <данных не найден: объект EntityManagerFactory по умолчанию> не будет создан".

Эта ошибка Quarkus, скорее всего, связана с тем, что приложение не может подключиться к базе данных Azure. Убедитесь, что параметр AZURE_POSTGRESQL_CONNECTIONSTRING приложения не был изменен и что application.properties правильно использует параметр приложения.

Часто задаваемые вопросы

Сколько стоит такая конфигурация?

Цены на созданные ресурсы приведены следующим образом:

  • План службы приложений создается на уровне Базовый, и его можно масштабировать вверх или вниз. См. цены на Службу приложений.
  • Гибкий сервер PostgreSQL создается на самом низком уровне с максимальным объемом памяти Standard_B1ms с минимальным размером хранилища, который можно масштабировать вверх или вниз. Цены на Базу данных Azure для PostgreSQL.
  • Плата за виртуальную сеть не взимается, если только вы не настроите дополнительные функциональные возможности, такие как пиринг. См. цены на виртуальные сети Azure.
  • За частную зону DNS взимается небольшая плата. См. цены на Azure DNS.

Разделы справки подключиться к серверу PostgreSQL, защищенному за виртуальной сетью с другими средствами?

  • Для базового доступа из программы командной строки можно запустить psql из терминала SSH приложения.
  • Чтобы подключиться из классического средства, компьютер должен находиться в виртуальной сети. Например, это может быть виртуальная машина Azure в одной из подсетей или компьютер в локальной сети с VPN-подключением типа "сеть — сеть" с виртуальной сетью Azure.
  • Вы также можете интегрировать Azure Cloud Shell с виртуальной сетью.

Как осуществляется разработка локальных приложений с использованием GitHub Actions?

Используя автоматически созданный файл рабочего процесса из Служба приложений в качестве примера, каждый git push запускает новую сборку и развертывание. Из локального клона репозитория GitHub необходимо внести необходимые обновления и отправить их в GitHub. Например:

git add .
git commit -m "<some-message>"
git push origin main

Что делать, если нужно выполнить тесты с PostgreSQL во время рабочего процесса GitHub?

Пример приложения Quarkus по умолчанию включает тесты с подключением к базе данных. Чтобы избежать ошибок подключения, добавлено -skipTests свойство. Если вы хотите, можно выполнить тесты в контейнере службы PostgreSQL. Например, в автоматически созданном файле рабочего процесса в GitHub fork (.github/workflows/main_cephalin-quarkus.yml), внесите следующие изменения:

  1. Добавьте в задание код YAML для контейнера build PostgreSQL, как показано в следующем фрагменте кода.

    ...
jobs:
  build:
    runs-on: ubuntu-latest

    # BEGIN CODE ADDITION
    container: ubuntu
    services:
      # Hostname for the PostgreSQL container
      postgresdb:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_USER: postgres
          POSTGRES_DB: postgres
        # Set health checks to wait until postgres has started
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    # END CODE ADDITION

    steps:
      - uses: actions/checkout@v4
      ...

    container: ubuntu сообщает GitHub запустить build задание в контейнере. Таким образом, строка подключения в среде jdbc:postgresql://postgresdb:5432/postgres разработки может работать как во время выполнения рабочего процесса. Дополнительные сведения о подключении PostgreSQL в GitHub Actions см. в разделе "Создание контейнеров служб PostgreSQL".

  2. На шаге Build with Maven удалите -DskipTests. Например:

          - name: Build with Maven
        run: mvn clean install -Dquarkus.package.type=uber-jar

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

Дополнительные сведения о запуске приложений Java на Служба приложений см. в руководстве разработчика.

Настройка приложения Java в службе приложение Azure

Узнайте, как защитить приложение с помощью личного домена и сертификата.

 Защита с помощью личного домена и сертификата