CentOS 8 安装 Apache Fineract 1.15.0 指南

在 CentOS 8 服务器上以官方二进制发行包安装 Apache Fineract 1.15.0，完成 JDK 21 前置、MariaDB 字符集与 10.11 升级适配、数据库初始化、服务启动与 REST 全链路验证（登录/建客户/贷款产品/贷款账户/审批/放款）。

Apache FineractApache Fineract2026/10/11

CentOS 8 安装 Apache Fineract 1.15.0 指南

目标：在 CentOS 8 服务器上以官方二进制发行包安装 Apache Fineract 1.15.0（开源核心银行/数字金融服务平台），完成 JDK 21 前置、MariaDB 字符集与版本适配、数据库初始化、服务启动与 REST 全链路业务验证。安装与验证流程在 CentOS 8 真实服务器实测通过。

一、环境信息

  • 操作系统：CentOS Linux 8（x86_64），systemd 作为 PID 1
  • 包管理器：dnf
  • 运行时环境：Eclipse Temurin 21（21.0.12.1，Fineract 1.15.0 由 Java 21 编译，必须 JDK 21）
  • 组件版本：Apache Fineract 1.15.0（apache-fineract-bin-1.15.0.tar.gz，约 425 MB）
  • 数据库：MariaDB 10.11.19（由 AppStream 10.5.9 升级，字符集修正为 utf8mb4）
  • JDBC 驱动：mariadb-java-client 3.5.3（官方发行包不含，需自备）
  • 安装目录：/opt/fineract/apache-fineract-bin-1.15.0
  • 驱动目录：/opt/fineract/driver
  • 默认端口：8443（HTTPS，自签证书），上下文路径 /fineract-provider
  • 默认管理员：mifos / password；租户标识固定 default
  • 数据库账号：root / q1w2e3r4
  • JVM 堆：-Xmx512m -Xms256m

二、前置条件

  • 拥有 root 权限，已配置可访问 Apache 官方站点与 Adoptium 下载站的网络
  • 已安装 wget、curl
  • 已安装 tar（解压官方发行包）
  • 内存建议不低于 8 GB（官方 README 建议 16 GB / 8 核；实测将堆限制到 512 MB 上限亦可完整跑通）

⚠️ 注意：Fineract 1.15.0 的 class 文件由 JDK 21 编译（class file version 65.0）。CentOS 8 的 AppStream 仓库最高只有 java-17，直接运行发行包 JAR 会报 UnsupportedClassVersionError: ... class file version 65.0，必须先安装 JDK 21。

三、版本选型说明

Apache Fineract 各版本差异：

版本说明建议
1.15.0Apache 分发目录当前最新稳定版（实测对象，2026-07-14 发布）推荐，本文按此版安装
1.14.0 / 1.13.0 / 1.12.1历史小版本如需旧版可从同一归档路径下载
1.16.0-SNAPSHOTdevelop 分支快照（官方 latest 发行物内置）非稳定版，不建议用于生产

💡 说明：GitHub Releases 不提供二进制资产，官方发行物统一发布在 Apache 分发目录 https://downloads.apache.org/fineract/1.15.0/，同时提供 .asc（PGP 签名）与 .sha512（校验）文件。运行基石是 Java 21。

四、官方二进制发行包安装方案

4.1 安装 JDK 21（Temurin）

CentOS 8 的 AppStream 仅有 java-17，需自备 JDK 21：

dnf install -y java-17-openjdk-devel wget curl
dnf list available 'java-21*'

实测回显（无匹配，即 CentOS 8 仓库无 Java 21）：

# （无匹配：CentOS 8 仓库无 Java 21）

从清华 Adoptium 站点获取 Temurin 21：

wget -q -O /opt/temurin21.tar.gz \
  'https://mirrors.tuna.tsinghua.edu.cn/Adoptium/21/jdk/x64/linux/OpenJDK21U-jdk_x64_linux_hotspot_21.0.12.1_1.tar.gz'
mkdir -p /opt/jdk21 && tar -xzf /opt/temurin21.tar.gz -C /opt/jdk21 --strip-components=1

验证版本：

/opt/jdk21/bin/java -version

实测回显：

openjdk version "21.0.12.1" 2026-08-18 LTS
OpenJDK Runtime Environment Temurin-21.0.12.1+1 (build 21.0.12.1+1-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.12.1+1 (build 21.0.12.1+1-LTS, mixed mode, sharing)

JDK 21 的安装路径为 /opt/jdk21，后续作为 JAVA_HOME。

4.2 安装 MariaDB 并升级至 10.11

CentOS 8 的 AppStream 的 mariadb 模块提供 10.3/10.5 两个流，实测启用 10.5：

dnf module list mariadb
dnf module reset -y mariadb && dnf module enable -y mariadb:10.5 && dnf install -y mariadb-server mariadb
mysql --version

实测回显：

mysql  Ver 15.1 Distrib 10.5.9-MariaDB, for Linux (x86_64)

⚠️ 注意：CentOS 8 自带的 MariaDB 默认字符集为 latin1；且 10.5.9 存在 camelcase 列重命名的外键索引限制（迁移到 m_creditreport 列重命名时报 (1553) Cannot drop index 'cbId': needed in a foreign key constraint），无法完成 Liquibase 全量迁移，需升级到 10.11。

先修正字符集，新建 /etc/my.cnf.d/zz-fineract.cnf：

cat > /etc/my.cnf.d/zz-fineract.cnf <<'EOF'
[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci
EOF
systemctl enable --now mariadb

升级至 MariaDB 10.11（MariaDB 官方 RHEL 8 源）：

curl -sS https://mirrors.tuna.tsinghua.edu.cn/mariadb/mariadb_repo_setup | bash -s -- --mariadb-server-version="mariadb-10.11"
dnf install -y MariaDB-server MariaDB-client
systemctl restart mariadb
mysql --version

实测回显：

mysql  Ver 15.1 Distrib 10.11.19-MariaDB, for Linux (x86_64)

设置 root 账号并确认服务器字符集：

mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4');"
mysql -uroot -pq1w2e3r4 -e "SHOW VARIABLES LIKE 'character_set_server';"

实测回显：

Variable_name         Value
character_set_server  utf8mb4

4.3 获取 MariaDB JDBC 驱动

官方发行包不含 MariaDB/MySQL JDBC 驱动（LGPL/GPL 许可证不兼容），需自行提供；实测从阿里云 Maven 仓库获取 mariadb-java-client 3.5.3：

mkdir -p /opt/fineract/driver && cd /opt/fineract/driver && \
  curl -sSL -o mariadb-java-client-3.5.3.jar \
  'https://maven.aliyun.com/repository/public/org/mariadb/jdbc/mariadb-java-client/3.5.3/mariadb-java-client-3.5.3.jar'
ls -lh /opt/fineract/driver/

实测回显：

-rw-r--r-- 1 root root 746140 mariadb-java-client-3.5.3.jar

⚠️ 注意：驱动 JAR 必须放在独立目录 /opt/fineract/driver，并以 -Dloader.path 挂载；若与发行目录中的 -sources.jar 混放，Liquibase 会因重复触发 Found 2 files with the path 'classpath:/db/changelog/db.changelog-master.xml' 而启动失败。

4.4 下载与校验官方发行包

官方 downloads.apache.org 直连较慢，实测改走 Apache 官方站点（清华 TUNA，同一官方发行物）：

mkdir -p /opt/fineract && cd /opt/fineract && \
  wget -q https://mirrors.tuna.tsinghua.edu.cn/apache/fineract/1.15.0/apache-fineract-bin-1.15.0.tar.gz
sha512sum apache-fineract-bin-1.15.0.tar.gz

实测回显（与官方 .sha512 完全一致）：

0db5983c228ed6c96dc2e9d8918f570172758acceb898525d39c44684e9125215d59c1b64f8c85ba18141ea3d9c0c4955f3a670681464784f2af06d34b74ce1c  apache-fineract-bin-1.15.0.tar.gz

解压并查看发行物清单：

tar -xzf apache-fineract-bin-1.15.0.tar.gz && ls -la apache-fineract-bin-1.15.0/

实测回显：

-rw-rw-r-- 1 root root 230133800 fineract-provider-1.15.0.jar
-rw-rw-r-- 1 root root 205321924 fineract-provider.war
-rw-rw-r-- 1 root root   3874672 fineract-client-1.15.0.jar
-rw-rw-r-- 1 root root   1633066 fineract-avro-schemas-1.15.0.jar
-rw-rw-r-- 1 root root   2240328 fineract-documentation.pdf
-rw-rw-r-- 1 root root     22809 README.md

💡 说明：官方发行包已可直接运行，无需 Gradle 源码构建。查看 JAR 清单可见：Main-Class: org.springframework.boot.loader.launch.PropertiesLauncher、Start-Class: org.apache.fineract.ServerApplication、Build-Jdk-Spec: 21、Spring-Boot-Version: 3.5.15。

4.5 数据库初始化

Fineract 需要两个库：fineract_tenants（租户注册/元数据）与 fineract_default（默认租户业务库）。schema 由 Liquibase 在首次启动时自动迁移，无需手工建表。建库时显式指定 utf8mb4：

mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4');"
mysql -uroot -pq1w2e3r4 -e "
  CREATE DATABASE IF NOT EXISTS fineract_default CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
  CREATE DATABASE IF NOT EXISTS fineract_tenants CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
  CREATE USER IF NOT EXISTS 'root'@'%' IDENTIFIED BY 'q1w2e3r4';
  GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION; FLUSH PRIVILEGES;"
mysql -uroot -pq1w2e3r4 -e 'SHOW DATABASES;'

实测回显：

Database
fineract_default
fineract_tenants
information_schema
mysql
performance_schema
sys

💡 说明：数据库账号统一 root / q1w2e3r4（本地回环连接）。

4.6 启动服务

新建启动脚本 /opt/fineract/start-fineract.sh：

#!/usr/bin/env bash
export JAVA_HOME=/opt/jdk21
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

启动服务并查看日志：

chmod +x /opt/fineract/start-fineract.sh
nohup /opt/fineract/start-fineract.sh > /opt/fineract/fineract.log 2>&1 &
grep 'Started ServerApplication' /opt/fineract/fineract.log

实测回显：

2026-10-11 12:54:13.960 - INFO 1689 [default] --- [main] org.apache.fineract.ServerApplication : Started ServerApplication in 122.542 seconds (process running for 123.695)

确认端口与进程：

ss -ltnp | grep 8443
/opt/jdk21/bin/jps -v | grep fineract

实测回显：

LISTEN 0 100 *:8443 *:*  users:(("java",pid=1689,fd=13))

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

数据库迁移结果（Liquibase 自动建表）：

mysql -uroot -pq1w2e3r4 -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fineract_default';"
mysql -uroot -pq1w2e3r4 -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fineract_tenants';"

实测回显：

288
6

五、REST 业务验证

所有业务 API 均需请求头：Authorization: Basic bWlmb3M6cGFzc3dvcmQ=、Fineract-Platform-TenantId: default、Content-Type: application/json。

5.1 健康检查

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

实测回显：

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

5.2 管理员登录

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/authentication' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"username":"mifos","password":"password"}'

实测回显：

{"username":"mifos","userId":1,"base64EncodedAuthenticationKey":"bWlmb3M6cGFzc3dvcmQ\u003d","authenticated":true,
 "officeId":1,"officeName":"Head Office",
 "roles":[{"id":1,"name":"Super user","description":"This role provides all application permissions.","disabled":false}]}

💡 版本要点：1.15.0 的 /authentication 为 POST（GET 返回 405 Method Not Allowed）；Basic 头为 base64("mifos:password") = bWlmb3M6cGFzc3dvcmQ=。

5.3 新建客户

1.15.0 强制要求 legalFormId（1=个人）：

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/clients' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"officeId":1,"legalFormId":1,"firstname":"Zhang","lastname":"San",
  "externalId":"CLI-C8-001","dateFormat":"dd MMMM yyyy","locale":"en","active":true,
  "activationDate":"10 October 2026","submittedOnDate":"10 October 2026"}'

实测回显：

{"officeId":1,"clientId":1,"resourceId":1,"resourceExternalId":"CLI-C8-001"}

5.4 新建贷款产品

实测必需字段含 daysInYearType、daysInMonthType、isInterestRecalculationEnabled：

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/loanproducts' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"name":"C8 Test Loan","shortName":"C8L","currencyCode":"USD",
  "digitsAfterDecimal":2,"inMultiplesOf":0,"principal":10000,"numberOfRepayments":12,"repaymentEvery":1,
  "repaymentFrequencyType":2,"interestRatePerPeriod":12,"interestRateFrequencyType":2,"amortizationType":1,
  "interestType":0,"interestCalculationPeriodType":1,"transactionProcessingStrategyCode":"mifos-standard-strategy",
  "accountingRule":1,"daysInYearType":365,"daysInMonthType":30,"isInterestRecalculationEnabled":false,
  "locale":"en","dateFormat":"dd MMMM yyyy"}'

实测回显：

{"resourceId":1}

5.5 建贷款账户 → 审批 → 放款

新建贷款账户：

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/loans' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"clientId":1,"productId":1,"principal":10000,"loanTermFrequency":12,
  "loanTermFrequencyType":2,"numberOfRepayments":12,"repaymentEvery":1,"repaymentFrequencyType":2,
  "interestRatePerPeriod":12,"interestRateFrequencyType":2,"amortizationType":1,"interestType":0,
  "interestCalculationPeriodType":1,"transactionProcessingStrategyCode":"mifos-standard-strategy",
  "expectedDisbursementDate":"10 October 2026","submittedOnDate":"10 October 2026","loanType":"individual",
  "locale":"en","dateFormat":"dd MMMM yyyy"}'

实测回显：

{"officeId":1,"clientId":1,"loanId":1,"resourceId":1}

审批贷款（command=approve）：

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/loans/1?command=approve' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"approvedOnDate":"10 October 2026","locale":"en","dateFormat":"dd MMMM yyyy"}'

实测回显（状态 200 Approved）：

{"officeId":1,"clientId":1,"loanId":1,"resourceId":1,
 "changes":{"status":{"id":200,"code":"loanStatusType.approved","value":"Approved","waitingForDisbursal":true,"active":false}}}

放款（command=disburse）：

curl -sk -X POST 'https://localhost:8443/fineract-provider/api/v1/loans/1?command=disburse' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default' \
  -H 'Content-Type: application/json' -d '{"actualDisbursementDate":"10 October 2026","locale":"en","dateFormat":"dd MMMM yyyy"}'

实测回显（状态 300 Active）：

{"officeId":1,"clientId":1,"loanId":1,"resourceId":1,"subResourceId":1,
 "changes":{"status":{"id":300,"code":"loanStatusType.active","value":"Active","active":true}}}

查询贷款账户最终状态：

curl -sk 'https://localhost:8443/fineract-provider/api/v1/loans/1' \
  -H 'Authorization: Basic bWlmb3M6cGFzc3dvcmQ=' -H 'Fineract-Platform-TenantId: default'

实测回显：

{"id":1,"accountNo":"000000001","status":{"id":300,"code":"loanStatusType.active","value":"Active","active":true},
 "clientId":1,"clientName":"Zhang San","clientExternalId":"CLI-C8-001","loanProductId":1,"loanProductName":"C8 Test Loan",
 "loanType":{"id":1,"code":"accountType.individual","value":"Individual"},"currency":{"code":"USD"}}

结论：本机完成「管理员登录 → 建客户 → 建贷款产品 → 建贷款账户 → 审批 → 放款」全链路真实业务验证，返回 JSON 均为真实回显。

六、配置说明（含 JVM 堆）

6.1 JVM 堆内存限定与生效验证

本实例堆统一定义为 -Xmx512m -Xms256m。验证方法：

/opt/jdk21/bin/jps -v | grep fineract

实测回显（可见堆参数已透传生效）：

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

也可用 ps -ef | grep [j]ava 复核。

6.2 systemd 托管（可选）

若用 systemd 将 Fineract 托管为本机服务，新建 /etc/systemd/system/fineract.service：

[Unit]
Description=Apache Fineract 1.15.0
After=network.target mariadb.service
Wants=mariadb.service

[Service]
Environment=JAVA_HOME=/opt/jdk21
Environment=FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME=org.mariadb.jdbc.Driver
Environment=FINERACT_HIKARI_JDBC_URL=jdbc:mariadb://localhost:3306/fineract_tenants
Environment=FINERACT_HIKARI_USERNAME=root
Environment=FINERACT_HIKARI_PASSWORD=q1w2e3r4
Environment=FINERACT_DEFAULT_TENANTDB_HOSTNAME=localhost
Environment=FINERACT_DEFAULT_TENANTDB_PORT=3306
Environment=FINERACT_DEFAULT_TENANTDB_UID=root
Environment=FINERACT_DEFAULT_TENANTDB_PWD=q1w2e3r4
Environment=FINERACT_DEFAULT_TENANTDB_NAME=fineract_default
Environment=FINERACT_DEFAULT_TENANTDB_IDENTIFIER=default
WorkingDirectory=/opt/fineract/apache-fineract-bin-1.15.0
ExecStart=/opt/jdk21/bin/java -Xmx512m -Xms256m -Dloader.path=/opt/fineract/driver -jar fineract-provider-1.15.0.jar
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 注意：Environment= 每行只能声明一个单元，服务文件需放在需要 systemd 的 Linux 真机上生效。

七、注意事项

  • 必须 JDK 21：CentOS 8 仓库无 Java 21，需自备 Temurin 21；JDK 17 会触发 UnsupportedClassVersionError。
  • MariaDB 需 utf8mb4 与 10.11：默认 latin1 会导致迁移时 Incorrect string value '\xE2\x82\xA1'（₡ 货币符号）失败；10.5.9 的外键索引限制会导致列重命名迁移失败。
  • JDBC 驱动须独立目录：-Dloader.path 指向仅含驱动的 /opt/fineract/driver，避免 -sources.jar 重复触发 Liquibase changelog。
  • 数据库账号：统一 root / q1w2e3r4。
  • 默认认证：管理员 mifos / password，租户头 Fineract-Platform-TenantId: default。

八、常见问题（FAQ）

Q1：启动 JAR 报 UnsupportedClassVersionError: ... class file version 65.0。

JDK 版本不对。1.15.0 由 Java 21 编译，需安装 Temurin 21 并将 JAVA_HOME 指向 /opt/jdk21。

Q2：启动报 Found 2 files with the path 'classpath:/db/changelog/db.changelog-master.xml'。

-Dloader.path 指向的目录含 -sources.jar。将 MariaDB 驱动单独放入 /opt/fineract/driver 并只挂载该目录。

Q3：迁移到 m_currency 报 Incorrect string value: '\xE2\x82\xA1' for column display_symbol。

CentOS 8 自带 MariaDB 默认 latin1。在 /etc/my.cnf.d/zz-fineract.cnf 设 character-set-server=utf8mb4、collation-server=utf8mb4_general_ci，重启并重建库。

Q4：ALTER TABLE m_creditreport CHANGE creditBureauId credit_bureau_id 报 (1553) Cannot drop index 'cbId': needed in a foreign key constraint。

MariaDB 10.5.9 限制。升级到 MariaDB 10.11.19 并重建库后重新迁移。

Q5：POST /clients 报 The parameter 'legalFormId' is mandatory。

请求体补 "legalFormId":1（1=个人）。

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

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

九、卸载方式

# 1. 停止服务
pkill -f fineract-provider-1.15.0.jar

# 2. 删除安装目录与启动脚本
rm -rf /opt/fineract /opt/jdk21 /opt/temurin21.tar.gz

# 3.（可选）删除数据库与库表
mysql -uroot -pq1w2e3r4 -e "DROP DATABASE IF EXISTS fineract_default; DROP DATABASE IF EXISTS fineract_tenants;"

十、参考链接

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

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