AEM as a Cloud Service 開發指導方針

本檔案提供在AEMas a Cloud Service上開發的准則，以及AMS中與內部部署和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排程器不應用於排程，因為執行無法保證。 只是更有可能會安排。

同樣地，如果非同步發生所有動作，例如對觀察事件採取行動（無論是JCR事件或Sling資源事件），就無法保證執行，因此必須謹慎使用。 目前的AEM部署已採用此方法。

傳出HTTP連線

強烈建議任何傳出的HTTP連線都設定合理的連線和讀取逾時；建議的值為連線逾時的1秒，讀取逾時的為5秒。 確切數字必鬚根據處理這些要求的後端系統效能來決定。

對於不套用這些逾時的程式碼，在AEMas a Cloud Service上執行的AEM例項將強制執行全域逾時。 這些逾時值是連線呼叫的10秒，連線的讀取呼叫的60秒。

Adobe建議使用提供的 Apache HttpComponents Client 4.x資料庫 用於建立HTTP連線。

已知可行，但可能需要自行提供相依性的替代方案為：

在提供逾時的旁邊，也應實作此類逾時和非預期HTTP狀態代碼的適當處理。

沒有傳統UI自定義

AEM as a Cloud Service僅支援第三方客戶代碼的觸控式UI。 傳統UI無法自訂。

避免本機二進位檔

程式碼將無法在執行階段下載二進位檔，也無法加以修改。 例如，它將無法解壓縮 jar 或 tar 檔案。

沒有透過AEMas a Cloud Service的串流二進位檔

二進位檔應透過CDN來存取，CDN將提供核心AEM服務以外的二進位檔。

例如，請勿使用 asset.getOriginal().getStream()，會觸發將二進位檔下載至AEM服務的短暫磁碟。

無反向複製代理

AEMas a Cloud Service不支援從「發佈」反向復寫至「作者」。 如果需要此策略，您可以使用在發佈執行個體群組（可能是製作叢集）中共用的外部永續性存放區。

可能需要移植轉發複製代理

內容會透過發佈子機制從製作複製到發佈。 不支援自定義複製代理。

監控與除錯

記錄檔

針對本機開發，記錄項目會寫入 /crx-quickstart/logs 檔案夾。

在雲端環境中，開發人員可以透過Cloud Manager下載記錄檔，或使用命令列工具追蹤記錄檔。

設定記錄層級

若要變更雲端環境的記錄層級，應修改Sling Logging OSGI設定，然後完全重新部署。 由於這並非即時進行，請務必小心，不要在接收大量流量的生產環境中啟用詳細記錄。 未來可能會有更快速變更記錄層級的機制。

注意

若要執行下列設定變更，您必須在本機開發環境中建立這些變更，然後推送至AEMas a Cloud Service執行個體。 如需如何執行此動作的詳細資訊，請參閱 部署至AEMas a Cloud Service.

啟用偵錯記錄層級

預設日誌級別為INFO，即未記錄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"
}

請勿讓除錯記錄層級的記錄超過必要時間，因為這會產生許多項目。

如果想要一律登入，可使用基於執行模式的OSGi組態鎖定目標，為不同AEM環境設定離散記錄層級 DEBUG 開發期間。 例如：

|環境 |按運行模式的OSGi配置位置 | org.apache.sling.commons.log.level 屬性值 | | - | - | - | |開發 | /apps/example/config/org.apache.sling.commons.log.LogManager.factory.config~example.cfg.json |除錯 | | Stage | /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 Console(/system/console)。

請注意，在本機開發（使用SDK）時， /apps 和 /libs 可直接寫入，這與雲端環境不同，雲端環境中的這些頂層資料夾不可修改。

AEM as a Cloud Service 開發工具

客戶可在製作層級的開發環境中存取CRXDE lite，但無法預備或生產。 不可變的儲存庫(/libs, /apps)無法在執行階段寫入，因此嘗試寫入會導致錯誤。

而是可從開發人員控制台啟動存放庫瀏覽器，提供製作、發佈和預覽層級上所有環境的存放庫唯讀檢視。 深入了解存放庫瀏覽器 此處.

針對RDE、開發、預備和生產環境，可在開發人員主控台中取得一組用於除錯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調用中使用的portForwerds參數中設定的原始代理埠的值。 例如30465（而非465）

SMTP伺服器埠應設定為 portDest 設定進階網路時，在API呼叫中使用的portForwards參數中設定的值，以及 portOrig 值應是介於所需範圍30000 - 30999內的有意義值。 例如，如果SMTP伺服器埠是465，則應使用埠30465作為 portOrig 值。

在此情況下，假設需要啟用SSL，請在 Day CQ Mail Service OSGI 服務：

  • 設定 smtp.port to 30465
  • 設定 smtp.ssl to true

或者，如果目標埠為587，則a 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 值。

Mail Service可選擇配置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).

大型MVP可能會導致錯誤，因為MongoDB文檔超過16 MB，導致類似以下的錯誤。

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

請參閱 Apache Oak檔案 以取得更多詳細資訊。

Assets 開發指南和使用案例

若要了解Assetsas a Cloud Service的開發使用案例、建議和參考資料，請參閱 資產的開發人員參考。

本頁內容