设置本地 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由以下部分组成:

  • 位于.../dispatcher-sdk-x.x.x/src的Apache HTTP Web Server和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
  • 不可变配置文件覆盖CLI工具,位于.../dispatcher-sdk-x.x.x/bin/update_maven
  • 使用Dispatcher模块运行Apache HTTP Web Server的Docker图像

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

NOTE
本页中的视频是在macOS上录制的。 Windows用户可以跟随,但使用随每个视频提供的等效的Dispatcher Tools Windows命令。

先决条件

  1. Windows用户必须使用Windows 10专业版(或支持Docker的版本)
  2. 在本地开发计算机上安装Experience ManagerPublish快速入门Jar
  • 或者,在本地AEM Publish服务上安装最新的AEM引用网站。 本教程将使用此网站来可视化正在运行的Dispatcher。
  1. 在本地开发计算机上安装并启动最新版本的Docker(Docker Desktop 2.2.0.5+ / Docker引擎v19.03.9+)。

下载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运行时,则无需重新下载。

  1. 使用您的Adobe ID登录到experience.adobe.com/#/downloads
    • 必须为您的Adobe组织​ 配置 AEM as a Cloud Service才能下载AEM as a Cloud Service SDK
  2. 单击要下载的最新​ AEM SDK ​结果行

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

TIP
Windows用户在包含本地Dispatcher工具的文件夹的路径中不能有任何空格或特殊字符。 如果路径中存在空格,docker_run.cmd将失败。

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

  1. 解压缩下载的aem-sdk-xxx.zip文件
  2. 将Dispatcher工具解压缩到~/aem-sdk/dispatcher
macOS
code language-shell
$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh
Windows
aem-sdk-dispatcher-tools-x.x.x-windows.zip解压缩到C:\Users\<My User>\aem-sdk\dispatcher中(根据需要创建缺少的文件夹)。
Linux®
code language-shell
$ 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配置文件

TIP
AEM项目Maven原型创建的Experience Manager项目已预填充这组Dispatcher配置文件,因此无需从Dispatcher Tools src文件夹进行复制。

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三个阶段的简便方法。

macOS
code language-shell
$ ./bin/validate.sh ./src
Windows
code language-shell
$ bin\validate src
Linux®
code language-shell
$ ./bin/validate.sh ./src

在本地运行Dispatcher

AEM Dispatcher是针对src Dispatcher和Apache Web Server配置文件使用Docker在本地运行的。

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

docker_run_hot_reload可执行文件优先于docker_run,因为它在配置文件更改时重新加载配置文件,而无需手动终止和重新启动docker_run。 或者,可以使用docker_run,但是当配置文件发生更改时,需要手动终止和重新启动docker_run

Windows
code language-shell
$ bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>
Linux®
code language-shell
$ ./bin/docker_run_hot_reload.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

docker_run_hot_reload可执行文件优先于docker_run,因为它在配置文件更改时重新加载配置文件,而无需手动终止和重新启动docker_run。 或者,可以使用docker_run,但是当配置文件发生更改时,需要手动终止和重新启动docker_run

可以将<aem-publish-host>设置为host.docker.internal,这是解析为主机的IP的容器中由Docker提供的特殊DNS名称。 如果host.docker.internal无法解析,请参阅下面的疑难解答部分。

例如,要使用Dispatcher工具提供的默认配置文件启动Dispatcher Docker容器,请执行以下操作:

启动Dispatcher Docker容器,提供Dispatcher配置src文件夹的路径:

macOS
code language-shell
$ ./bin/docker_run_hot_reload.sh ./src host.docker.internal:4503 8080
Windows
code language-shell
$ bin\docker_run src host.docker.internal:4503 8080
Linux®
code language-shell
$ ./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文件夹。

macOS
code language-shell
$ ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
Windows
code language-shell
$ bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
Linux®
code language-shell
$ ./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的有用参数包括:

  • DISP_LOG_LEVEL=Debug将Dispatcher模块日志记录设置为“调试”级别
    • 默认值为: Warn
  • REWRITE_LOG_LEVEL=Debug将Apache HTTP Web服务器重写模块日志记录设置为调试级别
    • 默认值为: Warn
  • DISP_RUN_MODE设置Dispatcher环境的“运行模式”,加载相应的运行模式Dispatcher配置文件。
    • 默认为dev
  • 有效值: devstageprod

一个或多个参数可以传递给docker_run

macOS
code language-shell
$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
Windows
code language-shell
$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
Linux®
code language-shell
$ 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的版本。

  • Cloud Manager >环境,按​ AEM版本 ​标签指定的环境

Experience Manager版本

请注意,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.ddispatcher/src/conf.dispatcher.d文件夹中的文件,并复制*.vhost*.conf*.farm*.any等文件,创建了项目特定的配置。 您的本地Dispatcher验证和Cloud Manager管道工作正常。

同时,由于新增功能、安全修复和优化等多种原因,基准Apache和Dispatcher配置得到了增强。 它们通过作为AEM as a Cloud Service版本一部分的Dispatcher Tools的较新版本发布。

现在,针对最新的Dispatcher工具版本验证特定于项目的Dispatcher配置时,这些配置会开始失败。 要解决此问题,需要使用以下步骤更新基线配置:

  • 验证针对最新Dispatcher Tools版本的验证是否失败

    code language-shell
    $ ./bin/validate.sh ${YOUR-AEM-PROJECT}/dispatcher/src
    
    ...
    Phase 3: Immutability check
    empty mode param, assuming mode = 'check'
    ...
    ** error: immutable file 'conf.d/available_vhosts/default.vhost' has been changed!
    
  • 使用update_maven.sh脚本更新不可变文件

    code language-shell
    $ ./bin/update_maven.sh ${YOUR-AEM-PROJECT}/dispatcher/src
    
    ...
    Updating dispatcher configuration at folder
    running in 'extract' mode
    running in 'extract' mode
    reading immutable file list from /etc/httpd/immutable.files.txt
    preparing 'conf.d/available_vhosts/default.vhost' immutable file extraction
    ...
    immutable files extraction COMPLETE
    fd72f4521fa838daaaf006bb8c9c96ed33a142a2d63cc963ba4cc3dd228948fe
    Cloud manager validator 2.0.53
    
  • 验证已更新的不可变文件,如dispatcher_vhost.confdefault.vhostdefault.farm,并根据需要在自定义文件中进行相关更改(这些更改派生自这些文件)。

  • 重新验证配置,它应该会通过

$ ./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 (macOSWindows):

从Docker 18.03开始,建议连接到特殊的DNS名称host.docker.internal,它解析为主机使用的内部IP地址

bin/docker_run src host.docker.internal:4503 8080导致消息​ 等待host.docker.internal可用时,然后:

  1. 确保Docker的安装版本为18.03或更高版本
  2. 您可能设置了本地计算机,阻止注册/解析host.docker.internal名称。 请改用本地IP。
macOS
  • 在终端中,执行ifconfig并记录主机​ inet IP地址,通常是​ en0 ​设备。

  • 然后使用主机IP地址执行docker_run$ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Windows
  • 在命令提示符下,执行ipconfig并记录主机的​ IPv4地址

  • 然后,使用此IP地址执行docker_run$ bin\docker_run src <HOST IP>:4503 8080

Linux®
  • 在终端中,执行ifconfig并记录主机​ inet IP地址,通常是​ en0 ​设备。

  • 然后使用主机IP地址执行docker_run$ bin/docker_run_hot_reload.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

其他资源

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69