設定本機 Dispatcher 工具 set-up-local-dispatcher-tools

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

AEM as a Cloud Service SDK包含建議的Dispatcher Tools版本，有助於設定驗證並在本機模擬Dispatcher。 Dispatcher Tools由以下部分組成：

請注意，~是用作使用者目錄的速記。 在Windows中，這相當於%HOMEPATH%。

先決條件

下載Dispatcher工具(做為AEM SDK的一部分)

AEM as a Cloud Service SDK (或AEM SDK)包含用於在本機執行Apache HTTP Web伺服器(包含Dispatcher模組以進行開發)的Dispatcher工具，以及相容的QuickStart Jar。

如果AEM as a Cloud Service SDK已下載至設定本機AEM執行階段，則不需要重新下載。

從AEM SDK Zip解壓縮Dispatcher工具

Dispatcher工具的版本與AEM SDK的版本不同。 確保透過與Dispatcher版本相符的AEM SDK版本來提供AEM as a Cloud Service工具的版本。

$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

$ 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設定檔

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指令碼提供執行validator的三個階段的便利方式。

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

在本機執行Dispatcher

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

$ ./bin/docker_run_hot_reload.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

$ bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

$ ./bin/docker_run_hot_reload.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_hot_reload.sh ./src host.docker.internal:4503 8080

$ bin\docker_run src host.docker.internal:4503 8080

$ ./bin/docker_run_hot_reload.sh ./src host.docker.internal:4503 8080

透過AEM as a Cloud Service SDK的Publish服務（于連線埠4503本機執行）可在http://localhost:8080透過Dispatcher取得。

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

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

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

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

Dispatcher工具記錄檔

在本機開發期間，Dispatcher記錄有助於瞭解HTTP請求是否遭到封鎖以及為何遭到封鎖。 記錄層級可以透過以環境引數為執行docker_run加上前置字元來設定。

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

用於偵錯Dispatcher的實用引數包括：

一或多個引數可以傳遞至docker_run

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

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

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

記錄檔存取

Apache Web Server和AEM Dispatcher記錄檔可直接在Docker容器中存取：

何時更新Dispatcher工具 dispatcher-tools-version

Dispatcher Tools版本的增加頻率低於Experience Manager，因此Dispatcher Tools在本機開發環境中所需的更新較少。

建議的Dispatcher工具版本是隨AEM as a Cloud Service SDK提供的符合Experience Manageras a Cloud Service版本的版本。 可透過Cloud Manager找到AEM as a Cloud Service的版本。

請注意，Dispatcher Tools版本與Experience Manager版本不符。

如何更新Apache和Dispatcher設定的基準組

Apache和Dispatcher設定的基準集已定期增強，並隨AEM as a Cloud Service SDK版本發行。 最佳實務是將基準設定增強功能合併到您的AEM專案中，並避免本機驗證和Cloud Manager管道失敗。 使用.../dispatcher-sdk-x.x.x/bin資料夾中的update_maven.sh指令碼更新它們。

此影片使用macOS作說明用途。 可使用同等的Windows/Linux命令來取得類似的結果。

假設您過去曾使用AEM專案原型建立AEM專案，基準Apache和Dispatcher設定為最新。 使用這些基準組態，您的專案特定組態是透過重複使用和從dispatcher/src/conf.d和dispatcher/src/conf.dispatcher.d資料夾複製*.vhost、*.conf、*.farm和*.any等檔案所建立的。 您的本機Dispatcher驗證和Cloud Manager管道運作正常。

同時，由於新功能、安全性修正和最佳化等多種原因，基準Apache和Dispatcher設定已獲得增強。 做為AEM as a Cloud Service發行版本的一部分，透過較新版本的Dispatcher Tools發行。

現在，針對最新的Dispatcher工具版本驗證您專案專屬的Dispatcher設定時，這些設定會開始失敗。 若要解決此問題，必須使用下列步驟更新基準線設定：

$ ./bin/validate.sh ${YOUR-AEM-PROJECT}/dispatcher/src

...
checking 'conf.dispatcher.d/renders/default_renders.any' immutability (if present)
checking existing 'conf.dispatcher.d/renders/default_renders.any' for changes
checking 'conf.dispatcher.d/virtualhosts/default_virtualhosts.any' immutability (if present)
checking existing 'conf.dispatcher.d/virtualhosts/default_virtualhosts.any' for changes
no immutable file has been changed - check is SUCCESSFUL
Phase 3 finished

疑難排解

docker_run導致「等到host.docker.internal可用」訊息 troubleshooting-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導致訊息​ 等候host.docker.internal可用時，則：

錯誤範例

$ 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

其他資源