教學課程:使用 Linux 上的 App Service 和 PostgreSQL 建置 Quarkus Web 應用程式
本教學課程示範如何在連線至 PostgreSQL 資料庫的 Azure App Service 中建置、設定及部署安全的 Quarkus 應用程式 (使用 適用於 PostgreSQL 的 Azure 資料庫)。 Azure App Service 是高度可調整、自我修補的 Web 裝載服務,可輕鬆在 Windows 或 Linux 上部署應用程式。 完成後,Linux 上的 Azure App Service 上將會執行 Quarkus 應用程式。
若要完成本教學課程,您需要:
- 具有有效訂用帳戶的 Azure 帳戶。 如果您沒有 Azure 帳戶,可以建立一個免費帳戶。
- 已安裝 Azure Developer CLI。 您可以遵循 Azure Cloud Shell 的步驟,因為這已安裝 Azure Developer CLI。
- 使用 Tomcat 開發瞭解 Java。
跳到結尾
您可以在本教學課程中快速部署範例應用程式,並查看它在 Azure 中執行。 只要在 Azure Cloud Shell 中執行下列命令,然後遵循提示:
mkdir msdocs-quarkus-postgresql-sample-app
cd msdocs-quarkus-postgresql-sample-app
azd init --template msdocs-quarkus-postgresql-sample-app
azd up
1.執行範例
首先,您會將範例數據驅動應用程式設定為起點。 為了方便起見,範例存放庫 (使用 Panache 和 RESTEasy 的休眠 ORM) 包含開發容器設定。 開發容器具有開發應用程式所需的全部內容,包括資料庫、快取,以及範例應用程式所需的所有環境變數。 開發容器可以在 GitHub codespace 中執行,這表示您可以在任何電腦上使用網頁瀏覽器執行範例。
第 1 步:在新的瀏覽器視窗中:
- 登入您的 GitHub 帳戶。
- 瀏覽至 https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app/fork。
- 取消選取 [僅複製主要分支]。 您想要所有分支。
- 選取 [建立派生]。
步驟 2: 在 GitHub 分支中:
- 選取入門分支的主要>入門-no-infra。 此分支只包含範例專案,且沒有與 Azure 相關的檔案或組態。
- 選取 main 上的 [程式代碼建立程式代碼>空間]。 程式代碼空間需要幾分鐘的時間才能設定。
步驟 3:在 codespace 終端機中:
- 執行
mvn quarkus:dev
。 - 當您看到通知
Your application running on port 8080 is available.
時,請選取 [在瀏覽器中開啟]。 如果您看到包含連接埠 5005 的通知,請略過。 您應該會在新的瀏覽器索引標籤中看到應用程式範例。若要停止 Quarkus 開發伺服器,請輸入Ctrl
+C
。
如需 Quarkus 應用程式範例建立方式的詳細資訊,請參閱 Quarkus 文件簡化休眠 ORM 與 Panache 和在 Quarkus 中設定資料來源。
有問題嗎? 查看疑難排解區段。
2.建立 App Service 和 PostgreSQL
首先,您會建立 Azure 資源。 本教學課程中使用的步驟會建立一組預設保護資源,其中包含 App Service 和 Azure Database for PostgreSQL。 針對建立程序,您將指定:
- Web 應用程式的 [名稱]。 此名稱會以
https://<app-name>.azurewebsites.net
的形式作為 Web 應用程式 DNS 名稱的一部分。 - 要實際執行應用程式的區域。
- 應用程式的執行階段堆疊。 您可以在此處選取要用於應用程式的 Java 版本。
- 應用程式的主控方案。 這是定價層,其中包含應用程式的一組功能和調整限度。
- 應用程式的 [資源群組]。 資源群組允許您將應用程式所需的所有 Azure 資源分組 (在邏輯容器中)。
登入 Azure 入口網站,遵循下列步驟建立您的 Azure App Service 資源。
步驟 1:在 Azure 入口網站中:
- 在 Azure 入口網站頂端的搜尋列中輸入「Web 應用程式資料庫」。
- 選取 [Marketplace] 標題下標示為 [Web 應用程式 + 資料庫] 的項目。 您也可以直接瀏覽至建立精靈。
步驟 2:在 [建立 Web 應用程式 + 資料庫] 頁面上,填寫表單,如下所示。
- 資源群組:選取 [新建],並使用 msdocs-quarkus-postgres-tutorial 的名稱。
- 區域:您附近的任何 Azure 區域。
- 名稱:msdocs-quarkus-postgres-XYZ,其中 XYZ 是任三個隨機字元。 此名稱在整個 Azure 中必須是唯一的。
- 運行時間堆疊: Java 17。
- Java Web 伺服器堆疊: Java SE (內嵌 Web 伺服器) 。
- 資料庫: PostgreSQL - 彈性伺服器。 伺服器名稱和資料庫名稱預設會設定為適當的值。
- 主控方案: 基本。 當一切就緒時,您可以在之後擴大至生產定價層。
- 選取 [檢閱 + 建立]。
- 驗證完成時,選取 [建立]。
步驟 3:部署需要數分鐘的時間才能完成。 在部署完成時,選取 [前往資源] 按鈕。 系統會將您直接帶至 App Service 應用程式,但會建立下列資源:
- 資源群組:所有已建立資源的容器。
- App Service 方案:定義 App Service 的計算資源。 系統會建立基本層中的 Linux 方案。
- App Service:代表您的應用程式,並在 App Service 方案中執行。
- 虛擬網路:與 App Service 應用程式整合,並隔離後端網路流量。
- 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器:只能從虛擬網路記憶體取。 系統會為您在伺服器上建立資料庫和使用者。
- 私用 DNS 區域:啟用虛擬網路中 PostgreSQL 伺服器的 DNS 解析。
有問題嗎? 查看疑難排解區段。
3.驗證連線設定
建立精靈已為您產生連線變數做為應用程式設定。 在此步驟中,您將瞭解如何尋找應用程式設定,以及如何建立自己的設定。
應用程式設定是將連線秘密保留在程式碼存放庫外部的一個方法。 當您準備好將祕密移至更安全的位置時,您可以改用 Key Vault 參考。
步驟 1: 在 App Service 頁面中,選取左側功能表中 的 [環境變數]。
步驟 2:在 [環境變數] 頁面的 [應用程式設定] 索引標籤中,確認是否存在AZURE_POSTGRESQL_CONNECTIONSTRING
。 其會在執行階段插入做為環境變數。
步驟 4: 選取 [ 新增應用程式設定]。 將設定命名為 PORT
,並將其值設定為 8080
,這是 Quarkus 應用程式的預設連接埠。 選取套用。
步驟 5: 選取 [ 套用],然後選取 [ 確認]。
有問題嗎? 查看疑難排解區段。
4.部署範例程式碼
在此步驟中,您將使用 GitHub Actions 來設定 GitHub 部署。 這只是部署至 App Service 的許多方式之一,但也是在部署程序中持續整合的絕佳方式。 根據預設,您 GitHub 存放庫的每個 git push
都會開始建置和部署動作。
請注意以下要點:
- 您部署的 Java 套件必須是 Uber-Jar。
- 為了簡化本教學課程,您將在部署程序期間停用測試。 GitHub Actions 執行器無法存取 Azure 中的 PostgreSQL 資料庫,因此任何需要資料庫存取的整合測試都會失敗,例如 Quarkus 應用程式範例的情況。
步驟 1:回到 [App Service] 頁面上的左側功能表,選取 [部署中心]。
步驟 2:在 [部署中心] 頁面中:
- 在 [來源] 中,選取 [GitHub]。 根據預設,系統會選取 GitHub Actions 作為組建提供者。
- 登入您的 GitHub 帳戶,並遵循提示來授權 Azure。
- 在 [組織] 中,選取您的帳戶。
- 在 [存放庫] 中,選取 msdocs-quarkus-postgresql-sample-app。
- 在 [分支] 中,選取 starter-no-infra。
- 在 [驗證類型] 中,選取 [使用者指派的身分識別 (預覽)]。
- 在最上層的功能表中,選取 [儲存]。 App Service 會將工作流程檔案認可至
.github/workflows
目錄中選擇的 GitHub 存放庫。
步驟 3:回到範例分支的 GitHub codespace 中,執行 git pull origin starter-no-infra
。
這會將新認可的工作流程檔案提取到您的 Codespace。
步驟 4:
- 在總管中開啟 src/main/resources/application.properties。 Quarkus 會使用此檔案來載入 Java 屬性。
- 尋找批注程序代碼(第 10-11 行),並取消批注。
此程式代碼會將生產變數
%prod.quarkus.datasource.jdbc.url
設定為您建立精靈的應用程式設定。 設定quarkus.package.type
為建置Uber-Jar,您必須在App Service中執行。
步驟 5:
- 在總管中開啟 .github/workflows/main_msdocs-quarkus-postgres-XYZ.yml。 此檔案是由 App Service 建立精靈所建立。
- 在
Build with Maven
步驟下,將 Maven 命令變更為mvn clean install -DskipTests
。-DskipTests
略過 Quarkus 專案中的測試,以避免 GitHub 工作流程過早失敗。
步驟 6:
- 選取 [原始檔控制] 延伸模組。
- 在文字方塊中,輸入提交訊息,例如
Configure DB and deployment workflow
。 - 選取 [認可],然後使用 [是] 來確認。
- 選取 [ 同步變更 1],然後確認 [ 確定]。
步驟 7:返回 Azure 入口網站的 [部署中心] 頁面:
- 選取 [記錄] 。 新的部署執行已從您認可的變更開始。
- 在部署執行的記錄項目中,選取最新時間戳記的 [建置/部署記錄] 項目。
步驟 8:您會前往 GitHub 存放庫,並看到 GitHub 動作正在執行。 工作流程檔案會定義兩個不同的階段:建置和部署。 等候 GitHub 執行到顯示 [完成] 狀態。 需要約 5 分鐘的時間。
有問題嗎? 查看疑難排解區段。
5.瀏覽至應用程式
步驟 1:在 [App Service] 頁面中:
- 從左側功能表中選取 [概觀]。
- 選取應用程式的 URL。 您也可以直接瀏覽至
https://<app-name>.azurewebsites.net
。
步驟 2:將一些水果新增至清單。 恭喜,您正在 Azure App Service 中執行 Web 應用程式,並安全地連線至 PostgreSQL 的適用於 PostgreSQL 的 Azure 資料庫。
6.資料流診斷記錄
Azure App Service 會擷取輸出到主控台的所有訊息,以協助您診斷應用程式的問題。 如下所示,應用程式範例包含可示範這項功能的標準 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:在 [App Service] 頁面中:
- 從左側功能表中,選取 [App Service 記錄]。
- 在 [應用程式記錄] 下,選取 [檔案系統]。
- 在最上層的功能表中,選取 [儲存]。
步驟 2:從左側功能表中,選取 [記錄串流]。 您會看到應用程式的記錄,包括平台記錄和來自容器內的記錄。
在啟用適用於 .NET、Node.js、Python 和 Java 應用程式的 Azure 監視器 OpenTelemetry 系列中深入了解 Java 應用程式中的記錄。
7.清除資源
完成後,您可以刪除資源群組,以從 Azure 訂用帳戶中刪除所有資源。
步驟 1:在 Azure 入口網站頂端的搜尋列中:
- 輸入資源群組名稱。
- 選取資源群組。
步驟 2:在資源群組頁面中,選取 [刪除資源群組]。
步驟 3:
- 輸入資源組名來確認刪除。
- 選取 [刪除]。
- 再次使用 [刪除] 來確認。
2.建立 Azure 資源並部署範例應用程式
在此步驟中,您會建立 Azure 資源,並將範例應用程式部署至 Linux 上的 App Service。 本教學課程中使用的步驟會建立一組預設保護資源,其中包含 App Service 和 Azure Database for PostgreSQL。
開發容器已經有 Azure 開發人員 CLI (AZD)。
從存放庫根路徑中執行
azd init
。azd init --template javase-app-service-postgresql-infra
出現提示時,請提供下列答案:
問題 回答 繼續在 『<your-directory>』 中初始化應用程式? Y 您要對這些檔案執行什麼動作? 維持現有的檔案不變 輸入新的環境名稱 輸入唯一名稱。 AZD 樣本會使用此名稱作為 Azure 中 Web 應用程式的 DNS 名稱的一部分( <app-name>.azurewebsites.net
)。 允許英數字元與連字號。執行
azd auth login
命令並遵循提示來登入 Azure:azd auth login
建立必要的 Azure 資源,並使用
azd up
命令部署應用程式程式代碼。 請依照提示選取 Azure 資源所需的訂用帳戶和位置。azd up
命令
azd up
需要大約 15 分鐘才能完成(Redis 快取需要最多時間)。 這也會編譯及部署您的應用程式程序代碼,但稍後會修改程序代碼以使用 App Service。 執行時,命令會提供佈建和部署程式的相關資訊,包括 Azure 中部署的連結。 完成時,命令也會顯示部署應用程式的連結。此 AZD 範本包含使用下列 Azure 資源產生安全預設架構的檔案 (azure.yaml 和 infra directory):
- 資源群組:所有已建立資源的容器。
- App Service 方案:定義 App Service 的計算資源。 系統會建立 B1 層中的 Linux 方案。
- App Service:代表您的應用程式,並在 App Service 方案中執行。
- 虛擬網路:與 App Service 應用程式整合,並隔離後端網路流量。
- 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器:只能從私人端點後方存取。 系統會為您在伺服器上建立資料庫。
- Azure Cache for Redis:只能從虛擬網路記憶體取。
- 私用 DNS 區域:在虛擬網路中啟用資料庫伺服器和 Redis 快取的 DNS 解析。
- Log Analytics 工作區:做為應用程式寄送其記錄的目標容器,您也可以在其中查詢記錄。
- 金鑰保存庫:當您使用 AZD 重新部署時,用來保留資料庫密碼。
有問題嗎? 查看疑難排解區段。
3.驗證 連接字串
您使用的 AZD 範本已為您產生連線變數作為 應用程式設定 ,並將它們輸出至終端機,以方便您使用。 應用程式設定是將連線秘密保留在程式碼存放庫外部的一個方法。
在 AZD 輸出中,尋找應用程式設定
AZURE_POSTGRESQL_CONNECTIONSTRING
。 為了保護祕密安全,只會顯示設定名稱。 它們看起來像在 AZD 輸出中:App Service app has the following connection strings: - AZURE_POSTGRESQL_CONNECTIONSTRING - AZURE_REDIS_CONNECTIONSTRING
AZURE_POSTGRESQL_CONNECTIONSTRING
包含 Azure 中 PostgreSQL 資料庫的 連接字串。 您稍後必須在程式代碼中使用。為了方便起見,AZD 範本會顯示應用程式應用程式設定頁面的直接連結。 尋找連結,並在新的瀏覽器索引標籤中開啟。稍後,您將使用 AZD 新增應用程式設定,而不是在入口網站中新增。
有問題嗎? 查看疑難排解區段。
4.修改範例程式代碼並重新部署
回到範例分支的 GitHub 程式代碼空間中,開啟 infra/resources.bicep。
appSettings
尋找資源並批註 屬性PORT: '8080'
。 當您完成時,您的appSettings
資源看起來應該會像下列程式代碼:resource appSettings 'config' = { name: 'appsettings' properties: { PORT: '8080' } }
從總管中,開啟 src/main/resources/application.properties。
尋找批注程序代碼(第 10-11 行),並取消批注。
%prod.quarkus.datasource.jdbc.url=${AZURE_POSTGRESQL_CONNECTIONSTRING} quarkus.package.type=uber-jar
此程式代碼會將生產變數
%prod.quarkus.datasource.jdbc.url
設定為您建立精靈的應用程式設定。 設定quarkus.package.type
為建置Uber-Jar,您必須在App Service中執行。回到 Codespace 終端機,執行
azd up
。azd up
提示
azd up
實際上會執行azd package
、azd provision
與azd deploy
。azd provision
可讓您更新您在 infra/resources.bicep 中所做的 Azure 變更。azd deploy
上傳建置的 Jar 檔案。若要瞭解 Jar 檔案的封裝方式,您可以自行執行
azd package --debug
。
有問題嗎? 查看疑難排解區段。
5.瀏覽至應用程式
在 AZD 輸出中,尋找您應用程式的 URL,並在瀏覽器中瀏覽至它。 AZD 輸出中 URL 看起來像這樣:
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: https://<app-name>.azurewebsites.net/
將一些水果新增至清單。
恭喜,您正在 Azure App Service 中執行 Web 應用程式,並安全地連線至 PostgreSQL 的適用於 PostgreSQL 的 Azure 資料庫。
有問題嗎? 查看疑難排解區段。
6.資料流診斷記錄
Azure App Service 會擷取主控台記錄,以協助您診斷應用程式的問題。 為了方便起見,AZD 範本已 啟用本機檔系統 的記錄,並將 記錄傳送至 Log Analytics 工作區。
如下所示,應用程式範例包含可示範這項功能的標準 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"));
}
在 AZD 輸出中,尋找串流 App Service 記錄的連結,並在瀏覽器中瀏覽至它。 連結在 AZD 輸出中看起來像這樣:
Stream App Service logs at: https://portal.azure.com/#@/resource/subscriptions/<subscription-guid>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name>/logStream
在啟用適用於 .NET、Node.js、Python 和 Java 應用程式的 Azure 監視器 OpenTelemetry 系列中深入了解 Java 應用程式中的記錄。
有問題嗎? 查看疑難排解區段。
7.清除資源
若要刪除目前部署環境中的所有 Azure 資源,請執行 azd down
並遵循提示。
azd down
疑難排解
我看到錯誤記錄檔「ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource] (vert.x-eventloop-thread-0) 無法處理要求:jakarta.ws.rs.NotFoundException:HTTP 404 找不到」。
這是 Vert.x 錯誤 (請參閱 Quarkus 回應式架構),指出用戶端要求未知的路徑。 每個應用程式啟動時都會發生此錯誤,因為 App Service 會將 GET
要求傳送至 /robots933456.txt
,以驗證應用程式是否啟動。
應用程式無法啟動並在記錄中顯示下列錯誤:「模型類別是針對預設持續性單位<預設值>所定義,但已設定的資料來源<預設值>找不到:將不會建立預設 EntityManagerFactory。」
此 Quarkus 錯誤很可能是因為應用程式無法連線到 Azure 資料庫。 請確定應用程式設定 AZURE_POSTGRESQL_CONNECTIONSTRING
尚未變更,且 application.properties 已正確使用應用程式設定。
常見問題集
- 這設定會產生多少費用?
- 如何使用其他工具連線至虛擬網路後方受保護的 PostgreSQL 伺服器?
- 本機應用程式開發如何與 GitHub Actions 搭配運作?
- 如果我想要在 GitHub 工作流程期間使用 PostgreSQL 執行測試,該怎麼辦?
這設定會產生多少費用?
建立資源的定價如下:
- App Service 方案是在基本層中建立,並可擴大或縮小。 請參閱 App Service 定價。
- PostgreSQL 彈性伺服器是在最低的高載層 Standard_B1ms 中建立,搭配最少的儲存體大小,儲存體大小可以相應增加或減少。 請參閱 Azure PostgreSQL Database 定價。
- 除非您設定額外的功能 (例如對等互連),否則虛擬網路不會產生費用。 請參閱 Azure 虛擬網路定價。
- 私人 DNS 區域會產生少量費用。 請參閱 Azure DNS 定價。
如何使用其他工具連線至虛擬網路後方受保護的 PostgreSQL 伺服器?
- 若要從命令列工具進行基本存取,您可以從應用程式的 SSH 終端機執行
psql
。 - 若要從桌面工具連線,您的電腦必須位於虛擬網路內。 例如,該電腦可以是其中一個子網路中的 Azure VM,或內部部署網路中具有與 Azure 虛擬網路站對站 VPN 連線的電腦。
- 您也可以將 Azure Cloud Shell 與虛擬網路整合。
本機應用程式開發如何與 GitHub Actions 搭配運作?
使用 App Service 自動產生的工作流程檔案為例,每個 git push
都會開始執行新的組建和部署。 從 GitHub 存放庫的本機複本,並將所需的更新推送至 GitHub。 例如:
git add .
git commit -m "<some-message>"
git push origin main
如果我想要在 GitHub 工作流程期間使用 PostgreSQL 執行測試,該怎麼辦?
預設 Quarkus 應用程式範例包含具有資料庫連線能力的測試。 若要避免連線錯誤,您新增了 -skipTests
屬性。 如有需要,您可以針對 PostgreSQL 服務容器執行測試。 例如,在 GitHub 分支 (.github/workflows/main_cephalin-quarkus.yml) 中自動產生的工作流程檔案中,進行下列變更:
將 PostgreSQL 容器的 YAML 程式碼新增至
build
作業,如下列程式碼片段所示。... 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
中的連接字串就可以如往常運作。 如需 GitHub Actions 中 PostgreSQL 連線能力的詳細資訊,請參閱建立 PostgreSQL 服務容器。在
Build with Maven
步驟中,移除-DskipTests
。 例如:- name: Build with Maven run: mvn clean install
下一步
在開發人員指南中深入了解如何在 App Service 上執行 Java 應用程式。
了解如何使用自訂網域和憑證保障您的應用程式。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應