AEM引入了使用Cloud Manager用户界面在2021.12.0版本中配置标准环境变量的功能。 有关更多信息,请参阅文档 此处.
osgi 是Adobe Experience Manager (AEM)技术栈栈中的基本元素。 它用于控制AEM的复合捆绑包及其配置。
OSGi提供了标准化的基元,允许使用小型、可重用的协作组件构建应用程序。 这些组件可以组合为一个应用程序并部署。 这样可以轻松地管理OSGi包,因为它们可以单独停止、安装和启动。 系统会自动处理相互依赖关系。 每个OSGi组件都包含在各种捆绑包中。 欲了解更多信息,请参见 OSGi规范.
您可以通过属于AEM代码项目一部分的配置文件来管理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配置格式。
使用不同文件格式(如)的先前版本的AEM支持的OSGi配置文件 .cfg
, .config
和XML sling:OsgiConfig
资源定义。 这些格式将被 .cfg.json
osgi配置格式。
AEM 6.x支持自定义运行模式,但AEMas a Cloud Service不支持。 AEMas a Cloud Service支持 精确的一组运行模式. AEMas a Cloud Service环境之间的OSGi配置中的任何变量都必须使用来处理 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有效。
A config.preview
OSGi配置文件夹 无法 以相同方式声明 config.publish
可以声明文件夹。 相反,预览层从发布层的值继承其OSGi配置。
在进行本地开发时,运行架构启动参数 -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配置值可以通过以下方式验证:
结果视图显示选定层的所有OSGi组件配置及其适用的OSGi配置值。 这些值可以与AEM项目源代码中的OSGi配置值交叉引用,位于 /apps/example/osgiconfig/config.<runmode(s)>
.
要验证是否应用了适当的OSGi配置值,请执行以下操作:
pid
表示要验证的OSGi配置;这是AEM项目源代码中的OSGi配置文件的名称。properties
的列表 pid
并验证键和值是否与要验证的运行模式的AEM项目源代码中的OSGi配置文件匹配。有三种版本的OSGi配置值可以与Adobe Experience Manager as a Cloud Service一起使用。
内联值,这些值已硬编码到OSGi配置中并存储在Git中。 例如:
{
"connection.timeout": 1000
}
密码值,出于安全原因,这些值不得存储在Git中。 例如:
{
"api-key": "$[secret:server-api-key]"
}
特定于环境的值,这些值在开发环境之间有所不同,因此无法通过运行模式进行准确定位(因为只有一个 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配置(其中包含内联值),从而提供了通过Cloud Manager API从外部管理OSGi配置值的功能。 了解何时应使用定义内联值并将其存储在Git中的常见和传统方法非常重要,而不是将这些值抽象为特定于环境的配置。
以下指南介绍了何时使用特定于非机密和机密环境的配置:
内联配置值被视为标准方法,应尽可能使用。 内联配置具有以下优势:
无论何时定义OSGi配置值,都应从内联值开始,并且仅在用例需要时选择密码或特定于环境的配置。
仅使用特定于环境的配置($[env:ENV_VAR_NAME]
)时,对于非机密配置值,如果预览层的值不同或在开发环境中不同,则会使用相同的值。 这包括本地开发实例和任何Adobe Experience Manager as a Cloud Service开发环境。 除了为预览层设置唯一值之外,请避免为Adobe Experience Manager as a Cloud Service暂存或生产环境使用非机密环境特定的配置。
Adobe Experience Manager as a Cloud Service需要使用特定于环境的配置($[secret:SECRET_VAR_NAME]
),用于任何机密的OSGi配置值,例如密码、私有API密钥或任何其他出于安全原因不能存储在Git中的值。
使用特定于密钥环境的配置来存储所有Adobe Experience Manager as a Cloud Service环境(包括暂存环境和生产环境)上的密钥值。
创建OSGi配置的方法有两种,如下所述。 前者通常用于配置具有已知的OSGi属性和值的自定义OSGi组件,后者用于AEM提供的OSGi组件。
可直接在AEM项目中手动编写JSON格式的OSGi配置文件。 这通常是为已知的OSGi组件(尤其是由定义配置的同一开发人员设计和开发的自定义OSGi组件)创建OSGi配置的最快方法。 此方法还可用于在不同的运行模式文件夹中复制/粘贴和更新同一OSGi组件的配置。
ui.apps
项目,找到或创建配置文件夹(/apps/.../config.<runmode>
)以新OSGi配置需要生效的运行模式为目标<PID>.cfg.json
文件。 PID是OSGi组件的永久标识。 它通常是OSGi组件实现的完整类名。 例如:/apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
<factoryPID>-<name>.cfg.json
命名约定.cfg.json
文件,并定义OSGi属性和值对的键/值组合,请遵循 JSON OSGi配置格式..cfg.json
文件AEM SDK快速入门Jar的AEM Web控制台可用于配置OSGi组件,并将OSGi配置导出为JSON。 这对于配置AEM提供的OSGi组件非常有用,在AEM项目中定义OSGi配置的开发人员可能无法很好地了解这些组件的OSGi属性及其值格式。
AEM Web控制台的配置UI不会写入 .cfg.json
文件放入存储库。 因此,请注意这一点,以避免在本地开发期间(当AEM项目定义的OSGi配置可能与生成的配置不同时)出现潜在的意外行为。
https://<host>:<port>/system/console
作为管理员用户ui.apps
项目,找到或创建配置文件夹(/apps/.../config.<runmode>
)以新OSGi配置需要生效的运行模式为目标。<PID>.cfg.json
文件。 PID与步骤5中的值相同。.cfg.json
文件。.cfg.json
文件。内联值的格式为标准的名称 — 值对,遵循标准JSON语法。 例如:
{
"my_var1": "val",
"my_var2": [ "abc", "def" ],
"my_var3": 500
}
OSGi配置应为打算按环境定义的变量分配一个占位符:
use $[env:ENV_VAR_NAME]
客户应仅将此技术用于与其自定义代码相关的OSGi配置属性;不得使用此技术覆盖Adobe定义的OSGi配置。
占位符不能用于 repoinit语句.
OSGi配置应为要按环境定义的密码分配一个占位符:
use $[secret:SECRET_VAR_NAME]
以下内容适用于特定于环境的配置值和机密配置值。
变量名称必须遵循以下规则:
[a-zA-Z_][a-zA-Z_0-9]*
变量值不得超过2048个字符。
有一些规则与对变量名称使用某些前缀有关:
带有前缀的变量名称 INTERNAL_
, ADOBE_
,或 CONST_
由Adobe保留。 任何以这些前缀开头的客户设置变量都将被忽略。
客户不得引用带有前缀的变量 INTERNAL_
或 ADOBE_
也不是。
带前缀的环境变量 AEM_
由产品定义为供客户使用和设置的公共API。
而客户可以使用和设置以前缀开头的环境变量 AEM_
他们不应使用此前缀定义自己的变量。
以下内容适用于特定于环境的配置值和机密配置值。
如果未设置每个环境的值,则在运行时将不替换占位符,并且由于未发生内插,占位符将保留在原位。 为避免出现此情况,可以使用以下语法将默认值作为占位符的一部分提供:
$[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
必须使用该本地目录进行配置。
文本文件不允许使用文件扩展名。
因此,对于上面的示例,必须将文本文件命名为 server_psword — 不带文件扩展名。
此 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
对于暂存环境和生产环境相同,但三个开发环境中的每个环境有所不同。
文件夹 | myfile.cfg.json的内容 |
config |
{ "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
对于暂存、生产和三个开发环境中的每一个而言,都会有所不同。 因此,必须调用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
适用于每个开发环境,包括应与暂存和生产环境具有相同值的开发环境。 它不会继承文件夹中设置的值 config.
文件夹 | myfile.cfg.json的内容 |
config |
{ "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的内容 |
config |
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "my_var1": "$[env:my_var1;default=val1]" "my_var2": "abc", "my_var3": 500 } |
参见 此页面 有关如何配置API的信息。
确保使用的Cloud Manager API已分配了“部署管理员 — Cloud Service”角色。 其他角色无法执行以下所有命令。
调用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属性本身中设置的。
参见 此页面 了解更多信息。
GET /program/{programId}/environment/{environmentId}/variables
参见 此页面 了解更多信息。
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/OCLI的Cloud Manager插件配置值的更多信息。
每个环境最多可以声明200个变量。
由于机密和特定于环境的配置值位于Git之外,因此不属于正式的Adobe Experience Manager as a Cloud Service部署机制,因此客户应该管理、治理并集成到Adobe Experience Manager as a Cloud Service部署过程中。
如上所述,调用API会将新变量和值部署到云环境,类似于典型的客户代码部署管道。 创作和发布服务将重新启动并引用新值,通常需要几分钟时间。 请注意,Cloud Manager在常规代码部署期间执行的质量审核和测试不会在此过程中执行。
通常,客户在部署在Cloud Manager中依赖于环境变量的代码之前,会调用API来设置环境变量。 在某些情况下,可能需要在部署代码后修改现有变量。
当管道正在使用中(AEM更新或客户部署)时,API可能会失败,具体取决于当时端到端管道执行的部分。 错误响应将指示请求不成功,但不会指示具体原因。
在某些情况下,计划客户代码部署依赖现有变量来获取新值,而新值对于当前代码并不合适。 如果出现此问题,建议以累加方式进行变量修改。 为此,请创建新的变量名称,而不是仅更改旧变量的值,这样旧代码永远不会引用新值。 然后,当新客户版本看起来稳定时,可以选择删除旧值。
同样,由于变量的值未进行版本控制,因此回滚代码可能会导致它引用导致问题的较新值。 前面提到的加性变量策略在这方面也会有所帮助。
此附加变量策略也可用于灾难恢复场景,在这些场景中,如果需要重新部署几天前的代码,则它引用的变量名称和值将保持不变。 这依赖于一种策略,即客户在删除这些旧变量之前等待几天,否则旧代码将没有合适的变量可引用。