为Adobe Experience Manager as a Cloud Service配置OSGi

osgi 是Adobe Experience Manager (AEM)技术栈栈中的基本元素。 它用于控制AEM的复合捆绑包及其配置。

OSGi提供了标准化的基元，允许使用小型、可重用的协作组件构建应用程序。 这些组件可以组合为一个应用程序并部署。 这样可以轻松地管理OSGi包，因为它们可以单独停止、安装和启动。 系统会自动处理相互依赖关系。 每个OSGi组件都包含在各种捆绑包中。 欲了解更多信息，请参见 OSGi规范.

您可以通过属于AEM代码项目一部分的配置文件来管理OSGi组件的配置设置。

OSGi配置文件

配置更改在AEM项目的代码包中定义(ui.apps)作为配置文件(.cfg.json)，位于runmode特定配置文件夹下：

/apps/example/config.<runmode>

OSGi配置文件的格式基于JSON，使用 .cfg.json Apache Sling项目定义的格式。

OSGi配置通过组件的永久标识(PID)来定位OSGi组件，该PID默认为OSGi组件的Java™类名称。 例如，为通过以下方式实现的OSGi服务提供OSGi配置：

com.example.workflow.impl.ApprovalWorkflow.java

在以下位置定义OSGi配置文件：

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

遵循 cfg.json osgi配置格式。

运行模式分辨率

可以使用运行模式将特定OSGi配置定位到特定AEM实例。 要使用runmode，请在下创建配置文件夹 /apps/example （其中example是您的项目名称），格式为：

/apps/example/config.<author|publish>.<dev|stage|prod>/

如果配置文件夹名称中定义的运行模式与AEM使用的运行模式匹配，则使用此类文件夹中的任何OSGi配置。

例如，如果AEM使用runmodes author和dev，则配置节点位于 /apps/example/config.author/ 和 /apps/example/config.author.dev/ ，而配置节点位于 /apps/example/config.publish/ 和 /apps/example/config.author.stage/ 不会应用。

如果同一PID有多个配置可用，则应用匹配运行模式数最多的配置。

此规则的粒度处于PID级别。 这意味着您不能在中为同一PID定义某些属性 /apps/example/config.author/ 以及中更具体的 /apps/example/config.author.dev/ 相同PID的。 匹配运行模式数量最多的配置对整个PID有效。

在进行本地开发时，运行架构启动参数 -r 用于指定运行架构 OSGI 配置。

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

验证运行模式

AEMas a Cloud Service的运行模式根据环境类型和服务进行了良好的定义。 查看 可用AEMas a Cloud Service运行模式的完整列表.

运行模式指定的OSGi配置值可以通过以下方式验证：

1. 打开AEM as aCloud Services环境的 开发人员控制台
2. 选择要检查的服务层，使用 Pod 下拉列表
3. 选择 状态 选项卡
4. 选择 配置 从 状态转储 下拉列表
5. 选择 获取状态 按钮

结果视图显示选定层的所有OSGi组件配置及其适用的OSGi配置值。 这些值可以与AEM项目源代码中的OSGi配置值交叉引用，位于 /apps/example/osgiconfig/config.<runmode(s)>.

要验证是否应用了适当的OSGi配置值，请执行以下操作：

1. 在开发人员控制台的配置输出中
2. 找到 pid 表示要验证的OSGi配置；这是AEM项目源代码中的OSGi配置文件的名称。
3. Inspect properties 的列表 pid 并验证键和值是否与要验证的运行模式的AEM项目源代码中的OSGi配置文件匹配。

OSGi配置值的类型

有三种版本的OSGi配置值可以与Adobe Experience Manager as a Cloud Service一起使用。

1. 内联值，这些值已硬编码到OSGi配置中并存储在Git中。 例如：

   {
      "connection.timeout": 1000
   }
   

2. 密码值，出于安全原因，这些值不得存储在Git中。 例如：

   {
   "api-key": "$[secret:server-api-key]"
   }
   

3. 特定于环境的值，这些值在开发环境之间有所不同，因此无法通过运行模式进行准确定位(因为只有一个 dev runmode(在Adobe Experience Manager as a Cloud Service中)。 例如：

   {
    "url": "$[env:server-url]"
   }
   

   单个OSGi配置文件可以结合使用这些配置值类型的任意组合。 例如：

   {
   "connection.timeout": 1000,
   "api-key": "$[secret:server-api-key]",
   "url": "$[env:server-url]"
   }
   

如何选择适当的OSGi配置值类型

OSGi的常见用例使用内联OSGi配置值。 特定于环境的配置仅用于不同开发环境的值不同的特定用例。

特定于环境的配置扩展了传统的静态定义的OSGi配置（其中包含内联值），从而提供了通过Cloud Manager API从外部管理OSGi配置值的功能。 了解何时应使用定义内联值并将其存储在Git中的常见和传统方法非常重要，而不是将这些值抽象为特定于环境的配置。

以下指南介绍了何时使用特定于非机密和机密环境的配置：

何时使用内联配置值

内联配置值被视为标准方法，应尽可能使用。 内联配置具有以下优势：

• 这些区段会得到维护，并在Git中保留治理和版本历史记录
• 值与代码部署隐式关联
• 它们不需要任何额外的部署考虑或协调

无论何时定义OSGi配置值，都应从内联值开始，并且仅在用例需要时选择密码或特定于环境的配置。

何时使用非机密环境特定的配置值

仅使用特定于环境的配置($[env:ENV_VAR_NAME])时，对于非机密配置值，如果预览层的值不同或在开发环境中不同，则会使用相同的值。 这包括本地开发实例和任何Adobe Experience Manager as a Cloud Service开发环境。 除了为预览层设置唯一值之外，请避免为Adobe Experience Manager as a Cloud Service暂存或生产环境使用非机密环境特定的配置。

• 仅将非机密环境特定的配置用于发布层和预览层之间不同的配置值，或用于开发环境（包括本地开发实例）之间不同的值。
• 除了预览层需要与发布层不同的情况之外，还可以在OSGi配置中为暂存和生产非机密值使用标准内联值。 因此，不建议使用特定于环境的配置来促进在运行时对暂存环境和生产环境进行配置更改；这些更改应通过源代码管理引入。

何时使用机密环境特定的配置值

Adobe Experience Manager as a Cloud Service需要使用特定于环境的配置($[secret:SECRET_VAR_NAME])，用于任何机密的OSGi配置值，例如密码、私有API密钥或任何其他出于安全原因不能存储在Git中的值。

使用特定于密钥环境的配置来存储所有Adobe Experience Manager as a Cloud Service环境（包括暂存环境和生产环境）上的密钥值。

创建OSGi配置

创建OSGi配置的方法有两种，如下所述。 前者通常用于配置具有已知的OSGi属性和值的自定义OSGi组件，后者用于AEM提供的OSGi组件。

编写OSGi配置

可直接在AEM项目中手动编写JSON格式的OSGi配置文件。 这通常是为已知的OSGi组件（尤其是由定义配置的同一开发人员设计和开发的自定义OSGi组件）创建OSGi配置的最快方法。 此方法还可用于在不同的运行模式文件夹中复制/粘贴和更新同一OSGi组件的配置。

1. 在IDE中，打开 ui.apps 项目，找到或创建配置文件夹(/apps/.../config.<runmode>)以新OSGi配置需要生效的运行模式为目标
2. 在此配置文件夹中，创建 <PID>.cfg.json 文件。 PID是OSGi组件的永久标识。 它通常是OSGi组件实现的完整类名。 例如：
   /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
   请注意，OSGi配置工厂文件名使用 <factoryPID>-<name>.cfg.json 命名约定
3. 打开新的 .cfg.json 文件，并定义OSGi属性和值对的键/值组合，请遵循 JSON OSGi配置格式.
4. 将更改保存到新 .cfg.json 文件
5. 添加新的OSGi配置文件并将其提交到Git

使用AEM SDK快速入门生成OSGi配置

AEM SDK快速入门Jar的AEM Web控制台可用于配置OSGi组件，并将OSGi配置导出为JSON。 这对于配置AEM提供的OSGi组件非常有用，在AEM项目中定义OSGi配置的开发人员可能无法很好地了解这些组件的OSGi属性及其值格式。

1. 登录到AEM SDK快速入门Jar的AEM Web控制台，网址为 https://<host>:<port>/system/console 作为管理员用户
2. 导航到 osgi > 配置
3. 要配置，请找到OSGi组件并点按其标题以进行编辑
   
4. 根据需要通过Web UI编辑OSGi配置属性值
5. 将永久标识(PID)记录到安全位置。 稍后将使用此选项来生成OSGi配置JSON
6. 点按保存
7. 导航到OSGi > OSGi安装程序配置打印机
8. 粘贴步骤5中复制的PID，确保序列化格式设置为“OSGi配置器JSON”
9. 点按打印
10. JSON格式的OSGi配置将显示在序列化配置属性部分中
    
11. 在IDE中，打开 ui.apps 项目，找到或创建配置文件夹(/apps/.../config.<runmode>)以新OSGi配置需要生效的运行模式为目标。
12. 在此配置文件夹中，创建 <PID>.cfg.json 文件。 PID与步骤5中的值相同。
13. 将步骤10中的序列化配置属性粘贴到 .cfg.json 文件。
14. 将更改保存到新 .cfg.json 文件。
15. 添加新的OSGi配置文件并将其提交到Git。

OSGi配置属性格式

内联值

内联值的格式为标准的名称 — 值对，遵循标准JSON语法。 例如：

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

特定于环境的配置值

OSGi配置应为打算按环境定义的变量分配一个占位符：

use $[env:ENV_VAR_NAME]

客户应仅将此技术用于与其自定义代码相关的OSGi配置属性；不得使用此技术覆盖Adobe定义的OSGi配置。

密码配置值

OSGi配置应为要按环境定义的密码分配一个占位符：

use $[secret:SECRET_VAR_NAME]

变量命名

以下内容适用于特定于环境的配置值和机密配置值。

变量名称必须遵循以下规则：

• 最小长度：2
• 最大长度：100
• 必须匹配正则表达式： [a-zA-Z_][a-zA-Z_0-9]*

变量值不得超过2048个字符。

默认值

以下内容适用于特定于环境的配置值和机密配置值。

如果未设置每个环境的值，则在运行时将不替换占位符，并且由于未发生内插，占位符将保留在原位。 为避免出现此情况，可以使用以下语法将默认值作为占位符的一部分提供：

$[env:ENV_VAR_NAME;default=<value>]

在提供了默认值的情况下，占位符会被替换为每个环境的值（如果提供）或提供的默认值。

本地开发

以下内容适用于特定于环境的配置值和机密配置值。

变量可以在本地环境中定义，以便在运行时由本地AEM提取。 例如，在Linux®上：

export ENV_VAR_NAME=my_value

建议编写一个简单的bash脚本，该脚本可设置配置中使用的环境变量，并在启动AEM之前执行它。 工具如 https://direnv.net/ 帮助简化此方法。 根据值的类型，如果这些值可以在所有人之间共享，则它们可能会被签入源代码管理。

从文件中读取密钥的值。 因此，对于使用密码的每个占位符，必须创建一个包含密码值的文本文件。

例如，如果 $[secret:server_password] 使用，一个名为 server_psword 必须创建。 所有这些机密文件必须存储在同一目录和框架属性中 org.apache.felix.configadmin.plugin.interpolation.secretsdir 必须使用该本地目录进行配置。

此 org.apache.felix.configadmin.plugin.interpolation.secretsdir 是Sling框架属性；因此此属性不是在felix控制台(/system/console?lang=zh-Hans)中设置的，而是在系统引导时使用的sling.properties文件中设置的。 此文件可在提取的Jar/install文件夹(crx-quickstart/conf)的/conf子目录中找到。

示例：将此行添加到“crx-quickstart/conf/sling.properties”文件的末尾以将“crx-quickstart/secretsdir”配置为机密文件夹：

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

作者与发布配置

如果OSGi属性对author和publish的值不同：

• 分隔 config.author 和 config.publish 必须使用OSGi文件夹，如 “运行模式分辨率”部分.
• 创建独立变量名称有两个选项，应该使用：

  • 推荐使用的第一个选项：在所有OSGi文件夹中(例如 config.author 和 config.publish)声明以定义不同的值，请使用相同的变量名称。 例如

    $[env:ENV_VAR_NAME;default=<value>]，其中默认值对应于该层的默认值（创作或发布）。 通过设置环境变量时 Cloud Manager API 或通过客户端，使用“服务”参数区分各层，如本中所述 API参考文档. “service”参数会将变量的值绑定到适当的OSGi层。 它可以是“作者”、“发布”或“预览”。

  • 第二个选项是使用前缀（例如）声明不同的变量 author_<samevariablename> 和 publish_<samevariablename>

配置示例

在下面的示例中，假设除了暂存环境和生产环境之外，还有三个开发环境。

示例1

目的是OSGi属性的值 my_var1 对于暂存环境和生产环境相同，但三个开发环境中的每个环境有所不同。

{ "my_var1"： "val"， "my_var2"： "abc"， "my_var3"： 500 }

{ "my_var1" ： "$[env：my_var1]" "my_var2"： "abc"， "my_var3"： 500 }

示例2

目的是OSGi属性的值 my_var1 对于暂存、生产和三个开发环境中的每一个而言，都会有所不同。 因此，必须调用Cloud Manager API来设置值 my_var1 每个开发环境。

{ "my_var1"： "val1"， "my_var2"： "abc"， "my_var3"： 500 }

{ "my_var1"： "val2"， "my_var2"： "abc"， "my_var3"： 500 }

{ "my_var1" ： "$[env：my_var1]" "my_var2"： "abc"， "my_var3"： 500 }

示例3

目的是OSGi属性的值 my_var1 对于暂存、生产环境以及仅开发环境之一而言，它们是相同的，但对于其他两个开发环境而言，它是不同的。 在这种情况下，必须调用Cloud Manager API来设置值 my_var1 适用于每个开发环境，包括应与暂存和生产环境具有相同值的开发环境。 它不会继承文件夹中设置的值 config.

{ "my_var1"： "val1"， "my_var2"： "abc"， "my_var3"： 500 }

{ "my_var1" ： "$[env：my_var1]" "my_var2"： "abc"， "my_var3"： 500 }

完成此任务的另一种方法是为config.dev文件夹中的替换令牌设置默认值，使其与 config 文件夹。

{ "my_var1"： "val1"， "my_var2"： "abc"， "my_var3"： 500 }

{ "my_var1"： "$[env：my_var1；default=val1]" "my_var2"： "abc"， "my_var3"： 500 }

用于设置属性的Cloud Manager API格式

参见 此页面 有关如何配置API的信息。

通过API设置值

调用API会将新变量和值部署到云环境，类似于典型的客户代码部署管道。 创作和发布服务将重新启动并引用新值，通常需要几分钟时间。

PATCH /program/{programId}/environment/{environmentId}/variables

]
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

通过API获取值

GET /program/{programId}/environment/{environmentId}/variables

参见 此页面 了解更多信息。

通过API删除值

PATCH /program/{programId}/environment/{environmentId}/variables

要删除变量，请将其包含在一个空值中。

参见 此页面 了解更多信息。

通过命令行获取值

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value
MY_VAR2  secretString ****

通过命令行设置值

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

通过命令行删除值

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

变量数量

每个环境最多可以声明200个变量。

针对密钥和特定于环境的配置值的部署注意事项

由于机密和特定于环境的配置值位于Git之外，因此不属于正式的Adobe Experience Manager as a Cloud Service部署机制，因此客户应该管理、治理并集成到Adobe Experience Manager as a Cloud Service部署过程中。

如上所述，调用API会将新变量和值部署到云环境，类似于典型的客户代码部署管道。 创作和发布服务将重新启动并引用新值，通常需要几分钟时间。 请注意，Cloud Manager在常规代码部署期间执行的质量审核和测试不会在此过程中执行。

通常，客户在部署在Cloud Manager中依赖于环境变量的代码之前，会调用API来设置环境变量。 在某些情况下，可能需要在部署代码后修改现有变量。

在某些情况下，计划客户代码部署依赖现有变量来获取新值，而新值对于当前代码并不合适。 如果出现此问题，建议以累加方式进行变量修改。 为此，请创建新的变量名称，而不是仅更改旧变量的值，这样旧代码永远不会引用新值。 然后，当新客户版本看起来稳定时，可以选择删除旧值。

同样，由于变量的值未进行版本控制，因此回滚代码可能会导致它引用导致问题的较新值。 前面提到的加性变量策略在这方面也会有所帮助。

此附加变量策略也可用于灾难恢复场景，在这些场景中，如果需要重新部署几天前的代码，则它引用的变量名称和值将保持不变。 这依赖于一种策略，即客户在删除这些旧变量之前等待几天，否则旧代码将没有合适的变量可引用。

Business.Adobe.com 资源