AEM as a Cloud Service 开发准则

本文档介绍了在AEMas a Cloud Service上进行开发的准则，以及与AMS中的AEM内部部署和AEM有所不同的重要方式。

代码必须具有群集意识

在AEMas a Cloud Service中运行的代码必须知道它始终在群集中运行这一事实。 这意味着始终会有多个实例在运行。代码必须具有弹性，尤其是当实例可能在任何时间点停止时。

在更新AEMas a Cloud Service期间，将有旧代码和新代码并行运行的实例。 因此，旧代码不得与由新代码创建的内容中断，而新代码必须能够处理旧内容。

如果需要识别群集中的主群集，则可以使用Apache Sling Discovery API来检测该群集。

内存中的状态

状态不得保留在内存中，但保留在存储库中。 否则，如果实例停止，此状态可能会丢失。

文件系统上的状态

实例的文件系统不应用于AEMas a Cloud Service。 该磁盘是短暂的，在实例循环使用时将进行处置。 对与处理单个请求相关的临时存储使用文件系统是可能的，但不应滥用它来获取大文件。 这是因为它可能对资源使用配额产生负面影响，并且会遇到磁盘限制。

例如，不支持文件系统使用，发布层应确保将需要保留的任何数据发送到外部服务，以便进行较长期的存储。

观察

类似地，由于异步发生的一切（如对观察事件执行操作），无法保证在本地执行，因此必须谨慎使用。 对于JCR事件和Sling资源事件，均是如此。 在发生更改时，该实例可能会被拆除并被其他实例替换。 拓扑中其他在当时处于活动状态的实例将能够对该事件做出响应。 但是，在这种情况下，这将不是一个地方性事件，甚至在发布该事件时，如果正在进行的领导人选举，也可能没有积极的领导人。

后台任务和长时间运行的作业

作为后台任务执行的代码必须假定它正在运行的实例可以随时关闭。 因此，代码必须是可复原的，最重要的是，它是可恢复的。 这意味着如果重新执行代码，则不应再次从开头开始，而应从离开的位置开始。 虽然这不是此类代码的新要求，但在AEMas a Cloud Service中，更有可能发生实例停用。

为了将问题降至最低，应尽可能避免长时间运行的作业，并且应至少恢复这些作业。 要执行此类作业，请使用Sling作业，Sling作业可至少保证一次，因此，如果中断，将尽快重新执行。 但它们或许不应该从头开始。 对于安排此类作业，最好使用 Sling作业 这样，调度程序可确保至少执行一次。

不应使用Sling Commons Scheduler进行计划，因为无法保证执行。 只是更有可能会安排时间。

同样，由于异步发生的所有事件(例如对观察事件执行操作（即JCR事件或Sling资源事件）)，无法保证会执行，因此必须谨慎使用。 目前，AEM部署已存在这种情况。

传出HTTP连接

强烈建议任何传出HTTP连接设置合理的连接和读取超时；连接超时的建议值为1秒，读取超时的建议值为5秒。 确切数字必须根据后端系统处理这些请求的性能来确定。

对于不应用这些超时的代码，在AEMas a Cloud Service上运行的AEM实例将强制执行全局超时。 这些超时值是连接调用为10秒，连接读取调用为60秒。

Adobe建议使用提供的 Apache HttpComponents客户端4.x库 用于建立HTTP连接。

已知有效但可能需要自行提供依赖关系的替代方案包括：

在提供超时的旁边，还应当实施对此类超时和意外HTTP状态代码的正确处理。

无经典UI自定义

AEMas a Cloud Service仅支持第三方客户代码的触屏UI。 经典UI无法进行自定义。

避免本机二进制文件

代码在运行时将无法下载或修改二进制文件。 例如，无法解包 jar 或 tar 文件。

无通过AEMas a Cloud Service的流二进制文件

应通过CDN访问二进制文件，CDN将在核心AEM服务之外提供二进制文件。

例如，请勿使用 asset.getOriginal().getStream()，这会触发将二进制文件下载到AEM服务的临时磁盘。

无反向复制代理

AEMas a Cloud Service不支持从“发布到作者”进行反向复制。 如果需要此类策略，您可以使用在发布实例场（可能是创作群集）之间共享的外部持久性存储。

可能需要移植转发复制代理

内容通过pub-sub机制从“创作”复制到“发布”。 不支持自定义复制代理。

监控和调试

日志

对于本地开发，日志条目将写入 /crx-quickstart/logs 文件夹。

在云环境中，开发人员可以通过Cloud Manager下载日志，或使用命令行工具跟踪日志。

设置日志级别

要更改云环境的日志级别，应修改Sling日志记录OSGi配置，然后完全重新部署。 由于这不是即时的，请谨慎在接收大量流量的生产环境中启用详细日志。 将来，可能会有一些机制来更快地更改日志级别。

注意

要执行下面列出的配置更改，您需要在本地开发环境中创建配置更改，然后将它们推送到AEMas a Cloud Service实例。 有关如何执行此操作的更多信息，请参阅 部署到AEMas a Cloud Service.

激活DEBUG日志级别

默认日志级别为“信息”，即不记录DEBUG消息。 要激活“调试”日志级别，请将以下属性更新为调试模式。

/libs/sling/config/org.apache.sling.commons.log.LogManager/org.apache.sling.commons.log.level

例如，设置 /apps/<example>/config/org.apache.sling.commons.log.LogManager.factory.config~<example>.cfg.json 的值。

{
   "org.apache.sling.commons.log.names": [
      "com.example"
   ],
   "org.apache.sling.commons.log.level": "DEBUG",
   "org.apache.sling.commons.log.file": "logs/error.log",
   "org.apache.sling.commons.log.additiv": "false"
}

请勿将日志保留在DEBUG日志级别，因为这样会生成大量条目。

如果希望始终登录，则可以使用基于运行模式的OSGi配置定位，为不同的AEM环境设置离散日志级别 DEBUG 开发期间。 例如：

|环境 |按运行模式划分的OSGi配置位置 | org.apache.sling.commons.log.level 属性值 | | - | - | - | |开发 | /apps/example/config/org.apache.sling.commons.log.LogManager.factory.config~example.cfg.json |调试 | |暂存 | /apps/example/config.stage/org.apache.sling.commons.log.LogManager.factory.config~example.cfg.json |警告 | |生产 | /apps/example/config.prod/org.apache.sling.commons.log.LogManager.factory.config~example.cfg.json |错误 |

调试文件中的一行通常以DEBUG开头，然后提供日志级别、安装程序操作和日志消息。 例如：

DEBUG 3 WebApp Panel: WebApp successfully deployed

日志级别如下：

0 致命错误 操作失败，安装程序无法继续。
1 错误 操作失败。 安装将继续进行，但CRX的一部分安装不正确，无法正常工作。
2 警告 操作已成功，但遇到问题。 CRX可能正常工作，也可能无法正常工作。
3 信息 操作成功。

线程转储

云环境中的线程转储会持续收集，但此时无法以自助方式下载。 同时，如果调试问题时需要线程转储，请联系AEM支持人员，并指定确切的时间窗口。

CRX/DE Lite和开发人员控制台

本地开发

对于本地开发，开发人员拥有对CRXDE Lite(/crx/de)和AEM Web控制台(/system/console)。

请注意，在进行本地开发（使用SDK）时， /apps 和 /libs 可以直接写入，这与顶级文件夹不可更改的云环境不同。

AEMas a Cloud Service开发工具

客户可以在创作层的开发环境中访问CRXDE lite，但不能在暂存或生产环境中访问。 不可变存储库(/libs, /apps)无法在运行时写入，因此尝试执行此操作将导致错误。

相反，可以从开发人员控制台启动存储库浏览器，为创作层、发布层和预览层上的所有环境提供对存储库的只读视图。 阅读有关存储库浏览器的更多信息 此处.

开发人员控制台中提供了一组用于调试AEMas a Cloud Service开发人员环境的工具，可用于开发、暂存和生产环境。 可通过调整创作或发布服务URL来确定该URL，如下所示：

https://dev-console/-<namespace>.<cluster>.dev.adobeaemcloud.com

作为快捷方式，可以使用以下Cloud Manager CLI命令根据下面描述的环境参数启动开发人员控制台：

aio cloudmanager:open-developer-console <ENVIRONMENTID> --programId <PROGRAMID>

请参阅 本页 以了解更多信息。

开发人员可以生成状态信息并解析各种资源。

如下图所示，可用状态信息包括包的状态、组件、OSGi配置、Oak索引、OSGi服务和Sling作业。

开发控制台1

如下所示，开发人员可以解决包依赖项和Servlet:

开发控制台2

开发控制台3

此外，开发人员控制台还有一个指向“解释查询”工具的链接，这对于调试非常有用：

开发控制台4

对于生产程序，开发人员控制台的访问权限由Admin Console中的“云管理器 — 开发人员角色”定义，而对于沙盒程序，任何具有产品配置文件且有权访问AEMas a Cloud Service的用户都可以使用开发人员控制台。 对于所有程序，状态转储需要“Cloud Manager — 开发人员角色”，并且还必须在创作和发布服务的AEM用户或AEM管理员产品配置文件中定义存储库浏览器和用户，才能查看两项服务的数据。 有关设置用户权限的更多信息，请参阅 Cloud Manager文档.

性能监控

Adobe监控应用程序性能，并采取措施在出现恶化时加以解决。 此时，无法查看应用程序量度。

发送电子邮件

以下各节介绍如何请求、配置和发送电子邮件。

注意

可以为邮件服务配置OAuth2支持。 有关更多信息，请参阅 对邮件服务的OAuth2支持.

启用出站电子邮件

默认情况下，用于发送电子邮件的端口处于禁用状态。 要激活端口，请配置 高级联网，请确保为每个需要的环境设置 PUT /program/<program_id>/environment/<environment_id>/advancedNetworking 端点的端口转发规则，该规则将目标端口（例如，465或587）映射到代理端口。

建议使用 kind 参数设置为 flexiblePortEgress 因为Adobe可以优化灵活的端口出口流量的性能。 如果需要唯一的出口IP地址，请选择 kind 参数 dedicatedEgressIp. 如果您出于其他原因配置了VPN，则还可以使用该高级网络变体提供的唯一IP地址。

您必须通过邮件服务器发送电子邮件，而不是直接通过电子邮件客户端发送。 否则，可能会阻止电子邮件。

发送电子邮件

的 Day CQ Mail Service OSGi服务 ，并且必须将电子邮件发送到支持请求中指示的邮件服务器，而不是直接发送给收件人。

配置

AEM中的电子邮件应使用 Day CQ Mail Service OSGi服务.

请参阅 AEM 6.5文档 有关配置电子邮件设置的详细信息。 对于AEMas a Cloud Service，请注意 com.day.cq.mailer.DefaultMailService OSGI 服务：

  • SMTP服务器主机名应设置为$[env:AEM_PROXY_HOST;default=proxy.tunnel]
  • 配置高级网络时，SMTP服务器端口应设置为在API调用中使用的portForwards参数中设置的原始代理端口值。 例如，30465（而不是465）

SMTP服务器端口应设置为 portDest 在配置高级网络和 portOrig 值应为一个介于所需范围30000 - 30999之间的有意义值。 例如，如果SMTP服务器端口为465，则应使用端口30465作为 portOrig 值。

在这种情况下，假设需要在配置 Day CQ Mail Service OSGI 服务：

  • 已设置 smtp.port to 30465
  • 已设置 smtp.ssl to true

或者，如果目标端口为587，则 portOrig 值30587的值。 假定应禁用SSL，则配置Day CQ Mail Service OSGI服务：

  • 已设置 smtp.port to 30587
  • 已设置 smtp.ssl to false

的 smtp.starttls 属性将由AEMas a Cloud Service在运行时自动设置为相应的值。 因此，如果 smtp.ssl 设置为true时， smtp.startls 将被忽略。 如果 smtp.ssl 设置为false时， smtp.starttls 设置为true。 这与 smtp.starttls 值。

可以选择为邮件服务配置OAuth2支持。 有关更多信息，请参阅 对邮件服务的OAuth2支持.

旧版电子邮件配置

在2021.9.0版本之前，电子邮件是通过客户支持请求配置的。 请注意以下必要调整 com.day.cq.mailer.DefaultMailService OSGI 服务：

AEMas a Cloud Service要求通过端口465发送邮件。 如果邮件服务器不支持端口465，则只要启用了TLS选项，就可以使用端口587。

如果已请求端口465:

  • set smtp.port to 465
  • set smtp.ssl to true

如果已请求端口587:

  • set smtp.port to 587
  • set smtp.ssl to false

的 smtp.starttls 属性将由AEMas a Cloud Service在运行时自动设置为相应的值。 因此，如果 smtp.ssl 设置为true时， smtp.startls 将被忽略。 如果 smtp.ssl 设置为false时， smtp.starttls 设置为true。 这与 smtp.starttls 值。

应将SMTP服务器主机设置为邮件服务器的主机。

避免大型多值属性

作为AEMas a Cloud Service基础的Oak内容存储库不打算与大量多值属性(MVP)一起使用。 经验法则是将MVP保持在1000以下。 但实际性能取决于许多因素。

在超过1000后，默认记录警告。 它们类似于以下内容。

org.apache.jackrabbit.oak.jcr.session.NodeImpl Large multi valued property [/path/to/property] detected (1029 values).

由于MongoDB文档超过16 MB，大型MVP可能会导致错误，从而导致与以下类似的错误。

Caused by: com.mongodb.MongoWriteException: Resulting document after update is larger than 16777216

请参阅 Apache Oak文档 以了解更多详细信息。

Assets 开发指南和用例

要了解资产as a Cloud Service的开发用例、建议和参考资料，请参阅 资产的开发人员参考。

在此页面上