Edge for Private Cloud 4.54.00 变更检测工具

变更检测工具

我们构建了一个变更检测工具，用于识别在迁移到 Edge for Private Cloud 4.54.00 期间和之后可能会受到影响的 Apigee 代理、政策、共享流和 资源 JAR（在代理、环境或组织级）。此工具会生成一份报告，详细说明受更改影响的已部署代理、共享流和资源 JAR，并提供指向与这些已识别代理或共享流相关的特定指南和策略的链接。

前提条件

1. 运行此工具需要基于 RHEL 或 Rocky Linux 的机器（请参阅 Edge 安装要求）。
2. 必须在主机上安装并正确配置 JRE 8 或更高版本，以允许工具的脚本运行。
3. 该工具需要网络访问管理服务器的端点 (URL)，并且需要有效的管理凭据进行身份验证和数据检索。
4. 该工具需要访问指定的工作目录（例如 /tmp），该目录需要有足够的磁盘空间和适当的读写权限，以便下载软件包、生成日志和存储输出。
5. （可选）从版本 4.53.00 升级时，该工具需要使用 ldapsearch 命令在 OpenLDAP 更改 - 提取 LDAP 数据 部分中生成的 LDIF 文件，以检测超过 241 个字符/字节的长 RDN。

运行工具

满足所有前提条件后，使用您的 Apigee 凭据从 Apigee 代码库下载该工具，然后解压缩下载的归档文件：

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.54.00_1.0.0.zip -o /tmp/change-detector-for-4.54.00_1.0.0.zip

unzip /tmp/change-detector-for-4.54.00_1.0.0.zip

下载完成后，您可以运行以下命令来查看该工具的所有可用选项：

./change-detector --help

如需运行该工具，请使用以下命令，并将占位符替换为您的信息：

export APIGEE_PASSWORD=YOUR_PASSWORD
./change-detector --username YOUR_USERNAME --mgmt-url MGMT_URL --source-version SOURCE_VERSION

如果直接从 Edge for Private Cloud 4.53.01 升级，请指定 --source-version 4.53.01 以扫描 Java 21 更改。如果从版本 4.53.00 升级，请指定 --source-version 4.53.00 以执行累积扫描，涵盖 4.53.01 政策弃用和 Java 21 更改。

该工具会生成 CSV 或 JSON 格式的输出，您可以直接查看这些输出，也可以将其导入到 Google 表格等电子表格应用中。

了解工具输出

该报告包含以下列：

组织

工件所在的组织的名称。对于 OpenLDAP 更改，此值为 None。

环境

组织内的特定环境（例如 dev、test、prod）。对于组织级 JAR，此字段为 N/A。对于 OpenLDAP 更改，此值为 None。

代理名称

API 代理或共享流的名称。对于组织级 JAR 资源，此字段会显示组织名称。对于环境级 JAR 资源，此字段会显示环境名称。对于 OpenLDAP 更改，此字段会显示 RDN 的 LDAP 实体。

范围

指定扫描的工件的范围和级别：

• proxy-level-jar：在代理级上传的 JAR 资源文件（位于 /resources/java 下）。
• env-level-jar：在环境级上传的 JAR 资源文件（请参阅资源文件）。
• org-level-jar：在组织级上传的 JAR 资源文件。
• proxy：API 代理修订版本中的政策或配置。
• sharedflow：共享流修订版本中的政策或配置。
• ldif：OpenLDAP LDIF 文件（用于 OpenLDAP 检查）。

修订版本

API 代理或共享流的特定修订版本号。对于环境级或组织级 JAR，此字段为 N/A。对于 OpenLDAP 更改，此值为 None。

政策名称

已被识别为潜在问题的特定政策的名称（例如 JavaCallout-ValidateAccount 或 OASValidation-1）。对于组织级资源，此字段会显示 N/A (Organization Resource)。对于环境级资源，此字段会显示 N/A (Environment Resource)。对于 OpenLDAP 更改，此值为 None。

政策类型

政策的类型（例如 java-callout 或 OASValidation）。对于 OpenLDAP 更改，此值为 None。

来源版本

为扫描配置的来源 OPDK 版本（4.53.00 或 4.53.01）。

受影响的资源

描述检测到的特定资源或库：

• 对于 Java 21 Callout 检测：受影响的 JAR 文件的确切名称（例如 order-transform.jar 或 corba-callout.jar）。
• 对于旧版 4.53 弃用：deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR。
• 对于 OAS、JSONPath 或 OpenLDAP 检测：特定政策元素或资源（例如 oas content type handling、wildcard expression 或 LDAP RDN exceeds 241 characters）。

检测原因

提供有关该项为何被标记的详细诊断信息：

• 对于 Java 21 Callout 检测：特定类、目标替换库（如果适用）和根本原因（例如 Class: javax.xml.bind.JAXBContext | Target Library: jakarta.xml.bind-api-2.3.3.jar | Root Cause: ClassNotFoundException: JAXB API was removed from Java SE in Java 11 (JEP 320)）。如果在同一 JAR 中检测到多个问题，则这些问题会合并，并以 ; 分隔。
• 对于旧版 4.53 弃用：已弃用库中引用的类列表（例如 ['Detected use of class CLASS_NAME from JAR_NAME']）。
• 对于 OAS 验证：Source 标记中指定的变量（例如 Source=response）。
• 对于 JSONPath：标记的确切表达式。
• 对于 OpenLDAP：超出 241 字节或字符的特定 LDAP 实体的 RDN。

影响确定性

此字段表示该工具识别升级阻止程序的置信度。值以大写形式标准化：

• HIGH： 该工具检测到不兼容的更改（例如，对永久移除的类（如 javax.xml.bind.JAXBContext 或 sun.misc.BASE64Encoder）的调用，或超出 241 字节的 OpenLDAP RDN）。除非进行补救，否则运行时失败（ClassNotFoundException 或 NoClassDefFoundError）的概率几乎是确定的。
• MEDIUM： 该工具检测到需要开发者检查和功能验证的模式：
  • 对于 Java Callout：在 METHOD_SIGNATURE_MODIFICATION 下标记（例如 org.w3c.dom.Document），其中类存在于 Java 21 中，但特定方法可能已更改或已弃用。
  • 对于 OASValidation 政策：当在 <Source> 元素中使用动态运行时变量（例如 Source=response）时标记，这需要捕获跟踪记录以在代理执行期间观察已解析的变量。

检测报告示例

定向 Java 21 扫描报告 (--source-version 4.53.01)

以下示例说明了从 OPDK 4.53.01 升级到 4.54.00 的报告输出：

累积扫描报告 (--source-version 4.53.00)

以下示例说明了从 OPDK 4.53.00 升级到 4.54.00 的报告输出：

如需获得有关补救已识别问题的指导，请参阅补救策略。