Apache Fineract 1.15.0 配置参数详解

目标：系统讲解 Apache Fineract 1.15.0 的核心配置参数，覆盖每个参数的作用、默认值与实测取值，并给出 JVM 堆内存与 MariaDB 生产配置模板。所有默认值均在 Ubuntu 22.04 / CentOS 8 的真实安装实例上核对。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS / CentOS Linux 8（Fineract 1.15.0 跨平台一致）
• 运行时环境：Java 21（OpenJDK 或 Temurin）
• 组件版本：Apache Fineract 1.15.0
• 安装目录：/opt/fineract/apache-fineract-bin-1.15.0
• 主程序：fineract-provider-1.15.0.jar（自包含 Spring Boot 3.5.15，内嵌 Tomcat）
• 驱动目录：/opt/fineract/driver
• 配置载体：配置已打包进 JAR（BOOT-INF/classes/application.properties），发行包无独立 application.properties 文件，全部可用环境变量覆盖

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南》或《CentOS 8 安装 Apache Fineract 1.15.0 指南》完成安装
• 服务已启动，可访问 https://localhost:8443/fineract-provider/actuator/health
• 了解 Fineract 参数可通过环境变量（FINERACT_*）或启动时的 -D 系统属性覆盖

三、参数查看与修改方式

3.1 查看运行参数

Fineract 的配置最终体现为 Java 进程的环境变量与启动实参，可用 jps -v 查看 JVM 实参：

/usr/lib/jvm/java-21-openjdk-amd64/bin/jps -v | grep fineract

实测回显（可见堆参数与 -Dloader.path）：

5430 fineract-provider-1.15.0.jar -Xmx512m -Xms256m -Dloader.path=/opt/fineract/driver

查看启动脚本中注入的环境变量：

cat /opt/fineract/start-fineract.sh

实测回显关键行：

export FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME=org.mariadb.jdbc.Driver
export FINERACT_HIKARI_JDBC_URL='jdbc:mariadb://localhost:3306/fineract_tenants'
export FINERACT_DEFAULT_TENANTDB_NAME=fineract_default

也可通过 Actuator 端点读取运行时配置（如健康、环境）：

curl -sk https://localhost:8443/fineract-provider/actuator/health

实测回显：

{"status":"UP","groups":["liveness","readiness"]}

3.2 修改方式对比

💡 说明：Fineract 官方推荐用环境变量覆盖。旧前缀 fineract_tenants_*（如 fineract_tenants_driver）仍可用，但官方推荐 FINERACT_HIKARI_*。

四、参数总览

本文覆盖的参数汇总（默认值来自 application.properties，实测取值为 MariaDB 部署）：

五、核心参数分类详解

5.1 数据源与 Hikari 连接池段

# BOOT-INF/classes/application.properties（JAR 内，可用环境变量覆盖）
spring.datasource.hikari.driverClassName=org.postgresql.Driver
spring.datasource.hikari.jdbcUrl=jdbc:postgresql://localhost:5432/fineract_tenants
spring.datasource.hikari.username=root
spring.datasource.hikari.password=postgres

💡 说明：Fineract 默认面向 PostgreSQL（官方 FSIP-9 建议 PostgreSQL ≥18）；改用 MariaDB 时必须同时提供 JDBC 驱动（-Dloader.path=/opt/fineract/driver）并覆盖驱动类与连接串。Hikari 是默认连接池实现。

5.2 多租户（Tenant）段

fineract.tenant.host=localhost
fineract.tenant.port=5432
fineract.tenant.username=root
fineract.tenant.password=postgres
fineract.tenant.name=fineract_default
fineract.tenant.identifier=default

💡 说明：fineract_tenants 为租户注册库，应用据此动态路由到各租户业务库；REST 请求需携带 Fineract-Platform-TenantId: default 定位租户。

5.3 服务端与 SSL 段

server.port=8443
server.servlet.context-path=/fineract-provider
server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.jks
server.ssl.key-store-password=openmf

💡 说明：实测启动日志 Tomcat started on port 8443 (https) with context path '/fineract-provider'。默认使用自签证书，浏览器/客户端会告警，curl 需加 -k 跳过校验。

5.4 数据库迁移（Liquibase）段

spring.liquibase.enabled=true
# changelog: classpath:/db/changelog/db.changelog-master.xml

💡 说明：实测首次启动自动建表，fineract_default 生成 288 张表、fineract_tenants 生成 6 张表，无需手工建表。若 -Dloader.path 目录混入 -sources.jar，会因重复 changelog 报 Found 2 files with the path 'classpath:/db/changelog/db.changelog-master.xml'。

5.5 管理与健康检查段

management.endpoint.health.probes.enabled=true

💡 说明：实测 GET /fineract-provider/actuator/health 返回 {"status":"UP","groups":["liveness","readiness"]}。

5.6 JVM 堆内存参数（-Xmx / -Xms）

Fineract 为 Java 进程，堆限制在 256–512MB 区间：

通过启动命令透传，验证：

/usr/lib/jvm/java-21-openjdk-amd64/bin/jps -v | grep fineract

实测回显：

5430 fineract-provider-1.15.0.jar -Xmx512m -Xms256m -Dloader.path=/opt/fineract/driver

💡 说明：Fineract 官方 README 建议运行环境 16 GB 内存 / 8 核；实测将堆压到 512 MB 上限后，Liquibase 全量迁移（288 张表）与业务请求均可正常完成，未出现 OOM。

六、生产配置模板

本模板面向「MariaDB 后端、单机部署」的典型场景。示例以环境变量注入（写入启动脚本）：

# /opt/fineract/start-fineract.sh
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME=org.mariadb.jdbc.Driver
export FINERACT_HIKARI_JDBC_URL='jdbc:mariadb://localhost:3306/fineract_tenants'
export FINERACT_HIKARI_USERNAME=root
export FINERACT_HIKARI_PASSWORD=q1w2e3r4
export FINERACT_DEFAULT_TENANTDB_HOSTNAME=localhost
export FINERACT_DEFAULT_TENANTDB_PORT=3306
export FINERACT_DEFAULT_TENANTDB_UID=root
export FINERACT_DEFAULT_TENANTDB_PWD=q1w2e3r4
export FINERACT_DEFAULT_TENANTDB_NAME=fineract_default
export FINERACT_DEFAULT_TENANTDB_IDENTIFIER=default
cd /opt/fineract/apache-fineract-bin-1.15.0
exec $JAVA_HOME/bin/java -Xmx512m -Xms256m -Dloader.path=/opt/fineract/driver -jar fineract-provider-1.15.0.jar

对应数据库侧字符集配置（MariaDB，CentOS 8 需显式设置）：

# /etc/my.cnf.d/zz-fineract.cnf
[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci

💡 说明：内存紧张或仅验证场景可将堆下调；生产写多场景应在测试环境先观测 baseline 再上调堆上限，但始终不超出本机物理内存。字符集务必 utf8mb4，否则迁移期 Incorrect string value '\xE2\x82\xA1'（₡ 货币符号）会失败。

七、常见问题（FAQ）

Q1：不设置 FINERACT_HIKARI_* 时连接失败。

默认驱动为 org.postgresql.Driver、连接串指向 PostgreSQL 的 5432 端口。使用 MariaDB 时必须覆盖驱动类、连接串、账号密码与端口。

Q2：GET /api/v1/authentication 返回 405 Method Not Allowed。

1.15.0 的认证接口为 POST，需携带请求体 {"username":"mifos","password":"password"}。

Q3：-Dloader.path 目录混入 -sources.jar 导致启动报重复 changelog。

将该参数指向仅含 MariaDB 驱动的独立目录 /opt/fineract/driver。

Q4：JVM 堆参数不生效。

确认启动命令携带 -Xmx512m -Xms256m，并用 jps -v 或 ps -ef | grep [j]ava 复核。

八、参考链接

• Apache Fineract 官方发行目录：https://downloads.apache.org/fineract/1.15.0/
• Apache Fineract 项目主页：https://fineract.apache.org/

系列其他文档：《Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南》《CentOS 8 安装 Apache Fineract 1.15.0 指南》《Apache Fineract 1.15.0 Docker Compose 部署指南》《Apache Fineract 1.15.0 常用 CLI 命令与工具详解》。