设置本地 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工具版本，该版本有助于在本地配置验证和模拟Dispatcher。 Dispatcher Tools由以下部分组成：

请注意，~用作用户目录的简写。 在Windows中，这相当于%HOMEPATH%。

先决条件

下载Dispatcher工具(作为AEM SDK的一部分)

AEM as a Cloud Service SDK(或AEM SDK)包含用于运行Apache HTTP Web Server的Dispatcher工具(在本地使用Dispatcher模块进行开发)以及兼容的快速入门Jar。

如果已将AEM as a Cloud Service SDK下载到设置本地AEM运行时，则无需重新下载。

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

Dispatcher Tools的版本与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 Tools内容。

本视频使用macOS进行说明。 可使用等效的Windows/Linux命令获得类似的结果。

了解Dispatcher配置文件

Dispatcher Tools提供了一组Apache HTTP Web Server和Dispatcher配置文件，这些文件定义所有环境（包括本地开发）的行为。

这些文件拟复制到Experience ManagerMaven项目的dispatcher/src文件夹中(如果Experience ManagerMaven项目中不存在这些文件)。

在解压缩的Dispatcher Tools中，配置文件的完整说明以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是针对src Dispatcher和Apache Web Server配置文件使用Docker在本地运行的。

$ ./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，这是解析为主机的IP的容器中由Docker提供的特殊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上本地运行）可通过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 Tools日志

在本地开发期间，Dispatcher日志有助于了解HTTP请求是否被阻止以及为什么被阻止。 可以通过为执行docker_run添加环境参数前缀来设置日志级别。

运行docker_run时，Dispatcher Tools日志将发出给标准。

用于调试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 Tools版本的增量频率低于Experience Manager，因此Dispatcher Tools在本地开发环境中所需的更新较少。

推荐的Dispatcher Tools版本是与Experience Manageras a Cloud Service版本匹配的AEM as a Cloud Service SDK捆绑在一起的版本。 可以通过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

其他资源