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

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

AEMas a Cloud ServiceSDK包含建議的Dispatcher工具版本，有助於設定驗證並在本機模擬Dispatcher。 Dispatcher工具由以下部分組成：

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

先決條件

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

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

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

從AEM SDK Zip解壓縮Dispatcher工具

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

$ 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專案中 dispatcher/src 資料夾(如果Experience ManagerMaven專案中不存在這些資料夾)。

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

驗證設定

Dispatcher和Apache Web伺服器設定(可選，透過 httpd -t)可使用進行驗證 validate 指令碼(不要與 validator 可執行檔)。 此 validate script提供一種便利的方式來執行 三個階段 的 validator.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

在本機執行Dispatcher

AEM Dispatcher是使用Docker針對在本機執行 src Dispatcher和Apache Web Server設定檔。

$ ./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

AEMas a Cloud ServiceSDK的發佈服務會在連線埠4503上本機執行，可透過Dispatcher存取： http://localhost:8080.

若要針對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 以及環境引數。

Dispatcher工具記錄檔在下列情況下發出到標準 docker_run 執行前填入。

用於偵錯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網頁伺服器和AEM Dispatcher記錄檔可直接在Docker容器中存取：

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

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

建議的Dispatcher工具版本是隨AEMas a Cloud ServiceSDK提供的版本，此版本符合Experience Manageras a Cloud Service版本。 AEMas a Cloud Service的版本可透過以下方式找到： Cloud Manager.

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

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

Apache和Dispatcher設定的基準集會定期增強，並與AEMas a Cloud ServiceSDK版本一起發行。 最佳實務是將基準設定增強功能併入您的AEM專案並避免 本機驗證 和Cloud Manager管道故障。 使用 update_maven.sh 指令碼來自 .../dispatcher-sdk-x.x.x/bin 資料夾。

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

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

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

現在，當針對最新的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

其他資源