文档AEM 6.5用户指南

升级前的维护任务 pre-upgrade-maintenance-tasks

Last update: Mon Apr 27 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 适用对象：
  • Experience Manager 6.5
  • 主题：

创建对象：

  • 管理员

在开始升级之前，请务必遵循这些维护任务，以确保系统已准备就绪，并且可以在出现问题时回滚：

确保有足够的磁盘空间 ensure-sufficient-disk-space

在执行升级时，除了内容和代码升级活动之外，还必须执行存储库迁移。 迁移过程会以新的Segment Tar格式创建存储库的副本。 因此，您需要足够的磁盘空间来保留存储库的第二个（可能更大）版本。

完全备份AEM fully-back-up-aem

在开始升级之前，应完全备份AEM。 确保备份存储库、应用程序安装、数据存储和Mongo实例（如果适用）。 有关备份和还原AEM实例的详细信息，请参阅备份和还原。

将更改备份到/etc backup-changes-etc

升级过程很好地维护和合并了存储库中/apps和/libs路径下的现有内容和配置。 对于对/etc路径所做的更改（包括Context Hub配置），通常需要在升级后重新应用这些更改。 虽然升级会为无法在/var下合并的任何更改创建备份副本，但Adobe建议您在开始升级之前手动备份这些更改。

生成快速入门.properties文件 generate-quickstart-properties

从jar文件启动AEM时，将在crx-quickstart/conf下生成quickstart.properties文件。 如果AEM以前仅使用启动脚本启动，则此文件不存在，且升级失败。 确保检查此文件是否存在，如果AEM不存在，请从jar文件重新启动它。

配置工作流和审核日志清除 configure-wf-audit-purging

WorkflowPurgeTask和com.day.cq.audit.impl.AuditLogMaintenanceTask任务需要单独的OSGi配置，没有它们将无法工作。 如果它们在升级前任务执行期间失败，则缺少配置是最可能的原因。 因此，请确保为这些任务添加OSGi配置，或者如果不想运行它们，则从升级前优化任务列表中完全删除它们。 有关配置工作流清除任务的文档可在管理工作流实例中找到，有关审核日志维护任务配置的文档可在AEM 6🔗中的审核日志维护中找到。

安装、配置和运行升级前任务 install-configure-run-pre-upgrade-tasks

由于AEM所允许的自定义级别，环境通常不遵循统一的执行升级方式。 因此，创建标准化的升级程序是一个困难的过程。

在以前的版本中，对于已停止或无法安全恢复的AEM升级，也会遇到困难。 此问题导致出现以下情况：需要重新启动完整升级过程，或者执行了有缺陷的升级而未触发任何警告。

为了解决这些问题，Adobe在升级过程中添加了几项增强功能，使其更具可复原性并且更便于用户使用。 以前必须手动执行的升级前维护任务正在优化和自动化。 此外，还添加了升级后报告，以便可以完全审查该过程，希望更容易发现任何问题。

升级前维护任务当前分布于各种手动部分或完全执行的接口上。 AEM 6.3中引入的升级前维护优化功能能够以统一的方式触发这些任务，并能够根据需要检查其结果。

从AEM 6.0开始，升级前优化步骤中包含的所有任务都与所有版本兼容。

如何设置 how-to-set-it-up

在AEM 6.3及更高版本中，快速入门jar中包含升级前维护优化任务。

使用方法 how-to-use-it

PreUpgradeTasksMBean OSGI组件预配置了可以一次运行的所有升级前维护任务列表。 您可以按照以下步骤配置任务：

  1. 通过浏览到​ https://serveraddress:serverport/system/console/configMgr ​转到Web控制台

  2. 搜索“preupgradetasks”，然后单击第一个匹配的组件。 组件的全名为com.adobe.aem.upgrade.prechecks.mbean.impl.PreUpgradeTasksMBeanImpl

  3. 修改必须运行的维护任务列表，如下所示：

    1487758925984

根据用于启动实例的运行模式，任务列表会有所不同。 以下是对每个维护任务所针对的运行模式的描述。

任务
运行模式
注释
TarIndexMergeTask
crx2
DataStoreGarbageCollectionTask
crx2
运行标记和整理。 对于共享数据存储，请删除此步骤，然后手动运行
，或者在执行之前正确准备实例。
ConsistencyCheckTask
crx2
WorkflowPurgeTask
crx2/crx3
必须在运行之前配置Adobe Granite工作流清除配置OSGi。
GenerateBundlesListFileTask
crx2/crx3
RevisionCleanupTask
crx3
对于AEM 6.0到6.2上的TarMK实例，请改为手动运行离线修订清理。
com.day.cq.audit.impl.AuditLogMaintenanceTask
crx3
在运行之前必须配置审计日志清除计划程序OSGi配置。
CAUTION
DataStoreGarbageCollectionTask调用具有标记和扫描阶段（如果已使用）的数据存储垃圾收集操作。 对于使用共享数据存储的部署，请确保正确重新配置它或准备实例以避免删除另一个实例引用的项目。 This process might require running the mark phase manually on all instances before triggering this pre-upgrade task.

Default Configuration of the Pre-Upgrade Health Checks default-configuration-of-the-pre-upgrade-health-checks

The PreUpgradeTasksMBeanImpl OSGI component comes pre-configured with a list of pre-upgrade health check tags to execute when the runAllPreUpgradeHealthChecks method is called:

  • system - the tag used by the granite maintenance health checks

  • pre-upgrade - a custom tag that could be added to all the health checks that you can set to run before an upgrade

The list is editable. You can use the plus (+) and minus (-) buttons besides the tags to add more custom tags, or remove the default ones.

MBean Methods

The managed bean functionality can be accessed using the JMX Console.

You can access the MBeans by:

  1. Going to the JMX Console at https://serveraddress:serverport/system/console/jmx

  2. Search for PreUpgradeTasks and click the result

  3. Select any method from the Operations section and select Invoke in the following window.

Below is a list of all the available methods that the PreUpgradeTasksMBeanImpl exposes:

Method Name
类型
描述
getAvailablePreUpgradeTasksNames()
信息
Displays the list of available pre-upgrade maintenance tasks names.
getAvailablePreUpgradeHealthChecksTagNames()
信息
Displays the list of pre-upgrade health checks tag names.
runAllPreUpgradeTasks()
操作
Runs all the pre-upgrade maintenance tasks in the list.
runPreUpgradeTask(preUpgradeTaskName)
操作
Runs the pre-upgrade maintenance task with the name given as the parameter.
isRunAllPreUpgradeTaskRunning()
ACTION_INFO
Checks if the runAllPreUpgradeTasksmaintenance task is running.
getAnyPreUpgradeTaskRunning()
ACTION_INFO
Checks if any pre-upgrade maintenance task is running and
returns an array containing the names of currently running tasks.
getPreUpgradeTaskLastRunTime(preUpgradeTaskName)
操作
Displays the exact running time of the pre-upgrade maintenance task with the name given as the parameter.
getPreUpgradeTaskLastRunState(preUpgradeTaskName)
操作
Displays the last running state of the pre-upgrade maintenance task with the name given as the parameter.
runAllPreUpgradeHealthChecks(shutDownOnSuccess)
操作

运行所有升级前运行状况检查，并将其状态保存在sling主路径中名为preUpgradeHCStatus.properties的文件中。 如果shutDownOnSuccess参数设置为true，则AEM实例将关闭，但前提是所有升级前运行状况检查的状态均为“正常”。

属性文件用作任何未来升级
的前提条件，如果升级前运行状况检查
执行失败，升级过程将停止。 如果要忽略升级前
运行状况检查的结果并仍启动升级，可以删除该文件。

detectUsageOfUnavailableAPI(aemVersion)
操作
列出
升级到指定的AEM版本时不再满足的所有导入包。 目标AEM版本必须是
作为参数提供的。
NOTE
可以通过以下方式调用MBean方法：
  • JMX控制台
  • 连接到JMX的任何外部应用程序
  • cURL

禁用自定义登录模块 disable-custom-login-modules

NOTE
仅当您从AEM 5版本升级时，才需要执行此步骤。 从旧版AEM 6升级时，可以完全跳过该步骤。

在Apache Oak中，为存储库级别的身份验证配置自定义LoginModules的方式发生了根本性变化。

在使用CRX2配置的AEM版本中，该文件放在repository.xml文件中，而从AEM 6开始，它通过Web控制台在Apache Felix JAAS Configuration Factory服务中完成。

因此，在升级后，必须禁用任何现有配置并重新创建Apache Oak。

要禁用repository.xml的JAAS配置中定义的自定义模块，必须编辑配置以使用默认LoginModule，如以下示例所示：

<Security >
             ....
          <!--
                 Use LoginModule authenticating against repository itself
                 -->
                 <LoginModule class = "com.day.crx.core.CRXLoginModule" >
                     <param name = "anonymousId" value = "anonymous" />
                     <param name = "adminId" value ="admin" />
                     <param name = "disableNTLMAuth" value = "true" />
                     <param name = "tokenExpiration" value = "43200000" />
                     <!--
param name="trust_credentials_attribute" value="d5b9167e95dad6e7d3b5d6fa8df48af8"/
                -->
                 </LoginModule >
         </ Security>
NOTE
有关详细信息，请参阅外部登录模块的身份验证。
有关AEM 6中LoginModule配置的示例，请参阅使用AEM 6配置LDAP。

从/install目录中删除更新 remove-updates-install-directory

NOTE
仅在关闭AEM实例后，从crx-quickstart/install目录中删除包。 此步骤是开始就地升级过程之前的最后一个步骤。

删除通过本地文件系统上的crx-quickstart/install目录部署的所有Service Pack、功能包或修补程序。 这样做可防止在更新完成后，在新AEM版本之上意外安装旧修补程序和Service Pack。

停止任何冷备用实例 stop-tarmk-coldstandby-instance

如果使用TarMK冷备用，请停止任何冷备用实例。 Doing so guarantees an efficient way to come back online if there are issues in the upgrade. After the upgrade has completed successfully, the cold standby instances must be rebuilt from the upgraded primary instances.

禁用自定义计划作业 disable-custom-scheduled-jobs

Disable any OSGi scheduled jobs that are included in your application code.

执行脱机修订版清理 execute-offline-revision-cleanup

NOTE
This step is only necessary for TarMK installations

If using TarMK, you should run Offline Revision Cleanup before upgrading. Doing so makes the repository migration step and subsequent upgrade tasks execute much faster and helps to ensure that Online Revision Cleanup can execute successfully after the upgrade has completed. For information on running Offline Revision Cleanup, see Performing Offline Revision Cleanup.

执行数据存储垃圾收集 execute-datastore-garbage-collection

NOTE
This step is only necessary for instances running crx3

After running revision cleanup on CRX3 instances, you should run Datastore Garbage Collection to remove any unreferenced blobs in the data store. For instructions, see the documentation on Data Store Garbage Collection.

根据需要升级数据库模式 upgrade-the-database-schema-if-needed

Usually, the underlying Apache Oak stack that AEM uses for persistence takes care of upgrading the database schema, if needed.

However, cases might arise when the schema cannot be upgraded automatically. Such cases are mostly high security environments where the database is running under a user with limited privileges. If such a situation occurs, AEM continues to use the old schema.

To prevent such a scenario from happening, upgrade the schema by doing the following:

  1. Shut down the AEM instance that must be upgraded.

  2. Upgrade the database schema. Consult the documentation for your database type to see what tooling is necessary to achieve the result.

    For more information on how Oak handles schema upgrades, see this page on the Apache website.

  3. Proceed with upgrading AEM.

删除可能妨碍升级的用户 delete-users-that-might-hinder-the-upgrade

NOTE
仅在以下情况下，才需要执行升级前维护任务：
  • 您正在从AEM 6.3之前的AEM版本升级
  • 在升级过程中，您会遇到以下提到的任何错误。

在极少数情况下，服务用户最终可能会在旧版AEM中被错误地标记为常规用户。

如果发生这种情况，升级将失败，并出现如下消息：

ERROR [Apache Sling Repository Startup Thread] com.adobe.granite.repository.impl.SlingRepositoryManager Exception in a SlingRepositoryInitializer, SlingRepository service registration aborted
java.lang.RuntimeException: Unable to create service user [communities-utility-reader]:java.lang.RuntimeException: Existing user communities-utility-reader is not a service user.

要解决此问题，请确保执行以下操作：

  1. 将实例与生产流量分离

  2. 创建一个或多个导致问题的用户的备份。 您可以通过包管理器完成此任务。 有关详细信息，请参阅如何使用包。

  3. 删除一个或多个导致问题的用户。 以下是可能属于此类别的用户列表：

    1. dynamic-media-replication
    2. communities-ugc-writer
    3. communities-utility-reader
    4. communities-user-admin
    5. oauthservice
    6. sling-scripting

旋转日志文件 rotate-log-files

Adobe建议在开始升级之前存档当前的日志文件。 这样，在升级期间和升级后，可以更轻松地监视和扫描日志文件，以识别并解决可能出现的任何问题。

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2