Apache Fortress 3.0.1 配置参数详解

一、配置体系概览

Fortress 的配置分三层，构建时单向流动，本文全部结论来自 fortress-core 3.0.1 在 Ubuntu 22.04 / OpenJDK 17 / Symas OpenLDAP 2.5.20 上的实测：

流动关系：mvn clean install 时 build.properties + slapd.properties 的值被写进 config/fortress.properties（由 fortress.properties.src 模板插值）。改运行时行为既可以改构建参数后重建，也可以直接编辑 fortress.properties 后重启应用。

二、构建参数（build.properties）

模板 build.properties.example 的关键键值（# 注释行略）：

suffix=dc=example,dc=com
org.hier roots=OU1,OU2,APP1,APP2
rbac.accelerator=false
enable.audit=true
save.disp.tree=false
fortress.admin.user=cn=manager,dc=example,dc=com
fortress.admin.pw=secret
...

三、安装参数（slapd.properties）

模板 slapd.properties.example 关键键值：

platform=symas-openldap
openldap.root=/opt/symas
slapd.conf=/opt/symas/etc/openldap/slapd.conf
root.dn=cn=manager,dc=example,dc=com
root.pw={SSHA}I1sk9R4skBTd5YspcM7jJVOY3VqxKGMs
cfg.root.pw=secret

四、运行时配置 fortress.properties 全解

以下为 mvn clean install 生成的 config/fortress.properties 实测内容整理（值未插值的键保留原样并注明）。

4.1 连接与凭据

host=localhost
port=389
ldap.server.type=openldap
admin.user=cn=manager,dc=example,dc=com
admin.pw=secret

4.2 连接池

min.admin.conn=1
max.admin.conn=10
min.user.conn=1
max.user.conn=10
validate.conn.borrow=${all.validate.conn.borrow}
validate.conn.idle=${all.validate.conn.idle}
max.conn.block=${all.max.conn.block}
max.conn.block.time=${all.max.conn.block.time}
debug.ldap.pool=true
enable.pool.reconnect=true

4.3 审计与 TLS

enable.audit=true
enable.ldap.ssl=${enable.ldap.ssl}
enable.ldap.ssl.debug=${enable.ldap.ssl.debug}
enable.ldap.starttls=false
trust.store=${trust.store}
trust.store.password=${trust.store.password}
log.admin.user=cn=manager,cn=log
log.admin.pw=secret
min.log.conn=1
max.log.conn=3

要点：

• enable.audit 仅 ldap.server.type=openldap 有效，依赖 slapo-accesslog overlay（Symas 包已含），日志库凭据在 cn=log 后缀下（log.admin.*）。
• enable.ldap.ssl 未插值时值为字面 ${enable.ldap.ssl}，等效于未启用；要启用 SSL/STARTTLS 需在 build.properties 设置或直接改此文件并配上 trust.store*。
• tls.enabled.protocols 可覆盖默认协议（注释示例 TLSv1/TLSv1.1/TLSv1.2，生产建议显式 TLSv1.2+）。

4.4 配置域与缓存

config.realm=DEFAULT
config.root=ou=Config,dc=example,dc=com
ehcache.config.file=ehcache.xml
enable.dsd.cache=true
crypto.prop=${crypto.prop}

4.5 实现类切换（REST 与自定义）

#enable.mgr.impl.rest=true
#http.user=${http.user}
#http.pw=${http.pw}
#http.host=${http.host}
#http.port=${http.port}
#http.protocol=${http.protocol}
#adminmgr.implementation=org.apache.directory.fortress.core.rest.AdminMgrOtherImpl

• enable.mgr.impl.rest=true 时 SDK 从直连 LDAP 切换到调 Fortress-REST 服务（需部署 fortress-rest-3.0.1.war），配套 http.* 四项。
• 也可按 mgr 逐个用 .implementation 键替换实现类（默认 LDAP 实现与 REST 实现各一套）。

4.6 其他

五、日志配置（log4j2.xml）

config/log4j2.xml 控制 CLI/SDK 日志输出。实测控制台日志格式为：

2026-10-14 15:27:013 INFO  CommandLineInterpreter:684 - command:auser was successful

排障时可临时把 root level 调到 DEBUG 观察 LDAP 连接与命令解析过程（arg: 逐 token 打印即来自此）。

六、缓存定义（ehcache.xml）

config/ehcache.xml 定义了 Fortress 的运行缓存（角色集合、权限图、DSD 约束等）。调优原则：

• 读多写少的授权校验场景增大 TTL/容量上限；
• 集群多节点写策略后，通过 AdminMgr API 的写路径会自动失效缓存，直改 LDAP 不经过 SDK 则需手动 flush；
• enable.dsd.cache=false 可关闭 DSD 缓存换取强一致。

七、改配置的正确姿势

实测两种路径：

1. 改构建参数：编辑 build.properties / slapd.properties → mvn clean install 重新插值生成 fortress.properties。适合后缀/凭据等结构性变更。
2. 直接改运行时文件：编辑 config/fortress.properties → 重启使用该配置的应用（CLI 是随起随读，无需重启服务）。适合池大小、日志、缓存开关等运维性调整。

注意：fortress.properties 中形如 ${key} 的未插值键不是错误——未启用特性的默认写法，SDK 读取时按空值处理；确要启用时必须替换成真实值。

八、常见问题

8.1 admin.pw 写成 {SSHA} 散列导致连不上

slapd.properties 的 root.pw（散列）与 fortress.properties 的 admin.pw（明文）是两个用途，混用会让 SDK 绑定失败（49 Invalid Credentials）。

8.2 改了 suffix 后 CLI 报命名错误

suffix 变更需要：重建（插值）+ 重新 init-slapd + 重新 load DIT，三步缺一不可。

8.3 enable.audit=true 但没有审计数据

audit 依赖 slapo-accesslog；非 openldap 类型被忽略。确认 ldap.server.type=openldap 且 slapd.conf 含 accesslog 配置。

8.4 池耗尽报错或长时间阻塞

max.admin.conn/max.user.conn 偏小、max.conn.block=true 阻塞 5 秒。并发场景调大池上限或按业务缩短阻塞时间。

8.5 缓存导致权限变更不生效

绕过 SDK 直改 LDAP 不会失效缓存。统一走 AdminMgr API，或调低缓存 TTL。

8.6 启用 REST 后全部命令报连接拒绝

enable.mgr.impl.rest=true 但 fortress-rest 未部署或 http.host/port 配错。先 curl REST 服务健康路径确认可达再启用。

8.7 未插值的 ${...} 键会不会影响运行

不会，按空值处理；只有需要该特性时才必须替换（4.3/4.5）。

8.8 多套环境共用一份配置

用 config.realm 区分：不同 realm 的配置存放在 config.root 节点下不同条目，SDK 按 realm 隔离读取。

九、参考链接