Apache Unomi 3.0.1 配置参数详解

详解 Apache Unomi 3.0.1 核心配置文件与参数：Elasticsearch 连接、索引分片、HTTP 端口、集群、安全账号与数据维护参数，并给出经实测验证的参数查看、修改方法与生产配置模板。

Apache UnomiApache Unomi2026/10/12

Apache Unomi 3.0.1 配置参数详解

本文系统梳理 Apache Unomi 3.0.1 的配置文件体系与核心参数，覆盖参数查看方式、在线修改方法、参数分类详解与生产配置模板。文中默认值均取自官方发行包原始文件，修改方法与回显均在真实环境实测通过。

一、环境信息

项目说明
操作系统Ubuntu 22.04.5 LTS
Apache Unomi3.0.1（bin 发行包，安装于 /opt/unomi）
Elasticsearch9.5.3（本机部署，堆内存 512MB）
JDKOpenJDK 17（Unomi 堆内存 256-512MB）
Karaf 运行时4.4.8
配置目录/opt/unomi/etc

二、前置条件

  1. 已完成 Unomi 3.0.1 与 Elasticsearch 的部署并能正常访问 8181 端口的 cxs REST 接口。
  2. 拥有 root 权限，可编辑 /opt/unomi/etc 下的配置文件。
  3. 已知晓 Karaf 管理账号（本文示例为 karaf / q1w2e3r4），用于通过命令行查看与修改配置。
  4. 理解配置生效机制：etc 目录下 *.cfg 文件由 Karaf fileinstall 组件监控，保存后自动加载；custom.system.properties 属于系统属性文件，修改后需重启 Unomi 服务。

三、参数查看与修改方式

3.1 配置文件布局

Unomi 的全部配置集中在 /opt/unomi/etc 目录。执行 ls /opt/unomi/etc 实测可见 50 余个文件，与业务直接相关的核心文件如下：

custom.system.properties                              系统属性总入口（端口、UNOMI_* 环境变量映射）
org.apache.unomi.persistence.elasticsearch.cfg        Elasticsearch 连接与索引参数
org.apache.unomi.cluster.cfg                          集群节点参数
org.apache.unomi.services.cfg                         服务层刷新参数
org.apache.unomi.plugins.base.cfg                     基础插件参数
org.apache.unomi.plugins.mail.cfg                     邮件插件参数
org.apache.unomi.plugins.request.cfg                  请求信息插件参数
org.apache.unomi.router.cfg                           导入导出路由参数
org.apache.unomi.geonames.cfg                         地理库参数
org.apache.unomi.healthcheck.cfg                      健康检查参数
org.apache.unomi.thirdparty.cfg                       第三方集成参数
org.apache.unomi.schema.cfg                           JSON Schema 参数
org.apache.unomi.migration.cfg                        版本迁移参数
org.apache.unomi.groovy.actions.cfg                   Groovy 脚本扩展参数
org.apache.unomi.web.cfg                              Web 层参数
users.properties                                      Karaf 账号与角色
org.apache.karaf.shell.cfg                            远程控制台 SSH 参数（sshPort=8102）
org.ops4j.pax.web.cfg、jetty.xml、keystore            HTTP 服务与 HTTPS 证书

3.2 用 config:list 查看参数

通过 Karaf 命令查看指定配置（过滤条件必须带引号，经标准输入传入）：

echo 'config:list "(service.pid=org.apache.unomi.persistence.elasticsearch)"' | /opt/unomi/bin/client -u karaf -p q1w2e3r4

实测回显（节选）：

Pid:            org.apache.unomi.persistence.elasticsearch
   cluster.name = contextElasticSearch
   elasticSearchAddresses = localhost:9200
   minimalElasticsearchVersion = 9.0.3
   sslEnable = false

不带过滤条件执行 config:list 可列出全部已加载配置。

3.3 用 config:edit 在线修改参数

config:edit、config:property-set、config:update 三条命令必须在同一次会话中依次执行（经标准输入一次传入）。实测将 defaultQueryLimit 从 10 改为 20：

printf 'config:edit org.apache.unomi.persistence.elasticsearch\nconfig:property-set defaultQueryLimit 20\nconfig:update\n' | /opt/unomi/bin/client -u karaf -p q1w2e3r4

等待数秒后确认文件已被 fileinstall 回写：

grep '^defaultQueryLimit' /opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg

实测回显：

defaultQueryLimit = 20

实测确认：config:update 保存后 fileinstall 自动重载配置，无需重启 Unomi 服务即可生效。恢复默认值只需按同样方法将参数改回 10。

3.4 custom.system.properties 与环境变量映射

custom.system.properties 是系统属性总入口，其中大量参数通过 环境变量名 注入，格式为「系统属性 = 读取环境变量，缺省时使用默认值」，实测文件节选：

org.osgi.service.http.port=${env:UNOMI_HTTP_PORT:-8181}
org.osgi.service.http.port.secure=${env:UNOMI_SECURE_HTTP_PORT:-9443}
org.apache.unomi.elasticsearch.addresses=${env:UNOMI_ELASTICSEARCH_ADDRESSES:-localhost:9200}
org.apache.unomi.security.root.password=${env:UNOMI_ROOT_PASSWORD:-karaf}

含义：系统属性 org.osgi.service.http.port 优先读取环境变量 UNOMI_HTTP_PORT，未设置时取默认值 8181。因此修改此类参数有两种途径：直接编辑该文件中的默认值（需重启 Unomi 生效），或在启动环境中设置同名环境变量。实测文件中可用环境变量超过 100 个，命名规律为 UNOMI_ 前缀，例如 UNOMI_ELASTICSEARCH_CLUSTERNAME（默认 contextElasticSearch）、UNOMI_ELASTICSEARCH_SSL_ENABLE 等。

3.5 直接编辑 cfg 文件

etc 下的 cfg 文件同样支持直接编辑。需要注意发行包中的取值多为「属性替换」写法，例如发行包原文为 cluster.name=${org.apache.unomi.elasticsearch.cluster.name:-elasticsearch-cluster}，即优先读取同名系统属性（在 custom.system.properties 中定义），读不到时使用默认值 elasticsearch-cluster。直接将整行改写为字面值（如 cluster.name=contextElasticSearch）是官方推荐且实测可行的做法，改写后 fileinstall 自动加载，无需重启。

四、参数总览

配置文件 / 参数组核心内容
org.apache.unomi.persistence.elasticsearch.cfgES 集群名、地址、认证、SSL、索引分片副本、rollover、批量写入、版本窗口
custom.system.propertiesHTTP 端口 8181/9443、cxs 上下文、集群地址、ES 环境变量映射、安全开关、数据维护周期
org.apache.unomi.cluster.cfg节点 ID、对内/对外地址、节点统计频率
users.propertiesKaraf 管理账号 karaf、健康检查账号 health
org.apache.unomi.healthcheck.cfg健康检查开关、检查项、超时
org.apache.unomi.services.cfg / 上述刷新类参数定义、规则、分段等缓存刷新间隔
org.apache.unomi.plugins.base.cfg合并画像数量上限等插件参数
org.apache.karaf.shell.cfg控制台 SSH 端口与监听地址

五、核心参数分类详解

5.1 Elasticsearch 连接参数（org.apache.unomi.persistence.elasticsearch.cfg）

参数默认值说明
cluster.namecontextElasticSearch（发行包原始默认为 elasticsearch-cluster，部署时必须改）ES 集群名，须与 elasticsearch.yml 一致
elasticSearchAddresseslocalhost:9200ES 地址，多节点逗号分隔，每个节点都要带端口
username / password空ES 开启认证时填写
sslEnable发行包原始默认 true，同机无认证部署必须改 false是否以 HTTPS 连接 ES
sslTrustAllCertificatestrue信任所有证书（自签场景保持 true）
minimalElasticsearchVersion9.0.3允许的 ES 最低版本，低于则拒绝连接
maximalElasticsearchVersion10.0.0允许的 ES 最高版本（不含）
clientSocketTimeout-1ES 客户端套接字超时，-1 表示系统默认
minimalClusterStateGREEN集群最低健康状态要求，可放宽为 YELLOW
taskWaitingTimeout3600000update_by_query 等任务等待超时（毫秒）

5.2 索引与查询参数（同文件）

参数默认值说明
index.prefixcontext索引名前缀，生成 context-profile、context-event 等
numberOfShards / numberOfReplicas5 / 0通用索引分片与副本数
rollover.numberOfShards / rollover.numberOfReplicas5 / 0event、session 滚动索引分片与副本数
rollover.indicesevent,session启用滚动的索引类型
rollover.maxSize30gb单个滚动索引最大体积
rollover.maxAge / rollover.maxDocs空按时间 / 文档数滚动，默认不启用
indexMappingTotalFieldsLimit1000单索引 mapping 最大字段数
defaultQueryLimit10默认查询返回条数
aggregateQueryBucketSize5000聚合查询桶上限
maximumIdsQueryCount5000ids 查询最大数量
itemTypeToRefreshPolicy空按类型设置写入刷新策略（如 event=WAIT_UNTIL）
alwaysOverwritetrue保存时覆盖已存在文档
useBatchingForUpdatetrue更新操作走批量接口
bulkProcessor.bulkActions / bulkSize / flushInterval1000 / 5 / 5批量写入条数、体积（MB）、刷新间隔（秒）

5.3 HTTP 服务参数（custom.system.properties）

系统属性默认值说明
org.osgi.service.http.port8181cxs REST API HTTP 端口
org.osgi.service.http.port.secure9443cxs REST API HTTPS 端口
org.osgi.service.http.secure.enabledtrue启用 HTTPS 监听
org.apache.unomi.admin.servlet.context/cxsREST API 上下文路径

5.4 集群参数（org.apache.unomi.cluster.cfg）

参数默认值说明
contextserver.publicAddresshttp://localhost:8181对外公布的地址，集群或多机部署时改为实际域名或 IP
contextserver.internalAddresshttps://localhost:9443节点间通信地址
nodeIdunomi-node-1节点 ID，多节点部署时每台必须唯一
nodeStatisticsUpdateFrequency10000节点统计信息上报间隔（毫秒）

5.5 安全与账号参数

users.properties 实测关键行：

karaf = q1w2e3r4,_g_:admingroup
health = ${org.apache.unomi.healthcheck.password:-health},health
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh,ROLE_UNOMI_ADMIN

说明：karaf 为管理账号（发行包默认密码 karaf，必须修改）；health 为健康检查专用账号，默认密码 health；admingroup 组拥有全部管理角色。其他安全参数（custom.system.properties）：org.apache.unomi.security.root.password（REST 管理接口口令，环境变量 UNOMI_ROOT_PASSWORD，默认 karaf）、org.apache.unomi.scripting.allow/forbid（脚本类白/黑名单，默认放行 org.apache.unomi.api 系列与 java.lang 等基础类）、org.apache.unomi.security.personalization.sanitizeConditions（默认 true，对外隐藏个性化条件明细）、org.apache.unomi.profile.cookie.name（默认 context-profile-id）、org.apache.unomi.security.encryption.enabled（默认 false，开启后对敏感属性加密）。

5.6 数据维护参数（custom.system.properties）

系统属性（UNOMI_ 环境变量）默认值说明
UNOMI_PROFILE_PURGE_INTERVAL1画像清理任务执行间隔（天）
UNOMI_PROFILE_PURGE_INACTIVETIME180画像不活跃判定阈值（天）
UNOMI_PROFILE_PURGE_EXISTTIME-1画像保留时长（天），-1 表示不按时间清理
UNOMI_SESSION_PURGE_EXISTTIME-1会话数据保留时长（天）
UNOMI_EVENT_PURGE_EXISTTIME-1事件数据保留时长（天）
UNOMI_MONTHLY_INDEX_PURGE_EXISTTIME12月度索引保留时长（月）
UNOMI_SEGMENT_REFRESH_INTERVAL1000分段定义刷新间隔（毫秒）
UNOMI_SEGMENT_UPDATE_BATCHSIZE1000分段批量更新画像数量
UNOMI_RULES_REFRESH_INTERVAL1000规则刷新间隔（毫秒）
UNOMI_DEFINITIONS_REFRESH_INTERVAL10000定义类缓存刷新间隔（毫秒）
UNOMI_SCHEDULER_THREAD_POOL_SIZE5调度线程池大小
UNOMI_MAX_PROFILES_IN_ONE_MERGE50单次画像合并数量上限

六、生产配置模板

适用场景：中小规模站点（日采集事件 10 万级），单台 2C4G 服务器，Unomi 与 ES 同机部署。

JVM 内存分配（Unomi 256-512MB、ES 512MB，合计约 1GB 堆，为系统与其他进程预留 2GB 以上物理内存）：

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

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

ES 连接关键项（/opt/unomi/etc/org.apache.unomi.persistence.elasticsearch.cfg 修改后的字面值）：

cluster.name=contextElasticSearch
elasticSearchAddresses=localhost:9200
sslEnable=false
minimalClusterState=YELLOW
defaultQueryLimit=25

磁盘要求：系统盘预留 40GB 以上（ES 索引数据随事件量增长，按 rollover.maxSize=30gb 与保留策略估算）；建议将 /opt/elasticsearch-9.5.3/data 放置于 SSD 分区。

安全基线：修改 users.properties 中 karaf 账号密码；8102 控制台端口不对公网开放；如 ES 开启认证与 HTTPS，同步设置 username、password、sslEnable=true 与证书信任参数。

七、常见问题

**Q1：**修改 cfg 文件后参数不生效？ 分三种情况：一是通过 config:edit 修改时未在同一会话执行 config:update，变更不会落盘；二是修改了 custom.system.properties，该文件属于系统属性，必须重启 unomi 服务；三是 cfg 中保留了属性替换写法而被同名系统属性覆盖，按 3.5 节改为字面值即可。cfg 字面值修改由 fileinstall 自动加载，实测数秒内生效，无需重启。

**Q2：**Unomi 启动日志报 Elasticsearch 版本不满足要求？ 发行包按 minimalElasticsearchVersion=9.0.3、maximalElasticsearchVersion=10.0.0 校验，版本窗口外的 ES（如 7.x 或 10.x）会被拒绝，更换 9.x 版本的 ES 即可。

**Q3：**Unomi 连不上本机 Elasticsearch？ 依次核对三项：cfg 的 cluster.name 是否与 elasticsearch.yml 一致（发行包默认 elasticsearch-cluster 与常见部署不一致）；sslEnable 是否与 ES 实际协议一致（ES 未开 HTTPS 时必须为 false，发行包默认 true，这是最常见的踩坑点）；地址端口是否正确（默认 localhost:9200）。

**Q4：**修改 users.properties 中 karaf 密码后 bin/client 连接失败，报 No more authentication methods available？ JAAS 账号文件修改后即时生效，连接必须使用新密码，例如 -u karaf -p q1w2e3r4；旧凭据会被拒绝。

**Q5：**health 账号有什么用途？ health 是健康检查专用账号（默认密码 health），仅具备 health 角色，供监控探针调用健康检查接口使用，避免在监控系统中暴露 karaf 管理账号；健康检查功能由 org.apache.unomi.healthcheck.cfg 的 healthcheck.enabled 控制，发行包默认关闭。

**Q6：**多节点部署时集群参数要改哪些？ 每台节点的 nodeId 必须唯一（默认 unomi-node-1）；contextserver.publicAddress 与 internalAddress 改为各节点实际可达地址；elasticSearchAddresses 填写全部 ES 节点。

八、参考链接