CentOS 8 安装 Apache Celix 指南

目标：在 CentOS 8 服务器上从零安装 Apache Celix（C/C++ 版 OSGi 运行时框架），覆盖 dnf 依赖安装、libuv/libffi 两个 CentOS 8 特有依赖的源码编译、Celix 源码构建与官方发布包两种方案，并实测最小 bundle 加载运行。本指南全部命令与回显已在 CentOS 8（gcc 8.5.0）实测通过。

一、环境信息

项目	实测值
操作系统	CentOS Linux 8（VERSION_ID=8）
内核架构	x86_64
编译器	gcc 8.5.0、g++ 8.5.0
CMake	3.20.2
包管理器	dnf（yum 兼容）
Apache Celix（主方案）	3.0.0（源码构建，master 分支）
Apache Celix（备用方案）	2.4.0（官方发布包）
安装前缀	/opt/celix（3.0.0）、/opt/celix-2.4（2.4.0）
源码目录	/opt/celix-src、/opt/libuv-1.43.0、/opt/libffi-3.4.4

二、版本选型说明

2.1 版本现状

与 Ubuntu 篇相同，Apache Celix 最新正式发布版为 2.4.0，3.x 目前仅有 master 分支源码（版本号 3.0.0）。CentOS 8 上没有现成的 Celix 软件包，两种方案均为源码编译。

版本	性质	获取方式	说明
3.0.0	开发版（master 分支）	git clone	框架库 SOVERSION 为 3
2.4.0	最新正式发布版	downloads.apache.org	官方发布目录唯一正式版

2.2 选型建议

CentOS 8 属于保守型服务器环境，建议优先 2.4.0 正式版（构建速度快、稳定）；需要 3.x 特性时再选择 3.0.0 源码版。本文主方案演示 3.0.0，备用方案演示 2.4.0。

三、依赖安装（dnf）

3.1 方案说明

Celix 编译需要完整 C 工具链与若干动态库开发包。CentOS 8 的 AppStream/BaseOS 仓库提供大部分包，但 libuv-devel 缺失、libffi 版本过旧（3.1），这两项需要额外源码编译，见第四章与第五章。

3.2 安装基础依赖

dnf install -y gcc gcc-c++ make cmake git curl wget pkgconfig \
    libzip-devel zlib-devel libxml2-devel libffi-devel \
    jansson-devel libcurl-devel libuuid-devel

3.3 安装编译辅助工具

libuv 与 libffi 源码编译需要 autotools 工具链：

dnf install -y libtool autoconf automake

3.4 验证依赖

gcc --version | head -1
cmake --version | head -1
rpm -q gcc gcc-c++ make cmake libzip-devel libxml2-devel libffi-devel jansson-devel

实测回显（输出节选，实测首尾）：

gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-4)
cmake version 3.20.2
gcc-8.5.0-4.el8_5.x86_64
gcc-c++-8.5.0-4.el8_5.x86_64
make-4.2.1-10.el8.x86_64
cmake-3.20.2-4.el8.x86_64
libzip-devel-1.5.1-2.module_el8.2.0+313+b04d0a66.x86_64
libxml2-devel-2.9.7-9.el8_4.2.x86_64
libffi-devel-3.1-22.el8.x86_64
jansson-devel-2.11-3.el8.x86_64

⚠️ 注意：rpm 查询显示 libffi-devel 为 3.1，该版本缺少 ffi_get_struct_offsets API，会导致 Celix 的 DFI 组件编译报错，必须按第五章升级到 3.4+。

四、libuv 源码编译安装

4.1 方案说明

CentOS 8 的 AppStream 仓库只有 libuv 运行库（1.41.1），没有 libuv-devel 开发包。Celix 的 libs/utils 强制依赖 libuv 头文件，因此从源码编译 libuv 1.43.0 安装到 /usr。

4.2 下载源码

cd /opt
curl -sL -o libuv.tar.gz https://github.com/libuv/libuv/archive/refs/tags/v1.43.0.tar.gz
tar xzf libuv.tar.gz
cd libuv-1.43.0

4.3 生成 configure 并编译安装

GitHub 源码包不含 configure，先用 autogen.sh 生成（依赖第三章安装的 libtool/autoconf/automake）：

cd /opt/libuv-1.43.0
./autogen.sh
./configure --prefix=/usr
make -j4
make install

实测回显（输出节选，实测首尾）：

+ libtoolize --copy
configure.ac:21: installing './missing'
Makefile.am: installing './depcomp'
config.status: executing depfiles commands
config.status: executing libtool commands
  CC       src/unix/libuv_la-epoll.lo
  CCLD     libuv.la
 /usr/bin/install -c -m 644 include/uv/errno.h include/uv/threadpool.h include/uv/version.h include/uv/unix.h include/uv/linux.h '/usr/include/uv'

4.4 验证

ls -la /usr/lib64/libuv.so* /usr/include/uv.h

实测回显：

-rw-r--r-- 1 root root   67166 Oct 13 18:01 /usr/include/uv.h
lrwxrwxrwx 1 root root      14 Oct 13 18:01 /usr/lib64/libuv.so -> libuv.so.1.0.0
lrwxrwxrwx 1 root root      14 Oct 13 18:01 /usr/lib64/libuv.so.1 -> libuv.so.1.0.0
-rwxr-xr-x 1 root root 1008512 Oct 13 18:01 /usr/lib64/libuv.so.1.0.0

五、libffi 升级（源码编译 3.4.4）

5.1 方案说明

libffi 3.4 起新增 ffi_get_struct_offsets 函数，Celix 的 DFI（动态函数调用）组件依赖它。CentOS 8 自带的 libffi-devel 3.1 编译 Celix 时必然报错（见常见问题 Q2），需升级到 3.4.4。

5.2 下载官方发布源码包

使用 libffi 官方 release 资产包（内含 configure，无需 autogen）：

cd /opt
curl -sL -o libffi-rel.tar.gz https://github.com/libffi/libffi/releases/download/v3.4.4/libffi-3.4.4.tar.gz
tar xzf libffi-rel.tar.gz
cd libffi-3.4.4

5.3 编译安装到 /usr

cd /opt/libffi-3.4.4
./configure --prefix=/usr
make -j4
make install

实测回显（输出节选，实测首尾）：

config.status: executing include commands
config.status: executing src commands
make[2]: Leaving directory '/opt/libffi-3.4.4/x86_64-pc-linux-gnu'
make[1]: Leaving directory '/opt/libffi-3.4.4/x86_64-pc-linux-gnu'
make[2]: Leaving directory '/opt/libffi-3.4.4/x86_64-pc-linux-gnu'
make[1]: Leaving directory '/opt/libffi-3.4.4/x86_64-pc-linux-gnu'

5.4 验证新版本生效

ls -la /usr/lib64/libffi.so*
grep -c ffi_get_struct_offsets /usr/include/ffi.h

实测回显：

lrwxrwxrwx 1 root root    15 Oct 13 18:23 /usr/lib64/libffi.so -> libffi.so.8.1.2
lrwxrwxrwx 1 root root    15 Jun 15  2020 /usr/lib64/libffi.so.6 -> libffi.so.6.0.2
lrwxrwxrwx 1 root root    15 Oct 13 18:23 /usr/lib64/libffi.so.8 -> libffi.so.8.1.2
-rwxr-xr-x 1 root root 61232 Oct 13 18:23 /usr/lib64/libffi.so.8.1.2
1

说明：系统原 libffi.so.6（3.1，soname 为 6）保留以兼容既有程序，新库以 libffi.so.8（3.4.4）接入；头文件已含 ffi_get_struct_offsets（grep 计数 1）。

六、Celix 3.0.0 源码编译安装（主方案）

6.1 方案说明

拉取 Apache Celix master 分支源码，CMake 构建并安装到 /opt/celix。CentOS 8 的 cmake 3.20.2 满足 Celix 要求的 CMake 3.19+。

6.2 获取源码

cd /opt
git clone --depth 1 https://github.com/apache/celix.git celix-src
cd celix-src
git log -1 --format="%h %ad %s"

实测回显：

Cloning into 'celix-src'...
0fff190 Mon Sep 28 11:49:10 2026 +0800 Add tests for handling invalid JSON replies and type mismatches in JSON serializer.

6.3 CMake 配置

cd /opt/celix-src
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/celix

实测回显（输出节选，实测首尾）：

-- Found libffi: /usr/lib64/libffi.so
-- Found CURL: /usr/lib64/libcurl.so (found version "7.61.1")
-- Found libuuid: /usr/lib64/libuuid.so
-- Found LibXml2: /usr/lib64/libxml2.so (found version "2.9.7")
-- Found RapidJSON: /usr/include/rapidjson
-- Configuring done
-- Generating done
-- Build files have been written to: /opt/celix-src/build

6.4 编译

cd /opt/celix-src
cmake --build build -j4

实测回显（输出节选，实测首尾）：

[ 13%] Building C object libs/framework/CMakeFiles/framework.dir/src/celix_bundle_manifest.c.o
[ 13%] Linking C shared library libcelix_framework.so
[ 13%] Built target framework
[100%] Linking CXX executable ../../../deploy/CalcTrackerContainer/CalcTrackerContainer
[100%] Built target CalcTrackerContainer
[100%] Built target celix-containers

6.5 安装

cd /opt/celix-src
cmake --install build

实测回显（输出节选，实测首尾）：

-- Installing: /opt/celix/share/celix/cmake/CelixDeps.cmake
-- Installing: /opt/celix/lib64/cmake/Celix/CelixConfig.cmake
-- Installing: /opt/celix/lib64/cmake/Celix/CelixConfigVersion.cmake

说明：CentOS 8 采用 lib64 布局，Celix 的 CMake 包安装到 /opt/celix/lib64/cmake/Celix，find_package(Celix) 自动兼容。

6.6 验证安装与帮助

ls /opt/celix/bin/
/opt/celix/bin/celix -h

实测回显：

celix
Usage:
  celix [-h|-p|-c] [path/to/runtime/config.properties]
Options:
        -h | --help: Show this message.
        -p | --props: Show the embedded and runtime properties for this Celix runtime and exit.
        -c | --create-bundle-cache: Create the bundle cache for this Celix runtime and exit.

6.7 最小 bundle 加载运行验证

编写最小 bundle（C 源码 + CMake 打包描述）并编译加载，验证框架端到端可用：

创建 /opt/my-bundle/src/bundle.c：

#include <stdio.h>
#include <celix_bundle_activator.h>

typedef struct activator_data {
    /*empty*/
} activator_data_t;

static celix_status_t activator_start(activator_data_t *data, celix_bundle_context_t *ctx) {
    printf("[my-bundle] activator_start: hello from my-bundle, bundle id=%li\n",
           celix_bundleContext_getBundleId(ctx));
    return CELIX_SUCCESS;
}

static celix_status_t activator_stop(activator_data_t *data, celix_bundle_context_t *ctx) {
    printf("[my-bundle] activator_stop: goodbye from my-bundle, bundle id=%li\n",
           celix_bundleContext_getBundleId(ctx));
    return CELIX_SUCCESS;
}

CELIX_GEN_BUNDLE_ACTIVATOR(activator_data_t, activator_start, activator_stop)

创建 /opt/my-bundle/CMakeLists.txt：

cmake_minimum_required(VERSION 3.19)
project(my_bundle C)

find_package(Celix REQUIRED)

add_celix_bundle(my_bundle
    VERSION 1.0.0
    SOURCES src/bundle.c
)

编译：

cd /opt/my-bundle
cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/celix
cmake --build build

实测回显（输出节选，实测首尾）：

-- Found LibRt: /usr/lib64/librt.so
-- Configuring done
-- Generating done
-- Build files have been written to: /opt/my-bundle/build
[100%] Packaging my_bundle
[100%] Built target my_bundle_bundle
[100%] Built target celix-bundles
[100%] Built target celix-containers

编写运行时配置并加载运行：

cat > /opt/my-bundle/config.json <<'EOF'
{
  "CELIX_AUTO_START_0": "file:///opt/my-bundle/build/my_bundle.zip"
}
EOF
cd /opt/my-bundle
timeout 8 /opt/celix/bin/celix config.json

实测回显：

[my-bundle] activator_start: hello from my-bundle, bundle id=1
[2026-10-13T18:19:17] [   info] [celix_framework] [framework_start:496] Celix framework started
[2026-10-13T18:19:25] [   info] [celix_framework] Stopping Celix framework due to signal Terminated
[my-bundle] activator_stop: goodbye from my-bundle, bundle id=1

验证结论：bundle 的 activator 启动/停止回调在框架启停时均被执行（bundle id=1），CentOS 8 上 Celix 3.0.0 全链路运行正常。

七、备用方案：官方发布包安装（Celix 2.4.0）

7.1 方案说明

从 Apache 官方发布目录下载 2.4.0 源码包编译安装，路径固定、来源可追溯，适合生产环境。

7.2 下载与解压

cd /opt
curl -sLO https://downloads.apache.org/celix/celix-2.4.0/celix-2.4.0.tar.gz
tar xzf celix-2.4.0.tar.gz
cd celix-2.4.0

7.3 编译安装

cd /opt/celix-2.4.0
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/celix-2.4
cmake --build build -j4
cmake --install build

实测回显（输出节选，实测首尾）：

-- Configuring done
-- Generating done
-- Build files have been written to: /opt/celix-2.4.0/build
[100%] Built target celix-containers
-- Installing: /opt/celix-2.4/share/celix/cmake/CelixDeps.cmake
-- Installing: /opt/celix-2.4/lib64/cmake/Celix/CelixConfig.cmake
-- Installing: /opt/celix-2.4/lib64/cmake/Celix/CelixConfigVersion.cmake

7.4 验证

ls /opt/celix-2.4/bin/
/opt/celix-2.4/bin/celix -h

实测回显：

celix
Usage:
  celix [-h|-p] [path/to/runtime/config.properties]
Options:
        -h | --help: Show this message.
        -p | --props: Show the embedded and runtime properties for this Celix runtime and exit.
        -c | --create-bundle-cache: Create the bundle cache for this Celix runtime and exit.
        --embedded_bundles: Show the embedded bundles for this Celix runtime and exit.

八、方案对比与选择建议

对比维度	方案 A：源码 3.0.0	方案 B：官方包 2.4.0
版本	3.0.0（开发版）	2.4.0（正式版）
获取来源	github.com	downloads.apache.org
构建时间（4 核实测）	约 3 分钟	约 2 分钟
额外依赖	同左	同左
新特性	3.x 全部	2.4.0 上限
稳定性	开发版	正式发布
适用场景	尝鲜 3.x	生产环境

选择建议：CentOS 8 生产服务器选 2.4.0 官方包更稳妥；两份安装独立前缀共存，可按需切换（详见第九章）。

九、多版本管理

两版本安装前缀独立（/opt/celix 与 /opt/celix-2.4），互不覆盖：

/opt/celix/bin/celix -h        # 3.0.0
/opt/celix-2.4/bin/celix -h    # 2.4.0

升级 3.x：cd /opt/celix-src && git pull && cmake --build build && cmake --install build；降级：编译目标版本到新前缀即可。升级前建议备份：

cp -r /opt/celix /opt/celix-backup-$(date +%Y%m%d)

十、卸载与清理

# 卸载安装目录
rm -rf /opt/celix /opt/celix-2.4
# 清理源码与构建目录
rm -rf /opt/celix-src /opt/celix-2.4.0 /opt/my-bundle
# 清理运行期 bundle 缓存
rm -rf /root/.cache/bundle* /opt/celix/bundle-cache

验证：

ls /opt/celix 2>&1; ls /opt/celix-src 2>&1

实测回显：

ls: cannot access '/opt/celix': No such file or directory
ls: cannot access '/opt/celix-src': No such file or directory

⚠️ 注意：libuv 1.43.0 与 libffi 3.4.4 已安装到 /usr 系统目录，卸载 Celix 后如需还原系统原版，用 dnf 重装对应包：dnf reinstall -y libffi-devel（libuv-devel 在 CentOS 8 仓库不存在，还原需自行处理，一般无需还原）。

十一、常见问题（FAQ）

Q1：dnf 安装报 Unable to find a match: libuv-devel？

实测报错：

Error: Unable to find a match: libuv-devel cpputest

原因：CentOS 8 AppStream 仅提供 libuv 运行库（1.41.1），无开发包；cpputest 在默认仓库也不存在。解决：libuv 按第四章源码编译；cpputest 仅在开启 ENABLE_TESTING 时需要，不装即可（Celix 默认测试关闭）。

Q2：编译 Celix 报 implicit declaration of function 'ffi_get_struct_offsets'？

实测报错：

/opt/celix-src/libs/dfi/src/dyn_type.c:317:11: error: implicit declaration of function 'ffi_get_struct_offsets' [-Werror=implicit-function-declaration]
cc1: all warnings being treated as errors

原因：系统 libffi 3.1 无此 API（3.4 引入）。解决：按第五章升级 libffi 3.4.4，然后清掉 build 重新配置编译：

cd /opt/celix-src
rm -rf build
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/celix
cmake --build build -j4

Q3：libuv 源码编译报 libtoolize: command not found？

实测报错：

./autogen.sh: line 43: libtoolize: command not found

原因：autogen.sh 依赖 libtool。解决：

dnf install -y libtool autoconf automake
cd /opt/libuv-1.43.0 && ./autogen.sh

Q4：celix 启动时报 Error creating runtime properties: Failed to open file --version.？

说明：celix 主程序不支持 --version 参数，会把未知参数当配置文件路径。版本以库文件后缀确认：ls /opt/celix/lib64/ | grep framework 返回 libcelix_framework.so.3.0.0。

Q5：找不到 celix_launcher 可执行文件？

实测说明：Celix 3.x 将 launcher 功能并入 celix 主程序（源码 libs/launcher/src/main.c 直接调用 celix_launcher_launchAndWait），不再提供独立 celix_launcher 二进制；该函数位于 libcelix_framework.so 中，供自定义启动器调用。

十二、参考链接

Apache Celix 官网：https://celix.apache.org/
Apache Celix 源码仓库：https://github.com/apache/celix
Apache 官方发布目录：https://downloads.apache.org/celix/
libuv 源码：https://github.com/libuv/libuv
libffi 发布页：https://github.com/libffi/libffi/releases