教學課程:將 Quarkus Web 應用程式部署至 Azure App 服務 和 PostgreSQL

在本教學中,你會將 Java 25 資料驅動的 Quarkus 3.38.1 網頁應用程式部署至 Azure App 服務,並搭配 適用於 PostgreSQL 的 Azure 資料庫 flexible server 16。 AZD 工作流程也提供 Azure Managed Redis。 Azure App 服務 支援 Windows 或 Linux 伺服器環境中的 Java Standard Edition (Java SE)。

螢幕擷取畫面顯示將資料儲存在 PostgreSQL 中的 Quarkus 應用程式。

在本教學課程中,您將瞭解如何:

  • 為 Azure App 服務 和適用於 PostgreSQL 的 Azure 資料庫彈性伺服器建立安全預設架構。
  • 使用受控識別和 金鑰保存庫 參考來保護連線秘密。
  • 從 GitHub 存放庫將範例 Quarkus 應用程式部署至 App Service。
  • 存取應用程式程式代碼中的App Service 應用程式設定。
  • 進行更新並重新部署應用程式程式碼。
  • 執行資料庫移轉來產生資料庫架構。
  • 將診斷記錄從 Azure 串流出來。
  • 在 Azure 入口網站中管理應用程式。
  • 使用 Azure Managed Redis 配置擴展架構,並使用 Azure Developer CLI 部署。
  • 使用 GitHub Codespaces 和 GitHub Copilot 最佳化您的開發工作流程。

先決條件

跳到結尾

如果你只想看到這個教學中的範例應用程式在 Azure 上執行,請在 Azure Cloud Shell 執行以下指令並依照提示操作。 環境名稱不得超過 25 個字元,以確保產生的 Azure Managed Redis 名稱符合跨區域命名限制。

git clone https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app
cd msdocs-quarkus-postgresql-sample-app
azd auth login
azd env new <environment-name>
azd provision --preview
azd up

1.執行範例

首先,建立一個以數據為基礎的範例應用程式作為起點。 為了方便起見,範例存放庫 (使用 Panache 和 RESTEasy 的休眠 ORM) 包含開發容器設定。 開發容器提供 Java 25、開發工具、PostgreSQL 16 以及本地執行範例所需的環境變數。 它沒有提供本地 Redis 服務。 開發容器可以在 GitHub codespace 中執行,這表示您可以在任何電腦上使用網頁瀏覽器執行範例。

第 1 步:在新的瀏覽器視窗中:

  1. 使用您的 GitHub 帳戶登入。
  2. 瀏覽至 https://github.com/Azure-Samples/msdocs-quarkus-postgresql-sample-app/fork。
  3. 取消選取 [僅複製主分支]。 您想要所有分支。
  4. 選取 [建立派生]。

步驟 2:在 GitHub 分支中:

  1. 為起始分支選取 [主分支]> [starter-no-infra]。 此分支只包含範例專案,沒有與 Azure 相關的檔案或設定。
  2. 選取 程式碼>在 starter-no-infra 上創建程式空間。 設定 Codespace 需要幾分鐘的時間。

步驟 2:在 GitHub fork 中,維持選取 main,然後選取 Code>Create codespace on main。 此分支包含範例應用及其 AZD 配置。 設定 Codespace 需要幾分鐘的時間。

步驟 3:在 codespace 終端機中:

  1. 執行 mvn quarkus:dev。
  2. 忽略通知 Your application running on port 5005 is available.
  3. 當您看到通知 Your application running on port 8080 is available. 時,請選取 [在瀏覽器中開啟]。 您應該會在新的瀏覽器索引標籤中看到應用程式範例。若要停止 Quarkus 程式開發伺服器,請輸入 Ctrl+C。 Java 25 的首次啟動可能需要幾分鐘,因為 Maven 需要下載相依項目,而 Quarkus 也需要完成初始化。

如需 Quarkus 應用程式範例建立方式的詳細資訊,請參閱 Quarkus 文件簡化休眠 ORM 與 Panache 和在 Quarkus 中設定資料來源。

秘訣

您可以向 GitHub Copilot 詢問此存放庫。 例如:

  • @workspace 此專案有何用途?
  • @workspace .devcontainer 資料夾的功能為何?

有問題嗎? 查看疑難排解區段。

2. 建立 App Service 和 PostgreSQL

在此步驟中,你建立入口網站工作流程的 Azure 資源。 完成的應用程式使用 Java 25、Quarkus 3.38.1 以及 適用於 PostgreSQL 的 Azure 資料庫 flexible server 16。 在建立流程中,請指定:

  • Web 應用程式的 [名稱]。 其會以 https://<app-name>-<hash>.<region>.azurewebsites.net 的形式作為您應用程式 DNS 名稱的一部分來使用。
  • 要實際執行應用程式的區域。 其也會作為您應用程式的 DNS 名稱的一部分來使用。
  • 應用程式的執行階段堆疊。 您可以在此處選取要用於應用程式的 Java 版本。
  • 應用程式的主控方案。 這是定價層,其中包含應用程式的一組功能和調整限度。
  • 應用程式的 [資源群組]。 資源群組允許您將應用程式所需的所有 Azure 資源分組 (在邏輯容器中)。

登入 Azure 入口網站,遵循下列步驟建立您的 Azure App 服務 資源。

步驟 1: 在 Azure 入口網站中:

  1. 在頂端搜尋列中,輸入 App Service。
  2. 請在 [服務] 標題下選取標示為 App Service 的項目。
  3. 選取 [建立>Web 應用程式]。 您也可以直接瀏覽至建立精靈。

步驟 2:設定新的應用程式 填寫表單,如下所示。

  1. 名稱: msdocs-quarkus-postgres。 已為您建立名為 msdocs-quarkus-postgres_group 的資源群組。
  2. 執行時堆疊:Java 25。
  3. Java 網頁伺服器堆疊:Java SE (內嵌網頁伺服器)。
  4. 作系統: Linux。
  5. [區域]:您附近的任何 Azure 區域。
  6. Linux 方案: 新建 並使用 msdocs-quarkus-postgres 名稱。
  7. 定價方案:基本 B1。 準備好時,您可以 升級 至不同的定價層。

步驟 3:新增資料庫

  1. 選取 資料庫 索引標籤。
  2. 選取 [建立資料庫]。
  3. 在 [引擎] 中,選取 [PostgreSQL - 彈性伺服器]。 伺服器名稱和資料庫名稱預設會設定為適當的值。
  4. 在 PostgreSQL 版本中,選擇或驗證 16。

步驟 4:設定 GitHub 部署

  1. 選取 [部署] 索引標籤。
  2. 選取 [持續部署]。
  3. 如果這是您第一次在 App Service 中設定 GitHub 部署,請選取 [ 授權 ] 並使用您的 GitHub 帳戶進行驗證。
  4. 在 [組織] 中,選取您的 GitHub 別名。
  5. 在 [存放庫] 中,選取 msdocs-quarkus-postgresql-sample-app。
  6. 在 [分支] 中,選取 [starter-no-infra]。
  7. 選取 [檢閱 + 建立]。
  8. 驗證完成時,選取 [建立]。 根據預設,建立精靈 會建立使用者指派的身分識別 ,讓工作流程使用 Microsoft Entra (OIDC 驗證) 進行驗證。 如需替代驗證選項,請參閱使用 GitHub Actions 部署至 App Service。

步驟 5: 部署需要幾分鐘的時間才能完成。 部署結束後,選擇 「前往資源 」按鈕。 便會讓您直接前往 App Service 應用程式。 精靈會創建以下資源:

  • 資源群組:所有已建立資源的容器。
  • App Service 方案:定義 App Service 的計算資源。 系統會建立基本層中的 Linux 方案。
  • App Service:代表你的 Java 25 應用程式,並運行於 App Service 方案中。
  • 虛擬網路:與 App Service 應用程式整合,並隔離後端網路流量。
  • 適用於 PostgreSQL 的 Azure 資料庫 flexible server 16: 僅能從虛擬網路內部存取。 精靈會在伺服器上為你建立資料庫和使用者。
  • 私人 DNS 區域:啟用虛擬網路中 PostgreSQL 伺服器的 DNS 解析。

3.安全連線秘密

建立精靈已為您產生連線變數做為應用程式設定。 不過,安全性最佳做法是將祕密完全從 App Service 中移出。 您將在服務連接器的協助下,將您的秘密移至密鑰保管庫,並將您的應用程式設定更改為 密鑰保管庫參考。

步驟 1:擷取現有的連接字串

  1. 在 App Service 頁面的左側功能表中,選取 [ 設定 > 環境變數]。
  2. 選取 [連接字串]。
  3. 選取 [AZURE_POSTGRESQL_CONNECTIONSTRING]。
  4. 在 [新增/編輯應用程式] 設定的 [ 值 ] 字段中,尋找字串結尾的使用者 標識元= 和 Password= 元件。
  5. 複製 使用者標識碼= 和 Password= 之後的使用者名稱和密碼字串,以供稍後使用。 此應用程式設定可讓您連線到私人端點後方所保護的Postgres資料庫。 不過,秘密會直接儲存在 App Service 應用程式中,這不是最好的方式。 您要變更此設定。

步驟 2:建立子網路以保護 金鑰保存庫 虛擬網路已有兩個子網路,但其中一個委派給 App Service,另一個則委派給 適用於 PostgreSQL 的 Azure 資料庫。 建立另一個子網路,以透過私人端點安全存取 金鑰保存庫。

  1. 在 App Service 頁面的左側功能表中,選取 [ 概觀] 索引標籤。
  2. 選取應用程式的資源群組。
  3. 選取資源群組中的虛擬網路。
  4. 在虛擬網路的左側功能表中,選取 [ 設定 > 子網]。
  5. 選取+ 子網路。
  6. 在 [名稱] 中,輸入 subnet-keyvault。 接受預設值。
  7. 選取 ,然後新增。

步驟 3:建立金鑰保存庫以安全地管理秘密

  1. 在頂端搜尋列中,輸入「密鑰保存庫」,然後選取 [Marketplace>金鑰保存庫]。
  2. 在 [資源群組] 中,選取 [msdocs-quarkus-postgres_group]。
  3. 在 [金鑰保存庫名稱] 中,輸入只包含字母和數字的名稱。
  4. 在 [區域] 中,將它設定為與資源群組相同的位置。

步驟 4:使用私人端點保護金鑰保存庫

  1. 選擇 網路 標籤。
  2. 取消勾選 啟用公用存取。
  3. 選取 [建立私人端點]。
  4. 在 [資源群組] 中,選取 [msdocs-quarkus-postgres_group]。
  5. 在對話方塊的 [位置] 中,選取與 App Service 應用程式相同的位置。
  6. 在 [名稱] 中,輸入 msdocs-quarkus-postgresVaultEndpoint。
  7. 在 [虛擬網络] 中,選取 [vnet-xxxxxxx]。
  8. 在 [子網] 中, 子網密鑰保存庫。
  9. 請選擇 [確定]。
  10. 選取 [檢閱 + 建立],然後選取 [建立]。 等候金鑰保存庫部署完成。 您應該會看到「您的部署已完成」。

步驟 5:建立 PostgreSQL 連接器

  1. 在頂端搜尋列中,輸入 msdocs-quarkus-postgres,然後選取名為 msdocs-quarkus-postgres 的 App Service 資源。
  2. 在 App Service 頁面的左側功能表中,選取 [ 設定 > 服務連接器 > 建立]。
  3. 在 [服務類型] 中,選取 [適用於 PostgreSQL 的 DB 彈性伺服器]。
  4. 在 PostgreSQL 彈性伺服器中,應該已經選取 msdocs-quarkus-postgres-server 。
  5. 在 PostgreSQL 資料庫中,選取 msdocs-quarkus-postgres-database。
  6. 在 [用戶端類型] 中,選取 [Java]。

步驟 6:將 PostgreSQL 秘密儲存在 key vault 中

  1. 選擇「驗證」索引標籤。
  2. 選取 [ 連接字串]。
  3. 在 [ 用戶名稱 ] 和 [ 密碼] 中,貼上您稍早複製的密碼。
  4. 選取 [在 金鑰保存庫 中儲存秘密]。
  5. 在 [金鑰保存庫連線] 底下,選取 [新建]。 [建立連線] 對話方塊會在編輯對話方塊的頂端開啟。

步驟 7:建立 金鑰保存庫 連線

  1. 在 建立連線 對話方塊中,於 金鑰保管庫 選擇您稍早建立的金鑰保管庫。
  2. 在 [用戶端類型] 中,選取 [Java ] 以取得一致性。 您的應用程式程式代碼實際上不會直接使用金鑰保存庫。
  3. 按一下 檢閱 + 建立。
  4. 驗證完成時,請選取 建立。

步驟 8:完成 PostgreSQL 連接器設定

  1. 您回到 PostgreSQL 連接器的編輯對話框中。 在 [驗證] 索引標籤中,等候建立金鑰保存庫連接器。 完成時,[金鑰保存庫 連線] 下拉式清單會自動加以選取。
  2. 按一下 檢閱 + 建立。
  3. 驗證完成時,請選取 建立。 等到 [建立成功 ] 通知出現為止。

步驟 9:驗證 金鑰保存庫 整合

  1. 從左側功能表中,再次選取 [ 設定 > 環境變數 ]。
  2. 在 AZURE_POSTGRESQL_CONNECTIONSTRING 旁,選取 [顯示值]。 此值應該是 @Microsoft.KeyVault(...),這表示它是 密鑰保存庫參考 ,因為密碼現在已在密鑰保存庫中管理。

步驟 10:從 App Service 刪除原始資料庫憑證

  1. 選取 連線字串 索引標籤。
  2. 在 AZURE_POSTGRESQL_CONNECTIONSTRING右側,選取 [ 刪除]。 請記住,建立精靈會在開頭為您建立此連接字串。

總結來說,確保您的連接密鑰的過程包括:

  • 從 App Service 應用程式的環境變數擷取連線秘密。
  • 使用私人端點建立金鑰保存庫。
  • 使用系統指派的受控識別建立 金鑰保存庫 連線。
  • 建立一個 PostgreSQL 服務連接器,將連線秘密存放在金鑰庫中。
  • 刪除 App Service 應用程式中舊的 PostgreSQL 連接字串。

有問題嗎? 查看疑難排解區段。

4.部署範例程式碼

在建立精靈中,您已使用 GitHub Actions 從範例 GitHub 存放庫設定連續部署。 這只是部署至 App Service 的許多方式之一,但也是在部署程序中持續整合的絕佳方式。 根據預設,每次對您的 GitHub 存放庫執行 git push 都會開始建置和部署動作。

請注意:

  • Quarkus 預設會接聽埠 8080。 在生產環境中,它必須設定為接聽 App Service 中環境變數所 PORT 指定的埠。
  • 您部署的 Java 套件必須是 Uber-Jar。
  • 為了簡化本教學課程,您將在部署程序期間停用測試。 GitHub Actions 執行器無法存取 Azure 中的 PostgreSQL 資料庫,因此任何需要資料庫存取的整合測試都會失敗,例如 Quarkus 應用程式範例的情況。
  • 第一次啟動 Java 25 可能只需幾分鐘。 App Service 在 Quarkus 初始化時持續發送預熱請求。

步驟 1: 回到範例分支的 GitHub 程式代碼空間中,執行 git pull origin starter-no-infra。 這會將新認可的 GitHub 工作流程檔案提取到 codespace。

步驟 2:設定 Java 25 啟動

  1. 在 App Service 頁面,選擇 設定>環境變數。
  2. 在 [應用程式設定] 索引標籤上,選取 [新增]。
  3. 對於名稱,輸入 JAVA_OPTS。
  4. 對於 價值,請在一行輸入以下數值:
--add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED
  1. 選擇 套用,然後選擇 確認。

Java 25 上的應用程式需要這些模組開啟選項。

步驟 3:設定 Quarkus 以支援 App Service

  1. 在程式碼空間中開啟 src/main/resources/application.properties 。
  2. 確保結構管理使用目前的 quarkus.hibernate-orm.schema-management.strategy 屬性名稱。 例如,開發配置可以使用 quarkus.hibernate-orm.schema-management.strategy=drop-and-create。
  3. 新增或更新生產屬性,使其符合以下範例:
%prod.quarkus.datasource.jdbc.url=${AZURE_POSTGRESQL_CONNECTIONSTRING}
quarkus.package.jar.type=uber-jar
%prod.quarkus.http.port=${PORT}

PostgreSQL 的 連接字串 由 Service Connector 透過 AZURE_POSTGRESQL_CONNECTIONSTRING提供。

步驟 4:配置 GitHub Actions 建置

  1. 打開 .github/workflows/starter-no-infra_msdocs-quarkus-postgres.yml。 這個檔案是建立精靈產生的 GitHub Actions 工作流程。
  2. 找到該 Build with Maven 步驟並設定其指令為:
run: mvn clean install -Dquarkus.package.jar.type=uber-jar -DskipTests

-DskipTests跳過整合測試,因為 GitHub 託管的執行者無法透過私有端點存取 PostgreSQL。 目前的 Quarkus Maven 屬性為 quarkus.package.jar.type。

步驟 5:

  1. 選取 [原始檔控制] 延伸模組。
  2. 在文字方塊中,輸入提交訊息,例如 Configure DB and deployment。 或者,選取 並讓 GitHub Copilot 為您產生認可訊息。
  3. 選取 [認可],然後使用 [是] 來確認。
  4. 選取 [同步變更 1],然後使用 [確定] 來確認。

步驟 6:

  1. 從左側功能表中,選取 [部署>中心>記錄]。
  2. 在部署執行的記錄項目中,選取時間戳記最新的 [建置/部署記錄] 項目。

第 7 步:您已前往 GitHub 存放庫,並看到 GitHub 動作正在執行。 工作流程檔案定義了獨立的建置與部署工作。 等候 GitHub 執行顯示成功狀態。 部署及首次啟動 Java 25 可能需要數分鐘。

有問題嗎? 查看疑難排解區段。

5.瀏覽至應用程式

步驟 1:在 [App Service] 頁面中:

  1. 從左側功能表中選取 [概觀]。
  2. 選取應用程式的 URL。

步驟 2:將一些水果新增至清單。 恭喜,您正在 Azure App 服務 中執行 Web 應用程式,並安全地連線至 PostgreSQL 的適用於 PostgreSQL 的 Azure 資料庫。

6.資料流診斷記錄

Azure App 服務 會擷取輸出到主控台的所有訊息,以協助您診斷應用程式的問題。 如下所示,應用程式範例包含可示範這項功能的標準 JBoss 記錄陳述式。

@Consumes("application/json")
public class FruitEntityResource {

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

    @GET
    public List<FruitEntity> get() {

步驟 1:在 [App Service] 頁面中:

  1. 從左側功能表中,選取 [監視]> [App Service 記錄]。
  2. 在 [應用程式記錄] 下,選取 [檔案系統]。
  3. 在最上層的功能表中,選取 [儲存]。

步驟 2:從左側功能表中,選取 [記錄串流]。 您會看到應用程式的記錄,包括平台記錄和來自容器內的記錄。

在啟用適用於 .NET、Node.js、Python 和 Java 應用程式的 Azure 監視器 OpenTelemetry 系列中深入了解 Java 應用程式中的記錄。

7.清除資源

完成後,您可以刪除資源群組,以從 Azure 訂用帳戶中刪除所有資源。

步驟 1:在 Azure 入口網站頂端的搜尋列中:

  1. 輸入資源群組名稱。
  2. 選取資源群組。

步驟 2:在資源群組頁面中,選取 [刪除資源群組]。

步驟 3:

  1. 輸入您確認要刪除的資源群組名稱。
  2. 選取 [刪除] 。
  3. 再次使用 [刪除] 來確認。

Azure 入口網站中刪除資源群組確認對話方塊的螢幕擷取畫面。 :

2.建立 Azure 資源並部署應用程式範例

在此步驟中,你會使用範例儲存庫 main 分支中已包含的 AZD 檔案。 他們建立預設安全架構,並將應用程式部署至 Linux 上的 App Service。 你不需要初始化或疊加獨立的範本。

開發容器已具備 Azure Developer CLI (AZD)。

  1. 從 GitHub 程式碼空間的倉庫根目錄,登入 Azure:

    azd auth login
    
  2. 建立一個 AZD 環境。 使用不超過 25 字元的獨特環境名稱。 允許英數字元與連字號。 此限制會讓產生的 Azure 管理 Redis 名稱保持在跨區域命名範圍內。

    azd env new <environment-name>
    
  3. 預覽基礎設施變更。 請依照提示選擇訂閱與地點。

    azd provision --preview
    

    預覽版評估基礎架構,卻不建立資源。 在繼續之前,請先檢視擬議的變更。

  4. 配置資源並部署應用程式:

    azd up
    

    配置與部署約需 15 分鐘。 Azure Managed Redis 通常最花時間配置,第一次啟動 Java 25 可能只需幾分鐘。 指令會顯示指向 Azure 部署與已部署應用程式的連結。

範例中的 azure.yaml 與 infra 目錄建立了以下資源與設定:

  • 資源群組:包含所有已建立的資源。
  • App Service 方案:提供 Basic 層級的 Linux 運算資源。
  • App Service:在 Java 25 上執行 Quarkus 應用程式。
  • 虛擬網路:整合 App Service 並隔離後端流量。
  • 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器 16:包含應用程式資料庫與使用者,僅能在虛擬網路內存取。
  • Azure Managed Redis Balanced_B0:其default資料庫使用加密連線、存取金鑰認證,以及關閉公共網路存取的私有端點。
  • 金鑰保存庫:儲存 PostgreSQL 與 Azure 管理的 Redis 秘密,僅能透過其私有端點存取。
  • 私有端點與網路介面:為 金鑰保存庫 和 Azure Managed Redis 提供私有 IP 位址。
  • 私用 DNS 區域:在虛擬網路中解析 PostgreSQL、金鑰保存庫 和 Azure Managed Redis 名稱。
  • Log Analytics 工作區:接收 App Service 日誌並支援日誌查詢。
  • Service Connectors:配置應用程式連接至 PostgreSQL、Azure Managed Redis 和 金鑰保存庫。

部署後,AZD 會顯示這四個連接器產生的設定名稱,且不會公開其秘密值:

App Service app has the following connection settings:
        - AZURE_POSTGRESQL_CONNECTIONSTRING
        - AZURE_REDIS_CONNECTIONSTRING
        - AZURE_KEYVAULT_RESOURCEENDPOINT
        - AZURE_KEYVAULT_SCOPE

這個範本會新增這些應用程式設定,並將秘密存放在 金鑰保存庫 中。 它也會使用 Java 25 模組開啟選項來設定JAVA_OPTS。 JAVA_OPTS 是執行時設定,不是連線設定,因此不包含在前面的清單中。

該範例已包含 Quarkus 的生產環境設定。 之後不要取消留言或新增設定 azd up。 若要部署後續的應用程式變更而不需重新配置基礎設施,請執行:

azd deploy

有問題嗎? 查看疑難排解區段。

3. 瀏覽應用程式

  1. 在 AZD 輸出中,找到顯示在 訊息後面的 Deploying service web,然後在瀏覽器中開啟它。

  2. 將一些水果新增至清單。

    Quarkus Web 應用程式的螢幕擷取畫面,其中在 Azure 中執行的 PostgreSQL 會顯示水果清單。

    恭喜,您正在 Azure App 服務 中執行 Web 應用程式,並安全地連線至 PostgreSQL 的適用於 PostgreSQL 的 Azure 資料庫。

有問題嗎? 查看疑難排解區段。

4. 串流診斷日誌

Azure App 服務 會擷取主控台記錄,以協助您診斷應用程式的問題。 為了方便起見,AZD 範本已經 啟用了本地文件系統的記錄功能,並將 日誌傳送至 Log Analytics 工作區。

如下所示,應用程式範例包含可示範這項功能的標準 JBoss 記錄陳述式。

@Consumes("application/json")
public class FruitEntityResource {

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

    @GET
    public List<FruitEntity> get() {

在 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 應用程式中的記錄。

有問題嗎? 查看疑難排解區段。

5.清除資源

要完全刪除目前部署環境中的所有 Azure 資源,包括已清除的軟刪除資源(如支援),請執行azd down --purge並依照提示操作。

azd down --purge

疑難排解

GitHub Actions 執行在建置階段失敗

選取失敗的建置階段,以查看哪個步驟失敗。 如果是 使用 Maven 構建 階段,展開步驟以確認使用了 -DskipTests 選項。 如果沒有,請返回 4。部署範例程序代碼 ,並根據指示修改 GitHub 工作流程檔案。

應用程式無法啟動,並在記錄數據流中顯示下列錯誤:「模型類別是針對預設持續性單位 <預設值> 所定義,但找不到已設定的數據源 <預設值> :將不會建立預設 EntityManagerFactory。」

此 Quarkus 錯誤很可能是因為應用程式無法連線到 Azure 資料庫。 請確定應用程式設定 AZURE_POSTGRESQL_CONNECTIONSTRING 尚未變更,且 application.properties 已正確使用應用程式設定。

應用程式無法啟動,日誌流顯示「等候容器熱身請求的回應」

第一次 Java 25 啟動可能需要幾分鐘,所以請等 Quarkus 初始化完成。 如果預熱持續進行,可能是因應用程式未設定為監聽 App Service 之PORT環境變數所指定的連接埠。 回到 4號。部署範例程式碼 並驗證 application.properties 是否包含 %prod.quarkus.http.port=${PORT}。

應用程式無法啟動,日誌串流顯示「java.base 模組不會開啟 java.lang 到未命名模組」

此應用程式在 Java 25 中需要模組開放選項。 AZD 範本會自動配置所需的 JAVA_OPTS 值。 對於入口網站工作流程,請確認 App Service 應用程式設定是否存在且值為:

--add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED

新增或修正設定後,重新啟動 App Service 應用程式。

應用程式顯示 PostgreSQL 伺服器版本不支援

Quarkus 3.38.1 使用 Hibernate ORM 7,這需要 PostgreSQL 14 或更新版本。 本教學及其 AZD 範本會佈建 PostgreSQL 16。 在 Azure 入口網站中,打開彈性伺服器概覽頁面,確認 PostgreSQL 版本為 16。 如果你把應用程式連接到舊伺服器,請升級或更換那台伺服器並更新服務連接器。

應用程式運作正常,但我看到錯誤記錄檔「ERROR [org.acm.hib.orm.pan.ent.FruitEntityResource] (vert.x-eventloop-thread-0) 無法處理要求:jakarta.ws.rs.NotFoundException: HTTP 404 Not Found“。

這是 Vert.x 錯誤 (請參閱 Quarkus 回應式架構),指出用戶端要求未知的路徑。 當用戶端在Hibernate資料庫移轉發生之前要求REST API時,第一次啟動應用程式時就會發生此情況。

在 App Service 中,每個應用程式啟動時也會發生此錯誤,因為 App Service 會透過將要求傳送 GET 至 /robots933456.txt來驗證應用程式是否啟動。

常見問題集

這設定會產生多少費用?

建立資源的定價如下:

  • App Service 方案是在基本層中建立,並可擴大或縮小。 請參閱 App Service 定價。
  • PostgreSQL 16 彈性伺服器會建立於最低的可突發層級 Standard_B1ms,並採用最小儲存體大小,且您可以向上或向下調整其規模。 請參閱 Azure PostgreSQL Database 定價。
  • AZD 工作流程會用 Balanced_B0 SKU 建立Azure受管的 Redis。 入口網站的工作流程不會建立 Azure Managed Redis。 請參閱 Azure Managed Redis 定價。
  • 除非您設定額外的功能 (例如對等互連),否則虛擬網路不會產生費用。 請參閱 Azure 虛擬網路定價。
  • 私人端點會衍生鐘點及資料處理費用。 入口網站工作流程會為 金鑰保存庫 使用私人端點;AZD 工作流程也會為 Azure Managed Redis 使用私人端點。 請參閱 Azure Private Link 定價。
  • 私人 DNS 區域會收取少許費用。 AZD 工作流程會為 PostgreSQL、金鑰保存庫 和 Azure Managed Redis 建立區域。 請參閱 Azure DNS 定價。
  • 金鑰保存庫 會針對已儲存的金鑰、祕密及其相關作業收費。 請參閱 金鑰保存庫 定價。
  • Log Analytics 會對資料的攝取與保存收取超出包含的津貼費用。 請參閱 Azure 監視器定價。

如何使用其他工具連線至虛擬網路後方受保護的 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 starter-no-infra

如果我想要在 GitHub 工作流程期間使用 PostgreSQL 執行測試,該怎麼辦?

預設 Quarkus 應用程式範例包含具有資料庫連線能力的測試。 若要避免連線錯誤,您新增了 -DskipTests 屬性。 如有需要,您可以針對 PostgreSQL 服務容器執行測試。 例如,在你的 GitHub fork 中自動產生的工作流程檔案(.github/workflows/starter-no-infra_<app-name>.yml)中,進行以下變更:

  1. 將 PostgreSQL 容器的 YAML 程式碼新增至 build 作業,如下列程式碼片段所示。

    ...
    jobs:
      build:
        runs-on: ubuntu-latest
    
        # BEGIN CODE ADDITION
        container: ubuntu
        services:
          # Hostname for the PostgreSQL container
          postgresdb:
                        image: postgres:16
            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 服務容器。

  2. 在 Build with Maven 步驟中,移除 -DskipTests。 該 starter-no-infra 分支不預先設定 Uber-Jar 封裝,因此保留目前的 Quarkus 封包特性:

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

我沒有權限可建立使用者指派的身分識別

請參閱 部署中心中的 GitHub Actions 部署設定。

我可以在 Codespace 中使用 GitHub Copilot 執行哪些作業?

您可能已經注意到建立 Codespace 時,GitHub Copilot 聊天檢視已可供您使用。 不過,您需要一個 GitHub Copilot 帳戶 (英文) (可免費試用 30 天)。

與 GitHub Copilot 交談時,有幾項提示可供您使用:

  • 在單一聊天中,問題和答案會相互累積,您可以調整問題來微調您得到的答案。
  • 根據預設,GitHub Copilot 無法存取存放庫中的任何檔案。 若要詢問檔案相關問題,請先在編輯器中開啟檔案。
  • 為了讓 GitHub Copilot 在準備其解答時存取存放庫中的所有檔案,請在問題開頭加上 @workspace。 如需詳細資訊,請參閱Use the @workspace agent。
  • 在聊天過程中,GitHub Copilot 可以建議變更,(使用 @workspace)甚至可以建議在何處進行變更,但不允許自動為您進行變更。 您可以自行新增建議的變更並加以測試。

後續步驟

在開發人員指南中深入了解如何在 App Service 上執行 Java 應用程式。

了解如何使用自訂網域和憑證保障您的應用程式。