تغییرات در Edge for Private Cloud نسخه ۴.۵۴.۰۰

نمای کلی تغییرات

Edge for Private Cloud 4.54.00 introduces multiple changes that enhance the security posture of the platform and updates platform components to run with Java 21. دو بخش زیر این تغییرات را پوشش می‌دهند:

• تغییرات خط‌مشی Java Callout
• تغییرات TLS و مجموعه رمز

علاوه‌بر این تغییرات، راهنمای ابزار تشخیص تغییر اختصاصی را مرور کنید. این ابزار برای شناسایی تغییرات در پراکسی‌ها، جاری‌سازی‌های مشترک، یا دیگر آرتیفکت‌های موجود در خوشه‌تان دردسترس قرار گرفته است که ممکن است درنتیجه این ارتقا باعث اختلال شوند.

تغییرات خط‌مشی Java Callout

در Edge for Private Cloud نسخه 4.54.00، اجزای اصلی پلاتفرم—ازجمله «پردازشگر پیام»، «سرور مدیریت»، و «مسیریاب»—به‌روزرسانی شده‌اند تا در Java 21 LTS اجرا شوند. ‫Java 21 پلاتفرم Java را مدرن می‌کند که شامل حذف ماژول‌های قدیمی Java EE و CORBA (JEP 320)، حذف کلاس‌های ابزار داخلی قدیمی، و اعمال کپسوله‌سازی ماژولار قوی (JEP 403) است.

به‌دلیل این تغییرات، کارگزاران API با خط‌مشی‌های JavaCallout سفارشی یا منابع JAR سفارشی (ذخیره‌شده در سطح کارگزار، محیط، یا سازمان) ممکن است پس‌از ارتقا به نسخه ۴.۵۴.۰۰ دچار اختلال شوند.

دسته‌های تغییراتی که ممکن است بر «فراخوانی‌های 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. تغییرات و حذف امضای روش در کلاس‌های جاوا باقی‌مانده: در برخی‌از واحدهای جاوا، کلاس در جاوا ۲۱ باقی می‌ماند، اما سازنده‌های خاص یا امضاهای روش حذف، منسوخ، یا تغییر کرده‌اند (مثل روش‌های تجزیه DOM خاص در org.w3c.dom.Document و کلاس‌های تجزیه XML مرتبط).

   شناسایی ابزار: ابزار شناسایی تغییر، ارجاع‌های مربوط به این کلاس‌ها را در دسته METHOD_SIGNATURE_MODIFICATION با MEDIUM قطعیت تأثیر پرچم‌گذاری می‌کند و از توسعه‌دهندگان می‌خواهد کد منبع برنمای‌هایشان را برای فراخوانی‌های روش اصلاح‌شده بازرسی کنند.

راهبردهای اصلاح

قبل‌از ارتقا دادن، مطمئن شوید که خط‌مشی‌های «تماس با جاوا» و منابع JAR سفارشی شما با زمان اجرای Java 21 سازگار است. استفاده از ابزار تشخیص تغییر به شما کمک می‌کند پراکسی‌های API، جریان‌های مشترک، و منابع JAR محیط یا سازمان تحت‌تأثیر قرارگرفته را در سراسر خوشه‌تان شناسایی کنید.

استراتژی‌های اصلاحی شرح‌داده‌شده در این بخش راهنماهای کلی هستند و مانعه‌الجمع نیستند. بسته به الزامات عملیاتی‌تان، می‌توانید استراتژی‌ها را ترکیب کنید—برای مثال، مدرن‌سازی کد منبع فراخوانی بااستفاده از استراتژی ۲ و استقرار نسخه‌های بازبینی‌شده پراکسی به‌روزشده بااستفاده از استراتژی ۳ب برای دستیابی به زمان خرابی صفر درطول ارتقای «پردازشگر پیام».

راهبردهای 3A،‏ 3B، و 3C سه روش برای اجرای یک رویکرد عملیاتی هستند: ارتقای گره و استقرار مجدد پراکسی در زمان‌های مختلف، بدون تغییر بسته پراکسی. یک یا ترکیبی از این موارد را براساس الزامات دردسترس بودن API خود انتخاب کنید.

راهنمای تصمیم‌گیری زیر را مرور کنید تا مناسب‌ترین رویکرد را برای استقرارتان انتخاب کنید:

راهنمای تصمیم‌گیری برای اقدامات کاهشی «نوشته راهنمای Java»:

راهبرد ۱: پراکسی با سازگاری دوگانه ازطریق JARهای دسته‌ای (قبل‌از ارتقا آزمایش کنید تا زمان ازکارافتادگی به صفر برسد)

زمان استفاده: از این استراتژی در موارد زیر استفاده کنید:

• کتابخانه جایگزین مستقل با سازگاری دوگانه دردسترس است: یک JAR جایگزین وجود دارد که عملکرد موردنیاز را پیاده‌سازی می‌کند و می‌تواند مستقیماً در پراکسی میانای برنامه‌سازی کاربردی شما گنجانده شود، بدون اینکه نیاز به تغییر کد منبع باشد.
• می‌خواهید پراکسی‌های API و Java Callout موجودتان به‌طور یکپارچه هم در نسخه فعلی (برای مثال، Edge for Private Cloud 4.53.01) و هم در نسخه ارتقایافته (Edge for Private Cloud 4.54.00) کار کنند.
• می‌خواهید همه تغییرات را در محیط‌های آماده‌سازی و تولید قبل‌از ارتقا دادن خوشه Edge for Private Cloud آزمایش و تأیید کنید تا مطمئن شوید هیچ مشکل غیرمنتظره‌ای و هیچ زمان ازکارافتادگی در ترافیک زنده وجود ندارد.
• می‌خواهید از بازنویسی یا بازسازی کد منطق کسب‌وکار Java Callout خود اجتناب کنید.

نحوه عملکرد: در Java 8، برخی‌از کتابخانه‌ها (مانند JAXB javax.xml.bind.* یا Activation javax.activation.*) مستقیماً در زمان اجرای Java 8 ساخته شده‌اند. به‌همین دلیل، توسعه‌دهندگان نیازی به گنجاندن فایل‌های JAR اضافی در بسته‌های پراکسی خود نداشتند. در Java 21، این کتابخانه‌ها از زمان اجرای Java برداشته شدند.

برای اینکه پراکسی شما در 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/ قرار دهید، یا آن را بااستفاده از API فایل‌های منبع سطح پراکسی در نسخه اصلاح پراکسی بارگذاری کنید، یا آن را به‌عنوان فایل منبع در سطح محیط یا سطح سازمان بارگذاری کنید. برای کسب اطلاعات بیشتر درباره مدیریت فایل‌های منبع، به مستندات فایل‌های منبع Apigee مراجعه کنید.
4. استقرار و آزمایش قبل‌از ارتقا: «پردازشگرهای پیام» در هر دو Edge for Private Cloud 4.53.x و 4.54.00 کلاس‌ها را از این JARهای بسته‌بندی‌شده بار می‌کنند. اکنون می‌توانید این بسته پراکسی به‌روزشده را مستقر کنید و آن را با ترافیک مصنوعی در خوشه Edge for Private Cloud 4.53.x فعلی‌تان آزمایش کنید.
5. فعال کردن بارگیری بسته مجاز خارجی در «پردازشگرهای پیام» (برای نسخه ۴.۵۴.۰۰ الزامی است): به‌طور پیش‌فرض در Edge برای Private Cloud نسخه ۴.۵۴.۰۰، بارگیری بسته‌های Java حذف‌شده (مثل javax.xml.bind.* و javax.activation.*) از JARهای منبع خارجی یا بسته‌بندی‌شده غیرفعال است (conf_system_java.21.enable.external.allowed.packages=false)، بنابراین بسته‌بندی JARها به‌تنهایی به‌طور پیش‌فرض کار نخواهد کرد. باید این دارایی را در /opt/apigee/customer/application/message-processor.properties بااستفاده از کد با پیکربندی (CwC) فعال کنید (می‌توانید این دارایی را قبل‌از ارتقا دادن گره «پردازشگر پیام» پیکربندی کنید، یا آن را پس‌از ارتقا دادن تنظیم کنید و «پردازشگر پیام» را بازراه‌اندازی کنید):

   conf_system_java.21.enable.external.allowed.packages=true

6. Zero live traffic issues post-upgrade: When your cluster is subsequently upgraded to Edge for Private Cloud 4.54.00 with conf_system_java.21.enable.external.allowed.packages=true enabled, the Message Processor already has the required JAR available and loads the classes from the bundled resource file without any failure (NoClassDefFoundError), ensuring a smooth, zero-downtime upgrade.

نمونه کد: اعتبار سنجی و تجزیه XML سفارش

یک «پیام‌واره جاوا Apigee» معمولی را درنظر بگیرید که سفارش‌های XML ورودی را بااستفاده از JAXB (JAXBContext و Unmarshaller) استخراج و اعتبارسنجی می‌کند.

• قبل‌از اصلاح (در Edge for Private Cloud نسخه ۴.۵۴.۰۰ ناموفق است): در Edge for Private Cloud نسخه ۴.۵۳.x، بسته پراکسی فقط حاوی JAR پیام‌واره است و برای JAXB به کتابخانه‌های زمان اجرای Java 8 داخلی متکی است:

  apiproxy/
    resources/
      java/
        OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

  پیاده‌سازی «نوشته راهنمای جاوا»:

  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 برای Private Cloud نسخه 4.53.x، این دستور بدون مشکل اجرا می‌شود. وقتی گره به Edge for Private Cloud 4.54.00 ارتقا داده می‌شود، این پراکسی بلافاصله درطول پردازش درخواست ناموفق می‌شود:

  java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
          at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)

• پس‌از اصلاح (سازگاری دوگانه در Edge برای Private Cloud نسخه 4.53.x و 4.54.00): نیازی به بازنویسی یا بازهمگردانی کد Java Callout ندارید. با ارائه فایل‌های JAR مستقل می‌توانید پراکسی خود را مستقیماً سازگار با هر دو کنید:
  1. مستقیماً JARهای مستقل را بسته‌بندی یا بارگذاری کنید: کتابخانه‌های JAXB مستقل (jakarta.xml.bind-api-2.3.3.jar و jaxb-runtime-2.3.8.jar) را دریافت کنید و آن‌ها را در بسته پراکسی خود در apiproxy/resources/java/ قرار دهید:

     apiproxy/
       resources/
         java/
           OrderXmlParserCallout.jar
           jakarta.xml.bind-api-2.3.3.jar
           jaxb-runtime-2.3.8.jar

     یا jakarta.xml.bind-api-2.3.3.jar و jaxb-runtime-2.3.8.jar را به‌عنوان فایل‌های منبع بااستفاده از Resource Files API در سطح پراکسی، یا در سطح محیط یا سطح سازمان بارگذاری کنید تا همه پراکسی‌ها در همان محدوده بتوانند آن‌ها را بدون بسته‌بندی در هر بسته پراکسی جداگانه هم‌رسانی کنند.

     اگر بسته پراکسی‌تان را بااستفاده از Maven از منبع می‌سازید، این وابستگی‌ها را در pom.xml خود اعلام کنید تا به‌طور خودکار درطول ساخت بسته‌بندی شوند.

  2. در خوشه 4.53.x فعلی‌تان مستقر و آزمایش کنید: بسته پراکسی به‌روزشده را در محیط Edge for Private Cloud 4.53.x موجودتان مستقر کنید و تماس‌های آزمایشی ارسال کنید. Because Edge for Private Cloud 4.53.x Message Processors load classes from these bundled JARs, you can verify that the callout continues to function identically.
  3. فعال کردن بار کردن بسته مجاز خارجی ازطریق CwC: چون بار کردن بسته‌های مجاز خارجی به‌طور پیش‌فرض در Edge for Private Cloud 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false) غیرفعال است، آن را در هر گره «پردازشگر پیام» در /opt/apigee/customer/application/message-processor.properties بااستفاده از کد با پیکربندی (CwC) فعال کنید:

     conf_system_java.21.enable.external.allowed.packages=true

  4. بدون مشکل ترافیک زنده پس‌از ارتقا: پس‌از اعتبارسنجی در محیط 4.53.x و پیکربندی با ویژگی CwC، پراکسی شما کاملاً آماده است. وقتی خوشه‌تان را به Edge for Private Cloud 4.54.00 ارتقا می‌دهید، «پردازنده پیام» کلاس‌های JAXB دسته‌ای را بار می‌کند و صفر خطا و صفر اختلال در ترافیک زنده را تضمین می‌کند.

استراتژی ۲: پیاده‌سازی جایگزین (مدرن‌سازی کد و وابستگی)

زمان استفاده: برای پایگاه‌های کد فعال که کد منبع پراکسی به‌راحتی نگهداری می‌شود توصیه می‌شود. این تمیزترین رویکرد بلندمدت برای رعایت Java 21 است. یادداشت عرضه: ازآنجایی‌که استقرار نسخه‌های بازبینی پراکسی مدرن‌شده نیازمند هماهنگی «پردازشگر پیام» است، این استراتژی را با استراتژی 3A (درطول پنجره تعمیر و نگهداری برنامه‌ریزی‌شده) یا استراتژی 3B (برای دستیابی به زمان توقف صفر با «پردازشگرهای پیام» موازی) جفت کنید.

نحوه عملکرد: کلاس‌های داخلی Java حذف‌شده را با میاناهای برنامه‌سازی کاربردی رسمی استاندارد Java SE یا معادل‌های مستقل متن‌باز جایگزین کنید و وابستگی‌های شخص ثالث موردنیاز را مستقیماً در فایل‌های منبع بسته پراکسی یا POM بسته‌بندی کنید.

نمونه‌های کد:

مثال ۱: نوسازی روش و کد (جایگزین کردن ابزارهای داخلی برداشته‌شده)

در 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;
      }
  }

مثال ۲: بازسازی سطح واردات با کتابخانه دسته‌بندی‌شده (JAXB Namespace Prefix Mapper)

در Java 8، کارگزاران API که پیشوندهای فضای نام XML را سفارشی‌سازی می‌کنند معمولاً نگاشت‌گر داخلی 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>

راهبرد ۳الف: زمان اَکار نگهداری برنامه‌ریزی‌شده (استقرار مجدد در محل)

زمان استفاده: برای محیط‌هایی با پنجره‌های تعمیر و نگهداری عملیاتی زمان‌بندی‌شده که در آن‌ها وقفه کوتاه در سرویس قابل‌قبول است توصیه می‌شود.

رویه:

1. پنجره تعمیرات زمان‌بندی‌شده را با مصرف‌کنندگان میانای برنامه‌سازی کاربردی هماهنگ کنید.
2. با دنبال کردن راهنمای مسیرهای ارتقا، مؤلفه‌های Edge for Private Cloud را به نسخه ۴.۵۴.۰۰ ارتقا دهید.
3. بااستفاده از New Edge UI یا Apigee Management API (Deployments)، نسخه پیش‌کامپایل‌شده و سازگار با 4.54.00 از پراکسی میانای برنامه‌سازی کاربردی خود را مستقر کنید.
4. با ارسال درخواست‌های آزمایشی ترکیبی به «پردازشگرهای پیام» و بازرسی گزارش‌ها بااستفاده از ابزار ردیابی، اجرای پیام‌واره را درستی‌سنجی کنید.
5. پنجره تعمیرات را ببندید و ترافیک عمومی را دوباره باز کنید.

استراتژی ۳ب: ایجاد محیط جدید (انتقال بدون زمان خرابی)

زمان استفاده: برای محیط‌های تولیدی حیاتی که به زمان ازکارافتادگی صفر نیاز دارند توصیه می‌شود. وقتی Java Callout شما نمی‌تواند برای کار هم‌زمان در Java 8 و Java 21 به‌روز شود، از این گزینه استفاده کنید.

نحوه عملکرد: این استراتژی شامل تهیه یک یا چند محیط جدید است تا بتوانید گره‌های «پردازشگر پیام» نسخه‌های مختلف را به آن متصل کنید. سپس کارگزاران سازگار با Java 8 را در محیطی که با «پردازشگرهای پیام» نسخه 4.53.X سیم‌کشی شده است و کارگزاران سازگار با Java 21 را در محیطی که با «پردازشگرهای پیام» نسخه 4.54.00 سیم‌کشی شده است مستقر کنید. سپس از متعادل‌کننده بار یا دیگر تکنیک‌های مسیریابی استفاده کنید تا ترافیک را فقط به پراکسی سازگار با Java 21 مسیریابی کنید.

برای این استراتژی، درک نحوه تعامل سازمان‌ها، محیط‌ها، و «پردازشگرهای پیام» کلید انتقال بدون زمان خرابی است (برای اطلاعات بیشتر، به ساختار سازمان Apigee Edge مراجعه کنید):

• سازمان Apigee یک مرز اداری سطح بالا است که شامل چندین محیط (برای مثال، prod، test) می‌شود.
• بازبینی پراکسی میانای برنامه‌سازی کاربردی در محیط خاصی مستقر می‌شود. فقط «پردازشگرهای پیام» که به‌طور صریح به آن محیط محدود شده‌اند، بازبینی پراکسی را بار می‌کنند و اجرا می‌کنند.

+------------------------------------------------------------------------+
|                          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: نصب Edge for Private Cloud 4.54.00 روی نمونه‌های ماشین مجازی جدید یا موقت و پیوند دادن این گره‌ها به prod-migration (به افزودن پردازشگر پیام مراجعه کنید).
3. شناسایی پراکسی‌های تحت‌تأثیر و ایجاد نسخه‌های بازبینی به‌روزرسانی‌شده: پراکسی‌های API را بااستفاده از «فراخوانی‌های Java» (بااستفاده از ابزار تشخیص تغییر) شناسایی کنید و نسخه بازبینی جدیدی از هر پراکسی تحت‌تأثیر با «فراخوانی‌های Java» سازگار با Edge for Private Cloud 4.54.00 ایجاد کنید (استراتژی ۱ یا استراتژی ۲ را اعمال کنید).
4. نسخه‌های پراکسی مدرن‌شده را در محیط موقت مستقر کنید: نسخه‌های پراکسی به‌روزشده و سازگار را منحصراً در prod-migration مستقر کنید.
5. درستی‌سنجی و انتقال ترافیک: آزمایش‌های درستی‌سنجی ترکیبی را دربرابر میزبان مجازی جدید اجرا کنید. پس‌از درستی‌سنجی، ترازکننده بار خارجی (F5،‏ NGINX) را پیکربندی کنید تا ترافیک کارخواه را از prod به prod-migration هدایت کند.
6. ارتقا دادن گره‌های اصلی و برگشتن به حالت قبلی: لغو استقرار پراکسی‌های قدیمی از prod. گره‌های «پردازشگر پیام» اصلی را با دنبال کردن راهنمای مسیرهای ارتقا به نسخه ۴.۵۴.۰۰ ارتقا دهید. بازبینی‌های پراکسی مدرن‌شده را در prod مستقر کنید، ترافیک متعادل‌کننده بار را به prod برگردانید، و عملیات را درستی‌سنجی کنید.
7. ازکار انداختن محیط موقت: پراکسی‌ها را از prod-migration لغو استقرار کنید، گره‌های موقت «پردازشگر پیام» را بردارید، و محیط موقت را حذف کنید.

استراتژی 3C: جای‌گذاری کتابخانه خارجی سطح گره (کتابخانه‌های مشترک بازگشتی)

زمان استفاده: زمانی توصیه می‌شود که چندین پراکسی API دارید که به کلاس‌های Java که در Java 21 برداشته شده‌اند متکی هستند و بازکامپایل کردن یا بسته‌بندی مجدد هر بسته پراکسی قبل‌از ارتقا ازنظر عملی غیرممکن است.

نحوه عملکرد: در Edge for Private Cloud نسخه ۴.۵۴.۰۰، «پردازشگرهای پیام» سازوکاری برای بار کردن کلاس‌های جاوا از فهرست راهنمای گره اختصاصی ارائه می‌دهند: $APIGEE_ROOT/data/edge-message-processor/external-lib.

وقتی این سازوکار فعال باشد، «پردازشگر پیام» قبل‌از بازگشت به وضوح پیش‌فرض، این دایرکتوری را برای کلاس‌های مفقودشده بررسی می‌کند. می‌توانید کلاس‌های مفقود را با تأمین آن‌ها از 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 نسخه ۴.۵۴.۰۰، بار کردن بسته‌های مجاز خارجی غیرفعال است (conf_system_java.21.enable.external.allowed.packages=false). برای فعال کردن «پردازشگر پیام» برای حل کردن و بار کردن کلاس‌ها از /opt/apigee/data/edge-message-processor/external-lib، باید این دارایی را در /opt/apigee/customer/application/message-processor.properties بااستفاده از کد با پیکربندی (CwC) فعال کنید:

   conf_system_java.21.enable.external.allowed.packages=true

5. بازراه‌اندازی «پردازشگر پیام»:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

استراتژی ۴: پرچم‌های JVM‏ (--add-opens / --add-exports — احتیاط و آخرین راه‌حل)

زمان استفاده: از این استراتژی به‌عنوان آخرین راهکار برای کتابخانه‌های فروشنده طرف سوم با منبع بسته استفاده کنید که کد منبع در آن‌ها دردسترس نیست، فروشندگان به‌روزرسانی‌های Java 21 را منتشر نکرده‌اند، و فایل JAR کاملاً به دسترسی بازتابی به بسته‌های داخلی Java وابسته است.

روال:

1. بسته غیرقابل‌دسترس مورداستفاده برای بازتاب را شناسایی کنید: بسته و واحد داخلی جاوا را که کتابخانه طرف سوم به‌صورت بازتابی به آن دسترسی دارد تعیین کنید. توجه: این خطاهای انعکاس دقیقاً در Java 21 در Edge برای Private Cloud 4.54.00 رخ می‌دهد و در گزارش‌های نسخه 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. /opt/apigee/customer/application/message-processor.properties را بااستفاده از کد با پیکربندی (CwC) ویرایش کنید (اگر فایل وجود ندارد آن را ایجاد کنید).
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 نسخه ۴.۵۴.۰۰، مؤلفه‌های اصلی پلاتفرم (ازجمله Message Processor،‏ 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 موجود شما به زیرساخت پشتیبان قدیمی متصل می‌شوند که به پروتکل‌های غیرفعال یا رمزهای RSA ایستا نیاز دارد، اقدامات زیر را مرور کنید:

• به‌روزرسانی امنیت زیرینه (توصیه‌شده): سرورهای هدف و ترازکننده‌های بار را ارتقا دهید تا از «امنیت لایه انتقال» نسخه ۱.۲ یا ۱.۳ با مجموعه‌های رمزگذاری ECDHE مدرن پشتیبانی کنند. برای پیکربندی پروتکل‌ها و مجموعه‌های رمز در پراکسی‌های API، به پیکربندی «امنیت لایه انتقال» از Edge تا زیرینه و مرجع پیکربندی «امنیت لایه انتقال»/ SSL در TargetEndpoint (یا توزیع بار در سرورهای زیرینه درصورت استفاده از TargetServers) مراجعه کنید.
• فعال کردن مجدد الگوریتم‌های قدیمی بااستفاده از CwC (اقدام انتقالی درطول ارتقا): اگر ارتقاهای زیرینه قبل‌از ارتقای پلاتفرم تکمیل نشوند، می‌توانید الگوریتم‌های موردنیاز را به‌طور موقت بااستفاده از کد با پیکربندی (CwC) مجدداً فعال کنید:
  1. مقدار پیش‌فرض jdk.tls.disabledAlgorithms را در نصب Java 21 خود بررسی کنید (برای مثال، در $JAVA_HOME/conf/security/java.security).
  2. ‫conf_jvmsecurity_jdk.tls.disabledAlgorithms را در /opt/apigee/customer/application/message-processor.properties با همان فهرست الگوریتم‌های غیرفعال‌شده لغو کنید و فقط ورودی 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 ازقبل مجموعه‌های پشتیبانی‌شده را دارند و نیازی به تغییر نیست.
• به‌روزرسانی رمزهای «مسیریاب» داخلی به «پردازشگر پیام»: اگر قبلاً conf_message-processor-communication_local.http.ssl.ciphers را با مجموعه‌های RSA ایستا لغو کرده‌اید، قبل‌از ارتقا دادن، آن را با مجموعه‌های رمز مدرن پشتیبانی‌شده توسط پیاده‌سازی Java 21 به‌روز کنید، درغیراین‌صورت «مسیریاب» نمی‌تواند دست‌دهی TLS را با «پردازشگر پیام» تکمیل کند. سپس «پردازشگر پیام» را بازراه‌اندازی کنید:

  apigee-service edge-message-processor restart

  پیکربندی «امنیت لایه انتقال» بین «رهیاب» و «پردازشگر پیام» را ببینید.

برای جزئیات پیکربندی TLS بین مؤلفه‌های Edge، به پیکربندی TLS بین «مسیریاب» و «پردازشگر پیام» مراجعه کنید.

ابزار تشخیص تغییر

Apigee ابزاری برای تشخیص تغییر ارائه می‌دهد تا خوشه شما را برای پراکسی‌های API، خط‌مشی‌ها، جریان‌های مشترک، و JARهای منابع مستقرشده که ممکن است تحت‌تأثیر ارتقا به Edge برای Private Cloud 4.54.00 قرار گیرند، اسکن کند.

این ابزار موانع احتمالی ارتقا را شناسایی می‌کند (ازجمله کتابخانه‌های ناسازگار با Java 21، میاناهای برنامه‌سازی کاربردی داخلی با کپسوله‌سازی قوی، منسوخ شدن خط‌مشی‌های قدیمی، و محدودیت‌های OpenLDAP RDN) و گزارش‌های قابل‌اجرایی تولید می‌کند تا به شما در انتخاب استراتژی‌های اصلاحی مناسب کمک کند.

برای پیش‌نیازهای کامل، دستورالعمل‌های بارگیری، نحو خط فرمان، و گزارش‌های نمونه، به راهنمای اختصاصی ابزار تشخیص تغییر مراجعه کنید.