设置本地 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工具，以及兼容的快速入门Jar。

如果AEMas a Cloud ServiceSDK已下载到 设置本地AEM运行时，无需重新下载。

从AEM SDK zip文件中提取Dispatcher工具

Dispatcher工具的版本与AEM SDK的版本不同。 确保通过与AEMas a Cloud Service版本匹配的AEM SDK版本提供了Dispatcher Tools的版本。

$ 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 Manager的Maven项目中 dispatcher/src 文件夹(如果Experience ManagerMaven项目中不存在这些文件夹)。

在解压缩的Dispatcher工具中，提供了配置文件的完整说明，如下所示 dispatcher-sdk-x.x.x/docs/Config.html.

验证配置

（可选）Dispatcher和Apache Web Server配置(通过 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

日志文件访问

可直接在Docker容器中访问Apache Web Server和AEM Dispatcher日志：

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

Dispatcher工具版本的增量低于Experience Manager，因此Dispatcher工具在本地开发环境中所需的更新较少。

推荐的Dispatcher Tools版本是与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配置得到了增强。 它们通过较新版本的Dispatcher Tools作为AEMas a Cloud Service版本的一部分发布。

现在，针对最新的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

其他资源