Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南

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

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），systemd 作为 PID 1
运行时环境：OpenJDK 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.6.23（发行版仓库自带，默认字符集 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 官方站点的网络
已安装 wget、curl、unzip
已安装 tar（解压官方发行包）
内存建议不低于 8 GB（官方 README 建议 16 GB / 8 核；实测将堆限制到 512 MB 上限亦可完整跑通）

⚠️ 注意：Fineract 1.15.0 的 class 文件由 JDK 21 编译（class file version 65.0）。若用 JDK 17 运行发行包 JAR，会报 UnsupportedClassVersionError: ... class file version 65.0, ... only recognizes ... up to 61.0，必须先安装并切换 JDK 21。

三、版本选型说明

Apache Fineract 各版本差异：

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

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

四、在线官方发行包安装方案（推荐）

4.1 安装 JDK 21

Ubuntu 22.04 发行版仓库直接提供 openjdk-21：

export DEBIAN_FRONTEND=noninteractive; apt-get update -qq && \
  apt-get install -y -qq openjdk-21-jdk-headless wget curl unzip

验证版本：

/usr/lib/jvm/java-21-openjdk-amd64/bin/java -version

实测回显：

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

JDK 21 的安装路径为 /usr/lib/jvm/java-21-openjdk-amd64，后续作为 JAVA_HOME。

JDK 17 启动失败实证（版本选型依据）：

/usr/lib/jvm/java-17-openjdk-amd64/bin/java -jar fineract-provider-1.15.0.jar

实测回显：

Exception in thread "main" java.lang.UnsupportedClassVersionError: org/apache/fineract/ServerApplication
  has been compiled by a more recent version of the Java Runtime (class file version 65.0),
  this version of the Java Runtime only recognizes class file versions up to 61.0

4.2 安装 MariaDB（默认字符集 utf8mb4）

apt-get install -y -qq mariadb-server mariadb-client
systemctl enable --now mariadb
mariadb --version

实测回显：

mariadb  Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64)

确认服务器字符集（Ubuntu 版 MariaDB 默认 utf8mb4，可直接迁移）：

mysql -uroot -pq1w2e3r4 -e "SHOW VARIABLES LIKE 'character_set_server';"

实测回显：

Variable_name         Value
character_set_server  utf8mb4

💡 说明：Ubuntu 22.04 的 MariaDB 默认字符集即 utf8mb4，无需像 CentOS 8 那样额外修正 /etc/mysql 配置；客户端命令 mariadb 与 mysql 均可使用。

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 在首次启动时自动迁移，无需手工建表：

mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4');"
mysql -uroot -pq1w2e3r4 -e "
  CREATE DATABASE IF NOT EXISTS fineract_tenants;
  CREATE DATABASE IF NOT EXISTS fineract_default;
  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=/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

启动服务并查看日志：

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:43:57.697 - INFO 5430 [default] --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8443 (https) with context path '/fineract-provider'
2026-10-11 12:43:57.710 - INFO 5430 [default] --- [main] org.apache.fineract.ServerApplication : Started ServerApplication in 113.213 seconds (process running for 114.251)

确认端口与进程：

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

实测回显：

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

5430 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}],
 "permissions":["FORCE_WITHDRAWAL_SAVINGSACCOUNT","ALL_FUNCTIONS","FORCE_WITHDRAWAL_SAVINGSACCOUNT_CHECKER"],
 "shouldRenewPassword":false,"isTwoFactorAuthenticationRequired":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-U22-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-U22-001"}

查询客户详情：

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

实测回显：

{"id":1,"accountNo":"000000001","externalId":"CLI-U22-001",
 "status":{"id":300,"code":"clientStatusType.active","value":"Active"},"active":true,
 "activationDate":[2026,10,10],"firstname":"Zhang","lastname":"San","displayName":"Zhang San",
 "officeId":1,"officeName":"Head Office",
 "legalForm":{"id":1,"code":"legalFormType.person","value":"Person"}}

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":"U22 Test Loan","shortName":"U22L","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-U22-001","loanProductId":1,"loanProductName":"U22 Test Loan",
 "loanType":{"id":1,"code":"accountType.individual","value":"Individual"},"currency":{"code":"USD"}}

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

六、配置说明（含 JVM 堆）

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

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

/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

也可用 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=/usr/lib/jvm/java-21-openjdk-amd64
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=/usr/lib/jvm/java-21-openjdk-amd64/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：JDK 17 会触发 UnsupportedClassVersionError；Ubuntu 22.04 仓库自带 openjdk-21-jdk-headless。
MariaDB 默认 utf8mb4：Ubuntu 版 MariaDB 无需额外修正字符集即可迁移。
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 编译，需安装 openjdk-21-jdk-headless 并将 JAVA_HOME 指向 /usr/lib/jvm/java-21-openjdk-amd64。

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

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

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

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

Q4：POST /loanproducts 报 daysInYearType/daysInMonthType/isInterestRecalculationEnabled 为必填。

补齐 "daysInYearType":365、"daysInMonthType":30、"isInterestRecalculationEnabled":false。

Q5：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

# 3.（可选）删除数据库与卸载 JDK 21、MariaDB
mysql -uroot -pq1w2e3r4 -e "DROP DATABASE IF EXISTS fineract_default; DROP DATABASE IF EXISTS fineract_tenants;"
apt-get purge -y openjdk-21-jdk-headless mariadb-server mariadb-client

十、参考链接

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

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