Show Menu
主题×

为 AEM 云服务配置 OSGi

OSGi是 Adobe Experience Manager技术堆栈(AEM)中的一个基本元素。 它用于控制AEM及其配置的复合捆绑包。
OSGi提供标准化的基元,它允许应用程序由小的、可重用的和协作的组件构建。 这些组件可以组成应用程序并进行部署。 这允许轻松管理OSGi捆绑包,因为可以单独停止、安装和启动它们。 互依关系将自动处理。 每个OSGi组件都包含在各种包中的一个。 有关详细信息,请参阅 OSGi规范
您可以通过AEM代码项目中的配置文件管理OSGi组件的配置设置。

OSGi配置文件

配置更改在AEM Project的代码包()中定义为运行 ui.apps 模式特定配置文件夹下 .cfg.json 的配置文件():
/apps/example/config.<runmode>
OSGi配置文件的格式基于JSON,使用Apache Sling .cfg.json 项目定义的格式。
OSGi配置通过OSGi组件的永久身份(PID)目标OSGi组件,该身份默认为OSGi组件的Java类名称。 例如,为通过以下方式实现的OSGi服务提供OSGi配置:
com.example.workflow.impl.ApprovalWorkflow.java
OSGi配置文件在以下位置进行定义:
/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
遵循cfg.json OSGi配置格式。
先前版本的AEM支持使用不同文件格式(如。cfg.、.config和XML sling:OsgiConfig资源定义)的OSGi配置文件。 这些格式由cfg.json OSGi配置格式取代。

运行模式分辨率

通过使用运行模式,可以将特定OSGi配置定向到特定AEM实例。 要使用运行模式,请在(其 /apps/example 中是您的项目名称)下创建配置文件夹,格式为:
/apps/example/config.<author|publish>.<dev|stage|prod>/
如果配置文件夹名称中定义的运行模式与AEM使用的运行模式匹配,则将使用此类文件夹中的所有OSGi配置。
例如,如果AEM使用运行模式作者和开发,则将应用和中 /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/ 为同一PID定义更 /apps/example/config.author.dev/ 多特定属性。 匹配运行模式数目最多的配置对于整个PID是有效的。
本地开发时,可以传入运行模式启动参数,以指定将使用哪个运行模式OSGI配置。

OSGi配置值的类型

有三种OSGi配置值可与AEM一起用作Cloud Service。
  1. 内联值 ,即硬编码到OSGi配置并存储在Git中的值。 例如:
    {
       "connection.timeout": 1000
    }
    
    
  2. 机密值 ,即出于安全原因不应存储在Git中的值。 例如:
    {
    "api-key": "$[secret:server-api-key]"
    } 
    
    
  3. 环境特定值 ,这些值是不同开发环境的值,因此无法按运行模式准确定位(因为AEM中有一个 dev 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维护,其管理和版本历史记录在Git中
  • 值隐式绑定到代码部署
  • 它们不需要任何额外的部署考虑或协调
无论何时定义OSGi配置值(与内联值开始),只要在用例需要时选择机密或环境特定配置。

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

当这些值在开发环境中 $[env:ENV_VAR_NAME] 不同时,仅对非机密配置值使用环境特定配置()。 这包括本地开发实例和任何作为Cloud Service开发环境的AEM。 避免将AEM的非机密环境特定配置用作Cloud Service阶段或生产环境。
  • 只对不同开发环境(包括本地开发实例)的配置值使用非机密环境特定配置。
  • 请改用OSGi配置中的标准内联值作为舞台和生产非机密值。 与此相关,不建议使用环境特定配置以便于在运行时对舞台和生产环境进行配置更改; 这些更改应通过源代码管理引入。

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

AEM作为Cloud Service,需要对任何机密OSGi配置值( $[secret:SECRET_VAR_NAME] 如口令、专用API密钥)使用环境特定配置(),或出于安全原因无法存储在Git中的任何其他值。
使用特定于机密环境的配置将所有AEM上机密的值存储为Cloud Service环境,包括阶段和生产。

创建OSGi配置

有两种方法可创建新OSGi配置,如下所述。 前一种方法通常用于配置自定义OSGi组件,这些组件具有开发人员所熟知的OSGi属性和值,后一种方法用于AEM提供的OSGi组件。

编写OSGi配置

JSON格式的OSGi配置文件可以直接手工写入AEM项目。 这通常是为知名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配置工厂文件名使用命 <PID>-<factory-name>.cfg.json 名约定
  3. 打开新 .cfg.json 文件,按照JSON OSGi配置格式定义OSGi属性和值对的键/ 值组合
  4. 保存对新文件的更 .cfg.json
  5. 向Git添加并提交新的OSGi配置文件

使用AEM SDK快速启动生成OSGi配置

AEM SDK Quickstart Jar的AEM Web Console可用于配置OSGi组件,以及将OSGi配置导出为JSON。 这对于配置AEM提供的OSGi组件很有用,这些组件的OSGi属性及其值格式可能无法被在AEM项目中定义OSGi配置的开发人员很好地理解。 请注意,使用AEM Web Console的配置UI会将文件写入存储库,因此请注意,当AEM项目定义的OSGi配置可能与生成的配置不同时, .cfg.json 为了避免在本地开发过程中出现潜在的意外行为,请注意。
  1. 以管理员用户身份登录到AEM SDK Quickstart Jar的AEM Web控制台
  2. 导航到OSGi >配置
  3. 找到要配置的OSGi组件,然后点按其标题进行编辑
  4. 根据需要通过Web UI编辑OSGi配置属性值
  5. 将永久标识(PID)记录到安全位置,稍后将使用它生成OSGi配置JSON
  6. 点按保存
  7. 导航到OSGi > OSGi Installer Configuration Printer
  8. 粘贴到步骤5中复制的PID中,确保序列化格式设置为“OSGi Configurator 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. 向Git添加并提交新的OSGi配置文件。

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_password 的文本文件。 所有这些机密文件都需要存储在同一个目录中,框架属 org.apache.felix.configadmin.plugin.interpolation.secretsdir 性需要使用该本地目录进行配置。

作者配置与发布配置

如果OSGI属性要求创作值与发布值不同:
  • 应使 config.author config.publish 单独的和OSGi文件夹,如“Runmode Resolution”(运行模式分 辨率)部分中所述
  • 应使用独立变量名称。 建议使用变量名称相同 author_<variablename> publish_<variablename> 前缀,如和

配置示例

在以下示例中,假定除了舞台和prod环境外,还有3个开发环境。
示例1
其目的是使OSGI属性的值在级和 my_var1 prod上相同,但对于3个开发环境中的每个都不同。
文件夹 myfile.cfg.json的内容
配置
{ "my_var1": "val", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1": "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


示例2
其目的是使OSGI属性的值对 my_var1 于舞台、prod和3个开发环境中的每个都不同。 因此,需要调用Cloud Manager API来为每个开发环境 my_var1 设置值。
文件夹 myfile.cfg.json的内容
config.stage
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.prod
{ "my_var1": "val2", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1": "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


示例3
其目的是使OSGi属性的值对于舞台、 my_var1 生产和只是其中一个开发环境相同,但对于其他两个开发环境不同。 在这种情况下,需要调用Cloud Manager API,以设置每个开发环境的值, my_var1 包括应具有与舞台和生产相同值的开发环境的值。 它不会继承文件夹配置中设置的
文件夹 myfile.cfg.json的内容
配置
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1": "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


实现此目的的另一种方法是在config.dev文件夹中设置替换令牌的默认值,使其与在config文件夹中的值 同。
文件夹 myfile.cfg.json的内容
配置
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1": "$[env:my_var1;default=val1]" "my_var2": "abc", "my_var3": 500}


用于设置属性的Cloud Manager 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设置的,而是在OSGi属性本身中设置的。
请参 阅本页 ,了解详细信息。

通过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

关如何使 用Adobe I/O CLI的Cloud Manager插件配置值的详细信息,请参阅此页。

变量数

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

机密和环境特定配置值的部署注意事项

由于特定机密和环境配置值位于Git之外,因此不是正式AEM(作为Cloud Service部署机制)的一部分,因此客户应作为Cloud Service部署流程管理、管理并集成到AEM。
如上所述,调用API会将新变量和值部署到云环境,类似于典型的客户代码部署渠道。 创作和发布服务将重新启动并引用新值,通常需要几分钟时间。 请注意,在定期代码部署过程中,Cloud Manager执行的质量门和测试不会在此过程中执行。
通常,客户会先调用API设置环境变量,然后再在Cloud Manager中部署依赖它们的代码。 在某些情况下,在已部署代码后,可能需要修改现有变量。
请注意,API在使用管道(AEM更新或客户部署)时可能无法成功,具体取决于当时正在执行端到端管道的哪部分。 错误响应将指示请求未成功,但不会指明具体原因。
在某些情况下,计划客户代码部署依赖现有变量来设置新值,这与当前代码不符。 如果这是问题,建议以附加方式进行变量修改。 为此,请创建新变量名称,而不是只更改旧变量的值,这样旧代码就不会引用新值。 当新客户版本看起来稳定时,您可以选择删除旧值。
同样,由于变量的值未版本化,因此回滚代码可能会导致引用导致问题的较新值。 上述附加变量策略也有助于实现。
此附加变量策略还适用于灾难恢复情况,如果需要重新部署前几天的代码,则其引用的变量名称和值将保持不变。 这取决于客户在删除这些旧变量前等待几天的策略,否则旧代码将没有适当的变量可引用。