设置本地 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%
.
前提条件
- Windows用户必须使用Windows 10专业版(或支持Docker的版本)
- 安装 Experience Manager发布快速入门Jar 在本地开发计算机上。
- 或者,安装最新的 AEM参考网站 在本地AEM Publish服务上。 本教程将使用此网站来可视化正在运行的Dispatcher。
- 安装并启动最新版本的 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运行时,无需重新下载。
- 登录 experience.adobe.com/#/downloads 使用您的Adobe ID
- 您的Adobe组织 必须 已配置AEMas a Cloud Service以下载AEMas a Cloud ServiceSDK
- 单击最新的 AEM SDK 要下载的结果行
从AEM SDK zip文件中提取Dispatcher工具
docker_run.cmd
失败。Dispatcher工具的版本与AEM SDK的版本不同。 确保通过与AEMas a Cloud Service版本匹配的AEM SDK版本提供了Dispatcher Tools的版本。
- 解压缩下载的
aem-sdk-xxx.zip
文件 - 将Dispatcher工具解压缩到
~/aem-sdk/dispatcher
code language-shell |
---|
|
aem-sdk-dispatcher-tools-x.x.x-windows.zip
到 C:\Users\<My User>\aem-sdk\dispatcher
(根据需要创建缺少的文件夹)。code language-shell |
---|
|
下面发出的所有命令都假定当前工作目录包含扩展的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
.
code language-shell |
---|
|
code language-shell |
---|
|
code language-shell |
---|
|
在本地运行Dispatcher
AEM Dispatcher在本地运行,使用Docker针对 src
Dispatcher和Apache Web Server配置文件。
code language-shell |
---|
|
此 docker_run_hot_reload
可执行文件优先于 docker_run
因为它在配置文件更改时重新加载这些文件,而无需手动终止和重新启动 docker_run
. 或者, docker_run
可以使用,但需要手动终止和重新启动 docker_run
更改配置文件时。
code language-shell |
---|
|
code language-shell |
---|
|
此 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文件夹的路径:
code language-shell |
---|
|
code language-shell |
---|
|
code language-shell |
---|
|
AEMas a Cloud ServiceSDK的发布服务在端口4503上本地运行,可通过Dispatcher在以下位置获取: http://localhost:8080
.
要针对Experience Manager项目的Dispatcher配置运行Dispatcher工具,请指向您项目的 dispatcher/src
文件夹。
code language-shell |
---|
|
code language-shell |
---|
|
code language-shell |
---|
|
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
- 默认为
- 有效值:
dev
,stage
,或prod
可以将一个或多个参数传递到 docker_run
code language-shell |
---|
|
code language-shell |
---|
|
code language-shell |
---|
|
日志文件访问
可直接在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版本 标签
请注意,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配置时,这些配置会开始失败。 要解决此问题,需要使用以下步骤更新基线配置:
-
验证针对最新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.conf
,default.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 (macOS, Windows):
从Docker 18.03开始,建议连接到特殊的DNS名称host.docker.internal,它解析为主机使用的内部IP地址
时间 bin/docker_run src host.docker.internal:4503 8080
消息中的结果 等待host.docker.internal可用,则:
- 确保Docker的安装版本为18.03或更高版本
- 您可能设置了本地计算机,阻止注册/解析
host.docker.internal
名称。 请改用本地IP。
-
从终端,执行
ifconfig
并记录主机 inet IP地址,通常为 en0 设备。 -
然后执行
docker_run
使用主机IP地址:$ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080
-
在命令提示符下,执行
ipconfig
,并记录主机的 IPv4地址 主机的URL。 -
然后,执行
docker_run
使用此IP地址:$ bin\docker_run src <HOST IP>:4503 8080
-
从终端,执行
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