Ubuntu 22.04 安装 Apache Felix 指南

Ubuntu 22.04 上安装 Apache Felix Framework 7.0.5 指南：JDK 17 安装、发行包下载解压、目录结构与 Gogo shell 启动、版本验证，以及最小 bundle 的安装启动与卸载。

Apache FelixApache Felix2026/10/12

Ubuntu 22.04 安装 Apache Felix 指南

目标：在 Ubuntu 22.04 服务器上从零部署 Apache Felix Framework 7.0.5，配置 JDK 17 运行环境，启动 Gogo shell 并验证版本，最后完成一个最小 OSGi bundle 的安装、启动、停止与卸载闭环。

一、组件简介与前置条件

1.1 组件说明

Apache Felix 是 OSGi R7 规范的完整开源实现，其中 Felix Framework 提供 bundle 的模块化运行时、服务注册表与生命周期管理。它没有独立守护进程，以 Java 进程方式运行，通过内置的 Gogo shell 提供交互式命令行：bin/felix.jar 既是框架本体，也是启动器。

Felix 常见形态有两种：

  • 独立发行包：解压后执行 java -jar bin/felix.jar 直接进入 shell，适合学习与调试。
  • 嵌入式：在自有 Java 应用中以 FrameworkFactory API 启动框架，把 OSGi 能力集成进应用。

1.2 前置条件

项目要求
操作系统Ubuntu 22.04 LTS（x86_64）
包管理器apt
JDKJDK 17（Felix 7.0.5 兼容 JDK 8+；示例 bundle 声明 osgi.ee=JavaSE 11，建议使用 17）
磁盘安装目录约需 10 MB（发行包约 2.7 MB）
内存建议 ≥ 1 GB；JVM 堆限制在 256–512 MB
网络可访问 Apache 归档站 archive.apache.org
运行账号root

1.3 软件清单

软件版本说明
OpenJDK17运行环境
Apache Felix Framework7.0.5OSGi 框架实现
发行包org.apache.felix.main.distribution-7.0.5.zip大小 2,760,367 字节
安装位置/opt/felix/felix-framework-7.0.5解压目录

二、安装 JDK 17

2.1 通过 apt 安装

apt-get update
apt-get install -y openjdk-17-jdk unzip

2.2 验证

java -version
ls -d /usr/lib/jvm/java-17-openjdk-*

真实回显示例：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
/usr/lib/jvm/java-17-openjdk-amd64

三、下载与解压 Felix Framework 发行包

3.1 下载发行包

mkdir -p /opt/felix
cd /tmp
curl -sL -o felix.zip \
  https://archive.apache.org/dist/felix/org.apache.felix.main.distribution-7.0.5.zip
ls -l felix.zip

真实回显：

-rw-r--r-- 1 root root 2760367 Oct 11 15:02 felix.zip

3.2 校验并解压

sha512sum felix.zip
unzip -q felix.zip -d /opt/felix
ls /opt/felix

真实回显：

...  felix.zip
felix-framework-7.0.5

解压后框架根目录为 /opt/felix/felix-framework-7.0.5。

四、目录结构与启动

4.1 目录结构

felix-framework-7.0.5/
├── bin/felix.jar                     # 框架本体 + 启动器
├── bundle/                          # 默认自动部署的 Gogo 相关 bundle
│   ├── jansi-1.18.jar
│   ├── jline-3.13.2.jar
│   ├── org.apache.felix.bundlerepository-2.0.10.jar
│   ├── org.apache.felix.gogo.command-1.1.2.jar
│   ├── org.apache.felix.gogo.jline-1.1.8.jar
│   └── org.apache.felix.gogo.runtime-1.1.4.jar
├── conf/config.properties           # 框架配置文件
├── doc/                             # 官方 HTML 文档与 changelog
├── DEPENDENCIES / LICENSE / NOTICE
└── felix-cache/                     # 首次启动后生成的 bundle 缓存

4.2 启动框架

cd /opt/felix/felix-framework-7.0.5
java -Xms256m -Xmx512m -jar bin/felix.jar

启动后进入 Gogo shell，回显：

____________________________
Welcome to Apache Felix Gogo

g!

在无终端的场景（如通过管道喂入命令）会打印 WARNING: Unable to create a system terminal, creating a dumb terminal，属正常现象，不影响命令执行。

4.3 默认 bundle 列表

在 shell 中执行 lb（list bundles），真实回显：

g! START LEVEL 1
   ID|State      |Level|Name
    0|Active     |    0|System Bundle (7.0.5)|7.0.5
    1|Active     |    1|jansi (1.18.0)|1.18.0
    2|Active     |    1|JLine Bundle (3.13.2)|3.13.2
    3|Active     |    1|Apache Felix Bundle Repository (2.0.10)|2.0.10
    4|Active     |    1|Apache Felix Gogo Command (1.1.2)|1.1.2
    5|Active     |    1|Apache Felix Gogo JLine Shell (1.1.8)|1.1.8
    6|Active     |    1|Apache Felix Gogo Runtime (1.1.4)|1.1.4

其中 ID 0 是系统 bundle（框架自身），ID 1–6 是 Gogo 技术支持 bundle，状态均为 Active。

五、版本验证

5.1 通过 lb 与 headers 验证

lb 回显中 System Bundle (7.0.5) 即框架版本。更精确的方式是查看系统 bundle 的响应头：

g! headers 0
System Bundle (0)
-----------------
Bundle-Name = System Bundle
Bundle-SymbolicName = org.apache.felix.framework
Bundle-Version = 7.0.5
...

5.2 felix:frameworklevel

查看框架启动级别：

g! felix:frameworklevel
Level is 1

5.3 关于 system:version 命令

Felix Framework 发行版不包含 system:version 命令（该命令属于 Karaf 发行版）。在 Felix 中执行会得到：

g! system:version
CommandNotFoundException: Command not found: system:version

因此 Felix 的版本只能以 headers 0 的 Bundle-Version、lb 中的 System Bundle (7.0.5) 或 felix:frameworklevel 为准。system:* scope 在 Felix 中映射到 java.lang.System 方法。

六、最小 Bundle 安装与启动

6.1 准备最小 bundle

用 Maven 构建一个最小 OSGi bundle（Project 结构：pom.xml + src/main/java/com/example/hello/Activator.java）。pom.xml 关键片段：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-bundle-plugin</artifactId>
      <version>5.1.9</version>
      <extensions>true</extensions>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>com.example.hello</Bundle-SymbolicName>
          <Bundle-Version>1.0.0</Bundle-Version>
          <Bundle-Activator>com.example.hello.Activator</Bundle-Activator>
          <Export-Package>com.example.hello</Export-Package>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>

Activator.java：

package com.example.hello;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {
    public void start(BundleContext ctx) {
        System.out.println("[hello-osgi] Bundle started: " + ctx.getBundle().getSymbolicName());
    }
    public void stop(BundleContext ctx) {
        System.out.println("[hello-osgi] Bundle stopped: " + ctx.getBundle().getSymbolicName());
    }
}

打包：

mvn -q -B package
ls target/hello-osgi-1.0.0.jar

产物 MANIFEST 关键项：

Bundle-Activator: com.example.hello.Activator
Bundle-SymbolicName: com.example.hello
Bundle-Version: 1.0.0
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=11))"

6.2 安装 bundle

在 Gogo shell 中通过 file: URL 安装：

g! install file:/opt/felix-bundle/target/hello-osgi-1.0.0.jar
Bundle ID: 7
g! lb
    7|Installed  |    1|hello-osgi (1.0.0)|1.0.0

Installed 表示 bundle 已解析安装但未运行。

6.3 启动与停止

g! start 7
[hello-osgi] Bundle started: com.example.hello
g! lb
    7|Active     |    1|hello-osgi (1.0.0)|1.0.0
g! stop 7
[hello-osgi] Bundle stopped: com.example.hello
    7|Resolved   |    1|hello-osgi (1.0.0)|1.0.0

start 触发 Activator#start，状态变为 Active；stop 触发 Activator#stop，状态回退为 Resolved。

6.4 卸载

g! uninstall 7
g!

卸载后 lb 中不再列出 hello-osgi。

七、停止与卸载 Felix

7.1 停止框架

在 Gogo shell 中执行 exit，或直接结束输入流，框架会主动停机：

g! exit
gosh: stopping framework

7.2 卸载 Felix

Felix 为绿色包，卸载只需删除安装目录：

rm -rf /opt/felix

若不再需要 JDK：

apt-get remove -y openjdk-17-jdk
apt-get autoremove -y

八、常见问题

Q1：启动时报 Unable to create a system terminal？

在无 TTY 环境（如脚本管道输入）下的正常告警，Gogo 会退化为 dumb terminal，命令仍可执行。

Q2：安装 bundle 后 start 报无法解析？

多为 osgi.ee 不匹配。示例 bundle 声明 osgi.ee=JavaSE 11，请确认框架运行在 JDK 11 及以上，可执行 java -version 核对。

Q3：install 报 URL 无法识别？

本地 jar 必须使用 file: 前缀的绝对路径，如 install file:/opt/felix-bundle/target/hello-osgi-1.0.0.jar。

Q4：执行 system:version 报 CommandNotFoundException？

Felix Framework 无该命令，请改用 headers 0 或 felix:frameworklevel 查看版本。

Q5：如何限制 JVM 堆？

启动时显式指定 -Xms256m -Xmx512m，示例命令已内置该参数。