Apache Aries 常用 CLI 命令与工具详解

Apache Aries 常用 CLI 命令详解：Gogo shell 帮助体系、bundle 生命周期、查询诊断、文件脚本与服务上下文命令，基于 Felix 7.0.5 与 Aries Blueprint 1.10.3 实测回显。

Apache AriesAries2026/10/14

Apache Aries 常用 CLI 命令与工具详解

目标：掌握 Aries 运行环境（Felix 7.0.5 + Gogo shell）的常用命令行工具：bundle 生命周期管理、状态与服务查询、装配诊断、脚本化操作，全部命令回显来自真实运行。

一、Gogo Shell 概览

1.1 启动进入 Shell

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

真实回显：

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

Welcome to Apache Felix Gogo

g!

g! 为 Gogo shell 提示符，在此输入命令。命令解析采用作用域限定：felix:lb 与 lb 等价，同名命令可用冒号前缀区分。

💡 技术拓展：不同 OSGi 运行时的 shell 命令不同——Felix 使用 Gogo（felix:* 与 gogo:* 命令组）；Apache Karaf 在 Gogo 基础上扩展了 feature:list、bundle:list 等子命令体系；Eclipse Equinox 使用 OSGi 控制台（osgi> 提示符）。Aries 组件本身的部署与验证命令以 Felix/Gogo 为例展开。

1.2 查看全部命令

g! help

真实回显（按作用域分组）：

context:addbundlelistener
context:addframeworklistener
context:addservicelistener
context:allservicereferences
context:bundle
context:bundles
context:createfilter
context:datafile
context:getallservicereferences
context:getbundle
context:getbundles
context:getdatafile
context:getproperty
context:getservice
context:getserviceobjects
context:getservicereference
context:getservicereferences
context:installbundle
context:property
context:registerservice
context:removebundlelistener
context:removeframeworklistener
context:removeservicelistener
context:service
context:serviceobjects
context:servicereference
context:servicereferences
context:ungetservice
felix:bundlelevel
felix:cd
felix:frameworklevel
felix:headers
felix:help
felix:inspect
felix:install
felix:lb
felix:log
felix:ls
felix:refresh
felix:resolve
felix:start
felix:stop
felix:uninstall
felix:update
felix:which
gogo:bg
gogo:break
gogo:cat
gogo:cd
gogo:clear
gogo:complete
gogo:continue
gogo:date
gogo:each
gogo:echo
gogo:fg
gogo:format
gogo:getopt
gogo:gosh
gogo:grep
gogo:head
gogo:help
gogo:history
gogo:if
gogo:jobs
gogo:keymap
gogo:less
gogo:ls
gogo:nano
gogo:new
gogo:not
gogo:pwd
gogo:set
gogo:setopt
gogo:sh
gogo:sleep
gogo:sort

二、bundle 生命周期命令

2.1 安装（install）

g! install file:/opt/aries-src/demo/target/aries-blueprint-demo-1.0.0.jar
Bundle ID: 17

install 接受 file: 与 http: 形式的 URL，返回分配的 Bundle ID。

2.2 启动（start）

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

start 按 ID 启动 bundle，Aries 扩展器随之创建 Blueprint 运行时。注意：start 参数不接受 symbolic name，实测传入名称会报错：

g! start com.example.aries.blueprint.demo
java.net.MalformedURLException: no protocol: com.example.aries.blueprint.demo

2.3 停止（stop）

g! stop 17

停止后 bundle 回到 Resolved 状态，Blueprint 运行时同步销毁；再次 start 可重建运行时（日志显示新运行时已创建）。

2.4 卸载（uninstall）

g! uninstall 19
[pipe-uninstall 19] INFO org.apache.aries.blueprint.container.BlueprintExtender - Destroying container for blueprint bundle com.example.aries.blueprint.consumer/1.0.0

卸载即从运行时移除 bundle，Aries 先销毁其 Blueprint 运行时再移除服务。

2.5 更新（update）与刷新（refresh）

g! update 17
g! refresh 17

update 重新读取 jar 内容并重装；refresh 对指定 bundle 及其依赖重新解析。两者常用于热更新场景。

三、查询与诊断命令

3.1 列出 bundle（lb）

g! lb
START LEVEL 1
   ID|State      |Level|Name
    0|Active     |    0|System Bundle (7.0.5)|7.0.5
   17|Active     |    1|aries-blueprint-demo (1.0.0)|1.0.0
   19|Active     |    1|aries-blueprint-consumer (1.0.0)|1.0.0

各列含义：ID 为 Bundle ID；State 为生命周期状态（Installed、Resolved、Active）；Level 为启动级别；Name 显示 Bundle-Name。

3.2 查看 symbolic name（lb -s）

g! lb -s
   17|Installed  |    1|com.example.aries.blueprint.demo (1.0.0)|1.0.0

-s 选项将 Name 列切换为 Bundle-SymbolicName，用于核对安装来源。

3.3 查看 MANIFEST（headers）

g! headers 17
aries-blueprint-demo (17)
-------------------------
Bnd-LastModified = 1791909072012
Build-Jdk-Spec = 17
Bundle-Blueprint = OSGI-INF/blueprint/demo.xml
Bundle-ManifestVersion = 2
Bundle-Name = aries-blueprint-demo
Bundle-SymbolicName = com.example.aries.blueprint.demo
Bundle-Version = 1.0.0
Created-By = Apache Maven Bundle Plugin 5.1.9
Export-Package = com.example.aries.api;version="1.0.0",com.example.aries.impl;version="1.0.0";uses:="com.example.aries.api"
Export-Service = com.example.aries.api.Greeting;osgi.service.blueprint.compname=greetingBean
Import-Package = com.example.aries.api;version="[1.0,2)",java.lang,java.lang.invoke,org.osgi.service.blueprint;version="[1.0.0,2.0.0)"
Manifest-Version = 1.0
Require-Capability = osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=17))"
Tool = Bnd-6.3.1.202206071316

Bundle-Blueprint 与 Export-Service 是 Aries 装配诊断的关键项。

3.4 检查服务能力（inspect cap service）

g! inspect cap service 17
com.example.aries.blueprint.demo [17] provides:
-----------------------------------------------
service; com.example.aries.api.Greeting with properties:
   osgi.service.blueprint.compname = greetingBean
   service.bundleid = 17
   service.id = 33
   service.scope = bundle
   Used by:
      com.example.aries.blueprint.consumer [19]
service; org.osgi.service.blueprint.container.BlueprintContainer with properties:
   osgi.blueprint.container.symbolicname = com.example.aries.blueprint.demo
   osgi.blueprint.container.version = 1.0.0
   service.bundleid = 17
   service.id = 34
   service.scope = singleton

Used by 列出正在使用该服务的其他 bundle，是验证服务装配闭环的直接证据。

3.5 检查包依赖（inspect req package）

g! inspect req package 19
com.example.aries.blueprint.consumer [19] requires:
---------------------------------------------------
package [EMPTY]

列出 bundle 对包的导入需求，依赖由框架自动满足时显示解析成功。

3.6 定位导出方（which）

g! which com.example.aries.api

which 用于查询某个包由哪个 bundle 导出，快速定位类来源。

四、文件与脚本命令

4.1 文件浏览

g! ls
g! cat config.properties
g! pwd

ls 与 cat 类似 shell 同名命令，作用于 felix.home 目录；pwd 显示当前目录。

4.2 脚本化

Gogo 支持变量、管道与分支：

g! echo 1 + 2
3
g! gogo:echo Hello | gogo:grep Hello
Hello
g! if { gogo:echo ok } { gogo:echo branch }

常用组合：sleep 控制节奏、date 查看时间、each 遍历、sort 排序，可把重复操作写成脚本一次执行。

4.3 运行脚本（gosh）

g! gosh file:/opt/scripts/deploy.gogo

gosh 执行脚本文件，内容为逐行命令，适合固定的部署与验证流程。

五、服务与上下文命令

5.1 服务查询

g! context:servicereferences com.example.aries.api.Greeting
命令说明
context:servicereferences列出指定接口的服务引用
context:serviceobjects列出服务实现对象
context:getservice获取服务实例
context:allservicereferences列出全部服务引用
context:registerservice注册服务

5.2 上下文与框架属性

g! context:property org.osgi.framework.version
命令说明
context:property读取框架属性
context:bundles列出全部 bundle 对象
context:createfilter创建并测试 LDAP 过滤器

六、日志与启动级别命令

6.1 查看框架日志（felix:log）

g! felix:log

输出框架日志缓冲，Aries 扩展器的运行时创建与销毁记录均可在此复核。

6.2 启动级别管理

g! felix:frameworklevel
g! felix:bundlelevel 17

frameworklevel 显示/设置框架启动级别，bundlelevel 查看单个 bundle 级别。批量部署时可用级别控制启动顺序。

6.3 关闭运行时

g! stop
[FelixShutdown] INFO org.apache.aries.blueprint.container.BlueprintExtender - Destroying container for blueprint bundle com.example.aries.blueprint.consumer/1.0.0
[FelixShutdown] INFO org.apache.aries.blueprint.container.BlueprintExtender - Destroying container for blueprint bundle com.example.aries.blueprint.demo/1.0.0
[FelixShutdown] INFO org.apache.aries.blueprint.container.BlueprintExtender - Destroying container for blueprint bundle org.apache.aries.blueprint.core/1.10.3
g! gosh: stopping framework

不带参数的 stop 关闭整个框架，Aries 按反序销毁全部 Blueprint 运行时。

七、参考链接