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

  • Apache HTTP Web服务器和Dispatcher配置文件的基线集,位于 .../dispatcher-sdk-x.x.x/src
  • 配置验证器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服务器的Docker图像

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

NOTE
本页中的视频是在macOS上录制的。 Windows用户可以随后进行操作,但使用随每个视频提供的等效的Dispatcher工具Windows命令。

先决条件

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

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

AEMas a Cloud ServiceSDK(或AEM SDK)包含用于在本机运行带有Dispatcher模块的Apache HTTP Web服务器以进行开发的Dispatcher工具,以及兼容的快速入门Jar。

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

  1. 登录 experience.adobe.com/#/downloads 使用您的Adobe ID
    • 您的Adobe组织 必须 已配置AEMas a Cloud Service以下载AEMas a Cloud ServiceSDK
  2. 单击最新的 AEM SDK 要下载的结果行

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

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

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

  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.zipC:\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工具内容。

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

了解Dispatcher配置文件

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

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.

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在本地运行,使用Docker针对 src Dispatcher和Apache Web Server配置文件。

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,Docker在解析为主机的IP的容器中提供的特殊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

AEMas a Cloud ServiceSDK的发布服务在端口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工具日志

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

Dispatcher工具日志在下列情况下发出到标准 docker_run 运行。

用于调试Dispatcher的有用参数包括:

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

可以将一个或多个参数传递到 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工具版本的增量低于Experience Manager,因此Dispatcher工具在本地开发环境中所需的更新较少。

推荐的Dispatcher Tools版本是与AEMas a Cloud ServiceSDK捆绑在一起,与Experience Manageras a Cloud Service版本匹配的。 AEMas a Cloud Service的版本可以通过以下方式找到 Cloud Manager.

  • Cloud Manager >环境,根据指定的环境 AEM版本 标签

Experience 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*.anydispatcher/src/conf.ddispatcher/src/conf.dispatcher.d 文件夹。 您的本地Dispatcher验证和Cloud Manager管道工作正常。

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

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

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

    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.vhost、和 default.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 设备。

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

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

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

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

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