Apache Aries 配置参数详解

Apache Aries 配置参数详解：Felix Framework 运行时配置、Aries Blueprint 组件参数、Blueprint XML 装配与 JVM 启动参数，基于 7.0.5 与 1.10.3 实测回显说明用途与验证。

Apache AriesAries2026/10/14

Apache Aries 配置参数详解

目标：梳理 Apache Aries 运行环境的全部配置入口——OSGi 框架配置（conf/config.properties）、Aries Blueprint 组件参数、Blueprint XML 装配参数与 JVM 启动参数，并结合 Felix 7.0.5 + Aries Blueprint 1.10.3 的真实运行回显说明每项参数的作用。

一、配置体系总览

1.1 三层配置结构

Aries 运行在 OSGi 框架之上，配置分为三层：

层次配置文件作用
框架层conf/config.properties控制 OSGi 框架行为与 bundle 自动部署
组件层bundle 内 OSGI-INF/blueprint/*.xml声明 bean、服务与依赖装配
进程层JVM 启动参数内存、模块开放与日志级别

三层配置在启动时刻共同决定运行时行为，本文依次详解。

💡 技术拓展：OSGi 框架有多个实现，配置风格略有差异——Felix 用 conf/config.properties 键值对；Apache Karaf 用 etc/ 目录下按模块拆分配置文件；Eclipse Equinox 用插件化的 configuration 文件。三者都遵循 OSGi 规范，Aries 组件在其上的装配方式一致。

1.2 本文实测环境

项目值
OSGi 框架Apache Felix Framework 7.0.5
Aries Blueprint1.10.3（扩展器 org.apache.aries.blueprint.core）
运行环境JDK 17，x86_64 Linux
部署目录/opt/felix

二、Felix Framework 核心参数

2.1 配置文件位置与加载

Felix 启动器从工作目录下的 conf/config.properties 读取配置；缺省文件时启动直接中止，实测回显：

$ java -jar bin/felix.jar
No config.properties found.

验证结果：conf/config.properties 是启动的必备文件。

2.2 自动部署参数

auto.deploy 系列控制 bundle/ 目录的自动安装与启动：

felix.auto.deploy.action=install,start
felix.auto.deploy.dir=bundle
参数取值说明
felix.auto.deploy.actioninstall,start启动时对 bundle 目录内组件执行的动作，可为 install、start、update、uninstall 的组合
felix.auto.deploy.dirbundle自动部署目录，相对 felix.home 的路径

实测回显：bundle/ 目录放置 16 个组件后启动，Gogo shell 中 lb 全部为 Active 状态：

    5|Active     |    1|Apache Aries Blueprint API (1.0.1)|1.0.1
    6|Active     |    1|Apache Aries Blueprint Core (1.10.3)|1.10.3

验证结果：Blueprint 组件随框架启动自动完成安装与启动。

2.3 日志级别

felix.log.level=4
级别值含义
ERROR1仅记录错误
WARNING2记录警告与错误
INFO3记录常规信息
DEBUG4记录调试信息（框架默认）

实测回显：设为 4 后 Aries 扩展器的 INFO 日志直接输出到控制台：

[Blueprint Extender: 1] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle org.apache.aries.blueprint.core/1.10.3 has been started

验证结果：调整日志级别可观察 Blueprint 运行时生命周期。

2.4 框架存储与缓存

org.osgi.framework.storage=felix-cache
参数默认值说明
org.osgi.framework.storagefelix-cachebundle 缓存的相对路径，安装过的组件在重启后由此恢复
org.osgi.framework.storage.cleannone设为 onFirstInit 可在首次初始化时清空缓存

实测回显：安装两个示例组件后退出，重启框架时缓存自动恢复安装记录（Bundle ID 17 仍在）：

g! lb
   17|Installed  |    1|aries-blueprint-demo (1.0.0)|1.0.0

验证结果：缓存保证了重启后组件状态持久化；需要全新环境时删除 felix-cache 目录即可。

2.5 启动级别

org.osgi.framework.startlevel.beginning=1
felix.startlevel.bundle=1
参数默认值说明
org.osgi.framework.startlevel.beginning1框架启动时的起始级别
felix.startlevel.bundle1新安装 bundle 的默认启动级别

lb 输出第三列即 bundle 所在启动级别，实测均为 1。

2.6 其他常用框架参数

参数默认值说明
org.osgi.service.http.port8080HTTP 服务端口（安装 HTTP bundle 时生效）
felix.service.urlhandlerstrue是否注册 URL 流与内容处理器工厂
felix.shutdown.hooktrue注册关闭钩子，Ctrl+C 时优雅停止框架
felix.bootdelegation.implicittrue隐式引导委派，简化外部类加载兼容

实测回显：设置 org.osgi.service.http.port=8080 后框架正常启动，无端口冲突。

三、Aries Blueprint 组件参数

3.1 组件间依赖关系

Aries Blueprint 1.10.3 运行需要以下组件协同：

组件版本作用
org.apache.aries.blueprint.core1.10.3扩展器与 Blueprint 运行时实现
org.apache.aries.blueprint.api1.0.1Blueprint API 定义
org.apache.aries.util1.1.3工具类库
org.apache.aries.proxy.api / impl1.1.1 / 1.0.6代理生成，支撑 reference 注入
org.apache.aries.quiesce.api1.0.0优雅停止支持
asm9.6字节码操作
slf4j-api / slf4j-simple1.7.36日志门面与输出实现

3.2 组件放置与自动启动

组件以 jar 形式放入自动部署目录，Felix 按文件名顺序安装。实测目录内容：

org.apache.aries.blueprint.api-1.0.1.jar
org.apache.aries.blueprint.core-1.10.3.jar
org.apache.aries.proxy.api-1.1.1.jar
org.apache.aries.proxy.impl-1.0.6.jar
org.apache.aries.util-1.1.3.jar

验证结果：扩展器随框架启动，在日志中输出自身 Blueprint 运行时已创建的信息，说明组件参数（版本、路径）配置正确。

四、Blueprint XML 装配参数

4.1 命名空间与根元素

装配描述位于 bundle 内 OSGI-INF/blueprint 目录，根元素固定：

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

XML 中出现的每个元素都对应一个装配参数，Aries 扩展器启动时读取并逐项执行。

4.2 bean 元素

<bean id="greetingBean" class="com.example.aries.impl.GreetingImpl">
  <property name="prefix" value="Hello"/>
</bean>
属性取值说明
idgreetingBeanbean 标识，供其他元素引用
class全限定类名bean 类型
property nameprefixsetter 方法名（setPrefix）
property valueHellosetter 入参

验证结果：bean 实例化后通过 setPrefix 注入默认值，实测 greet 输出 Hello 前缀：

[consumer] Hello, Aries Blueprint!

4.3 service 元素

<service ref="greetingBean" interface="com.example.aries.api.Greeting"/>
属性取值说明
refgreetingBean引用已声明的 bean
interface全限定接口名注册为 OSGi 服务的接口

实测回显（inspect cap service）：服务注册表出现两个服务，其中 Greeting 服务带 osgi.service.blueprint.compname=greetingBean 属性：

service; com.example.aries.api.Greeting with properties:
   osgi.service.blueprint.compname = greetingBean
   service.bundleid = 17
   service.id = 33
   service.scope = bundle

4.4 reference 元素

<reference id="greetingRef" interface="com.example.aries.api.Greeting"/>
属性取值说明
idgreetingRef引用标识
interface全限定接口名依赖的服务接口

reference 是惰性依赖：Aries 会在目标服务不可用时保持 Blueprint 运行时等待状态，服务注册后自动注入。实测 consumer 运行时在 demo 启动后才完成创建。

4.5 bean 与 reference 的组合

<bean id="client" class="com.example.aries.consumer.GreetingClient"
      init-method="init">
  <property name="greeting" ref="greetingRef"/>
</bean>
属性取值说明
init-methodinit运行时创建完成后回调的方法
property namegreeting注入目标属性
property refgreetingRef注入来源引用

验证结果：消费方运行时创建后立即回调 init，完成对远程（跨 bundle）服务的调用：

[Blueprint Extender: 1] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle com.example.aries.blueprint.consumer/1.0.0 has been started

五、JVM 与启动参数

5.1 内存参数

java -Xms256m -Xmx512m -jar bin/felix.jar
参数推荐值说明
-Xms256m初始堆大小
-Xmx512m最大堆大小（小型环境 512 MB 足够）

5.2 模块开放参数

Felix main jar 的 MANIFEST 已内置 Add-opens 指令，覆盖 java.base 网络与协议包，JDK 17 下直接运行无需额外参数。

5.3 启动目录约定

启动器以工作目录为 felix.home：conf/ 与 bundle/ 均相对工作目录解析。切换部署位置时先 cd 到 felix 根目录再启动：

cd /opt/felix
java -jar bin/felix.jar

六、常见问题与验证

6.1 缺少配置文件

现象：No config.properties found.

处理：确认 conf/config.properties 存在且含 felix.log.level 等键值。

6.2 Maven 版本过旧

现象：Fatal error compiling: invalid target release: 17

处理：升级 Maven 至 3.9.9（实测修复，见安装指南）。

6.3 手动安装而非自动部署

现象：install 命令成功但 bundle 未启动，lb 状态为 Installed。

处理：执行 start 后状态转 Active，此时 Blueprint 运行时才创建：

g! start 17
[Blueprint Extender: 2] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle com.example.aries.blueprint.demo/1.0.0 has been started

6.4 服务未注册时的消费方

现象：consumer 运行时迟迟不创建。

处理：先启动提供方，reference 命中后运行时自动完成创建，日志中随之出现服务调用输出。

七、参考链接