Apache Felix 配置参数详解
详解 Apache Felix 核心配置文件 conf/config.properties：框架存储与缓存、启动级别、日志级别、自动部署与自动启动、File Install、HTTP 端口及 Web Console 等关键参数。
Apache Felix 配置参数详解
Felix Framework 的启动配置集中在发行包根目录的 conf/config.properties，内容为标准 key=value 属性文件。框架启动时读取该文件，并以系统属性（-Dkey=value）作为更高优先级的覆盖来源。本文所列键名均与 Felix 7.0.5 发行包内 conf/config.properties 一致，其中标注【实测】者已在本机验证。
一、配置文件与加载方式
1.1 配置文件位置
发行包默认提供 conf/config.properties，位于框架根目录下：
cd /opt/felix/felix-framework-7.0.5
ls conf/config.properties
未显式指定 -Dfelix.config.properties 时，启动器自动加载该文件。
1.2 两种生效方式
- 修改配置文件：直接编辑
conf/config.properties，对每次启动生效。 - 系统属性覆盖：
java -Dorg.osgi.service.http.port=9090 -jar bin/felix.jar，优先级高于配置文件，适合临时调试。
1.3 启动命令中的内存约定
框架以 Java 进程运行，示例统一将堆限制在 256–512 MB：
java -Xms256m -Xmx512m -jar bin/felix.jar
二、框架存储与缓存
2.1 org.osgi.framework.storage
指定 bundle 缓存（框架工作区）的目录。默认值为当前工作目录下的 felix-cache。若取相对路径，则由 felix.cache.rootdir 决定其绝对位置。
org.osgi.framework.storage=/opt/felix/cache-custom
【实测】写入上述配置后启动，缓存目录落在 /opt/felix/cache-custom，lb 中 bundle 状态与默认启动一致。
2.2 felix.cache.rootdir
把相对缓存路径换算为绝对路径时使用的根目录，默认 ${user.dir}（当前工作目录）。
felix.cache.rootdir=${user.dir}
2.3 org.osgi.framework.storage.clean
控制首次初始化框架时是否清空缓存，取值 none（默认）或 onFirstInit。改动框架级配置后希望强制重建缓存时使用：
org.osgi.framework.storage.clean=onFirstInit
2.4 嵌入式场景覆盖缓存
以 API 方式启动时，缓存同样由 org.osgi.framework.storage 指定，可在配置 Map 中传入独立目录，避免与发行包默认缓存互相污染。
三、启动级别
3.1 org.osgi.framework.startlevel.beginning
设置框架启动后要达到的起始启动级别，默认 1。
org.osgi.framework.startlevel.beginning=1
【实测】配置该项后启动正常，felix:frameworklevel 返回 Level is 1。
3.2 felix.startlevel.bundle
新安装 bundle 的默认启动级别，默认 1。
felix.startlevel.bundle=1
查看单个 bundle 的级别可用 bundlelevel <id>：
g! bundlelevel 7
com.example.hello [7] is level 1
四、日志级别
4.1 felix.log.level
控制框架内部日志输出级别：
| 取值 | 含义 |
|---|---|
| 1 | Error（发行包默认） |
| 2 | Warning |
| 3 | Info |
| 4 | Debug |
felix.log.level=4
【实测】置为 4 后，启动过程打印大量 DEBUG: WIRE: ... 连线（wiring）日志，便于排查 bundle 依赖解析问题；置回 1 则仅输出错误。
4.2 与日志服务的关系
felix.log.level 只影响框架自带日志。读取日志服务的命令 felix:log 依赖已部署的 Log 服务 bundle；默认发行包未部署时执行会得到 Log reader service is unavailable.。
五、自动部署与自动启动
5.1 felix.auto.deploy.action
处理自动部署目录时执行的动作，逗号分隔，可选 install、start、update、uninstall。发行包默认：
felix.auto.deploy.action=install,start
留空或不设置等价于关闭自动部署。
5.2 felix.auto.deploy.dir
自动部署目录，默认工作目录下的 bundle。发行包 bundle/ 中的 Gogo 相关 jar 即由此机制在启动时安装并启动。
5.3 felix.auto.start.<n> 与 felix.auto.install.<n>
以空格分隔的 bundle URL 列表，结尾数字为目标启动级别。felix.auto.start.<n> 会在启动时安装并启动，felix.auto.install.<n> 只安装。
felix.auto.start.1=file:/opt/felix-bundle/target/hello-osgi-1.0.0.jar
【实测】配置该项后启动，框架自动安装并激活 hello-osgi，输出 [hello-osgi] Bundle started: com.example.hello，lb 中该 bundle 为 Active。
六、File Install 目录轮询
以下键由 Felix File Install bundle 提供（需先将其安装到框架中），用于将某目录下的 jar 自动安装/启动：
| 配置键 | 说明 | 默认 |
|---|---|---|
| felix.fileinstall.dir | 被监视的自动装载目录 | ./load |
| felix.fileinstall.poll | 轮询间隔（毫秒），0 表示只处理一次 | 2000 |
| felix.fileinstall.noInitialDelay | 是否跳过首次延迟扫描 | false |
| felix.fileinstall.start.level | 自动装载 bundle 的启动级别 | 1 |
| felix.fileinstall.log.level | File Install 自身日志级别 | 1 |
| felix.fileinstall.filter | 文件名正则过滤 | 全部 |
felix.fileinstall.dir=/opt/felix/load
felix.fileinstall.poll=5000
放入 felix.fileinstall.dir 的 jar 会被自动安装，按 felix.fileinstall.start.level 决定是否启动。
七、HTTP 服务与 Web Console
7.1 org.osgi.service.http.port
HTTP 服务监听端口，发行包默认：
org.osgi.service.http.port=8080
该端口由 HTTP 服务实现 bundle（如 Felix HTTP Service）消费；未部署 HTTP bundle 时该键不产生监听。
7.2 felix.webconsole.*
Web Console 由 org.apache.felix.webconsole bundle 提供，常用键如下（需先安装该 bundle）：
| 配置键 | 说明 |
|---|---|
| felix.webconsole.title | 控制台标题 |
| felix.webconsole.username | 控制台登录用户名 |
| felix.webconsole.password | 控制台登录密码 |
| felix.webconsole.realm | 认证域 |
| felix.webconsole.manager.root | 拥有管理权限的用户/角色 |
felix.webconsole.title=Felix Console
felix.webconsole.username=admin
felix.webconsole.password=admin
Web Console 复用 org.osgi.service.http.port 端口（默认 8080），通过 http://<服务器IP>:8080/system/console 访问。
八、类加载与系统包
8.1 org.osgi.framework.system.packages.extra
向框架默认导出的系统包集合中追加包，使这些包对所有 bundle 可见：
org.osgi.framework.system.packages.extra=sun.misc,com.example.spi
8.2 org.osgi.framework.bootdelegation 与 felix.bootdelegation.implicit
将指定的类路径包对全部 bundle 开放（相当于绕过 OSGi 导入）：
org.osgi.framework.bootdelegation=sun.*,com.sun.*,jdk.*
felix.bootdelegation.implicit=false
Felix 默认会隐式进行 boot delegation，建议仅在确有兼容性需求时关闭。
8.3 felix.service.urlhandlers 与 felix.shutdown.hook
felix.service.urlhandlers=false：不安装 URL Handlers 服务。felix.shutdown.hook=false：不注册框架关闭钩子。
#felix.service.urlhandlers=false
#felix.shutdown.hook=false
九、配置排错
Q1：修改 conf/config.properties 后不生效？
确认启动时的当前工作目录为框架根目录（配置文件按相对路径加载），或检查是否被同名 -D 系统属性覆盖。
Q2：felix.auto.start.1 没生效？
检查 felix.auto.deploy.action 是否包含 start；确认 jar 路径使用 file: 前缀且文件可读；felix.log.level=4 可帮助观察安装过程。
Q3：felix:log 报 Log reader service is unavailable.？
默认发行包未部署 Log 服务 bundle。需要日志服务能力时，另行安装对应 bundle。
Q4：HTTP 端口配置了但无法访问？
org.osgi.service.http.port 只声明端口，必须部署 HTTP 服务实现 bundle 才会真正监听。
Q5：如何清理损坏的缓存？
停止框架后设置 org.osgi.framework.storage.clean=onFirstInit 重启一次，或直接删除 felix-cache 目录。