CentOS 8 安装 Apache Syncope 4.1.3 指南

一、环境信息

二、前置条件

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 字节码，在 Java 17 下 Tomcat 能启动但 Spring Boot 应用静默不启动（详见常见问题 Q1）。

CentOS 8 的软件仓库（AppStream/BaseOS）实测最高只提供 java-17-openjdk，没有 java-21-openjdk 包，因此 JDK 21 需要手动解压安装（见 2.2 节）。

2.2 安装 JDK 21（手动解压方式）

先安装基础工具（实测命令）：

dnf makecache
dnf install -y unzip wget curl

下载 OpenJDK 21.0.2 压缩包（华为云下载站，195 MB，实测可直连下载）：

curl -sSL -o /tmp/jdk21.tar.gz https://mirrors.huaweicloud.com/openjdk/21.0.2/openjdk-21.0.2_linux-x64_bin.tar.gz

核对校验值（实测输出）：

sha256sum /tmp/jdk21.tar.gz

a2def047a73941e01a73739f92755f86b895811afb1f91243db214cff5bdac3f  /tmp/jdk21.tar.gz

解压到 /usr/lib/jvm：

mkdir -p /usr/lib/jvm
tar -xzf /tmp/jdk21.tar.gz -C /usr/lib/jvm/

验证版本（实测回显）：

/usr/lib/jvm/jdk-21.0.2/bin/java -version

openjdk version "21.0.2" 2024-01-16
OpenJDK Runtime Environment (build 21.0.2+13-58)
OpenJDK 64-Bit Server VM (build 21.0.2+13-58, mixed mode, sharing)

说明：手动解压安装的 JDK 不会写入系统 PATH，Syncope 的启动脚本通过 bin/setenv.sh 中的 JAVA_HOME 变量定位它（见 5.1 节，该配置为必需项）。

2.3 端口要求

确认以下端口未被占用：9080（HTTP 服务）、9443（HTTPS 服务）、9805（Tomcat 停止指令端口）、5432（内嵌 PostgreSQL 本机监听）。

ss -ltnp | grep -E ':9080|:9443|:9805|:5432'

无输出即表示端口可用。若启用了 firewalld，需放行对应端口：

firewall-cmd --permanent --add-port=9080/tcp
firewall-cmd --reload

三、版本选型说明

到官方下载页（https://downloads.apache.org/syncope/）确认当前稳定版本。实测时官方提供的版本为 4.1.3（最新稳定线）与 4.0.8（上一稳定线），本文采用 4.1.3。

官方下载页提供的发行物只有三类：

说明：standalone 发行版自带嵌入式 PostgreSQL，数据在重启后会重新初始化（见 5.5 节），适合初次部署与功能验证；生产环境应将 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 文件内容比对一致后继续。查看文件大小（实测）：

ls -lh syncope-standalone-4.1.3-distribution.zip

-rw-r--r-- 1 root root 1.1G Oct 12 00:49 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

各目录含义：

4.3 配置 JAVA_HOME 并首次启动

先在 bin/setenv.sh 首行写入 JAVA_HOME 指向 JDK 21（手动解压安装的 JDK 必须配置，否则启动脚本会使用系统默认 Java 导致服务不工作）：

sed -i '1i JAVA_HOME=/usr/lib/jvm/jdk-21.0.2' /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/bin/setenv.sh
head -2 /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/bin/setenv.sh | tail -1

JAVA_HOME=/usr/lib/jvm/jdk-21.0.2

为启动脚本添加执行权限并启动：

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:58:10.482 INFO [main] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/webapps/syncope-enduser]

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 登录管理控制台。

确认运行时 JVM 版本（实测回显）：

/opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/bin/version.sh | grep -E 'Server version|JVM Version'

Server version: Apache Tomcat/10.1.57
JVM Version:    21.0.2

4.5 停止与重启

停止服务：

cd /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
./bin/shutdown.sh

Tomcat stopped.

再次启动重复执行 ./bin/startup.sh 即可（JAVA_HOME 已写入 setenv.sh，无需重复设置）。注意：重启后内嵌数据库数据会重置（见 5.5 节）。

五、配置说明

5.1 JAVA_HOME 配置

bin/setenv.sh 是 Syncope standalone 注入环境与 JVM 参数的统一入口。手动解压安装 JDK 的环境下，JAVA_HOME 必须写入该文件首行（实测踩坑：曾只在启动命令前临时 export JAVA_HOME，重启时忘记携带导致回退系统 Java 17，服务静默不启动）。写入后每次启动自动生效：

head -2 /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57/bin/setenv.sh | tail -1

JAVA_HOME=/usr/lib/jvm/jdk-21.0.2

5.2 端口配置

端口定义在 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.3 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 提取堆参数验证生效（实测回显）：

/usr/lib/jvm/jdk-21.0.2/bin/jps -v | grep Bootstrap | grep -o '\-Xms[0-9]*m -Xmx[0-9]*m'

-Xms256m -Xmx512m

说明：Core/Console/Enduser/WA 四个应用运行在同一个 JVM 中，512 MB 堆可以运行但偏紧，服务器内存充裕时可适当调大 Xmx。jps 与 jcmd 位于 JDK 的 bin 目录下，手动解压安装时直接用绝对路径调用（如 /usr/lib/jvm/jdk-21.0.2/bin/jps）。

5.4 修改管理员密码

默认管理员账号为 admin，默认密码为 password（官方默认值，启动日志中会有 "The default adminPassword property is being used" 的告警）。admin 是配置型账号而非用户实体，修改密码需修改 core.properties 后重启。

第一步，计算新密码 q1w2e3r4 的 SHA512 哈希（十六进制）。将下面内容保存为 /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())));
  }
}

执行：

/usr/lib/jvm/jdk-21.0.2/bin/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.5 内嵌数据库与数据持久化说明

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.

关键特性（实测确认）：

1. PostgreSQL 进程数据目录位于 $CATALINA_HOME/temp/epg<随机数>，每次重启重新初始化，已创建的数据在重启后丢失，并重新导入示例数据（内置 rossini、bellini 等 5 个示例用户）。
2. 旧的 temp/epg* 目录不会被自动清理，长期运行需定期手动清理。
3. 若需数据持久化，编辑 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 配置，随后重启。

六、注意事项

1. 必须使用 JDK 21 及以上版本；CentOS 8 仓库无 java-21 包，需按 2.2 节手动解压安装，并在 setenv.sh 写入 JAVA_HOME。
2. 首次启动约需 2 分钟进入可用状态，验证前先确认 logs/core.log 出现 Started SyncopeCoreApplication。
3. 日志文件较多（core.log、core-persistence.log、core-rest.log、core-connid.log、console.log 等，均在 logs/ 目录），log4j2 配置了 immediateFlush=false，日志有少量缓冲延迟。
4. conf/keystore.jks 内置自签名证书已于 2024-11-22 过期，启动日志会出现 WARNING，生产使用必须替换。
5. 管理脚本 bin/.sh 需要可执行权限，解压后首次启动前执行 chmod 755 ./bin/.sh。
6. SELinux 或 firewalld 可能拦截端口访问，部署后无法远程访问时优先检查这两项。

七、常见问题

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 被静默吞掉。解法：按 2.2 节安装 JDK 21，在 bin/setenv.sh 首行写入 JAVA_HOME，然后重启服务。

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.4 节操作，管理操作用 admin 账号调用 REST 或登录 console 完成。

Q4：启动日志提示 trusted certificate 证书过期警告（NotAfter: Fri Nov 22）？

内置 keystore.jks 中的自签名证书已过期的提示，不影响功能启动。生产环境应使用正式证书替换 conf/keystore.jks（keytool 导入），或关闭 9443 的 HTTPS Connector 只保留 9080。

Q5：重启后创建的用户、组等数据全部消失？

standalone 的内嵌 PostgreSQL 每次启动都会重新初始化（见 5.5 节），属预期行为。演示数据可反复使用，重要数据需外接数据库。

八、卸载方式

停止服务：

cd /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
./bin/shutdown.sh

确认进程已退出：

/usr/lib/jvm/jdk-21.0.2/bin/jps | grep Bootstrap

无输出即已停止。删除安装目录与下载缓存：

rm -rf /opt/syncope-standalone-4.1.3
rm -rf /opt/syncope-dl

如不再需要手动安装的 JDK，可一并删除：

rm -rf /usr/lib/jvm/jdk-21.0.2
rm -f /tmp/jdk21.tar.gz

九、参考链接

1. Apache Syncope 官网：https://syncope.apache.org/
2. Getting Started 指南（版本要求与部署方式）：https://syncope.apache.org/docs/getting-started.html
3. 官方下载页：https://downloads.apache.org/syncope/
4. Reference Guide（配置与 REST API）：https://syncope.apache.org/docs/reference-guide.html
5. Apache Tomcat 10.1 文档：https://tomcat.apache.org/tomcat-10.1-doc/