Ubuntu 22.04 安装 Apache Syncope 4.1.3 指南
以 standalone 发行版在 Ubuntu 22.04 部署 Apache Syncope 4.1.3 的完整指南，涵盖 JDK 21 安装、发行包下载校验、部署启动验证、JVM 内存配置、管理员密码修改及卸载清理，全程实测。
Ubuntu 22.04 安装 Apache Syncope 4.1.3 指南
一、环境信息
| 项目 | 实测值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（x86_64） |
| 内核 | 6.8.0-138-generic |
| 组件版本 | Apache Syncope 4.1.3（2026-09-11 发布） |
| 部署形态 | standalone 发行版（内嵌 Apache Tomcat 10.1.57） |
| Java 环境 | OpenJDK 21.0.12.1（Ubuntu 官方仓库） |
| 内嵌数据库 | Zonky 嵌入式 PostgreSQL 18.6（standalone 自带，无需单独安装） |
| 服务器规格 | 4 vCPU / 32 GB 内存 / 40 GB 可用磁盘（发行包约 1.1 GB，解压后约 1.3 GB） |
| 安装目录 | /opt/syncope-standalone-4.1.3 |
| 服务端口 | 9080（HTTP）、9443（HTTPS）、9805（Tomcat SHUTDOWN） |
二、前置条件
2.1 软件要求
Apache Syncope 4.1.3 官方要求使用 JDK 21（官方 Getting Started 原文："Apache Syncope 4.1.3 requires the latest JDK 21 that is available"）。实测确认：Syncope 4.1.3 自身类文件为 Java 21 字节码（major version 65），在 Java 17 下 Tomcat 能启动但 Spring Boot 应用静默不启动（详见常见问题 Q1），务必使用 JDK 21 或更高版本。
2.2 安装 JDK 21 与基础工具
安装 OpenJDK 21：
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-21-jdk
安装解压与下载工具：
DEBIAN_FRONTEND=noninteractive apt-get install -y unzip curl
确认 Java 版本（实测回显）：
java -version
openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment (build 21.0.12.1+1-1-22.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.12.1+1-1-22.04.4-Ubuntu, mixed mode, sharing)
若系统中存在多个 JDK 版本，将默认 java 切换为 21（路径按实际安装版本调整）：
update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java
update-alternatives --set javac /usr/lib/jvm/java-21-openjdk-amd64/bin/javac
2.3 端口要求
确认以下端口未被占用：9080（HTTP 服务）、9443（HTTPS 服务）、9805（Tomcat 停止指令端口）、5432（内嵌 PostgreSQL 本机监听）。
ss -ltnp | grep -E ':9080|:9443|:9805|:5432'
无输出即表示端口可用。
三、版本选型说明
到官方下载页（https://downloads.apache.org/syncope/）确认当前稳定版本。实测时官方提供的版本为 4.1.3（最新稳定线）与 4.0.8（上一稳定线），本文采用 4.1.3。
官方下载页提供的发行物只有三类：
| 发行物 | 说明 | 适用场景 |
|---|---|---|
| syncope-standalone-4.1.3-distribution.zip | 约 1.0 GB，解压即为可运行的完整环境（内嵌 Tomcat + 嵌入式 PostgreSQL + Core/Console/Enduser/WA 四个应用） | 快速部署、体验与评估，本文采用 |
| syncope-4.1.3-source-release.zip | 源码包 | 需要自行构建或定制开发 |
| syncope-core-persistence-jpa-upgrader-4.1.3.jar | 数据库结构升级工具（仅从旧版本升级时使用） | 存量数据升级 |
说明：standalone 发行版自带嵌入式 PostgreSQL，数据在重启后会重新初始化（见 5.4 节），适合初次部署与功能验证；生产环境应将 Syncope Core 的持久化配置改为外部 PostgreSQL/MySQL 等数据库后另行部署。
四、部署步骤
4.1 创建目录并下载发行包
创建安装目录：
mkdir -p /opt/syncope-dl
cd /opt/syncope-dl
下载 standalone 发行包（约 1.0 GB，耗时取决于带宽）：
curl -sSL -o syncope-standalone-4.1.3-distribution.zip https://downloads.apache.org/syncope/4.1.3/syncope-standalone-4.1.3-distribution.zip
下载官方 SHA512 校验文件并核对（实测回显）：
curl -sSL -o syncope-standalone-4.1.3-distribution.zip.sha512 https://downloads.apache.org/syncope/4.1.3/syncope-standalone-4.1.3-distribution.zip.sha512
sha512sum syncope-standalone-4.1.3-distribution.zip
<下载页 .sha512 文件中记录的哈希值> syncope-standalone-4.1.3-distribution.zip
将上述输出第一列哈希值与 .sha512 文件内容比对一致后继续。查看文件大小（实测）：
ls -lh syncope-standalone-4.1.3-distribution.zip
-rw-r--r-- 1 root root 1.1G Oct 12 00:50 syncope-standalone-4.1.3-distribution.zip
4.2 解压发行包
unzip -q syncope-standalone-4.1.3-distribution.zip -d /opt/
解压完成后查看目录结构（实测）：
ls /opt/syncope-standalone-4.1.3/
LICENSE NOTICE README apache-tomcat-10.1.57
standalone 发行版解压后就是一个完整的 Apache Tomcat 10.1.57 目录，其中已部署好全部 Syncope 应用。查看 webapps 目录（实测）：
ls /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/webapps/
ROOT host-manager manager syncope syncope-console syncope-enduser syncope-fit-build-tools syncope-wa
各目录含义：
| 目录 | 含义 |
|---|---|
| syncope | Syncope Core（IdM 核心引擎 + REST API） |
| syncope-console | 管理控制台（管理员 Web 界面） |
| syncope-enduser | 最终用户自助界面 |
| syncope-wa | Web Access（认证中心，基于 CAS） |
| syncope-fit-build-tools | 内置测试辅助工具 |
| ROOT / host-manager / manager | Tomcat 默认应用 |
4.3 首次启动
为启动脚本添加执行权限：
cd /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
chmod 755 ./bin/*.sh
启动服务：
./bin/startup.sh
Tomcat started.
查看启动日志（首次启动需要初始化嵌入式 PostgreSQL 并导入示例数据，Tomcat 层约 30 秒完成部署）：
tail -20 logs/catalina.out
关键回显（实测）：
12-Oct-2026 00:53:16.886 INFO [main] org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["http-nio-9080"]
12-Oct-2026 00:53:45.250 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["https-jsse-nio-9443"]
12-Oct-2026 00:53:45.266 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-9080"]
12-Oct-2026 00:53:45.271 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [28383] milliseconds
4.4 验证服务状态
Syncope Core 的 Spring 上下文在 Tomcat 部署完成后还需约 40-90 秒初始化（首次启动要创建内嵌数据库并导入示例数据）。启动完成后，Core 业务日志写入 logs/core.log，可观察其就绪标志：
tail -f logs/core.log
INFO org.apache.syncope.core.starter.SyncopeCoreApplication - Started SyncopeCoreApplication in 36.95 seconds (process running for 96.241)
出现 Started SyncopeCoreApplication 后即可验证 REST 服务。使用默认管理员账号 admin/password 调用 self 接口并提取用户名（实测回显）：
curl -s -u admin:password http://localhost:9080/syncope/rest/users/self | grep -o '"username":"[^"]*"'
"username":"admin"
返回 username":"admin" 即表示 Core 服务正常。再验证管理控制台可达性（实测返回 302 跳转到登录页）：
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9080/syncope-console/
302
浏览器访问 http://<服务器IP>:9080/syncope-console/，使用 admin/password 登录管理控制台。
4.5 停止与重启
停止服务：
cd /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
./bin/shutdown.sh
Tomcat stopped.
再次启动重复执行 4.3 节的 ./bin/startup.sh 即可。注意：重启后内嵌数据库数据会重置（见 5.4 节）。
五、配置说明
5.1 端口配置
端口定义在 conf/server.xml 中，实测关键配置（完整行）：
<Server port="9805" shutdown="SHUTDOWN">
HTTP Connector 监听 9080，HTTPS Connector 监听 9443 并引用 conf/keystore.jks（certificateKeystorePassword=password），另有 AJP 连接器定义于 9889。
如需修改端口，编辑 conf/server.xml 后重启服务。9443 的 HTTPS 使用 conf/keystore.jks 密钥库，默认库密码为 password（仅内置自签名证书，生产环境应更换为自己的证书）。
5.2 JVM 内存参数
官方默认在 bin/setenv.sh 中以 JAVA_OPTS 设置了较大堆内存（实测默认值 -Xms2048m -Xmx2048m），该文件是修改 JVM 参数的唯一推荐位置。将堆限制调整到 512 MB 内（实测可正常运行）：
sed -i 's/-Xms2048m -Xmx2048m -XX:NewSize=256m -XX:MaxNewSize=256m/-Xms256m -Xmx512m/' bin/setenv.sh
grep -o '\-Xms[0-9]*m -Xmx[0-9]*m' bin/setenv.sh
-Xms256m -Xmx512m
重启后用 jps -v 提取堆参数验证生效（实测回显）：
jps -v | grep Bootstrap | grep -o '\-Xms[0-9]*m -Xmx[0-9]*m'
-Xms256m -Xmx512m
进一步确认运行时堆上限（实测回显，garbage-first heap total 524288K 即 512 MB）：
jcmd $(jps | awk '/Bootstrap/{print $1}') GC.heap_info
9043:
garbage-first heap total 524288K, used 481288K [0x00000000e0000000, 0x0000000100000000)
region size 1024K, 12 young (12288K), 4 survivors (4096K)
Metaspace used 417671K, committed 420160K, reserved 1441792K
说明：Core/Console/Enduser/WA 四个应用运行在同一个 JVM 中，512 MB 堆可以运行但偏紧，服务器内存充裕时可适当调大 Xmx。
5.3 修改管理员密码
默认管理员账号为 admin，默认密码为 password（官方默认值，启动日志中会有 "The default adminPassword property is being used" 的告警）。admin 是配置型账号而非用户实体，修改密码需修改 core.properties 后重启。
第一步，计算新密码 q1w2e3r4 的 SHA512 哈希（十六进制）。可用 JDK 直接计算：将下面内容保存为 /tmp/Sha512.java：
import java.security.MessageDigest;
import java.util.HexFormat;
public class Sha512 {
public static void main(String[] a) throws Exception {
System.out.println(HexFormat.of().formatHex(
MessageDigest.getInstance("SHA-512").digest(a[0].getBytes())));
}
}
执行：
java /tmp/Sha512.java q1w2e3r4
e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9
第二步，修改 core.properties（将哈希值写入 security.adminPassword，并将算法改为 SHA512）：
CFG=/opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/webapps/syncope/WEB-INF/classes/core.properties
sed -i 's/^security.adminPassword=.*/security.adminPassword=e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9/' $CFG
sed -i 's/^security.adminPasswordAlgorithm=.*/security.adminPasswordAlgorithm=SHA512/' $CFG
grep '^security.admin' $CFG
security.adminUser=admin
security.adminPassword=e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9
security.adminPasswordAlgorithm=SHA512
第三步，重启服务后验证新旧密码（实测：新密码 200、旧密码 401）：
curl -s -u admin:q1w2e3r4 http://localhost:9080/syncope/rest/users/self -w 'new=%{http_code}\n' -o /dev/null
curl -s -u admin:password http://localhost:9080/syncope/rest/users/self -w 'old=%{http_code}\n' -o /dev/null
new=200
old=401
5.4 内嵌数据库与数据持久化说明
standalone 发行版使用 Zonky 嵌入式 PostgreSQL（实测 core.log 回显）：
INFO org.apache.syncope.fit.persistence.embedded.EmbeddedPostgreSQLContext - Creating embedded databases: [syncope, syncopetwo, syncopetest]
INFO openjpa.jdbc.JDBC - Connected to PostgreSQL version 18.6 using JDBC driver PostgreSQL JDBC Driver version 42.7.13.
关键特性（实测确认）：
- PostgreSQL 进程数据目录位于
$CATALINA_HOME/temp/epg<随机数>，每次重启重新初始化，已创建的数据在重启后丢失，并重新导入示例数据（内置 rossini、bellini 等 5 个示例用户）。 - 旧的 temp/epg* 目录不会被自动清理，长期运行需定期手动清理。
- 若需数据持久化，编辑 webapps/syncope/WEB-INF/classes/core.properties，将 persistence.domain[0].* 系列参数指向外部 PostgreSQL 实例（默认模板即为 jdbc:postgresql://localhost:5432/syncope，账号 syncope/syncope），并从 webapps/syncope/WEB-INF/classes 中删除或移开 core-embedded.properties 以停用 embedded 配置，随后重启。
六、注意事项
- 必须使用 JDK 21 及以上版本，Java 17 会导致应用静默不启动且无报错日志（见 Q1）。
- 首次启动约需 2 分钟进入可用状态，验证前先确认 logs/core.log 出现 Started SyncopeCoreApplication。
- 日志文件较大且多（core.log、core-persistence.log、core-rest.log、core-connid.log、console.log 等，均在 logs/ 目录），log4j2 配置了 immediateFlush=false，日志有少量缓冲延迟。
- conf/keystore.jks 内置自签名证书已于 2024-11-22 过期，启动日志会出现 WARNING，生产使用必须替换。
- 管理脚本 bin/.sh 需要可执行权限，解压后首次启动前执行 chmod 755 ./bin/.sh。
- 若将安装目录迁移或重命名，需同步检查 setenv.sh 与 server.xml 中的绝对路径。
七、常见问题
Q1：启动后访问 http://localhost:9080/syncope/rest/ 一直返回 404，console 也 404，日志无任何报错？
Java 版本低于 21 所致。实测 Java 17 环境下：Tomcat 正常启动、各 webapp 部署完成、日志中还能看到 "1 Spring WebApplicationInitializers detected on classpath"，但 Spring Boot 从未启动（logs/ 下不会生成 core.log）。原因是 Syncope 4.1.3 自身类是 Java 21 字节码，Spring 上下文初始化时抛出的 UnsupportedClassVersionError 被静默吞掉。解法：安装 OpenJDK 21，确认 java -version 输出 21.x，然后重启服务。CentOS 8 仓库无 java-21 包，可解压安装 OpenJDK 21.0.2 压缩包并在 bin/setenv.sh 首行加入 JAVA_HOME 指向 JDK 21 目录。
Q2：通过 REST 创建用户返回 500 或 400，响应体为空？
依次排查三点：其一，请求体中 UserCR 对象必须携带 _class 字段（值为 org.apache.syncope.common.lib.request.UserCR），缺失会导致 500；其二，默认用户模板必填属性 fullname、surname、userId，缺失返回 400 RequiredValuesMissing；其三，默认密码策略要求密码不少于 10 个字符。真实错误详情可在 logs/core-rest.log 中查看（错误响应体受日志组件影响可能为空）。
Q3：GET /users/admin 返回 404 NotFound（Null key）？
admin 是配置型管理员账号，不是用户实体，不存储在用户表中，属正常现象。修改 admin 密码按 5.3 节操作，管理操作用 admin 账号调用 REST 或登录 console 完成。
Q4：启动日志提示 trusted certificate 证书过期警告（NotAfter: Fri Nov 22）？
内置 keystore.jks 中的自签名证书已过期的提示，不影响功能启动。生产环境应使用正式证书替换 conf/keystore.jks（keytool 导入），或关闭 9443 的 HTTPS Connector 只保留 9080。
Q5：重启后创建的用户、组等数据全部消失？
standalone 的内嵌 PostgreSQL 每次启动都会重新初始化（见 5.4 节），属预期行为。演示数据可反复使用，重要数据需外接数据库。
八、卸载方式
停止服务：
cd /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
./bin/shutdown.sh
确认进程已退出：
jps | grep Bootstrap
无输出即已停止。删除安装目录与下载缓存：
rm -rf /opt/syncope-standalone-4.1.3
rm -rf /opt/syncope-dl
如不再需要 Java 环境，可一并卸载：
apt-get remove -y openjdk-21-jdk unzip
九、参考链接
- Apache Syncope 官网：https://syncope.apache.org/
- Getting Started 指南（版本要求与部署方式）：https://syncope.apache.org/docs/getting-started.html
- 官方下载页：https://downloads.apache.org/syncope/
- Reference Guide（配置与 REST API）：https://syncope.apache.org/docs/reference-guide.html
- Apache Tomcat 10.1 文档：https://tomcat.apache.org/tomcat-10.1-doc/