CentOS 8 安装 Apache Unomi 3.0.1 指南

本文介绍在 CentOS 8 服务器上从零安装 Apache Unomi 3.0.1 的完整流程。Apache Unomi 是 OASIS CDP（Context Data Management / Customer Data Platform）标准的参考实现，以 Apache Karaf 4.4.8 为运行时，依赖 Elasticsearch 作为持久化存储。全部命令均在真实环境实测通过。

一、环境信息

项目	说明
操作系统	CentOS Linux release 8.4.2105
Apache Unomi	3.0.1（官方最新稳定版，bin 发行包）
Elasticsearch	9.5.3（tar 包部署）
JDK	OpenJDK 17（java-17-openjdk-devel-17.0.1.0.12-2.el8_5.x86_64）
Karaf 运行时	4.4.8（Unomi 发行包内置）
安装路径	/opt/unomi、/opt/elasticsearch-9.5.3
服务端口	8181（HTTP）、9443（HTTPS）、8102（Karaf 远程控制台 SSH）、9200（Elasticsearch HTTP）
运行账号	elasticsearch、unomi（均为无登录系统账号）

二、前置条件

拥有 root 权限，可执行 dnf、systemctl 等系统命令。
服务器可访问 dlcdn.apache.org 与 artifacts.elastic.co 完成软件包下载。
已具备 curl、tar、sha512sum 基础工具，执行以下命令确保安装（已安装会自动跳过）：

dnf install -y tar curl

内存规划：Unomi 运行堆内存限定 256-512MB，Elasticsearch 堆内存限定 512MB，建议服务器可用内存不低于 2GB；磁盘可用空间不低于 10GB。
端口规划：8181（cxs REST HTTP）、9443（cxs REST HTTPS）、9200（Elasticsearch HTTP）需对外可达；8102 为 Karaf 远程控制台 SSH 端口，仅限本机运维使用，不建议对外放行。

三、版本选型说明

Apache Unomi 3.0.1 为官方当前最新稳定版，其内置 org.apache.unomi.persistence.elasticsearch.cfg 明确要求 Elasticsearch 版本窗口为 minimalElasticsearchVersion=9.0.3、maximalElasticsearchVersion=10.0.0，本文选择窗口内最新的 9.5.3。
Unomi 3.x 要求 JDK 17 运行环境，本文使用 CentOS 8 官方源中的 java-17-openjdk-devel（含 jps 等诊断工具，便于后续堆内存验证）。
发行包下载地址与校验值（实测一致）：

https://dlcdn.apache.org/unomi/3.0.1/unomi-3.0.1-bin.tar.gz
SHA512: 99e1d9f729eb4adfe9288fdfd9d1ec6a35489dfa8c17e7658c1a08ceb550b1bca31646355c043cf59a926cca7f2a00d692d7ce59d95b318e1baaf11c311f1cc9

四、部署步骤

4.1 安装 JDK 17

dnf install -y java-17-openjdk-devel
java -version

实测回显：

openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)

确认 JDK 安装目录（后续 setenv 需要使用）：

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

实测回显：

/usr/lib/jvm/java-17-openjdk
/usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64

4.2 创建系统用户

Elasticsearch 与 Unomi 均不允许以 root 运行，创建两个无登录权限的系统账号：

useradd -r -M -s /sbin/nologin elasticsearch

useradd -r -M -s /sbin/nologin unomi

id unomi

实测回显：

uid=997(unomi) gid=995(unomi) groups=995(unomi)

4.3 调整内核参数

Elasticsearch 9 要求 vm.max_map_count 不低于 262144，默认值 65530 会导致启动失败：

cat > /etc/sysctl.d/99-unomi-elasticsearch.conf <<'EOF'
vm.max_map_count = 262144
EOF

sysctl -p /etc/sysctl.d/99-unomi-elasticsearch.conf

实测回显：

vm.max_map_count = 262144

4.4 安装 Elasticsearch 9.5.3

下载并解压到 /opt：

cd /opt
curl -fLO https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.5.3-linux-x86_64.tar.gz
tar -xzf elasticsearch-9.5.3-linux-x86_64.tar.gz

在 config/elasticsearch.yml 末尾追加最小化配置：

cat >> /opt/elasticsearch-9.5.3/config/elasticsearch.yml <<'EOF'
cluster.name: contextElasticSearch
node.name: node-1
network.host: 127.0.0.1
http.port: 9200
discovery.type: single-node
xpack.security.enabled: false
EOF

说明：cluster.name 必须为 contextElasticSearch（Unomi 默认连接的集群名）；xpack.security.enabled: false 关闭 ES 9 自带的安全认证，与 Unomi 默认的无认证连接方式匹配；network.host: 127.0.0.1 表示 ES 仅本机可用，Unomi 与 ES 同机部署时最安全。

限定 ES 堆内存为 512MB：

mkdir -p /opt/elasticsearch-9.5.3/config/jvm.options.d
cat > /opt/elasticsearch-9.5.3/config/jvm.options.d/heap.options <<'EOF'
-Xms512m
-Xmx512m
EOF

调整目录属主：

chown -R elasticsearch:elasticsearch /opt/elasticsearch-9.5.3

4.5 安装 Apache Unomi 3.0.1

下载发行包并校验：

curl -fLo /opt/unomi-3.0.1-bin.tar.gz https://dlcdn.apache.org/unomi/3.0.1/unomi-3.0.1-bin.tar.gz
sha512sum /opt/unomi-3.0.1-bin.tar.gz

实测回显（与第三节校验值一致）：

99e1d9f729eb4adfe9288fdfd9d1ec6a35489dfa8c17e7658c1a08ceb550b1bca31646355c043cf59a926cca7f2a00d692d7ce59d95b318e1baaf11c311f1cc9  /opt/unomi-3.0.1-bin.tar.gz

解压安装到 /opt/unomi：

tar -xzf /opt/unomi-3.0.1-bin.tar.gz -C /opt
mv /opt/unomi-3.0.1 /opt/unomi
chown -R unomi:unomi /opt/unomi
ls /opt/unomi

实测回显：

BUILD  LICENSE  NOTICE  bin  data  deploy  etc  instances  lib  system

4.6 配置 Unomi 基础参数

创建 setenv 文件设定 JAVA_HOME 并限定 Unomi 堆内存为 256-512MB（JAVA_HOME 使用 4.1 节确认的版本化路径）：

cat > /opt/unomi/bin/setenv <<'EOF'
export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64"
export EXTRA_JAVA_OPTS="-Xms256M -Xmx512M"
EOF

修改 Elasticsearch 连接配置。发行包默认 cluster.name=elasticsearch-cluster、sslEnable=true，与本文部署的 ES 不匹配，必须修改（elasticSearchAddresses 默认值 localhost:9200 已符合，执行同样命令可确保一致）：

sed -i 's/^cluster.name=.*/cluster.name=contextElasticSearch/' /opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg

sed -i 's/^elasticSearchAddresses=.*/elasticSearchAddresses=localhost:9200/' /opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg

sed -i 's/^sslEnable=.*/sslEnable=false/' /opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg

确认修改结果：

grep -E '^(cluster.name|elasticSearchAddresses|sslEnable)=' /opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg

实测回显：

cluster.name=contextElasticSearch
elasticSearchAddresses=localhost:9200
sslEnable=false

将 Karaf 管理账号 karaf 的密码改为 q1w2e3r4（默认密码为 karaf，生产环境务必修改）：

sed -i 's/^karaf = .*/karaf = q1w2e3r4,_g_:admingroup/' /opt/unomi/etc/users.properties

grep '^karaf' /opt/unomi/etc/users.properties

实测回显：

karaf = q1w2e3r4,_g_:admingroup

4.7 配置 systemd 服务

创建 Elasticsearch 服务单元：

cat > /etc/systemd/system/elasticsearch.service <<'EOF'
[Unit]
Description=Elasticsearch
Documentation=https://www.elastic.co
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=elasticsearch
Group=elasticsearch
Environment=ES_HOME=/opt/elasticsearch-9.5.3
Environment=ES_PATH_CONF=/opt/elasticsearch-9.5.3/config
ExecStart=/opt/elasticsearch-9.5.3/bin/elasticsearch
Restart=on-failure
RestartSec=10
LimitNOFILE=65535
LimitNPROC=4096

[Install]
WantedBy=multi-user.target
EOF

创建 Unomi 服务单元（Type=simple 配合 bin/karaf server 前台模式，避免 fork 模式产生孤儿进程）：

cat > /etc/systemd/system/unomi.service <<'EOF'
[Unit]
Description=Apache Unomi Context Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=unomi
Group=unomi
ExecStart=/opt/unomi/bin/karaf server
ExecStop=/opt/unomi/bin/stop
TimeoutStartSec=900
Restart=on-failure
RestartSec=15
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

加载并启动（先 Elasticsearch 后 Unomi，Unomi 启动时依赖 ES 就绪）：

systemctl daemon-reload

systemctl enable --now elasticsearch

systemctl enable --now unomi

确认两个服务状态：

systemctl is-active elasticsearch

systemctl is-active unomi

实测回显均为：

active

4.8 首次初始化（unomi:start）

Unomi 3.0.1 首次启动时 boot feature 只安装不启动，必须执行一次 Karaf 命令 unomi:start 完成初始化（官方手册「快速开始」的第 7 步）。等待 Unomi 完成系统启动（约 2-5 分钟）后执行：

echo "unomi:start" | /opt/unomi/bin/client -u karaf -p q1w2e3r4

该命令幂等，重复执行无副作用。确认初始化结果：

grep "Server successfully started" /opt/unomi/data/log/karaf.log | tail -1

实测回显：

2026-10-12T08:30:41,049 | INFO  | Blueprint Extender: 2 | BundleWatcherImpl                | 191 - org.apache.unomi.lifecycle-watcher - 3.0.1 |  Server successfully started 31 bundles and 1 required services in 2804477 ms

说明：初始化状态持久化在 Karaf 的 felix cache 中，此后通过 systemctl 重启 unomi 服务无需再次执行 unomi:start（实测 systemctl restart unomi 后 REST 接口直接可用）。

4.9 验证部署

确认服务进程状态：

systemctl status unomi --no-pager | head -3

实测回显关键行：

● unomi.service - Apache Unomi Context Server
     Loaded: loaded (/etc/systemd/system/unomi.service; enabled; vendor preset: disabled)
     Active: active (running) since ...

验证 Unomi 堆内存限制（256M-512M，jps 随 java-17-openjdk-devel 安装）：

/usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64/bin/jps -lv | grep karaf.main.Main

实测回显（截取关键部分）：

55801 org.apache.karaf.main.Main -XX:+UnlockDiagnosticVMOptions -Djava.security.manager=allow -Xms256M -Xmx512M --add-reads=java.xml=java.logging ...

验证 Elasticsearch 堆内存限制：

ps -ef | grep elasticsearch | grep -oE '\-Xm[sx]512m'

实测回显：

-Xms512m
-Xmx512m

调用 REST 接口验证（注意：请求体必须携带 sessionId，详见第六节注意事项）：

curl -s -X POST http://127.0.0.1:8181/cxs/context.json -H 'Content-Type: application/json' -d '{"source":{"itemId":"home","itemType":"page","scope":"mysite"},"sessionId":"demo-session-001"}'

实测回显：

{"profileId":"2e7d0eb1-89f5-4b05-986e-3274fac27f36","sessionId":"demo-session-001","processedEvents":0,"trackedConditions":[],"anonymousBrowsing":false,"consents":{}}

验证 HTTPS 集群接口（9443 使用自签证书，需加 -k；使用 karaf 账号做 Basic 认证）：

curl -sk -u karaf:q1w2e3r4 -o /dev/null -w '%{http_code}\n' https://127.0.0.1:9443/cxs/cluster

实测回显：

五、配置说明

路径	用途
/opt/unomi/bin/setenv	JVM 内存等启动参数，本文设定 -Xms256M -Xmx512M
/opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg	ES 连接参数：集群名、地址、SSL、版本窗口等
/opt/unomi/etc/users.properties	Karaf 管理账号（karaf）与监控账号（health）密码
/opt/unomi/etc/custom.system.properties	系统属性总入口，UNOMI_* 环境变量映射与 8181/9443 端口定义
/opt/unomi/data/log/karaf.log	Unomi 运行日志
/opt/elasticsearch-9.5.3/config/elasticsearch.yml	ES 集群与网络配置
/opt/elasticsearch-9.5.3/config/jvm.options.d/heap.options	ES 堆内存，本文设定 512m
/etc/systemd/system/unomi.service、elasticsearch.service	开机自启与进程守护

Unomi 常用端口：8181 为 cxs REST API 的 HTTP 端口，9443 为 HTTPS 端口，8102 为 Karaf 远程控制台 SSH 端口（bin/client 默认连接此端口）。

六、注意事项

启动顺序：Unomi 依赖 Elasticsearch，重启服务器后若 unomi 服务启动失败，先确认 systemctl is-active elasticsearch 为 active，再执行 systemctl restart unomi。
首次启动必须执行一次 unomi:start（见 4.8 节），否则所有 bundle 停留在 Resolved 状态、8181 端口无响应。
Unomi 堆内存已通过 setenv 限定为 256-512MB，调整时同步修改该文件并重启服务，用 jps -lv 验证。JDK 升级后 JAVA_HOME 中的版本号路径会变化，需同步修改 setenv。
Unomi 3.x 对 REST 请求做了强校验：POST /cxs/context.json 必须在请求体中携带 sessionId（或 profileId/personaId），否则返回 {"errorMessage":"internalServerError"}，服务端日志记录 Couldn't find profileId, sessionId or personaId in incoming request!。
9443 端口默认使用自签证书，curl 验证需加 -k 参数；浏览器访问需确认安全提示。
bin/client 连接前确保 Unomi 已完全启动，启动过程中连接会报 Closed 或长时间挂起，可加 timeout 30 包裹并重试；连接必须携带 -u karaf -p q1w2e3r4。
8102 是 Karaf 的 SSH 控制台端口，发行包默认监听 0.0.0.0，生产环境建议在防火墙层面对外屏蔽，或修改 /opt/unomi/etc/org.apache.karaf.shell.cfg 的 sshHost 为 127.0.0.1。
CentOS 8 已停止维护，官方 mirror.centos.org 源已下线：若 dnf 报仓库下载失败，需将 /etc/yum.repos.d/ 中的源切换至公共软件仓库站点提供的 vault 历史仓库模板（本文实测环境已预置可用源）。
若系统启用 firewalld，需放行业务端口：

firewall-cmd --permanent --add-port=8181/tcp

firewall-cmd --permanent --add-port=9443/tcp

firewall-cmd --permanent --add-port=9200/tcp

firewall-cmd --reload

SELinux 处于 Enforcing 模式时可能拦截自定义路径下的进程运行，本文实测环境为 Disabled；如为 Enforcing，建议先以 getenforce 确认模式并按企业安全基线处理。

七、常见问题

**Q1：**执行 /opt/unomi/bin/karaf start 后进入交互式控制台不返回？ bin/karaf 脚本仅支持 server、run、daemon、client、status、stop、console 等子命令，不支持 start。守护方式启动请使用 /opt/unomi/bin/start；systemd 托管请使用 ExecStart=/opt/unomi/bin/karaf server（本文采用方式）。

**Q2：**通过 JAVA_MIN_MEM、JAVA_MAX_MEM 环境变量设置堆内存不生效？ Karaf 4.4.8 的 Linux 启动脚本不再消费这两个变量（仅保留在 Windows 脚本中）。正确做法是在 /opt/unomi/bin/setenv 中设置 export EXTRA_JAVA_OPTS="-Xms256M -Xmx512M"，然后用 jps -lv | grep karaf.main.Main 验证回显中的 -Xms/-Xmx 值。

**Q3：**首次启动后 8181 端口无响应，日志中所有 bundle 处于 Resolved 状态？这是 3.x 的正常首次启动行为，boot feature 只安装不启动。执行 echo "unomi:start" | /opt/unomi/bin/client -u karaf -p q1w2e3r4 完成初始化，日志出现 Server successfully started 31 bundles and 1 required services 即成功。

**Q4：**bin/client 连接时报 Closed 或 Failed to get the session？两种原因：一是 Unomi 尚未完全启动（SSH 端口已监听但会话服务未就绪），等待 2-5 分钟后重试，脚本调用建议加 timeout 30；二是未提供正确凭据，users.properties 修改密码后必须使用 -u karaf -p q1w2e3r4。

**Q5：**POST /cxs/context.json 返回 {"errorMessage":"internalServerError"}？ Unomi 3.x 要求请求体必须携带 sessionId、profileId 或 personaId 之一，例如 {"source":{"itemId":"home","itemType":"page","scope":"mysite"},"sessionId":"demo-session-001"}。补齐后返回 200，并在响应中得到 profileId。

**Q6：**unomi 服务启动失败，日志报 Error creating bundle cache / Permission denied？曾以 root 身份手动启动过 Unomi，data 目录属主被改为 root。执行 chown -R unomi:unomi /opt/unomi 后重新启动服务即可。

**Q7：**Elasticsearch 启动失败，日志报 max virtual memory areas vm.max_map_count [65530] is too low？执行第四节 4.3 的内核参数调整，将 vm.max_map_count 提升至 262144 后重启 elasticsearch 服务。

**Q8：**dnf 安装软件时报仓库地址 404 或无法同步元数据？ CentOS 8 官方源已下线，将 /etc/yum.repos.d/ 下的 repo 文件切换到公共软件仓库站点的 CentOS 8 vault 历史仓库后重新执行 dnf makecache。

八、卸载方式

停止并注销两个服务（逐个执行）：

systemctl stop unomi

systemctl stop elasticsearch

systemctl disable unomi

systemctl disable elasticsearch

删除服务单元文件并重载：

rm /etc/systemd/system/unomi.service /etc/systemd/system/elasticsearch.service

systemctl daemon-reload

删除程序与数据目录（ES 数据位于 /opt/elasticsearch-9.5.3/data，删除前请确认无需保留用户画像数据）：

rm -rf /opt/unomi /opt/elasticsearch-9.5.3

rm -f /opt/unomi-3.0.1-bin.tar.gz /opt/elasticsearch-9.5.3-linux-x86_64.tar.gz

删除系统账号与内核参数配置：

userdel unomi

userdel elasticsearch

rm -f /etc/sysctl.d/99-unomi-elasticsearch.conf

九、参考链接

Apache Unomi 官方手册：https://unomi.apache.org/manual/latest/
Apache Unomi 下载页：https://unomi.apache.org/download.html
Unomi 3.0.1 发行包：https://dlcdn.apache.org/unomi/3.0.1/unomi-3.0.1-bin.tar.gz
Elasticsearch 9.5.3 下载：https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-9.5.3-linux-x86_64.tar.gz
Apache Karaf 文档：https://karaf.apache.org/documentation.html