部署到 AEM as a Cloud Service deploying-to-aem-as-a-cloud-service

最近更新： 2026年9月30日

适用对象：
Experience Manager as a Cloud Service

主题：
Deploying

创建对象：

Admin

简介 introduction

与 AEM 内部部署和 Managed Services 解决方案相比，AEM as a Cloud Service 中的代码开发基础是相似的。开发人员编写代码并在本地进行测试，然后将代码推送到 AEM as a Cloud Service 上的远程环境。需要使用 Cloud Manager，它曾是 Managed Services 的一个可选内容传递工具。现在，该交付工具是用于将代码部署到 AEM as a Cloud Service 开发、暂存和生产环境的唯一机制。要在部署上述环境之前进行快速功能验证和调试，可以将代码从本地环境同步到快速开发环境。

AEM 版本的更新始终是独立于推送自定义代码的部署事件。或者，应该根据生产环境中的AEM版本测试自定义代码版本，因为这是其部署的位置。之后进行的AEM版本更新（经常进行并自动应用）旨在与已部署的客户代码向后兼容。

本文档的其余部分描述了开发人员如何调整其实践以用于AEM as a Cloud Service的版本更新和客户更新。

客户版本 customer-releases

针对正确的 AEM 版本进行编码 coding-against-the-right-aem-version

对于以前的AEM解决方案，AEM版本更改很少，客户参照API Jar将生产实例更新到最新的快速入门。但是，AEM as a Cloud Service 上的应用程序会更频繁地自动更新到最新版本的 AEM，因此，应针对最新的 AEM 版本构建内部版本的自定义代码。

与现有非云AEM版本一样，支持基于特定快速入门的本地离线开发，并且通常希望将其作为调试的主要工具。

NOTE

应用程序在本地计算机上的行为与Adobe云基础架构之间存在微妙的操作差异。这些体系结构差异需要在本地开发期间进行考虑，并在云基础架构上部署时导致不同的行为。由于存在这些差异，因此，在生产中推出新的自定义代码之前，务必要对开发和暂存环境执行详尽的测试。

若要为内部版本开发自定义代码，应下载并安装相关版本的 AEM as a Cloud Service SDK。有关使用AEM as a Cloud Service Dispatcher工具的其他信息，请参阅云中的Dispatcher。

以下视频概括介绍了如何将代码部署到 AEM as a Cloud Service：

https://video.tv.adobe.com/v/32908?captions=chi_hans&quality=9&learn=on

通过Cloud Manager和包管理器部署内容包 deploying-content-packages-via-cloud-manager-and-package-manager

通过Cloud Manager部署 deployments-via-cloud-manager

客户通过 Cloud Manager 将自定义代码部署到云环境。 Cloud Manager将本地组装的内容包转换为符合Sling功能模型的构件。此模型描述在云环境中运行时AEM as a Cloud Service上的应用程序。因此，在云环境中的包管理器中查看包时，名称会包含“cp2fm”，并且转换后的包中的所有元数据已被删除。无法与它们交互，这意味着无法下载、复制或打开它们。有关转换器的详细文档，请参阅GitHub上的sling-org-apache-sling-feature-cpconverter。

AEM as a Cloud Service的内容包必须分隔不可变和可变内容。 Cloud Manager仅安装可变内容并输出如下消息：

Generated content-package <PACKAGE_ID> located in file <PATH> is of MIXED type

此部分的其余内容描述的是不可变包和可变包的构成及其影响。

不可变内容包 immutabe-content-packages

持久保存在不可变存储库中的所有内容和代码都必须签入 Git，并通过 Cloud Manager 进行部署。换句话说，与当前的 AEM 解决方案不同，代码绝不会直接部署到正在运行的 AEM 实例。该工作流可确保在任意云环境中为给定版本运行的代码是相同的，从而消除生产中发生意外代码变化的风险。例如，OSGI 配置应提交给源代码管理，而不是在运行时通过 AEM Web 控制台的配置管理器进行管理。

由于部署模式不同，交换机允许应用程序更改，因此除了服务用户、其ACL、节点类型和索引定义更改之外，它们不能依赖于可变存储库中的更改。

对于拥有现有代码库的客户，请务必完成 AEM 文档中描述的存储库重构实践，以确保将以前位于 /etc 下的内容移动到正确的位置。

这些代码包还受到一些其他限制，例如，安装挂接不受支持。

OSGI配置 osgi-configuration

如上所述，OSGI 配置应提交给源代码管理，而不是通过 Web 控制台管理。用于执行此操作的方法包括：

使用 AEM Web 控制台的配置管理器对开发人员的本地 AEM 环境进行必要的更改，然后将结果导出到本地文件系统上的 AEM 项目
在本地文件系统上的AEM项目中手动创建OSGI配置，然后引用AEM控制台的配置管理器中的属性名称。

参阅为 AEM as a Cloud Service 配置 OSGi，了解有关 OSGI 配置的更多信息。

可变内容 mutable-content

有时，在源代码管理中准备内容更改很有用，这样Cloud Manager就会在环境更新时部署这些更改。例如，为某些根文件夹结构提供种子是合理的。要启用应用程序部署更新的策略组件，请将更改排列在可编辑模板中。

Cloud Manager使用两种策略将内容部署到可变存储库：可变内容包和repoinit语句。

可变内容包 mutable-content-packages

文件夹路径层次结构、服务用户和访问控制 (ACL) 等内容通常会提交到基于 Maven 原型的 AEM 项目中。方法包括从 AEM 导出或以 XML 形式直接写入。在构建和部署过程中，Cloud Manager 将打包生成的可变内容包。在管道的部署阶段，可变内容会在三个不同的时间点安装：

在启动新版本的应用程序之前：

索引定义（添加、修改、删除）

在启动新版本的应用程序期间，但在切换之前：

服务用户（添加）
服务用户 ACL（添加）
节点类型（添加）

切换到新版本的应用程序之后：

可通过 Jackrabbit 库定义的所有其他内容。例如：
- 文件夹（添加、修改、删除）
- 可编辑模板（添加、修改、删除）
- 上下文感知配置（/conf 下的任何内容）（添加、修改、删除）
- 脚本（软件包可以触发安装挂接）。请参阅Jackrabbit filevault文档。

可以通过在 /apps 下的 install.author 或 install.publish 文件夹中嵌入包，来仅允许创作或发布可变内容安装。反映此分隔的重构已在AEM 6.5中完成，有关建议的项目重构的详细信息可在AEM 6.5文档中找到。

NOTE

内容包将部署到所有环境类型（开发、暂存、生产）。无法将部署限于特定环境。施加此限制以确保能够选择自动执行的测试运行。特定于环境的内容需要通过包管理器手动安装。

此外，在应用可变内容包更改后，没有机制可回滚这些更改。如果客户检测到问题，他们可以选择在下一个代码版本中修复它，或者在万不得已的情况下，将整个系统恢复到部署前的某个时间点。

必须验证任何包含的第三方包是否与AEM as a Cloud Service兼容；否则，包含这些第三方包会导致部署失败。

如上所述，具有现有代码库的客户遵循AEM 6.5文档中所述的6.5存储库更改所需的存储库重构练习。

Repoinit repoinit

对于以下情况，最好采用在OSGI工厂配置中手动编码显式内容创建repoinit语句的方法：

创建/删除/禁用服务用户
创建/删除组
创建/删除用户

添加 ACL

note
NOTE
ACL 的定义要求节点结构已存在。因此，前面的create path语句是必需的。

添加路径（例如，根文件夹结构的路径）
添加 CND（节点类型定义）

由于 Repoinit 的以下好处，对于这些受支持的内容修改用例，Repoinit 更可取：

Repoinit 在启动时创建资源，因此，逻辑可以将这些资源的存在视为理所当然。在可变内容包方法中，资源是在启动后创建的，因此依赖它们的应用程序代码会失败。
Repoinit 是一个相对安全的指令集，因为您可以明确控制要执行的操作。此外，唯一支持的操作是累加的，但几种与安全相关的情况除外，这些情况允许删除用户、服务用户和组。相比之下，在可变内容包方法中删除某些内容是明确的；在定义过滤器时，过滤器涵盖的任何内容都会被删除。不过，应谨慎行事，因为对于任何内容，在某些场景下，新内容的存在都可能改变应用程序的行为。
Repoinit 执行快速和原子操作。相比之下，可变内容包在性能方面可能在很大程度上取决于过滤器涵盖的结构。即使更新单个节点，也会创建大型树的快照。
可以在运行时在本地开发环境中验证 repoinit 语句，因为在注册 OSGi 配置时会运行这些语句。
Repoinit 语句是原子和显式的，如果状态已匹配，则会跳过它们。

当 Cloud Manager 部署应用程序时，它会独立于任何内容包的安装来执行这些语句。

要创建repoinit语句：

在项目的配置文件夹中，为工厂 PID org.apache.sling.jcr.repoinit.RepositoryInitializer 添加 OSGi 配置。为配置使用描述性名称，例如 org.apache.sling.jcr.repoinit.RepositoryInitializer~initstructure。
将 repoinit 语句添加到配置的脚本属性中。 Sling 文档中记录了语法和选项。在其子文件夹之前显式创建父文件夹。例如，在 /content/myfolder 和 /content/myfolder/mysubfolder 之前显式创建 /content。对于在低层次结构上设置的 ACL，建议在更高层次设置它们并使用 rep:glob 限制。例如：(allow jcr:read on /apps restriction(rep:glob,/msm/wcm/rolloutconfigs))。
在运行时在本地开发环境上进行验证。

WARNING

对于为/apps或/libs下的节点定义的ACL，repoinit执行从空白存储库开始。这些包是在 repoinit 之后安装的，因此，语句无法依赖包中定义的任何内容，但必须定义先决条件，例如下面的父结构。

TIP

对于ACL，深层结构的创建非常复杂。因此，更合理的做法是在更高的级别上定义 ACL，并通过 rep:glob 限制的方式限制其应采取的行动。

有关 repoinit 的更多详细信息，请参阅 Sling 文档

使用包管理器一次性安装可变内容包 package-manager-oneoffs-for-mutable-content-packages

在某些情况下，内容包应作为“一次性”安装进行安装。例如，将特定内容从生产环境导入到暂存环境来调试生产问题。在这些场景中，可以在 AEM as a Cloud Service 上的环境中使用包管理器。

包管理器是一个运行时概念；无法将内容或代码安装到不可变存储库中，并且这些内容包由可变内容（主要是/content或/conf）组成。如果内容包包含混合内容（可变内容和不可变内容），则只会安装可变内容。

IMPORTANT

如果包安装时间超过10分钟，包管理器用户界面将返回 未定义 错误消息。

这不是因安装错误导致的，而是因 Cloud Service 对所有请求的超时导致的。

如果您看到此类错误，请不要重试安装。安装过程在后台正常进行。如果重新启动安装，则多个并发导入过程会导致冲突。

Cloud Manager安装的任何内容包（可变和不可变）在AEM包管理器用户界面中都会显示为冻结。无法重新安装、重新生成或甚至下载这些软件包，它们以 "cp2fm" 后缀列出，表示Cloud Manager已执行其安装。

包括第三方软件包 including-third-party

客户通常将包含来自第三方来源（例如，Adobe 的翻译合作伙伴等软件供应商）的预建包。建议在远程存储库中托管这些包，并在 pom.xml 中引用它们。可以在公共存储库以及受密码保护的私有存储库中使用该方法，如受密码保护的 maven 存储库中所述。

如果无法将包存储在远程存储库中，客户可以将包放置在基于文件系统的本地 Maven 存储库中，该存储库作为项目的一部分提交到 SCM。不管怎样，它都会引用它。存储库在项目 pom 中声明，如下所示：

<repository>
    <id>project.local</id>
    <name>project</name>
    <url>file:${maven.multiModuleProjectDirectory}/repository</url>
</repository>

任何包含的第三方软件包都必须遵守本文中所述的AEM as a Cloud Service编码和打包准则，否则包含它们会导致部署失败。

以下 Maven POM.xml 代码片段展示了如何通过 filevault-package-maven-plugin Maven 插件配置将第三方包嵌入项目的“容器”包（通常名为 ‘all’）中。

...
<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
      ...
      <embeddeds>

          ...

          <!-- Include any other extra packages  -->
          <embedded>
              <groupId>com.vendor.x</groupId>
              <artifactId>vendor.plug-in.all</artifactId>
              <type>zip</type>
              <target>/apps/vendor-packages/container/install</target>
          </embedded>
      <embeddeds>
  </configuration>
</plugin>
...

滚动部署的工作原理 how-rolling-deployments-work

与 AEM 更新一样，客户版本使用滚动部署策略进行部署，以便在适当的情况下消除创作群集停机时间。下面描述了事件的一般顺序，其中具有旧版本和新版本客户代码的节点运行相同版本的 AEM 代码。

TIP

作为标准滚动部署的替代方法，您可以在将实时流量路由到生产基础设施之前，使用Canary部署验证该基础设施上的新版本。请参阅使用Canary部署验证代码。

具有旧版本的节点处于活动状态，新版本的候选发布版本已构建并可用。
如果存在任何新的或更新的索引定义，则处理相应的索引。旧版本的节点始终使用旧索引，而新版本的节点则始终使用新索引。
具有新版本的节点将启动，而旧版本仍会提供流量。
具有旧版本的节点正在运行并继续服务，而新版本的节点则通过运行状况检查是否准备就绪。
准备就绪的新版本节点会接受流量，并替换旧版本且已关闭的节点。
随着时间的推移，具有新版本的节点会使用旧版本替换节点，直到只有具有新版本的节点保留为止，从而完成部署。
然后部署任何新的或修改后的可变内容。

索引 indexes

在新版本可以接受流量之前，新的或修改后的索引会导致额外的索引或重新索引步骤。有关AEM as a Cloud Service中索引管理的详细信息可在内容搜索和索引编制下找到。您可以在 Cloud Manager 上的构建页面中查看索引状态，并会在新版本准备好接收流量时收到通知。

NOTE

滚动部署所需的时间根据索引的大小而有所不同。原因是在生成新索引之前，新版本无法接受流量。

目前，AEM as a Cloud Service 无法与 ACS Commons Ensure Oak Index 工具等索引管理工具配合使用。

复制 replication

发布机制与 AEM Replication Java™ API 向后兼容。

要使用AEM云就绪快速入门开发和测试复制，请将经典复制功能与创作/发布设置结合使用。如果已为云删除 AEM 创作上的用户界面入口点，用户会转到 http://localhost:4502/etc/replication 以进行配置。

用于滚动部署的向后兼容代码 backwards-compatible-code-for-rolling-deployments

如上所述，AEM as a Cloud Service的滚动部署策略意味着新旧版本同时运行。因此，请注意代码更改不会向后兼容仍在运行的旧AEM版本。

此外，如果发生回滚，应测试旧版本是否与新版本应用的任何新的可变内容结构兼容，因为不会删除可变内容。

服务用户和ACL更改 service-users-and-acl-changes

更改服务用户（即访问内容或代码的ACL）会导致较旧的AEM版本中出现错误，从而导致服务用户过时访问这些内容或代码。要处理此行为，建议在至少两个版本中进行更改，第一个版本充当桥梁，然后在后续版本中进行清理。

索引更改 index-changes

如果对索引进行了更改，则旧版本应继续使用其索引，直到其终止，而新版本则使用自己的修改后的索引集，这一点非常重要。开发人员遵循内容搜索和索引下描述的索引管理技术。

保守的回滚编码 conservative-coding-for-rollbacks

如果部署后报告或检测到失败，则可能需要回滚到旧版本。确保新代码与新版本所创建的任何新结构兼容，因为新结构（任何可变内容）不会回滚。如果旧代码不兼容，则必须在后续的客户版本中应用修复。

快速开发环境 (RDE) rde

快速开发环境（或RDE）允许开发人员快速部署和查看更改。这样可以最大限度地减少测试已证明可在本地开发环境中工作的功能所需的时间。

与通过 Cloud Manager 管道部署代码的常规开发环境不同，开发人员使用命令行工具将代码从本地开发环境同步到 RDE。在 RDE 中成功测试更改后，应通过 Cloud Manager 管道将更改部署到常规云开发环境，这可让代码通过相应的质量关卡。

运行模式 runmodes

在现有AEM解决方案中，客户可以选择使用任意运行模式运行实例，并应用OSGI配置或将OSGI捆绑包安装到这些特定实例。定义的运行架构通常包括服务（创作和发布）和环境（RDE、开发、暂存、生产）。

另一方面，AEM as a Cloud Service 对哪些运行模式可用以及如何将 OSGI 捆绑包和 OSGI 配置映射到这些模式有更明确的规定：

OSGI 配置运行架构必须引用 RDE、开发、暂存或生产作为环境，或引用创作和发布作为服务。支持<service>.<environment_type>的组合，其中必须按此特定顺序使用这些环境（例如，author.dev或publish.prod）。应在代码中直接引用OSGi令牌，而不是使用getRunModes方法，因为在运行时该方法不再包含环境类型。有关更多信息，请参阅为 AEM as a Cloud Service 配置 OSGi。
OSGI 捆绑包的运行模式仅限于服务（创作、发布）。每运行架构 OSGI 捆绑包应安装在 install.author 或 install.publish 下的内容包中。

AEM as a Cloud Service 不允许使用运行模式为特定环境或服务安装内容。如果必须向开发环境填充暂存或生产环境中不存在的数据或 HTML，则可以使用包管理器。

不受支持的运行架构配置包括：

config（默认值，适用于所有 AEM 服务）
config.author（适用于所有 AEM 创作服务）
config.author.dev（适用于 AEM 开发创作服务）
config.author.rde（适用于 AEM RDE 创作服务）
config.author.stage（适用于 AEM 暂存创作服务）
config.author.prod（适用于 AEM 生产创作服务）
config.publish（适用于 AEM 发布服务）
config.publish.dev（适用于 AEM 开发发布服务）
config.publish.rde（适用于 AEM RDE 发布服务）
config.publish.stage（适用于 AEM 暂存发布服务）
config.publish.prod（适用于 AEM 生产发布服务）
config.dev（适用于 AEM 开发服务）
config.rde（适用于 RDE 服务）
config.stage（适用于 AEM 暂存服务）
config.prod（适用于 AEM 生产服务）

使用与运行模式最匹配的 OSGI 配置。

在进行本地开发时，运行架构启动参数 -r 用于指定运行架构 OSGI 配置。

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

源代码管理中的维护任务配置 maintenance-tasks-configuration-in-source-control

维护任务配置必须保留在源代码管理中，因为 工具 > 操作 屏幕在云环境中不再可用。这样做的好处是确保有意保留更改，而不是被动应用并忘记更改。有关详细信息，请参阅AEM as a Cloud Service中的维护任务。

recommendation-more-help

experience-manager-cloud-service-help-main-toc