Ubuntu 22.04 安装 Apache Fortress 3.0.1 指南

一、环境信息

本文所有命令与回显均在以下环境实测采集，读者在其他环境操作时输出可能略有差异。

项目	值
操作系统	Ubuntu 22.04.5 LTS（GNU/Linux x86_64）
内核	5.15.0
主机名	node1.fortress.example
IP	172.17.0.8
登录账号	root / q1w2e3r4
Java	OpenJDK 17.0.20.1（openjdk-17-jdk-headless）
Maven	3.6.3（Ubuntu 软件源）
LDAP 后端	Symas OpenLDAP 2.5.20（repo.symas.com）
目标版本	Apache Fortress 3.0.1（fortress-core）
源码目录	/opt/src/fortress-core-3.0.1
DIT 后缀	dc=example,dc=com

Apache Fortress 是 Apache Directory 旗下的 RBAC（基于角色的访问控制）身份与访问管理框架，由三层组成：fortress-core（SDK 与 CLI，基于 LDAP 存储策略）、fortress-realm（Tomcat JAAS 域）、fortress-web/rest（Web 与 REST 门户）。本文安装 fortress-core 3.0.1，配套 Symas OpenLDAP 后端，最终跑通 CLI 管理控制台的完整 RBAC 工作流。

二、前置条件

2.1 安装 JDK 17 与基础工具

DEBIAN_FRONTEND=noninteractive apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y curl wget unzip openjdk-17-jdk-headless

实测输出（节选）：

Setting up openjdk-17-jdk-headless:amd64 (17.0.20.1+1-0ubuntu1~22.04) ...
Setting up curl (7.81.0-1ubuntu1.21) ...

2.2 版本要求：必须使用 JDK 17（重要）

Fortress 官方 README 写的最低要求是 Java 11，但实测 3.0.1 用 JDK 11 无法编译：依赖树中的 jakarta.ws.rs-api 4.0.0 按 Java 17 字节码（class file 61.0）发布，JDK 11 的 javac（目标 55.0）拒绝读取，编译 RestUtils.java 直接报错：

[ERROR] .../fortress/core/rest/RestUtils.java:[496,41] package Response does not exist
[ERROR] -> [Help 1]

原因是 jakarta.jakartaee-api 11.0.0 这一代依赖实际需要 JDK 17。验证依赖字节码版本：

python3 - << 'EOF'
import struct, zipfile
z = zipfile.ZipFile('/root/.m2/repository/jakarta/ws/rs/jakarta.ws.rs-api/4.0.0/jakarta.ws.rs-api-4.0.0.jar')
d = z.read('jakarta/ws/rs/core/Response.class')[:8]
print('class file major:', struct.unpack('>H', d[6:8])[0])
EOF

实测输出：

class file major: 61

结论：构建与运行 Fortress 3.0.1 请直接装 JDK 17，README 的 Java 11 说法已过时。

2.3 安装 Maven

DEBIAN_FRONTEND=noninteractive apt-get install -y maven
mvn -version

实测输出：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Private Build, runtime: /usr/lib/jvm/java-17-openjdk-amd64

Maven 构建需要从 Maven Central 下载约 400MB 依赖。实测国内网络到 repo1.maven.org 只有约 53 KB/s，建议配置阿里云镜像（实测 1.66 MB/s）——新建 /root/.m2/settings.xml：

<settings>
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <mirrorOf>central</mirrorOf>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

三、获取 Fortress 发行文件

3.1 版本与目录

Fortress 发行包挂在 dlcdn.apache.org/directory/fortress/dist/3.0.1/（注意路径是 /directory/fortress/dist/，不是 /fortress/ 顶层）：

文件	说明
fortress-core-3.0.1.jar	核心 SDK（含 CLI 控制台类）
fortress-core-3.0.1-source-release.zip	源码包（本文用它构建，609,120 字节）
fortress-core-3.0.1.jar.sha512	SHA-512 校验
fortress-realm-3.0.1.jar / .war	Tomcat 域
fortress-web-3.0.1.war、fortress-rest-3.0.1.war	Web/REST 门户

3.2 下载与校验

mkdir -p /opt/downloads && cd /opt/downloads
curl -sS -O https://dlcdn.apache.org/directory/fortress/dist/3.0.1/fortress-core-3.0.1.jar \
     -O https://dlcdn.apache.org/directory/fortress/dist/3.0.1/fortress-core-3.0.1.jar.sha512 \
     -O https://dlcdn.apache.org/directory/fortress/dist/3.0.1/fortress-core-3.0.1-source-release.zip
ls -l

实测输出：

-rw-r--r-- 1 root root 607871 Oct 14 15:02 fortress-core-3.0.1.jar
-rw-r--r-- 1 root root    139 Oct 14 15:02 fortress-core-3.0.1.jar.sha512
-rw-r--r-- 1 root root 609120 Oct 14 15:04 fortress-core-3.0.1-source-release.zip

校验（官方 .sha512 是大写分组格式，需去空格转小写比对）：

cat fortress-core-3.0.1.jar.sha512

实测输出：

./fortress-core-3.0.1.jar: 31DFCA52 75A2BCE5 77F1A85E B4E8F5DB
                           F8E92226 CDBBE9A2 C1A82B28 055858FA
                           CFE97F79 E7767822 E377AC7B 6D089A5E
                           D49097C9 5F8A1D8E 6B369793 1F95A870

grep -oE '[0-9A-F]{8}' fortress-core-3.0.1.jar.sha512 | tr -d ' \n' | tr 'A-Z' 'a-z' > expected.sha
sha512sum fortress-core-3.0.1.jar | awk '{print $1}' > calc.sha
[ "$(cat calc.sha)" = "$(cat expected.sha)" ] && echo CHECKSUM-OK || echo CHECKSUM-FAIL

实测输出：

CHECKSUM-OK

3.3 解压源码包

mkdir -p /opt/src && cd /opt/src
unzip -q /opt/downloads/fortress-core-3.0.1-source-release.zip
ls fortress-core-3.0.1 | head -20

实测输出：

NOTICE.txt  README.md  build-config.xml  build.properties.example  config/
fortress-schema/  ldap/  pom.xml  slapd.properties.example  src/

关键文件：build.properties.example / slapd.properties.example（构建参数模板，Maven 构建时会插值生成运行时配置）、ldap/（OpenLDAP schema 与 LDIF）、README-QUICKSTART-SLAPD.md（官方 OpenLDAP 快速开始）。

四、构建 fortress-core

cd /opt/src/fortress-core-3.0.1
cp build.properties.example build.properties
cp slapd.properties.example slapd.properties
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export LANG=C.UTF-8
mvn clean install

实测输出（节选，依赖已缓存时）：

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] Total time:  38.518 s

首次构建从镜像下载依赖（实测阿里云镜像约 1.6 MB/s，全程约 3 分钟）。构建产物 target/fortress-core-3.0.1.jar，同时 build.properties 的值被插值写入 config/fortress.properties（运行时配置，详见配置篇）。

注意 build.properties.example 里的默认值即 Quickstart 约定：suffix=dc=example,dc=com、root DN cn=manager、口令 secret。改这些值后重新构建即可定制。

五、安装 Symas OpenLDAP 后端

5.1 为什么不用 Ubuntu 自带 slapd

Fortress 需要 slapo-rbac RBAC 加速 overlay 与 schema 加载脚本，官方 Quickstart 指定使用 Symas 打包的 OpenLDAP 2.5（/opt/symas 路径，自带 RBAC overlay）。按 Symas 仓库说明添加源：

wget -q https://repo.symas.com/repo/gpg/RPM-GPG-KEY-symas-com-signing-key -O /usr/share/keyrings/symas-key.asc
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/symas-key.asc] https://repo.symas.com/repo/deb/main/release25 jammy main" > /etc/apt/sources.list.d/soldap-release25.list
apt-get update

实测输出（节选）：

Hit:1 https://repo.symas.com/repo/deb/main/release25 jammy InRelease
Get:5 http://archive.ubuntu.com/ubuntu jammy-updates InRelease [128 kB]
Reading package lists... Done

5.2 安装软件包

DEBIAN_FRONTEND=noninteractive apt-get install -y symas-openldap-clients symas-openldap-server
dpkg -l | grep -oE "symas-openldap-[a-z]+\s+[0-9.]+-1jammy1"

实测输出：

symas-openldap-clients                2.5.20-1jammy1
symas-openldap-lib                    2.5.20-1jammy1

5.3 初始化 schema 与配置

README-QUICKSTART-SLAPD 的标准做法是 mvn test -Pinit-slapd（生成 /opt/symas/etc/openldap/slapd.conf、加载 fortress-schema）。实测该目标在 root 下运行正常：

cd /opt/src/fortress-core-3.0.1
mvn test -Pinit-slapd

实测输出（节选）：

[INFO] --- maven-antrun-plugin:3.1.0:run (default) @ fortress-core ---
[INFO] Executing tasks
[INFO]      [echo] in slapd install
[INFO] Executed tasks
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

注意：ant 的 apt 安装步骤在某些环境会静默不生效（本次实测 /opt/symas/lib/slapd 未生成），此时手动补装一次（5.2）再重跑 init-slapd 即可；slapd.conf 与 schema 文件由 init-slapd 正确生成。可随时用 ls /opt/symas/etc/openldap/slapd.conf 核对。

六、启动 slapd 并加载 Fortress DIT

6.1 启动（两种方式）

方式一：Maven profile 启动（Quickstart 默认）：

mvn test -Pstart-slapd
ps aux | grep "[s]lapd" | head -1

实测输出：

root      5733  0.4  2.4 262840 24460 pts/0 Sl 15:10 0:00 /opt/symas/lib/slapd -h ldap://localhost:389 -f /opt/symas/etc/openldap/slapd.conf

方式二（推荐生产）：systemd 托管。/etc/systemd/system/symas-slapd.service：

[Unit]
Description=Symas OpenLDAP Server (Apache Fortress backend)
After=network.target

[Service]
Type=forking
ExecStart=/opt/symas/lib/slapd -h ldap://localhost:389 -f /opt/symas/etc/openldap/slapd.conf
PIDFile=/var/symas/run/slapd.pid
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target

实测验证：

kill $(pgrep -x slapd); sleep 2
systemctl daemon-reload && systemctl enable --now symas-slapd
systemctl restart symas-slapd && systemctl is-active symas-slapd

实测输出：

Synchronizing state of symas-slapd.service with SysV service script with /lib/systemd/systemd-sysv-install.
active
active

两个坑：其一，PIDFile 必须写 /var/symas/run/slapd.pid（slapd.conf 里的 pidfile 指令路径），写成 /opt/symas/var/ 会导致 systemd 等不到 pid 报 timeout；其二，先杀掉 Maven 启动的旧 slapd 再 enable，否则端口 389 被占、systemd 反复重启失败（实测 restart counter 5）。

6.2 加载 RBAC 目录数据

mvn install -Dload.file=./ldap/setup/refreshLDAPData.xml

实测输出：

[INFO] BUILD SUCCESS
[INFO] Total time:  7.413 s

6.3 验证 DIT

/opt/symas/bin/ldapsearch -x -H ldap://localhost:389 \
  -D "cn=manager,dc=example,dc=com" -w secret \
  -b "dc=example,dc=com" "(objectclass=organizationalunit)" dn

实测输出：

dn: ou=Config,dc=example,dc=com

dn: ou=People,dc=example,dc=com

dn: ou=Policies,dc=example,dc=com

dn: ou=Groups,dc=example,dc=com

DC 后缀与 fortress.properties（构建时生成）一致：host=localhost、port=389、admin.user=cn=manager,dc=example,dc=com、admin.pw=secret。

七、运行 CLI 管理控制台

7.1 Maven 方式启动

cd /opt/src/fortress-core-3.0.1
mvn -Pcli test

实测输出（启动横幅）：

2026-10-14 15:27:013 INFO  CommandLineInterpreter:184 - CLI function groups include admin, review, system, dadmin, group
2026-10-14 15:27:013 INFO  CommandLineInterpreter:186 - Enter one from above or 'q' to quit

7.2 独立 java 方式启动（免 Maven）

生成 classpath 后直接调主类，便于脚本化：

mvn -q dependency:build-classpath -Dmdep.outputFile=/work/cp.txt
java -cp "target/classes:config:$(cat /work/cp.txt)" \
  org.apache.directory.fortress.core.cli.CommandLineInterpreter

实测输出（启动日志，节选）：

static init: loading from file:...
load config from bootstrap:...
LDAP POOL: registerCodecControls()
LDAP POOL: startup()

两种方式等价，都是交互式控制台：一级输入命令组（admin / review / system / dadmin / group）+ 命令与参数，完整命令清单与实测工作流见《Apache Fortress 3.0.1 常用 CLI 命令与工具详解》。

八、常见问题排障

8.1 编译报 package Response does not exist

JDK 11 编译 Java 17 字节码依赖所致，装 openjdk-17-jdk-headless 并设 JAVA_HOME 后重跑（2.2）。

8.2 Maven 下载依赖极慢或失败

配置阿里云镜像（2.3）；注意个别大版本 POM 在镜像站偶发 404（实测 org.apache.directory.project:35 在 TUNA 缺失），换源重试即可。

8.3 init-slapd 显示 BUILD SUCCESS 但 /opt/symas/lib/slapd 不存在

ant 的 apt 安装步骤未生效，手动 apt-get install symas-openldap-clients symas-openldap-server 后重跑 init-slapd（5.3）。

8.4 systemd 启动 symas-slapd 报 timeout

PIDFile 路径写错了，用 /var/symas/run/slapd.pid（6.1）。

8.5 systemd 反复重启失败 restart counter

旧 slapd 进程占着 389 端口（Maven -Pstart-slapd 启动过），pkill -x slapd 后 systemctl reset-failed 再 start（6.1）。

8.6 ldapsearch 返回 34 Invalid DN

确认 -b 与 -D 的后缀是 dc=example,dc=com（与 build.properties 的 suffix 一致），管理口令是明文 secret（slapd.properties 的 root.pw 是 SSHA 散列，供 slapd.conf 用，运行时配置用明文）。

8.7 CLI 报 caught SecurityException rc=8018

用户/角色的 ou 参数指向不存在的组织单元。先 dadmin auou -n <OU> / dadmin apou -n <OU> 创建，再执行 auser/aobj。

8.8 CLI 报 caught SecurityException rc=5005 null entity

命令参数映射错位（如 asgnrole 误用 -R 传角色名，正确是 -n）。详见 CLI 篇选项对照表。

8.9 加载 refreshLDAPData 报 schema 相关错误

init-slapd 未成功或 slapd.conf 未包含 fortress schema；重跑 init-slapd 并核对 /opt/symas/etc/openldap/slapd.conf 的 include 行。

8.10 端口冲突 Address already in use

389 被其他 slapd/服务占用，ss -tlnp | grep 389 定位进程后处理；同一台机多实例时改 build.properties 的 fortress.port 并重建。

九、参考链接

资源	地址
Fortress 官网	https://directory.apache.org/fortress/
3.0.1 发行目录	https://dlcdn.apache.org/directory/fortress/dist/3.0.1/
OpenLDAP Quickstart	源码包内 README-QUICKSTART-SLAPD.md
Symas OpenLDAP 2.5 仓库	https://repo.symas.com/soldap2.5/ubuntu22/
Fortress CLI 手册	源码包内 README.md SECTION 11