Edge for Private Cloud 4.54.00 的異動

異動概要

Edge for Private Cloud 4.54.00 推出多項變更，可提升平台安全防護，並更新平台元件，以便使用 Java 21 執行。下方有兩個章節說明這些異動：

除了這些異動外，請參閱專屬的變更偵測工具指南。我們提供這項公用程式，協助您找出叢集中可能因升級而中斷的 Proxy、共用流程或其他構件。

Java 呼叫政策異動

在 Edge for Private Cloud 4.54.00 中，核心平台元件 (包括訊息處理器、Management Server 和 Router) 已更新為在 Java 21 LTS 上執行。Java 21 翻新了 Java 平台，包括移除舊版 Java EE 和 CORBA 模組 (JEP 320)、移除舊版內部公用程式類別，以及強制執行強大的模組化封裝 (JEP 403)。

由於這些異動，升級至 4.54.00 版後，具有自訂 JavaCallout 政策或自訂資源 JAR (儲存在 Proxy、環境或組織層級) 的 API Proxy 可能會中斷。

可能影響 Java 呼叫的變更類別

  1. 永久移除 Java EE 和 CORBA 模組 (JEP 320)：先前內建於 Java 8 執行階段的模組 (包括 JAXB javax.xml.bind.*、JAF javax.activation.*、JAX-WS javax.xml.ws.* 和 CORBA org.omg.*) 已從 Java SE 移除。如果呼叫參照這些套件，但未繫結獨立替代項目，則會在執行階段失敗，並顯示 NoClassDefFoundError。
  2. 移除內部公用程式類別：移除舊版內部輔助程式，例如 sun.misc.BASE64Encoder 和 sun.misc.BASE64Decoder。呼叫這些類別的呼叫會失敗，並傳回 NoClassDefFoundError。
  3. Java 內部項目強烈封裝 (JEP 403)：無法從自訂標註以反射方式存取 java.base 中的內部套件 (例如 sun.security.*、sun.reflect.* 和 com.sun.*)。反射呼叫在執行階段失敗，並顯示 InaccessibleObjectException。
  4. 在保留的 Java 類別中，方法簽章有所變更或移除：在某些 Java 模組中，Java 21 仍保留該類別，但特定建構函式或方法簽章已移除、淘汰或變更 (例如 org.w3c.dom.Document 和相關 XML 剖析類別中的特定 DOM 剖析方法)。

    工具偵測：異動偵測工具會將 METHOD_SIGNATURE_MODIFICATION 類別下對這些類別的參照標記為「MEDIUM Impact Certainty」，提示開發人員檢查呼叫的原始碼，確認是否有修改過的方法叫用。

修復策略

升級前，請確認 Java 呼叫政策和自訂 JAR 資源與 Java 21 執行階段相容。使用變更偵測工具，有助於找出叢集中受影響的 API Proxy、共用流程，以及環境或機構 JAR 資源。

本節所述的補救策略為一般指南，且不會互相排斥。您可以根據作業需求結合多種策略，例如使用策略 2 翻新呼叫原始碼，並使用策略 3B 部署更新後的 Proxy 修訂版本，在升級訊息處理器時達到零停機時間。

策略 3A、3B 和 3C 是執行相同作業方法的 3 種方式：在不同時間升級節點並重新部署 Proxy，而不變更 Proxy 組合。請根據 API 可用性需求，選擇其中一個或多個選項。

請參閱下列決策指南，選擇最適合的部署方式：

Java 呼叫緩解措施決策指南：

是否需要更新及重新部署 Proxy 繫結？ 情境或需求 建議策略 解決的問題 重要限制
是 (僅更新套裝組合) 有雙重相容的程式庫，不需停機 策略 1：透過套裝 JAR 檔案提供雙重相容的 Proxy 還原各版本缺少的程式庫，完全不必停機 必須提供雙重相容的獨立程式庫，並在 4.54.00 中啟用 conf_system_java.21.enable.external.allowed.packages=true
是 (修改原始碼) 原始碼已維護；需要乾淨的長期修正 策略 2：替代實作 (程式碼和依附元件翻新) 永久解決已移除類別和內部 API 依附元件的問題 需要變更原始碼並重新部署 (搭配策略 3A 或 3B 推出)
否 (作業方法) 允許的排定維護期間 策略 3A：計畫性維護停機時間 (就地重新部署) 可先升級節點，再部署更新後的 Proxy API 使用者需要排定停機時間
否 (作業方法) 完全不必停機；無法綁定雙重 JAR 策略 3B：建立新環境 (零停機時間遷移) 在遷移期間隔離 4.53 和 4.54 節點，流量不會中斷 需要採購臨時訊息處理器節點
否 (作業方法) 升級前無法修改 Proxy 套裝組合 * 策略 3C：節點層級外部程式庫放置 在整個節點提供缺少的程式庫 JAR，無須編輯 Proxy 繫結 在節點上的所有 Proxy 之間共用；無法解決反射或 java.* 套件問題
否 (封閉原始碼的第三方程式庫) 使用 Java 內部反射的第三方供應商程式庫 * 策略 4：JVM 標記 (--add-opens / --add-exports) 放寬內部 Java 套件的反射限制 無法還原已移除的類別或方法；適用於整個節點

策略 1：透過套裝 JAR 建立雙重相容 Proxy (升級前測試，確保零停機時間)

使用時機：在下列情況下，請使用這項策略：

  • 提供雙重相容的獨立替代程式庫：有替代 JAR 可實作必要功能，並可直接綁定至 API Proxy，不需修改原始碼。
  • 您希望現有的 API Proxy 和 Java 呼叫，能在目前版本 (例如 Edge for Private Cloud 4.53.01) 和升級版本 (Edge for Private Cloud 4.54.00) 上順暢運作。
  • 您希望在升級 Edge for Private Cloud 叢集「之前」，先在預備和正式環境中測試及驗證所有變更，確保不會發生任何非預期的問題，且即時流量不會中斷。
  • 您不想重寫或重構 Java 呼叫商業邏輯。

運作方式：在 Java 8 中，某些程式庫 (例如 JAXB javax.xml.bind.* 或 Activation javax.activation.*) 是直接建構在 Java 8 執行階段中。因此，開發人員不需要在 Proxy 繫結中加入額外的 JAR 檔案。在 Java 21 中，這些程式庫已從 Java 執行階段中移除。

如要讓 Proxy 在 Edge for Private Cloud 4.53.x 和 4.54.00 之間「雙重相容」：

  1. 找出呼叫所需的遺漏程式庫 (例如 JAXB 或 Activation)。
  2. 取得獨立的開放原始碼替代 JAR (例如 jakarta.xml.bind-api-2.3.3.jar 和 jaxb-runtime-2.3.8.jar)。
  3. 您可以將替代 JAR 直接放入 apiproxy/resources/java/ 下的 Proxy 組合，也可以使用Proxy 層級的資源檔案 API 上傳至 Proxy 修訂版本，或在環境層級或機構層級上傳為資源檔案。如要進一步瞭解如何管理資源檔案，請參閱「Apigee 資源檔案說明文件」。
  4. 升級前部署及測試：Edge for Private Cloud 4.53.x 和 4.54.00 中的訊息處理器都會從這些隨附的 JAR 載入類別。您現在可以部署這個更新後的 Proxy 繫結，並在目前的 Edge for Private Cloud 4.53.x 叢集中，使用合成流量進行測試。
  5. 在訊息處理器上啟用外部允許的套件載入 (4.54.00 版的必要條件)：在 Edge for Private Cloud 4.54.00 版中，系統預設會停用從外部或組合資源 JAR 載入已移除的 Java 套件 (例如 javax.xml.bind.* 和 javax.activation.*) (conf_system_java.21.enable.external.allowed.packages=false)，因此預設情況下，單獨組合 JAR 無法運作。您必須使用程式碼與設定 (CwC) 在 /opt/apigee/customer/application/message-processor.properties 中啟用這項屬性 (您可以在升級訊息處理器節點前設定這項屬性，也可以在升級後設定並重新啟動訊息處理器)：
    conf_system_java.21.enable.external.allowed.packages=true
  6. 升級後，即時流量問題為零：當叢集後續升級至 Edge for Private Cloud 4.54.00 並啟用 conf_system_java.21.enable.external.allowed.packages=true 時，訊息處理器已備妥必要的 JAR，並從隨附的資源檔案載入類別，不會發生任何失敗 (NoClassDefFoundError)，確保升級過程順暢無停機。

程式碼範例：訂單 XML 驗證和剖析呼叫

假設有一個典型的 Apigee Java 呼叫，使用 JAXB (JAXBContext 和 Unmarshaller) 擷取及驗證傳入的 XML 訂單。

  • 修正前 (在 Edge for Private Cloud 4.54.00 中失敗)：在 Edge for Private Cloud 4.53.x 中，Proxy 繫結僅包含呼叫 JAR，依賴內建的 Java 8 執行階段程式庫進行 JAXB：
    apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

    Java 呼叫實作：

    package com.example.callout;

// other required imports
import java.io.StringReader;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;

public class OrderXmlParserCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        try {
            String requestXml = messageContext.getMessage().getContent();
            JAXBContext jaxbContext = JAXBContext.newInstance(Order.class);
            Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
            Order order = (Order) unmarshaller.unmarshal(new StringReader(requestXml));
            messageContext.setVariable("order_id", order.getId());
            return ExecutionResult.SUCCESS;
        } catch (Exception e) { }
    }
}

    失敗：在 Edge for Private Cloud 4.53.x 中，這項作業會順利執行。節點升級至 Edge for Private Cloud 4.54.00 後，這個 Proxy 在處理要求時會立即失敗：

    java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
        at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)
  • 修正後 (適用於 Edge for Private Cloud 4.53.x 和 4.54.00 的雙重相容性)：您不需要重寫或重新編譯 Java 呼叫程式碼。您可以提供獨立 JAR，直接讓 Proxy 具備雙重相容性：
    1. 直接將獨立 JAR 檔案組合或上傳：取得獨立 JAXB 程式庫 (jakarta.xml.bind-api-2.3.3.jar 和 jaxb-runtime-2.3.8.jar)，並將其放在 apiproxy/resources/java/ 下的 Proxy 組合中： 
      apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar
      jakarta.xml.bind-api-2.3.3.jar
      jaxb-runtime-2.3.8.jar

      或者，您也可以使用Proxy 層級資源檔案 API，或在環境層級或組織層級，將 jakarta.xml.bind-api-2.3.3.jar 和 jaxb-runtime-2.3.8.jar 上傳為資源檔案，這樣一來，相同範圍內的所有 Proxy 都能共用這些檔案，不必將這些檔案綁定至每個個別 Proxy 組合。

      如果您使用 Maven 從原始碼建構 Proxy 繫結，請在 pom.xml 中宣告這些依附元件，以便在建構期間自動封裝。

    2. 在目前的 4.53.x 叢集上部署及測試：將更新後的 Proxy 繫結部署至現有的 Edge for Private Cloud 4.53.x 環境，並傳送測試呼叫。Edge for Private Cloud 4.53.x 訊息處理器會從這些套裝 JAR 載入類別，因此您可以確認呼叫是否能繼續正常運作。
    3. 透過 CwC 啟用外部允許套件載入功能：由於 Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false) 預設會停用載入外部允許套件的功能，請使用程式碼與設定 (CwC)，在 /opt/apigee/customer/application/message-processor.properties 的每個訊息處理器節點上啟用這項功能：
      conf_system_java.21.enable.external.allowed.packages=true
    4. 升級後，即時流量問題為零：在 4.53.x 環境中完成驗證，並設定 CwC 屬性後，您的 Proxy 就已準備就緒。將叢集升級至 Edge for Private Cloud 4.54.00 後，訊息處理器會載入隨附的 JAXB 類別，確保不會發生錯誤，也不會中斷即時流量。

策略 2：替代實作 (程式碼和依附元件翻新)

使用時機：建議用於容易維護 Proxy 原始碼的活躍程式碼集。這是最乾淨俐落的長期做法，可確保符合 Java 21 規範。推出注意事項：部署現代化 Proxy 修訂版本時，需要訊息處理器協調，因此請將這項策略與策略 3A (在預定維護期間) 或策略 3B (使用平行訊息處理器，達到零停機時間) 搭配使用。

運作方式：將已移除的 Java 內部類別，替換為官方標準 Java SE API 或開放原始碼的獨立對等項目，並直接在 Proxy 組合資源檔案或 POM 中封裝必要的第三方依附元件。

程式碼範例：

範例 1：方法和程式碼現代化 (取代已移除的內部公用程式)

在 Java 8 中，呼叫經常使用內部公用程式類別，例如 sun.misc.BASE64Encoder。在現代 Java 中，這些類別已移除，但標準 java.util.Base64 API 提供直接替代方案，不需要外部依附元件 JAR：

  • 之前 (舊版 Java 8 實作)： 
    // Incompatible in Edge for Private Cloud 4.54.00: sun.misc package removed
import sun.misc.BASE64Encoder;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        BASE64Encoder encoder = new BASE64Encoder();
        String encoded = encoder.encode("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
  • 之後 (符合 Java 21 的實作)： 
    // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
import java.util.Base64;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
範例 2：使用已組合的程式庫 (JAXB 命名空間前置字元對應器) 進行匯入層級的重構

在 Java 8 中，自訂 XML 命名空間前置字元的 API Proxy 通常會擴充 Sun 的內部 JAXB 對應器 com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper。Java 21 移除內部 Sun 套件，因此無法存取。

獨立開放原始碼程式庫 (org.glassfish.jaxb:jaxb-runtime) 會在 com.sun.xml.bind.marshaller.NamespacePrefixMapper 下提供相同的類別。所有方法簽章、參數和傳回類型都相同，程式碼變更嚴格來說只在匯入陳述式中：

  • 變更前 (舊版 Java 8 實作)： 
    // In Java 8: Relied on internal Sun class in Java 8 runtime
import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • 之後 (符合 Java 21 的實作)： 
    // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • 套裝依附元件設定 (pom.xml)：如要在執行階段提供這個類別，請將獨立 JAXB 程式庫套裝在 apiproxy/resources/java/ 中，或在 pom.xml 中宣告：
    <dependencies>
    <!-- Standalone JAXB API for Java 21 -->
    <dependency>
        <groupId>jakarta.xml.bind</groupId>
        <artifactId>jakarta.xml.bind-api</artifactId>
        <version>2.3.3</version>
    </dependency>
    <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>2.3.8</version>
    </dependency>
</dependencies>

策略 3A：預定維護作業停機時間 (就地重新部署)

使用時機：建議用於排定作業維護期間的環境，可接受短暫的服務中斷。

程序：

  1. 與 API 消費者協調排定的維護期間。
  2. 請按照升級路徑指南，將 Edge for Private Cloud 元件升級至 4.54.00 版。
  3. 使用新版 Edge UI 或 Apigee Management API (部署作業)，部署預先編譯且與 4.54.00 相容的 API Proxy 修訂版本。
  4. 傳送合成測試要求至訊息處理器，並使用追蹤工具檢查記錄，確認呼叫執行作業。
  5. 關閉維護期間，並重新開放公開流量。

策略 3B：建立新環境 (零停機時間遷移)

使用時機：建議用於執行重要任務的正式環境，且必須零停機。如果無法更新 Java Callout，使其同時適用於 Java 8 和 Java 21，請使用這個選項。

運作方式：這項策略需要取得一或多個新環境，以便將不同版本的訊息處理器節點連接至該環境。接著，將與 Java 8 相容的 Proxy 部署至與 4.53.X 訊息處理器連結的環境，並將與 Java 21 相容的 Proxy 部署至與 4.54.00 訊息處理器連結的環境。然後使用負載平衡器或其他路由技術，將流量只轉送至與 Java 21 相容的 Proxy。

如要採用這項策略，您必須瞭解組織、環境和訊息處理器之間的互動方式，才能在不停機的情況下完成轉換 (詳情請參閱「Apigee Edge 組織結構」)：

  • Apigee 組織是頂層管理邊界，包含多個環境 (例如 prod、test)。
  • API Proxy 修訂版本會部署至特定環境。只有明確繫結至該環境的訊息處理器，才會載入及執行 Proxy 修訂版本。
+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

程序：

  1. 建立臨時環境：在機構內建立新環境 (例如 prod-migration)，並使用專屬虛擬主機和連接埠 (請參閱「設定虛擬主機和環境」)。
  2. 佈建 4.54.00 訊息處理器節點：在新的或暫時的 VM 執行個體上安裝 Edge for Private Cloud 4.54.00，並將這些節點繫結至 prod-migration (請參閱「新增訊息處理器」)。
  3. 找出受影響的 Proxy 並建立更新版本：使用異動偵測工具找出採用 Java 呼叫的 API Proxy，並使用與 Edge for Private Cloud 4.54.00 相容的 Java 呼叫，為每個受影響的 Proxy 建立新版本 (套用策略 1 或策略 2)。
  4. 將新版 Proxy 修訂版本部署至臨時環境：只將更新後的相容 Proxy 修訂版本部署至 prod-migration。
  5. 驗證及轉移流量：對新的虛擬主機執行合成驗證測試。確認後，請設定外部負載平衡器 (F5、NGINX)，將用戶端流量從 prod 重新導向至 prod-migration。
  6. 升級原始節點並切換回來：從 prod 取消部署舊版 Proxy。按照升級路徑指南，將原始訊息處理器節點升級至 4.54.00。將現代化 Proxy 修訂版本部署至 prod，將負載平衡器流量重新導向回 prod，並確認作業。
  7. 停用臨時環境：從 prod-migration 取消部署 Proxy、移除臨時訊息處理器節點，並刪除臨時環境。

策略 3C：節點層級的外部程式庫放置位置 (共用備用程式庫)

使用時機：如果有多個 API Proxy 依賴 Java 21 中移除的 Java 類別，且在升級前重新編譯或重新封裝每個 Proxy 組合在作業上不可行，建議使用這個方法。

運作方式：在 Edge for Private Cloud 4.54.00 中，訊息處理器提供一種機制，可從專屬節點目錄 $APIGEE_ROOT/data/edge-message-processor/external-lib 載入缺少的 Java 類別。

啟用這項機制後，訊息處理器會先檢查這個目錄是否有缺少的類別，再回復為預設解析度。您可以從第三方程式庫 JAR 取得缺少的類別，或將所需類別封裝至 JAR 並放入 external-lib，藉此提供缺少的類別。

程序：

  1. 在每個訊息處理器節點上建立外部程式庫目錄： 
    mkdir -p /opt/apigee/data/edge-message-processor/external-lib
  2. 將必要的 JAR 放入目錄：將含有必要類別的 JAR 檔案複製到 /opt/apigee/data/edge-message-processor/external-lib。
  3. 設定適當的檔案權限：確認 apigee 服務使用者具備讀取的權限：
    chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
chmod 755 /opt/apigee/data/edge-message-processor/external-lib
chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar
  4. 在訊息處理器設定中啟用外部套件載入功能：在 Edge for Private Cloud 4.54.00 中，預設會停用載入外部允許套件的功能 (conf_system_java.21.enable.external.allowed.packages=false)。如要啟用訊息處理器來解析及載入 /opt/apigee/data/edge-message-processor/external-lib 中的類別，您必須使用設定程式碼 (CwC) 在 /opt/apigee/customer/application/message-processor.properties 中啟用這項屬性：
    conf_system_java.21.enable.external.allowed.packages=true
  5. 重新啟動訊息處理器：
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

策略 4：JVM 旗標 (--add-opens / --add-exports — 謹慎使用，最後手段)

使用時機：如果第三方供應商程式庫為閉源，且無法取得原始碼、供應商尚未發布 Java 21 更新，且 JAR 嚴格依賴內部 Java 封裝的反射存取權，請使用這項策略做為最後手段。

程序：

  1. 找出用於反射的無法存取套件：判斷第三方程式庫以反射方式存取的內部 Java 模組和套件。注意：這些反映錯誤只會發生在 Edge for Private Cloud 4.54.00 的 Java 21 中，且不會出現在 4.53.x 版記錄中。升級後，請查看訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/system.log)，找出 InaccessibleObjectException，確認所需的模組和套件：
    java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module
  2. 使用程式碼搭配設定 (CwC) 編輯 /opt/apigee/customer/application/message-processor.properties (如果檔案不存在，請建立檔案)。
  3. 將指定的 --add-opens 或 --add-exports 旗標附加至 bin_setenv_ext_jvm_opts。 
    # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"
  4. 確保檔案擁有權和權限正確無誤： 
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
chmod 644 /opt/apigee/customer/application/message-processor.properties
  5. 使用 apigee-service 重新啟動訊息處理器：
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

TLS 和加密套件異動

在 Edge for Private Cloud 4.54.00 中，核心平台元件 (包括訊息處理器、Management Server 和 Router) 已更新為在 Java 21 LTS 上執行。這項更新預設啟用 TLS 1.3 (JEP 332)，可提升密碼編譯安全性。訊息處理器現在會協商 TLS 1.3 做為傳出後端連線的首選通訊協定，如果後端不支援，則會改用 TLS 1.2。

舊版後端需求和修復

Java 21 密碼學基準會更新 jdk.tls.disabledAlgorithms 中預設停用的通訊協定和加密套件清單 (例如舊版 TLS 通訊協定和非正向密碼靜態 RSA 金鑰交換組合：TLS_RSA_*)。由於您提供自己的 Java 21 執行階段，停用的通訊協定和加密套件確切清單取決於您的特定 Java 21 實作。

如果現有 API Proxy 連線至舊版後端基礎架構，而該基礎架構需要停用的通訊協定或靜態 RSA 加密，請參閱下列動作：

  • 更新後端安全性 (建議)：升級目標伺服器和負載平衡器，支援 TLS 1.2 或 TLS 1.3，並搭配現代 ECDHE 加密套件。如要在 API Proxy 中設定通訊協定和密碼套件，請參閱「設定從 Edge 到後端的 TLS」和「TLS/SSL TargetEndpoint 設定參考資料」(如果使用 TargetServer，請參閱「在後端伺服器之間進行負載平衡」)。
  • 使用 CwC 重新啟用舊版演算法 (升級期間的過渡措施)：如果後端升級無法在平台升級前完成，您可以使用程式碼與設定 (CwC) 暫時重新啟用所需演算法：
    1. 檢查 Java 21 安裝中的預設 jdk.tls.disabledAlgorithms 值 (例如在 $JAVA_HOME/conf/security/java.security 中)。
    2. 使用相同的停用演算法清單，覆寫 /opt/apigee/customer/application/message-processor.properties 中的 conf_jvmsecurity_jdk.tls.disabledAlgorithms，僅移除 TLS_RSA_* 項目 (保留所有其他停用的演算法，確保其餘保護措施維持啟用狀態)。
    3. 使用 apigee-service 重新啟動 訊息處理器。後端支援 ECDHE 加密套件後，請移除這項覆寫設定。
  • 更新自訂加密套件許可清單：如果您先前曾覆寫 conf_http_HTTPTransport.ssl.cipher.suites.whitelist，請先檢查該清單再升級。Java 21 不再支援靜態 RSA 套件 (TLS_RSA_*)，因此如果許可清單只包含這些套件，訊息處理器就沒有可用的密碼，後端呼叫也會失敗並顯示 no cipher suites in common。請移除 TLS_RSA_* 項目，並設定 Java 21 實作支援的新式加密套件。如果您未覆寫這項屬性，4.54.00 預設值已包含支援的套件，因此無須變更。
  • 更新路由器與訊息處理器之間的內部加密套件：如果您先前曾以靜態 RSA 套件覆寫 conf_message-processor-communication_local.http.ssl.ciphers，請在升級前，將其更新為 Java 21 實作支援的新式加密套件，否則路由器無法與訊息處理器完成 TLS 握手。然後重新啟動訊息處理器：
    apigee-service edge-message-processor restart
     請參閱「設定路由器和訊息處理器之間的 TLS」。

如要進一步瞭解如何在 Edge 元件之間設定 TLS，請參閱「在路由器和訊息處理器之間設定 TLS」。

變更偵測工具

Apigee 提供異動偵測工具，可掃描叢集，找出已部署的 API Proxy、政策、共用流程和資源 JAR，這些項目可能會受到 Edge for Private Cloud 4.54.00 升級作業影響。

這項工具會找出可能阻礙升級的問題，包括與 Java 21 不相容的程式庫、高度封裝的內部 API、淘汰的舊版政策，以及 OpenLDAP RDN 限制，並產生可做為行動依據的報表，協助您選擇適當的修正策略。

如需完整的先決條件、下載操作說明、指令列語法和報表範例，請參閱專屬的異動偵測工具指南。