在 Azure App Service 中設定 Tomcat、JBoss 或 Java SE 應用程式的資料來源

發行項
07/27/2024

本文說明如何在 App Service 中設定 Java SE、Tomcat 或 JBoss 應用程式中的資料來源。

Azure App Service 會以三種變體在完全受控的服務上執行 Java Web 應用程式：

Java SE - 可以執行部署為包含內嵌伺服器的 JAR 套件的應用程式 (例如 Spring Boot、Dropwizard、Quarkus 或具有內嵌 Tomcat 或 Jetty 伺服器的應用程式)。
Tomcat - 內建 Tomcat 伺服器可以執行部署為 WAR 套件的應用程式。
JBoss EAP - 僅支援 Premium v3 和隔離 v2 定價層中的 Linux 應用程式。內建 JBoss EAP 伺服器可以執行部署為 WAR 或 EAR 套件的應用程式。

注意

針對 Spring 應用程式，我們建議使用 Azure Spring 應用程式。不過，您仍然可以使用 Azure App Service 作為目的地。如需建議，請參閱 Java 工作負載目的地指導。

設定資料來源

若要連接到 Spring Boot 應用程式中的資料來源，建議您建立連接字串，並將其插入 application.properties 檔案。

在 App Service 頁面的 [設定] 區段中，設定字串的名稱，在 [值] 欄位中貼上 JDBC 連接字串，並將類型設定為 [自訂]。您可以選擇將此連接字串設定為位置設定。

此連接字串可以名為 CUSTOMCONNSTR_<your-string-name> 的環境變數提供應用程式存取。例如： CUSTOMCONNSTR_exampledb 。
在 application.properties 檔案中，使用環境變數名稱來參考此連接字串。在我們的範例中，我們會使用下列程式碼：
```
app.datasource.url=${CUSTOMCONNSTR_exampledb}
```

如需詳細資訊，請參閱有關資料存取的 Spring Boot 文件和外部化設定。

提示

根據預設，Linux Tomcat 容器可以在 Tomcat 伺服器中自動為您設定共用資料來源。您唯一的工作是將包含有效 JDBC 連接字串的應用程式設定新增至 Oracle、SQL Server、PostgreSQL 或 MySQL 資料庫 (包括連線認證)，App Service 便會自動為您使用容器中可用的適當驅動程式，將對應的共用資料庫新增至 /usr/local/tomcat/conf/context.xml。如需使用此方法的端對端案例，請參閱教學課程：使用 Linux 上的 App Service 和 MySQL 建置 Tomcat Web 應用程式。

這些指示適用於所有資料庫連線。您必須在預留位置中填入您所選資料庫的驅動程式類別名稱和 JAR 檔案。下表提供常見資料庫的類別名稱和驅動程式下載。

Database	驅動程式類別名稱	JDBC 驅動程式
PostgreSQL	`org.postgresql.Driver`	下載
MySQL	`com.mysql.jdbc.Driver`	下載 (請選取 [Platform Independent] $不受平台影響$)
SQL Server	`com.microsoft.sqlserver.jdbc.SQLServerDriver`	下載

若要設定讓 Tomcat 使用「Java 資料庫連線」(JDBC) 或「Java 保存 API」(JPA)，請先自訂 Tomcat 在啟動時所讀入的 CATALINA_OPTS 環境變數。請透過 App Service Maven 外掛程式中的應用程式設定來設定這些值：

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

或是在 Azure 入口網站的 [設定]>[應用程式設定] 頁面中設定環境變數。

接著，決定資料來源應僅供在 Tomcat Servlet 上執行的一個應用程式還是所有應用程式使用。

應用程式層級資料來源

在專案的 META-INF/ 目錄中，建立 context.xml 檔案。建立 META-INF/ 目錄 (如果此目錄不存在)。

在 context.xml 中，新增 Context 元素以將資料來源連結至 JNDI 位址。以上表中您驅動程式的類別名稱取代 driverClassName 預留位置。

<Context>
    <Resource
        name="jdbc/dbconnection"
        type="javax.sql.DataSource"
        url="${connURL}"
        driverClassName="<insert your driver class name>"
        username="${dbuser}"
        password="${dbpassword}"
    />
</Context>

更新您應用程式的 web.xml，以使用您應用程式中的資料來源。

<resource-env-ref>
    <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
    <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
</resource-env-ref>

要新增共用的伺服器層級資料來源就必須編輯 Tomcat 的 server.xml。最可靠的操作方式如下：

上傳啟動指令碼，並在 [設定]>[啟動命令] 中設定指令碼的路徑。您可以使用 FTP 上傳啟動指令碼。

啟動指令碼會對 server.xml 檔案進行 xsl 轉換，並將產生的 xml 檔案輸出至 /usr/local/tomcat/conf/server.xml。啟動指令碼會透過 apk 安裝 libxslt。您可以透過 FTP 上傳 xsl 檔案和啟動指令碼。以下是啟動指令碼範例。

# Install libxslt. Also copy the transform file to /home/tomcat/conf/
apk add --update libxslt

# Usage: xsltproc --output output.xml style.xsl input.xml
xsltproc --output /home/tomcat/conf/server.xml /home/tomcat/conf/transform.xsl /usr/local/tomcat/conf/server.xml

下列範例 XSL 檔案會將新的連接器節點加入至 Tomcat server.xml。

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@* | node()" name="Copy">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()" mode="insertConnector">
    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                 contains(., '&lt;Connector') and
                                 (contains(., 'scheme=&quot;https&quot;') or
                                  contains(., &quot;scheme='https'&quot;))]">
    <xsl:value-of select="." disable-output-escaping="yes" />
  </xsl:template>

  <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                   comment()[contains(., '&lt;Connector') and
                                             (contains(., 'scheme=&quot;https&quot;') or
                                              contains(., &quot;scheme='https'&quot;))]
                                  )]
                      ">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="insertConnector" />
    </xsl:copy>
  </xsl:template>

  <!-- Add the new connector after the last existing Connnector if there's one -->
  <xsl:template match="Connector[last()]" mode="insertConnector">
    <xsl:call-template name="Copy" />

    <xsl:call-template name="AddConnector" />
  </xsl:template>

  <!-- ... or before the first Engine if there's no existing Connector -->
  <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                mode="insertConnector">
    <xsl:call-template name="AddConnector" />

    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template name="AddConnector">
    <!-- Add new line -->
    <xsl:text>&#xa;</xsl:text>
    <!-- This is the new connector -->
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
               maxThreads="150" scheme="https" secure="true" 
               keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS" />
  </xsl:template>

</xsl:stylesheet>

完成設定

最後，將驅動程式 JAR 放在 Tomcat 類別路徑中，然後重新啟動您的 App Service。

請確定 Tomcat classloader 可以使用 JDBC 驅動程式檔案，方法是將它們放在 [/home/site/lib] 目錄中。在 Cloud Shell 中，為每個驅動程式 JAR 執行 az webapp deploy --type=lib：

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

如果您已建立伺服器層級的資料來源，請重新啟動 App Service Linux 應用程式。 Tomcat 會將 CATALINA_BASE 重設為 /home/tomcat，並使用更新後的設定。

您無法直接修改 Tomcat 安裝來進行全伺服器的設定，因為安裝位置是唯讀的。若要對 Windows Tomcat 安裝進行伺服器層級的設定變更，最簡單的方式是在應用程式啟動時執行下列動作：

將 Tomcat 複製到本機目錄 (%LOCAL_EXPANDED%)，並使用該目錄作為 CATALINA_BASE (請參閱關於此變數的 Tomcat 文件)。
使用 XSL 轉換將共用資料來源新增至 %LOCAL_EXPANDED%\tomcat\conf\server.xml。

新增啟動檔案

建立名為 startup.cmd %HOME%\site\wwwroot 目錄的檔案。此檔案會在 Tomcat 伺服器啟動前自動執行。此檔案應具有下列內容：

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File  %HOME%\site\configure.ps1

新增 PowerShell 設定指令碼

接下來，使用下列程式碼，將名為 configure.ps1 的設定指令碼新增至 %HOME%_\site 目錄：

# Locations of xml and xsl files
$target_xml="$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
$target_xsl="$Env:HOME\site\server.xsl"

# Define the transform function
# Useful if transforming multiple files
function TransformXML{
    param ($xml, $xsl, $output)

    if (-not $xml -or -not $xsl -or -not $output)
    {
        return 0
    }

    Try
    {
        $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
        $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
        $xslt_settings.EnableScript = 1;

        $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
        $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
        $xslt.Transform($xml, $output);
    }

    Catch
    {
        $ErrorMessage = $_.Exception.Message
        $FailedItem = $_.Exception.ItemName
        echo  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
        return 0
    }
    return 1
}

# Start here

# Check for marker file indicating that config has already been done
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
    return 0
}

# Delete previous Tomcat directory if it exists
# In case previous config isn't completed or a new config should be forcefully installed
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
    Remove-Item "$Env:LOCAL_EXPANDED\tomcat" Recurse
}

md -Path "$Env:LOCAL_EXPANDED\tomcat"

# Copy Tomcat to local
# Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

# Perform the required customization of Tomcat
$success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

# Mark that the operation was a success if successful
if($success){
    New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File
}

此 PowerShell 會完成下列步驟：

檢查是否已存在自訂 Tomcat 複本。如果存在，啟動指令碼便可以在這裡結束。
將 Tomcat 複製到本機。
使用 XSL 轉換，將共用資料來源新增至自訂 Tomcat 的設定。
指出設定已順利完成。

新增 XSL 轉換檔案

用於自訂內建 Tomcat 安裝的常見使用案例是修改 server.xml、context.xml 或 web.xml Tomcat 設定檔。 App Service 已修改這些檔案以提供平台功能。若要繼續使用這些功能，請務必先保留這些檔案的內容，再變更這些檔案。若要達成此目的，請使用 XSL 轉換 (XSLT)。

將名為 configure.ps1 的 XSL 轉換檔案新增至 %HOME%_\site 目錄。您可以使用下列 XSL 轉換程式碼，在 server.xml 中新增連接器節點。開頭的「身分識別轉換」會保留設定檔的原始內容。

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>

    <!-- Identity transform: this ensures that the original contents of the file are included in the new file -->
    <!-- Ensure that your transform files include this block -->
    <xsl:template match="@* | node()" name="Copy">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
    </xsl:template>

    <xsl:template match="@* | node()" mode="insertConnector">
      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                   contains(., '&lt;Connector') and
                                   (contains(., 'scheme=&quot;https&quot;') or
                                    contains(., &quot;scheme='https'&quot;))]">
      <xsl:value-of select="." disable-output-escaping="yes" />
    </xsl:template>

    <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                     comment()[contains(., '&lt;Connector') and
                                               (contains(., 'scheme=&quot;https&quot;') or
                                                contains(., &quot;scheme='https'&quot;))]
                                    )]
                        ">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()" mode="insertConnector" />
      </xsl:copy>
    </xsl:template>

    <!-- Add the new connector after the last existing Connnector if there's one -->
    <xsl:template match="Connector[last()]" mode="insertConnector">
      <xsl:call-template name="Copy" />

      <xsl:call-template name="AddConnector" />
    </xsl:template>

    <!-- ... or before the first Engine if there's no existing Connector -->
    <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                  mode="insertConnector">
      <xsl:call-template name="AddConnector" />

      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template name="AddConnector">
      <!-- Add new line -->
      <xsl:text>&#xa;</xsl:text>
      <!-- This is the new connector -->
      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
                 maxThreads="150" scheme="https" secure="true" 
                 keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
                 clientAuth="false" sslProtocol="TLS" />
    </xsl:template>

</xsl:stylesheet>

設定 `CATALINA_BASE` 應用程式設定

平台也需要知道您自訂 Tomcat 版本的安裝位置。您可以在 CATALINA_BASE 應用程式設定中設定安裝的位置。

您可以使用 Azure CLI 來變更此設定：

    az webapp config appsettings set -g $MyResourceGroup -n $MyUniqueApp --settings CATALINA_BASE="%LOCAL_EXPANDED%\tomcat"

或者，您也可以在 Azure 入口網站中手動變更設定：

移至 [設定]>[設定]>[應用程式設定]。
選取 [新增應用程式設定]。
使用下列值來建立設定：
1. 名稱：CATALINA_BASE
2. 值："%LOCAL_EXPANDED%\tomcat"

完成設定

最後，將驅動程式 JAR 放在 Tomcat 類別路徑中，然後重新啟動您的 App Service。請確定 Tomcat classloader 可以使用 JDBC 驅動程式檔案，方法是將它們放在 [/home/site/lib] 目錄中。在 Cloud Shell 中，為每個驅動程式 JAR 執行 az webapp deploy --type=lib：

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

使用 JBoss EAP 註冊資料來源時有三個核心步驟：上傳 JDBC 驅動程式、將 JDBC 驅動程式新增為模組，以及註冊模組。 App Service 是無狀態裝載服務，因此用於新增和註冊資料來源模組的設定命令，必須編寫到指令碼並於容器啟動時套用。

取得資料庫的 JDBC 驅動程式。

建立 JDBC 驅動程式的 XML 模組定義檔案。下列範例顯示 PostgreSQL 的模組定義。

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="org.postgres">
    <resources>
    <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
    <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

將您的 JBoss CLI 命令放入名為 jboss-cli-commands.cli 的檔案中。 JBoss 命令必須新增模組，並將其註冊為資料來源。下列範例顯示 PostgreSQL 的 JBoss CLI 命令。

#!/usr/bin/env bash
module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml

/subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)

data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker

建立啟動指令碼 startup_script.sh 以呼叫 JBoss CLI 命令。下列範例顯示如何呼叫 jboss-cli-commands.cli。稍後，您會設定 App Service，以在容器啟動時執行此指令碼。
```
$JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
```
使用您選擇的 FTP 用戶端，將 JDBC 驅動程式 jboss-cli-commands.cli、startup_script.sh 和模組定義上傳至 /site/deployments/tools/。
設定您的網站，使其在容器啟動時執行 startup_script.sh。在 Azure 入口網站中，瀏覽至 [設定]>[一般設定]>[啟動命令]。將啟動命令欄位設定為 /home/site/deployments/tools/startup_script.sh。儲存您的變更。

若要確認資料來源已新增至 JBoss 伺服器，請透過 SSH 連線到您的 Webapp 並執行 $JBOSS_HOME/bin/jboss-cli.sh --connect。連線到 JBoss 之後，請執行 /subsystem=datasources:read-resource 以列印資料來源的清單。

下一步

瀏覽適用於 Java 開發人員的 Azure 中心，以找出 Azure 快速入門、教學課程和 Java 參考文件。

共用方式為

在 Azure App Service 中設定 Tomcat、JBoss 或 Java SE 應用程式的資料來源

設定資料來源

應用程式層級資料來源

共用伺服器層級資源

完成設定

新增啟動檔案

新增 PowerShell 設定指令碼

新增 XSL 轉換檔案

設定 `CATALINA_BASE` 應用程式設定

完成設定

下一步

意見反應

其他資源