将 AEM 边缘交付从基于文件的配置迁移到配置服务的指南

style

border-bottom-glow

注：这是一个关于边缘交付服务& 文档撰写的高级话题。有关 EDS& Document Authoring 的介绍，请先查看此文以了解背景情况。

基于文件的 AEM 边缘交付配置背景& 配置服务

在 Adobe 首次推出边缘交付服务（或内部称为 Helix）时，所有主要的全站配置都是通过将配置文件检查到网站资源库来完成的。部署新配置的方法是推送到软件仓库的main 分支，该分支会将配置推送到网站上。这样做的一个缺点是，任何给定的存储库都必须与站点和文件存储库直接绑定。这样就不能用一个代码库驱动多个网站，甚至是一个网站的多个版本（如dev/stg/prd 风格的内容或配置暂存环境）。

由于这个原因和其他技术方面的考虑，Adobe 已经开始转向以配置服务为基础的新架构设计。在这种模式下，配置由 Adobe 在其 API 驱动的配置服务中集中存储和版本控制，一旦迁移到该服务，Edge Delivery 项目中的文件将不再对网站产生任何影响。

转到配置服务的先决条件

如https://www.aem.live/docs/config-service-setup#prerequisites 上所述，在开始向配置服务迁移之前，首先需要确保 Adobe 用户被映射为 Github org 的管理员，这样你才有权在配置服务中进行更改。您通常与之打交道的 Adobe 技术联系人应该能帮您解决这个问题。

端点& 受移至配置服务影响的配置界面

这会影响边缘交付项目中的以下配置界面：

内容总线映射：/fstab.yaml 中项目映射到 DA（或其他地方，如 AEM/Universal Editor 或 Sharepoint）位置的配置现在在配置服务中。这是最关键的一点，它允许一个 repo 驱动多个网站（以前称为"无 repoless" 设置，因为它意味着代码 repo 和内容 repo 没有千丝万缕的联系）。
查询索引：所有语言的索引配置以前都存储在项目的 /helix-query.yaml
网站地图配置：网站地图配置以前在/helix-sitemap.yaml 中进行，现在将在配置服务中进行。
Sidekick 配置：有两种不同类型的 Sidekick 配置以前保存在 git 项目中，现在放在了其他地方。
- DA 插件：以前，在 DA 的早期，我们将 DA 插件保存在代码库中的/tools/sidekick/config.json 文件中。这将用于各种 DA UI 增强功能，如我们的日期选择器、AEM 标签插件等。这些信息现在保存在 DA 配置中的Library 表中，而不是代码库中。
- Sidekick 插件/配置：其他 AEM Sidekick 配置，如用于快速编辑或 AEM 实验的配置，现在直接保存在配置服务中，而不是 DA 中。EDS git 项目中的 Sidekick 配置不再有任何作用。
HTTP 标头配置：该配置以前保存在headers 的 DA 表中，但现在将推送到配置服务中。用于 CORS 配置，如在某些主机上粘贴access-control-allow-origin 标头。
Helix 预览/发布身份验证：对于通过身份验证的预览/发布访问控制，我们一直使用基于工作表的身份验证模型，在https://da.live/sheet#/[orgname]/[sitename]/.helix/config 中有一个data 工作表，其中列出了映射到用户/文件的各个 Adobe 实体 ID 的admin.role.author 或admin.role.publish 角色。现在，配置服务取消了这一功能，直接在配置服务中管理用户的预览/发布角色以及访问请求。此外，以前的验证发布要求使用难以辨认的 Adobe 配置文件/用户 ID，如"[email protected]" ，该 ID 将映射到用户在特定 org 上的登录信息。现在，在配置服务中，Helix 会让你使用电子邮件地址，而不是无法使用的实体 ID，甚至会允许用户在遇到预览/发布问题时，"请求访问" ，然后会显示到 DA 中的管理界面应用程序，以批准/拒绝访问请求。
Robots.txt 配置：该配置以前保存在 git 项目的/robots.txt 中，但现在在配置服务中进行配置。
CDN 配置：该配置以前保存在 DA 中的.helix/config 表中，但现在被推送到配置服务中。这将用于设置类似的值：
- cdn.prod.host
- cdn.prod.type
- cdn.prod.serviceId
- cdn.prod.authToken

将现有基于文件的边缘交付站点移至配置服务的步骤

AEM 管理（Helix）应用程序接口中有一个migrate 命令，可以将基于文件的边缘交付设置自动迁移到配置服务。不过也有一些注意事项，下面就来了解一下。

首先，假设您有一个使用基于文件的配置在 DA 上创建的现有网站（我知道我有几个这样的网站，我可能是少数，但这是我的博文--您需要根据自己的使用情况重新评估步骤）。

步骤：

确保您是组织的管理员：如上所述，请与 Adobe 合作，确保您的 Github org 上有admin 。请登录https://tools.aem.live/tools/site-admin/index.html 验证。如果运行正常，您应该会看到一个成功的 200 请求，内容是 https://admin.hlx.page/config/[orgname]/sites.json
获取授权令牌：使用 shift+ctrl+I 或 shift+cmd+I 弹出开发工具，然后查看上述sites.json 请求。如果打开网络选项卡，查看 "标头"，就会看到x-auth-token 值。复制该值，因为这是您在以下与 AEM 配置服务交互的 API 请求中需要使用的承载令牌。
复制一个网站：最好在你的网站（使用基于文件的配置的网站）上进行一次测试运行，这样你就可以在 prod 上运行之前测试这个过程。创建一个新的 EDS repo& 站点，并在其中填充与当前站点相同的代码库（如果还没有开发 repo）。最好还能填充一个开发内容源，这样你就有了一个全副武装、可运行的沙盒，可以随意摆弄。
运行迁移命令模拟运行： 运行以下命令，进行从基于文件到配置服务的迁移的模拟运行：

curl --request GET --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true&validate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"

如果运行成功，它将吐出如下验证文本，告诉你迁移是否成功。就我而言，这意味着我还没准备好迁移，还有一些问题需要解决：

"error": "validation failed.", "message": "/sidekick/plugins/0/environments/0 must be equal to one of the allowed values; /sidekick/plugins/2/environments/0 must be equal to one of the allowed values",

此外，如果你在调用时收到 400 bad request，也可以使用 HTTP 响应中的x-error 标头，它也会告诉你迁移干运行请求中的任何问题：

在这种情况下，该错误告诉我，在我的 AEM Sidekick 插件列表中，/tools/sidekick/config.json 中的第一个插件无效，因为 Config Service 不再支持以这种方式配置插件。在本例中，我需要将此插件迁移到 DA 插件的 DA 库表单中。
如上所述，修复任何验证问题：您需要检查并修复出现的任何问题，然后重新运行验证请求。

将项目中定义为 Sidekick 插件的任何现有插件放到 DA 中。在 Sidekick 插件出现类似问题的情况下，DA 插件将在https://da.live/config#/[orgname]/[sitename]/ 的工作表"库" 选项卡中进行配置。

或者另一个类似的问题：

这表明我们的标头中有一些不再受支持的非法属性（或者可能从未受支持，只是没有破坏任何东西，所以被错误地留在了标头中）。

处理完这些问题后，就可以运行迁移本身了。
将& 验证过的干净配置推送/迁移到配置服务：要推送配置，请使用以下命令：

curl --request POST --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"

与上述命令基本相同，但使用POST 代替GET 。这将把您迁移到配置服务。
验证：迁移后有几件事需要立即验证。
1. 验证索引：访问https://tools.aem.live/tools/index-admin/index.html 并验证索引是否已正确调入
2. 验证网站地图：访问https://tools.aem.live/tools/sitemap-admin/index.html 并验证所有网站地图都已通过
3. 验证用户：访问https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} ，确保您的预览/发布用户显示在那里。
4. 在 DA 中验证用户：转到https://da.live/apps/aem-permissions#/{orgname}/{sitename} ，这将让你看到用户友好的预览/发布权限列表，因为它们暴露在 DA 中。在这里，您还可以
5. 验证预览/发布：以具有预览/发布权限的用户身份登录时，确保您仍具有适当的预览/发布能力。找一个没有预览或发布权限的用户，并确保适当锁定。
6. 您认为网站需要的任何其他验证。
磨合：QA& 与团队一起进行试运行，解决出现的任何其他预览/发布问题，并让新配置试运行至少一周，以消除可能出现的任何其他问题。
清理配置文件：烧录完成后，您将不再需要发布中的配置文件，可以开始逐个删除这些文件。出于灾难恢复的目的，我建议将当前配置的完整副本保存到 git 进行版本管理，以防有人提出错误的 API 请求，而无论出于什么原因都无法撤销。

关于配置服务的 CI/CD 影响的说明

关于 CI/CD 的注意事项：现在，您拥有了 API 驱动的配置服务所固有的灵活性，但也有一个缺点，那就是 git 驱动的 CI/CD 不再有任何作用。

好消息是，有一些工具（如版本管理器）可以跟踪配置更改以及谁做了哪些更改：

坏消息是，这将移除我们在 Edge Delivery 中熟悉和喜爱的以拉请求为中心的内置 CI/CD 框架。因此，如果您想让初级工程师提出变更建议，那么让他们向您提交一个拉取请求，证明他们的配置变更可以安全地向前推进，就会变得更加棘手。

API 的授权基于当前登录的用户，这使得将一组持久密钥集成到 CI/CD 管道中的尝试略显困难。我相信可以做到，只是需要一些调整。

因此，为此（在撰写本文时），您需要根据组织的规模和构成，推出自己觉得合适的 CI/CD 流程。

希望对您有所帮助，如果您在使用过程中遇到任何问题，请给我们留言！

关于作者

泰德-里夫斯

Arbory Digital 首席架构师

Tad 是两届 AEM 冠军，自 2010 年以来一直与 Adobe Experience Manager& CQ 合作。从 1996 年开始，他几乎戴过网站交付领域的所有帽子，从解决方案架构到产品管理，以及多年的开发和系统管理经验。他喜欢雅保利数字公司给他的机会，让他能够提供诚实有效的解决方案，即使这意味着要挑战普遍的销售观点。Tad 不工作的时候（有时工作的时候），喜欢骑山地自行车，并与妻子& 3 个孩子一起探索大自然。

在 Linkedin 上联系 Tad

喜欢你听到的吗？对什么适合您有疑问？我们很乐意与您交谈！联系我们