設定本機Dispatcher工具

Adobe Experience Manager(AEM)的Dispatcher是Apache HTTP Web伺服器模組,可在CDN和AEM Publish層級之間提供安全性和效能層。 Dispatcher是整體Experience Manager架構的必要部分,且應是本機開發設定的一部分。

AEM as a Dispatcher SDK包含建議的Dispatcher工具版本,有助於在本機設定、驗證和模擬Dispatcher。 Dispatcher工具由下列部分組成:

  • 位於.../dispatcher-sdk-x.x.x/src的Apache HTTP Web伺服器和Dispatcher配置檔案的基準集
  • 配置驗證器CLI工具,位於.../dispatcher-sdk-x.x.x/bin/validate
  • 配置生成CLI工具,位於.../dispatcher-sdk-x.x.x/bin/validator
  • 配置部署CLI工具,位於.../dispatcher-sdk-x.x.x/bin/docker_run
  • 使用Dispatcher模組執行Apache HTTP Web伺服器的Docker影像

請注意, ~是用戶目錄的簡稱。 在Windows中,這等同於%HOMEPATH%

注意

本頁的影片是在macOS上錄制的。 Windows使用者可以跟著,但使用每個視訊隨附的同等Dispatcher工具Windows命令。

必備條件

  1. Windows用戶必須使用Windows 10 Professional(或支援Docker的版本)
  2. 在本地開發電腦上安裝Experience Manager發佈快速入門Jar
    • (可選)在本機AEM發佈服務上安裝最新的AEM參考網站。 本教學課程會使用此網站來視覺化運作中的Dispatcher。
  3. 在本地開發電腦上安裝並啟動最新版本的Docker(Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+)。

下載Dispatcher工具(附於AEM SDK)

AEM as a Dispatcher SDK或AEM SDK包含Dispatcher工具,可用於在本機執行Apache HTTP Web伺服器,並搭配Dispatcher模組進行開發,以及相容的QuickStart Jar。

如果AEM as aCloud ServiceSDK已下載至設定本機AEM執行階段,則不需要重新下載。

  1. 使用您的Adobe ID登入experience.adobe.com/#/downloads
    • 您的Adobe組織​必須​布建給AEM作為Cloud Service,才能以Cloud ServiceSDK的形式下載AEM
  2. 按一下要下載的最新​AEM SDK​結果列

從AEM SDK壓縮Dispatcher工具

秘訣

Windows使用者在包含本機Dispatcher工具之資料夾的路徑中,不能有任何空格或特殊字元。 如果路徑中存在空格,docker_run.cmd將會失敗。

Dispatcher工具的版本與AEM SDK的版本不同。 確認Dispatcher工具的版本是透過與AEM相符的AEM SDK版本提供,作為Cloud Service版本。

  1. 將下載的aem-sdk-xxx.zip檔案解壓縮
  2. 將Dispatcher工具解壓縮至~/aem-sdk/dispatcher
    • 窗口:將aem-sdk-dispatcher-tools-x.x.x-windows.zip解壓縮至C:\Users\<My User>\aem-sdk\dispatcher(視需要建立遺失的資料夾)
    • macOS / Linux:執行隨附的shell指令碼aem-sdk-dispatcher-tools-x.x.x-unix.sh以解壓縮Dispatcher工具
      • chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh && ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

請注意,下面發出的所有命令都假設當前工作目錄包含展開的Dispatcher工具內容。

此影片會使用macOS做說明用途。可以使用等效的Windows/Linux命令來實現類似的結果

了解Dispatcher設定檔

秘訣

AEM專案Maven原型建立的Experience Manager專案會預先填入這組Dispatcher組態檔,因此不需要從Dispatcher工具src資料夾複製。

Dispatcher工具提供一組Apache HTTP Web伺服器和Dispatcher設定檔,可定義所有環境的行為,包括本機開發。

如果這些檔案尚未存在於Experience ManagerMaven專案中,則這些檔案將複製到Experience ManagerMaven專案中dispatcher/src資料夾。

解壓縮的Dispatcher工具中提供設定檔案的完整說明,如dispatcher-sdk-x.x.x/docs/Config.html

驗證配置

您可以選擇使用validate指令碼來驗證Dispatcher和Apache Web伺服器配置(透過httpd -t)(不要與validator執行檔混淆)。 validate指令碼提供了運行validator3個階段的便利方式。

  • 使用狀況:
    • Windows: bin\validate src
    • macOS / Linux:./bin/validate.sh ./src

在本機執行Dispatcher

AEM Dispatcher是針對src Dispatcher和Apache Web伺服器組態檔,使用Docker在本機上執行。

  • 使用狀況:
    • 窗口:bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>
    • macOS / Linux:./bin/docker_run.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

<aem-publish-host>可設為host.docker.internal,Docker在解析到主機IP的容器中提供特殊的DNS名稱。 如果host.docker.internal未解析,請參閱下面的疑難解答部分。

例如,若要使用Dispatcher工具提供的預設組態檔來啟動Dispatcher Docker容器:

啟動Dispatcher Docker容器,提供Dispatcher設定src資料夾的路徑:

  • 窗口:bin\docker_run src host.docker.internal:4503 8080
  • macOS / Linux:./bin/docker_run.sh ./src host.docker.internal:4503 8080

在連接埠4503上本機執行的AEM as aCloud ServiceSDK發佈服務,將可透過Dispatcher在http://localhost:8080取得。

若要針對Experience Manager專案的Dispatcher設定執行Dispatcher工具,請指向您專案的dispatcher/src資料夾。

  • Windows:

    $ bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
    
  • macOS / Linux:

    $ ./bin/docker_run.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
    

Dispatcher工具記錄檔

在本機開發期間,Dispatcher記錄檔有助於了解HTTP要求是否遭到封鎖及其原因。 可使用環境參數預先設定docker_run的執行,以設定記錄層級。

docker_run執行時,Dispatcher工具記錄檔會發出至標準輸出。

用於偵錯Dispatcher的實用參數包括:

  • DISP_LOG_LEVEL=Debug 將Dispatcher模組記錄設為「除錯」層級
    • 預設值為: Warn
  • REWRITE_LOG_LEVEL=Debug 將Apache HTTP Web伺服器重寫模組日誌設定為Debug級別
    • 預設值為: Warn
  • DISP_RUN_MODE 設定Dispatcher環境的「執行模式」,並載入相應的執行模式Dispatcher設定檔案。
    • 預設為 dev
  • 有效值:devstageprod

可傳遞一或多個參數至docker_run

  • 窗口:

    $ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
    
  • macOS / Linux:

    $ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug ./bin/docker_run.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
    

記錄檔存取

您可以在Docker容器中直接存取Apache Web伺服器和AEM Dispatcher記錄檔:

更新Dispatcher工具的時機

Dispatcher工具版本的遞增頻率比Experience Manager低,因此,Dispatcher工具在本機開發環境中需要的更新較少。

建議的Dispatcher工具版本是與AEM搭配的Cloud ServiceSDK,與Experience Manager作為Cloud Service版本相符。 您可以透過Cloud Manager找到AEM as aCloud Service版本。

  • Cloud Manager >環境,根據AEM Releaselabel指定的

Experience Manager版本

請注意,Dispatcher工具版本本身將不符合Experience Manager版本。

疑難排解

docker_run結果「等到host.docker.internal可用」消息

host.docker.internal 是提供給Docker包含的主機名,它解析到主機。根據docs.docker.com(macOS, Windows):

從Docker 18.03開始,我們的建議是連線至特殊的DNS名稱host.docker.internal,其解析至主機使用的內部IP位址

如果bin/docker_run src host.docker.internal:4503 8080導致消息​Waiting untith.docker.internal可用,則:

  1. 確保安裝的Docker版本為18.03或更高版本
  2. 您可能設定了本地電腦,該電腦會阻止host.docker.internal名稱的註冊/解析。 請改用本機IP。
    • 窗口:
      • 在命令提示符下,執行ipconfig,並記錄主機的​IPv4地址

      • 然後,使用此IP地址執行docker_run:

        bin\docker_run src <HOST IP>:4503 8080

    • macOS / Linux:
      • 從終端,執行ifconfig並記錄主機​inet IP地址,通常為​en0​設備。

      • 然後使用主機IP地址執行docker_run:

        bin/docker_run.sh src <HOST IP>:4503 8080

範例錯誤

$ docker_run src host.docker.internal:4503 8080

Running script /docker_entrypoint.d/10-check-environment.sh
Running script /docker_entrypoint.d/20-create-docroots.sh
Running script /docker_entrypoint.d/30-wait-for-backend.sh
Waiting until host.docker.internal is available

docker_run在Windows上無法啟動

在Windows上執行docker_run可能會導致下列錯誤,導致Dispatcher無法啟動。 這是Windows上Dispatcher回報的問題,將於未來版本中修正。

範例錯誤

$ \Users\MyUser\aem-sdk\dispatcher>bin\docker_run src host.docker.internal:4503 8080

Running script /docker_entrypoint.d/10-check-environment.sh
Running script /docker_entrypoint.d/20-create-docroots.sh
Running script /docker_entrypoint.d/30-wait-for-backend.sh
Waiting until host.docker.internal is available
host.docker.internal resolves to 192.168.65.2
Running script /docker_entrypoint.d/40-generate-allowed-clients.sh
Running script /docker_entrypoint.d/50-check-expiration.sh
Running script /docker_entrypoint.d/60-check-loglevel.sh
Running script /docker_entrypoint.d/70-check-forwarded-host-secret.sh
Starting httpd server
[Sun Feb 09 17:32:22.256020 2020] [dispatcher:warn] [pid 1:tid 140080096570248] Unable to obtain parent directory of /etc/httpd/conf.dispatcher.d/enabled_farms/farms.any: No such file or directory
[Sun Feb 09 17:32:22.256069 2020] [dispatcher:alert] [pid 1:tid 140080096570248] Unable to import config file: /etc/httpd/conf.dispatcher.d/dispatcher.any
[Sun Feb 09 17:32:22.256074 2020] [dispatcher:alert] [pid 1:tid 140080096570248] Dispatcher initialization failed.
AH00016: Configuration Failed

其他資源

本頁內容