Apache Syncope 4.1.3 常用 CLI 命令与工具详解

汇总 Apache Syncope 4.1.3 服务端日常管理命令与工具，涵盖启停与状态脚本、数据库升级工具、REST API 管理操作、JVM 诊断工具与密钥库管理，所有命令均基于真实环境实测并附完整回显。

Apache SyncopeApache Syncope2026/10/12

Apache Syncope 4.1.3 常用 CLI 命令与工具详解

一、工具总览

Apache Syncope 4.1.3 不再单独发布命令行客户端工具（旧版本的 syncope-client-cli 已停止维护，Maven Central 中无 4.1.3 对应构件，官方 4.1 文档亦移除相关章节）。4.1.x 的日常管理与运维由以下四类命令与工具承担，全部可直接在服务器上执行：

类别工具/命令用途
服务管理脚本bin/startup.sh、shutdown.sh、version.sh、configtest.sh、digest.sh启动、停止、版本查询、初始化测试、密码摘要生成
数据库升级工具syncope-core-persistence-jpa-upgrader-4.1.3.jar从 Syncope 2.x/3.x 存量数据库升级到 4.1 的表结构与数据处理
REST APIcurl 调用 http://localhost:9080/syncope/rest用户、组、资源、任务、日志等全部管理操作
JVM 诊断工具jps、jcmd、jstack、keytool进程与内存诊断、线程分析、证书管理

下文安装根目录记为 $SYNCOPE_HOME（standalone 发行版解压后的 apache-tomcat-10.1.57 目录），实测环境为 /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57。执行任何 bin/ 下脚本前需先 cd 到该目录。

二、服务管理脚本（bin/）

2.1 startup.sh：启动服务

./bin/startup.sh

Tomcat started.

启动后可观察 logs/catalina.out 与 logs/core.log。Core 就绪标志（实测回显）：

tail -5 logs/core.log

INFO  org.apache.syncope.core.starter.SyncopeCoreApplication - Started SyncopeCoreApplication in 36.95 seconds (process running for 96.241)

2.2 shutdown.sh：停止服务

./bin/shutdown.sh

Tomcat stopped.

停止为优雅模式（core.properties 中 server.shutdown=graceful，最长等待 30 秒）。确认进程退出：

jps | grep Bootstrap

无输出即已停止；有输出且长时间不退出时可结合 kill $(jps | awk '/Bootstrap/{print $1}') 处理。

2.3 version.sh：版本信息

./bin/version.sh

Using CATALINA_BASE:   /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
Using CATALINA_HOME:   /opt/syncope-standalone-4.1.3/apache-tomcat-10.1.57
Server version: Apache Tomcat/10.1.57
Server number:  10.1.57.0
JVM Version:    21.0.12.1

该命令同时能验证运行时 JVM 版本，排查 Java 版本问题时首先使用它。

2.4 configtest.sh：配置初始化测试

不启动服务的情况下验证 Tomcat 配置可正常加载：

./bin/configtest.sh

INFO: Initializing ProtocolHandler ["http-nio-9080"]
INFO: Server initialization in [834] milliseconds

输出无 SEVERE 行即表示 server.xml 等配置正确。

2.5 digest.sh：密码摘要生成

生成与 Tomcat 域（Realm）配合使用的摘要（支持 sha-512、md5 等算法，格式为 密码:摘要$盐$盐摘要）：

./bin/digest.sh -a sha-512 q1w2e3r4

q1w2e3r4:ff825f15729d9d5c182762658a1125c2b9e56b80c392fe4821881e2e972293c7$1$2667632df730fddf2e59c6c686b6f140dd9375fdda73b40c79080a210208be7d24c94fe2e2647d5c6287c44a3e8282051b0d4f6f4df5980faeabf2d04c19c7ef

注意：该摘要格式仅用于 Tomcat 自身的 Realm 配置；Syncope 管理员密码摘要（security.adminPassword）的算法由 Syncope 自行实现，须按 security.adminPasswordAlgorithm 支持的算法计算（SHA512 等无盐算法用 JDK MessageDigest 即可），两者不可混用。

三、数据库升级工具（syncope-core-persistence-jpa-upgrader）

从旧版本（2.x/3.x）升级到 4.1.3 时，对存量数据库执行结构与数据迁移。全新部署不需要此工具。

工具为 Spring Boot 可执行 jar，官方下载页直接提供：

curl -sSL -O https://downloads.apache.org/syncope/4.1.3/syncope-core-persistence-jpa-upgrader-4.1.3.jar

ls -lh syncope-core-persistence-jpa-upgrader-4.1.3.jar

-rw-r--r-- 1 root root 20M Sep 11 05:57 syncope-core-persistence-jpa-upgrader-4.1.3.jar

不带参数直接运行时（实测）会因缺少数据库连接配置而启动失败：

java -jar syncope-core-persistence-jpa-upgrader-4.1.3.jar --help 2>&1 | head -5

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /

标准用法是通过 Spring Boot 通用参数提供数据库连接（以下为模板，按实际库填写；升级前务必备份数据库）：

java -jar syncope-core-persistence-jpa-upgrader-4.1.3.jar \
  --spring.datasource.url=jdbc:postgresql://localhost:5432/syncope?stringtype=unspecified \
  --spring.datasource.username=syncope \
  --spring.datasource.password=syncope

执行成功时工具会输出 OpenJPA 与迁移日志并在完成后自动退出；实测中不带参数启动则报 UnsatisfiedDependencyException（DataSource 未配置），符合预期。

四、REST API 管理（curl）

REST 是 4.1.3 唯一的管理接口层（管理控制台同样调用它），基础地址为 http://localhost:9080/syncope/rest，认证方式为 HTTP Basic（账号 admin，密码默认 password）。

4.1 认证与自助信息

curl -s -u admin:q1w2e3r4 http://localhost:9080/syncope/rest/users/self | grep -o '"username":"[^"]*"'

"username":"admin"

返回 401 表示认证失败；返回 200 表示认证成功。

4.2 接口清单（WADL）

一次获取全部 REST 端点定义（实测约 76 KB，可用于核对接口路径）：

curl -s -u admin:q1w2e3r4 'http://localhost:9080/syncope/rest?_wadl' -o /tmp/wadl.xml -w '%{http_code}\n'

200

常用管理端点（实测可用）：

端点方法用途
/usersPOST/GET创建用户、分页查询
/users/{key}GET/PUT/DELETE读取、更新、删除用户
/users?fiql=<表达式>GETFIQL 条件查询
/groups、/anyObjects、/realmsGET组、任意对象、层级Realm查询
/policiesGET策略查询（密码策略等）

4.3 创建用户（完整实测示例）

请求体必须包含 _class 字段、必填属性 fullname/surname/userId，且密码满足默认密码策略（不少于 10 字符）：

curl -s -X POST -u admin:q1w2e3r4 -H 'Content-Type: application/json' \
  -d '{"_class":"org.apache.syncope.common.lib.request.UserCR","username":"appuser01","password":"Q1w2E3r4!@#5","realm":"/","plainAttrs":[{"schema":"fullname","values":["App User 01"]},{"schema":"surname","values":["User"]},{"schema":"userId","values":["appuser01@syncope.apache.org"]}]}' \
  'http://localhost:9080/syncope/rest/users?storePasswordOnSyncope=true' -D /tmp/hdr.txt -o /dev/null -w '%{http_code}\n'

201

grep -i syncope-key /tmp/hdr.txt

X-Syncope-Key: 01a12dc6-481a-772e-a9a0-90194a48eedb

201 表示创建成功，X-Syncope-Key 响应头返回新用户唯一标识。

4.4 FIQL 条件查询

curl -s -u admin:q1w2e3r4 'http://localhost:9080/syncope/rest/users?fiql=username%3D%3Dappuser01' | grep -o '"totalCount":[0-9]*'

"totalCount":1

fiql 参数中 == 需 URL 编码为 %3D%3D。totalCount 字段给出命中条数（实测示例数据共 5 个用户，按 username 精确匹配命中 1 条）。

4.5 排错方法

REST 出错时响应体常为空（受日志缓冲影响），真实异常输出在 logs/core-rest.log（实测示例）：

grep -A3 'ERROR' logs/core-rest.log | tail -8

2026-10-12 01:37:02,895 [qtp1234567-95] ERROR org.apache.syncope.core.rest.cxf.service.AbstractServiceImpl - RequiredValuesMissing{elements=[surname, fullname, userId]}

五、JVM 诊断工具（jps/jcmd/jstack）

5.1 jps：定位 Syncope 进程

jps | grep Bootstrap

9043 Bootstrap

5.2 jps -v：核对启动参数（验证 JVM 内存配置）

jps -v | grep Bootstrap | grep -o '\-Xms[0-9]*m -Xmx[0-9]*m'

-Xms256m -Xmx512m

5.3 jcmd：运行时堆信息

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

garbage-first heap total 524288K 即 512 MB 堆上限，可确认 bin/setenv.sh 中的 -Xmx 已生效。其他常用 jcmd 指令：Thread.print（线程栈，等价 jstack）、GC.class_histogram（类统计）。

5.4 jstack：线程转储

jstack $(jps | awk '/Bootstrap/{print $1}') > /tmp/stack.txt
grep -c '^"' /tmp/stack.txt

64

用于启动慢、假死等问题的线程级分析。

六、密钥库管理（keytool）

HTTPS（9443）使用的证书库为 conf/keystore.jks，默认库密码 password：

keytool -list -keystore conf/keystore.jks -storepass password

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

mykey, Nov 22, 2022, PrivateKeyEntry,
tomcat, Nov 22, 2022, PrivateKeyEntry,

注意：内置自签名证书已过期（NotAfter 2024-11-22），启动日志会出现 trusted certificate 证书过期（is not valid）警告。生产环境替换证书的标准流程：

keytool -genkeypair -alias syncope -keyalg RSA -keysize 2048 -validity 365 \
  -keystore conf/keystore.jks -storepass <新库密码> -dname "CN=<服务器域名>"

同时将 server.xml 中 9443 Connector 的 certificateKeystorePassword 与其保持一致，重启生效。

七、注意事项

  1. 所有 bin/ 脚本必须在安装目录内以相对路径或绝对路径执行，脚本依赖 CATALINA_HOME 环境推导。
  2. shutdown.sh 后应立即执行 jps 确认 Bootstrap 进程退出，避免端口占用导致下次启动失败。
  3. 升级工具只处理数据库结构迁移，应用配置（core.properties 等）仍需手工按新版本参数对照调整。
  4. curl 调用 REST 时，请求体 JSON 中的 _class 字段与 URL 编码（如 fiql 的 %3D%3D）最容易出错，返回 4xx 时优先检查这两处。
  5. Syncope 4.1.3 不再提供独立的命令行客户端，任何声称的 syncope-client-cli 4.1.3 下载源均为旧版本或非官方，不要在生产环境使用。
  6. 执行升级或数据库迁移前，务必备份 Syncope 数据库（standalone 内嵌库每次重启重置，升级场景须先切换到外部数据库）。

八、常见问题

Q1：旧版本的 syncope-client-cli 在 4.1.3 下还能用吗？

不建议。实测 Maven Central 已无 syncope-client-cli 4.1.3 构件，且官方 4.1 文档移除了 CLI 章节，说明该工具已被 REST API 取代。3.x 时代的 CLI 连接 4.1.3 Core 时会因接口版本不匹配产生不可预期的行为。

Q2：curl 返回 500 且响应体为空，如何定位原因？

查看 logs/core-rest.log 中同一时间点的 ERROR 行（实测常见三类：UserCR 缺 _class 字段、必填属性缺失 RequiredValuesMissing、默认密码策略不满足 InvalidEntityException）。日志配置 immediateFlush=false 时存在几秒缓冲延迟，也可在问题复现后稍等再查。

Q3：jps 看不到 Bootstrap 进程？

两种可能：其一服务未启动，先执行 bin/startup.sh；其二当前用户无权限读取其他用户的 JVM（/tmp/hsperfdata_root），用 root 或启动服务的同一用户执行 jps。

Q4：REST 管理端口能否只在内网开放？

可以。管理调用仅走 9080 的 /syncope/rest 路径，建议通过防火墙限制 9080 来源，或在前置反向代理上对 /syncope/rest 做访问控制，仅放行运维网段。

九、参考链接

  1. Apache Syncope Reference Guide（REST API 章节）：https://syncope.apache.org/docs/reference-guide.html
  2. 官方下载页（升级工具）：https://downloads.apache.org/syncope/
  3. Apache Tomcat 10.1 运维文档：https://tomcat.apache.org/tomcat-10.1-doc/
  4. FIQL 语法说明（Apache Syncope 查询规范）：https://syncope.apache.org/docs/reference-guide.html#query-syntax