Apache Fineract 1.15.0 常用 CLI 命令与工具详解

目标：详解 Apache Fineract 1.15.0 常用命令行与配套工具，覆盖 Java/JVM、服务与端口、发行包与完整性校验、数据库命令以及 REST 业务 API。每条命令均给出实测输入与回显，在 Ubuntu 22.04 / CentOS 8 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS / CentOS Linux 8（命令与 1.15.0 一致）
运行时环境：Java 21（Ubuntu 路径 /usr/lib/jvm/java-21-openjdk-amd64，CentOS 路径 /opt/jdk21）
组件版本：Apache Fineract 1.15.0
安装目录：/opt/fineract/apache-fineract-bin-1.15.0
数据库：MariaDB（Ubuntu 10.6.23 / CentOS 10.11.19）
服务端口：8443（HTTPS），上下文路径 /fineract-provider

二、工具概览

工具	作用
`java` / `jps`	查看 Java 版本、列举 JVM 进程与启动实参（验证堆参数）
`systemctl`	托管与查看 Fineract、MariaDB 服务状态
`ss`	检查监听端口（8443）
`sha512sum` / `unzip` / `tar`	校验、查看与解压官方发行包
`mysql` / `mariadb`	数据库版本、字符集、建库、表统计
`curl`	调用 REST API（认证、客户、贷款产品、贷款账户、审批、放款）

三、前置条件

已按《Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南》或《CentOS 8 安装 Apache Fineract 1.15.0 指南》完成安装并启动服务
已知应用端口 8443 与上下文路径 /fineract-provider
已准备 Basic 认证头 bWlmb3M6cGFzc3dvcmQ=（base64("mifos:password")）

四、版本、服务与进程管理命令

4.1 查看 Java 版本

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

实测回显（Ubuntu）：

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)

💡 说明：Fineract 1.15.0 由 Java 21 编译，JDK 17 会报 UnsupportedClassVersionError。

4.2 启动服务

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

实测回显（Ubuntu）：

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)

4.3 jps：JVM 进程与堆参数验证

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

实测回显（可见 -Xmx512m -Xms256m 与 -Dloader.path）：

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

4.4 ss：端口检查

ss -ltnp | grep 8443

实测回显：

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

4.5 systemctl：服务托管（可选）

若已将 Fineract 托管为 systemd 服务：

systemctl start fineract
systemctl status fineract
systemctl restart fineract

💡 说明：服务单元示例见《Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南》第 6.2 节。

五、发行包与完整性校验工具

5.1 下载与校验（sha512sum）

sha512sum apache-fineract-bin-1.15.0.tar.gz

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

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

5.2 查看发行物清单（unzip -p MANIFEST）

unzip -p fineract-provider-1.15.0.jar META-INF/MANIFEST.MF

实测回显：

Manifest-Version: 1.0
Main-Class: org.springframework.boot.loader.launch.PropertiesLauncher
Implementation-Title: Apache Fineract
Implementation-Version: 1.15.0
Start-Class: org.apache.fineract.ServerApplication
Spring-Boot-Version: 3.5.15
Build-Jdk-Spec: 21

5.3 解压发行包（tar）

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

六、数据库（MariaDB）命令

6.1 版本与字符集

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

实测回显（Ubuntu）：

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

Variable_name         Value
character_set_server  utf8mb4

💡 说明：Ubuntu 版 MariaDB 默认 utf8mb4；CentOS 8 需在 /etc/my.cnf.d/zz-fineract.cnf 显式配置 utf8mb4，并升级 MariaDB 至 10.11。

6.2 建库与账号

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;"
mysql -uroot -pq1w2e3r4 -e 'SHOW DATABASES;'

实测回显：

Database
fineract_default
fineract_tenants
information_schema
mysql
performance_schema
sys

6.3 迁移表统计

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';"

实测回显（Liquibase 首次启动自动建表）：

288
6

七、REST API 命令（curl）

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

7.1 健康检查

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

实测回显：

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

7.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,"authenticated":true,"officeId":1,"officeName":"Head Office",
 "roles":[{"id":1,"name":"Super user"}],"isTwoFactorAuthenticationRequired":false}

⚠️ 注意：1.15.0 的 /authentication 为 POST，GET 返回 405 Method Not Allowed。

7.3 新建客户

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","status":{"id":300,"code":"clientStatusType.active","value":"Active"},
 "displayName":"Zhang San","officeId":1,"officeName":"Head Office",
 "legalForm":{"id":1,"code":"legalFormType.person","value":"Person"}}

7.4 新建贷款产品

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}

⚠️ 注意：daysInYearType、daysInMonthType、isInterestRecalculationEnabled 为实测必填字段，缺失会报错。

7.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}}}

八、注意事项

必须 Java 21：JDK 17 会触发 UnsupportedClassVersionError。
驱动须独立目录：-Dloader.path=/opt/fineract/driver，避免 -sources.jar 重复触发 Liquibase changelog。
认证为 POST：/api/v1/authentication 用 POST + 请求体。
客户必填 legalFormId：1=个人。
贷款产品必填 daysInYearType/daysInMonthType/isInterestRecalculationEnabled。
统一请求头：Authorization: Basic bWlmb3M6cGFzc3dvcmQ=、Fineract-Platform-TenantId: default、Content-Type: application/json。
HTTPS 自签证书：curl 需加 -k 跳过证书校验。

九、常见问题（FAQ）

Q1：curl 报证书错误。

1.15.0 默认启用 SSL 且使用自签证书，加 -k（或 --insecure）跳过校验。

Q2：REST 返回 405 Method Not Allowed。

查看认证接口的请求方法，1.15.0 的 /authentication 必须用 POST。

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

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

Q4：jps 看不到 -Xmx/-Xms。

确认启动命令携带 -Xmx512m -Xms256m；jps -v 显示的是透传实参，未携带则说明堆未限定。

十、参考链接

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 配置参数详解》。