Apache Syncope 4.1.3 配置参数详解

一、配置文件总览

本文以 standalone 发行版（解压后为 apache-tomcat-10.1.57 目录）为基础，安装根目录记为 $SYNCOPE_HOME，下文均相对该目录。实测各配置文件位置如下：

配置生效方式：修改上述 properties 或 xml 文件后，需要重启 Syncope（bin/shutdown.sh 后再执行 bin/startup.sh）。core.properties 修改不改文件位置时无需其他操作，因为 setenv.sh 已通过 -Dsyncope.conf.dir 指向该目录。

二、JVM 与启动参数（bin/setenv.sh）

setenv.sh 是启动时唯一自动加载的环境配置文件，实测完整内容（JVM 内存部分已按 512 MB 上限调整过）：

JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -Djavax.net.ssl.trustStore=$CATALINA_HOME/conf/keystore.jks -Djavax.net.ssl.trustStorePassword=password -Dsyncope.conf.dir=$CATALINA_HOME/webapps/syncope/WEB-INF/classes -Dsyncope.connid.location=connid://testconnectorserver@localhost:4554 -Dsyncope.log.dir=$CATALINA_HOME/logs -Dspring.profiles.active=embedded,all -server -Xms256m -Xmx512m -DCATALINA_HOME=$CATALINA_HOME"

各参数详解：

JVM 内存修改后验证方法（实测回显，jps -v 提取堆参数）：

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

-Xms256m -Xmx512m

注意：Core、Console、Enduser、WA 四个应用运行在同一个 JVM 进程中，设置堆上限时需保证总容量足够，512 MB 为实测下限，内存充裕建议 1 GB 以上。

三、Tomcat 端口与连接器（conf/server.xml）

实测 server.xml 中与 Syncope 相关的关键完整行：

<Server port="9805" shutdown="SHUTDOWN">

连接器关键属性（实测读取）：

服务访问路径（实测端口与上下文）：

四、Core 核心配置参数（core.properties）

文件路径：webapps/syncope/WEB-INF/classes/core.properties。以下按实测文件内容分组说明。

4.1 应用与服务参数

4.2 持久化参数（Persistence）

内嵌模式（standalone）下 core-embedded.properties 会覆盖 jdbcURL 等参数，改用 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.

要点：嵌入式数据库数据存于 $CATALINA_HOME/temp/epg<随机数> 目录，每次重启重新初始化，数据不持久；接入外部 PostgreSQL 时，删除或移走 core-embedded.properties，让 core.properties 的 persistence.domain[0].* 生效即可。

4.3 安全参数（Security）

4.3.1 修改管理员密码（实测流程）

修改 admin 密码需改 security.adminPassword 与 security.adminPasswordAlgorithm 两个参数。以改为 q1w2e3r4、算法 SHA512 为例：先用 JDK 计算明文的 SHA512 十六进制值：

e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9

将上述值写入 core.properties 并改算法：

sed -i 's/^security.adminPassword=.*/security.adminPassword=e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9/' webapps/syncope/WEB-INF/classes/core.properties
sed -i 's/^security.adminPasswordAlgorithm=.*/security.adminPasswordAlgorithm=SHA512/' webapps/syncope/WEB-INF/classes/core.properties

重启后验证（实测回显，新密码 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

4.4 邮件参数（Email）

邮件参数用于密码重置、通知（Notification）等场景，standalone 内嵌模式下的 mail 主机与端口（mail.smpt.host=localhost、port 2525）在 core-embedded.properties 中另有覆盖。

4.5 治理接口参数（Management）

注意：standalone 实测中，用 admin 账号经 Basic 认证访问 /syncope/actuator/health 返回 403，该接口面向内部治理调用，不建议对外网开放。

4.6 内嵌模式参数（core-embedded.properties）

standalone 专用的覆盖配置文件（profile=embedded 时生效），实测完整有效项：

embedded.databases=syncope,syncopetwo,syncopetest
keymaster.address=http://localhost:9080/syncope/rest/keymaster
keymaster.username=anonymous
keymaster.password=anonymousKey
security.productionMode=false
security.jwsKey=ZW7pRixehFuNUtnY5Se47IemgMryTzazPPJ9CGX5LTCmsOJpOgHAQEuPQeV9A28f
security.aesSecretKey=1abcdefghilmnopqrstuvz2!
mail.smtp.host=localhost
mail.smtp.port=2525

五、域（Domain）配置与示例数据

Syncope 支持多域（Domain）管理，每个域对应独立数据库。域的基础连接信息在 core.properties 中以 persistence.domain[N].* 定义（实测 standalone 自带两个域定义：persistence.domain[0].key=Master 与 persistence.domain[1].key=Two），域的初始化数据与参数文件位于 webapps/syncope/WEB-INF/classes/domains/ 目录：

相关实测事实：

1. 内嵌模式每次启动会重新创建 syncope、syncopetwo 两个库并导入上述内容，因此任何数据修改在重启后都会还原为该 XML 定义的状态。
2. 新增域的做法：在 core.properties 增加 persistence.domain[2].* 系列（key/jdbcURL/账号等），并在 domains/ 目录放置对应 Content.xml 后重启。
3. REST API 中通过在请求头加 X-Syncope-Domain: Two 即可操作非默认域。

六、Console 与 Enduser 配置

6.1 console-embedded.properties（管理控制台）

路径：webapps/syncope-console/WEB-INF/classes/console-embedded.properties，实测完整有效项：

keymaster.address=http://localhost:9080/syncope/rest/keymaster
keymaster.username=anonymous
keymaster.password=anonymousKey
service.discovery.address=http://localhost:9080/syncope-console/
spring.devtools.livereload.enabled=false
spring.devtools.restart.enabled=false

6.2 enduser-embedded.properties（最终用户界面）

路径：webapps/syncope-enduser/WEB-INF/classes/enduser-embedded.properties，结构与 console 完全一致（keymaster.* 与 service.discovery.address，指向本机 Core 与 enduser 自身），参数含义同上。

改外置部署时，两文件的 keymaster.address 都指向 Core 的 keymaster 服务地址，匿名凭据改为与 Core 一致的值。

七、日志配置（log4j2.xml）

路径：webapps/syncope/WEB-INF/classes/log4j2.xml。实测日志输出到 -Dsyncope.log.dir 指定的 logs/ 目录，文件清单：

实测要点：

1. 各 RollingFile 配置 immediateFlush="false"，日志存在缓冲延迟，故障排查时可先执行 shutdown 触发缓冲落盘再查看。
2. 运行时调整日志级别可通过 Actuator loggers 端点（management.endpoints 已包含 loggers）或编辑 log4j2.xml 后重启。

八、注意事项

1. 所有配置修改均需重启 Syncope 后生效；重启会重置内嵌数据库数据。
2. security.jwsKey、security.aesSecretKey、security.anonymousKey 三项是安全核心，默认值仅用于测试，生产部署必须全部更换。
3. 修改 persistence.domain[0].* 接入外部数据库时，确保数据库实例已创建且账号具备建表权限（首次启动自动建表）。
4. core-embedded.properties 与 core.properties 同时存在时以 embedded profile 的覆盖值为准，接入外部数据库务必移除该文件。
5. setenv.sh 中 -Xmx 不宜低于 512 MB（四个应用同 JVM），也不建议超过宿主可用内存的一半。
6. X-Syncope-Domain 请求头用于多域操作，缺省操作 Master 域。

九、常见问题

Q1：改了 core.properties 里的持久化配置为什么还是连接内嵌 PostgreSQL？

core-embedded.properties 的覆盖优先级更高（spring.profiles.active 包含 embedded）。将该文件从 WEB-INF/classes 移走或删除后再重启，core.properties 的 persistence.domain[0].* 才会生效。

Q2：修改 admin 密码后旧密码仍能登录？

修改后必须重启服务，配置型账号的凭据在启动时加载。重启后旧密码立即失效（实测 admin:password 返回 401）。

Q3：启动日志报 The default adminPassword property is being used 警告？

当前仍在使用官方默认密码 password 的提示。按 4.3.1 节流程修改后重启即可消除。

Q4：重启后 core.log 报 Creating embedded databases 且数据全部回到初始状态？

这是内嵌模式的设计行为：每次启动重建 syncope/syncopetwo 库并导入 domains/*.xml 初始数据。需要持久化数据时改用外部数据库（见 Q1）。

Q5：Actuator health 端点访问返回 403？

standalone 的 Actuator 治理端点未对管理账号开放 Basic 认证访问，属默认安全策略。若需查看健康状态，可经反向代理限制来源后按需调整 management.endpoints 相关配置。

十、参考链接

1. Apache Syncope Reference Guide：https://syncope.apache.org/docs/reference-guide.html
2. Getting Started（standalone 与配置说明）：https://syncope.apache.org/docs/getting-started.html
3. Apache Tomcat 10.1 配置参考：https://tomcat.apache.org/tomcat-10.1-doc/config/
4. OpenJPA 手册（方言与远程提交）：https://openjpa.apache.org/documentation.html