Banner

Apache Fineract

2026-10-16

Apache Fineract 上手教程

Apache Fineract 的上手路径建议按“先跑通 API → 再理解业务模型 → 最后做二次开发”三步走。它本质是后端核心银行引擎，没有开箱即用的完整前端，所以学习重点是 REST API 和租户初始化流程。

1. 环境准备

  • JDK 17（较新版本 Fineract 的推荐版本）
  • Gradle：项目使用 Gradle 构建，仓库自带 gradlew  wrapper，一般无需单独安装
  • 数据库：MySQL 8.0 / MariaDB 11.2 / PostgreSQL（任选其一）
  • Docker + Docker Compose：用于快速拉起数据库，避免本地装库
  • IDE：IntelliJ IDEA 或 Eclipse，方便读源码和调试
  • API 调试工具：Postman 或 curl，用于调用 REST 接口

验证环境：

java -version
docker --version
docker compose version

2. 获取代码

git clone https://github.com/apache/fineract.git
cd fineract

进入仓库后先看 README.md 和 docs/ 目录，确认当前分支的环境要求和启动方式，不同版本的配置项和路径可能有差异。

3. 启动数据库

最省事的方式是用 Docker 起一个数据库容器：

docker run -d \
  --name fineract-db \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=fineract_tenants \
  -e MYSQL_USER=fineract \
  -e MYSQL_PASSWORD=fineract \
  -p 3306:3306 \
  mysql:8.0

如果需要持久化数据，加上 -v fineract-db-data:/var/lib/mysql。

4. 配置并启动应用

Fineract 是 Spring Boot 应用，核心配置在 application.properties（或 fineract-provider/src/main/resources/ 下的配置文件），主要改这几项：

  • 数据库连接地址、用户名、密码
  • 租户库名称（如 fineract_tenants）
  • 端口（默认常见为 8080 或 8443）

然后用 Gradle 启动：

./gradlew bootRun

首次启动会执行数据库迁移（Liquibase/Flyway），初始化表结构，耗时几分钟，注意观察日志是否有报错。

5. 验证服务是否就绪

启动完成后，先检查健康状态：

curl http://localhost:8080/fineract-provider/actuator/health

再试一个业务接口：

curl http://localhost:8080/fineract-provider/api/v1/offices

能返回 JSON 说明 API 层已经可用。路径前缀可能随版本变化，以启动日志为准。

6. 初始化租户与管理账号

Fineract 是多租户架构，必须先有租户才能做业务操作。一般流程：

  1. 确认租户库 fineract_tenants 已创建并完成迁移。
  2. 调用租户初始化接口，创建默认租户（通常包含一个示例机构）。
  3. 用默认管理员账号登录，获取访问令牌。
  4. 后续请求带上令牌或 Basic Auth 头。

默认的租户标识、管理员用户名和密码会随版本变化，不要直接照搬网上旧教程里的默认值，以当前仓库的 README、docs/ 或初始化脚本里的说明为准。生产环境务必第一时间修改默认密码。

7. 熟悉 API 文档

Fineract 从 1.2.0 版本起提供了基于 OpenAPI/Swagger 的在线 API 文档（对应 Jira 上的 FINERACT-422 需求），启动后通常可以访问类似 /fineract-provider/actuator 或 Swagger UI 路径，直接在页面上试接口。

建议按这个顺序学习接口：

  • 组织类：Office（机构）、Staff（员工）
  • 客户类：Client（客户）、Group（小组）、Center（中心）
  • 产品类：Loan Product（贷款产品）、Savings Product（储蓄产品）
  • 业务类：Loan Application（贷款申请）、Savings Account（储蓄账户）
  • 交易类：Disbursement（放款）、Repayment（还款）、Deposit（存款）
  • 会计类：GL Account（总账科目）、Journal Entry（分录）

8. 跑通一条完整业务链路

建议动手走一遍这个流程，比读文档有效得多：

  1. 创建一个 Office（机构）。
  2. 创建一个 Loan Product（定义利率、还款方式、费用规则）。
  3. 创建一个 Client（客户）。
  4. 提交 Loan Application（贷款申请）。
  5. 审批 → 放款 → 还款。
  6. 查看还款计划、逾期状态和会计分录。

每一步的接口参数都可以在 Swagger 页面上查看示例。

9. 源码结构与二次开发

主要模块：

  • fineract-core：租户管理、通用基础设施、命令处理管线
  • fineract-loan：贷款产品、申请、审批、还款、罚息
  • fineract-savings：储蓄与存款
  • fineract-provider：REST API 层，处理前端请求
  • fineract-accounting：双式记账、总账

扩展方式：

  • 通过插件机制加载自定义 JAR 模块
  • 基于 REST API 开发独立的前端或移动端
  • 利用外部事件系统对接下游消息通道

10. 常见问题排查

现象可能原因处理方式
启动报数据库连接失败数据库未就绪或配置错误检查容器状态和 application.properties
迁移脚本报错数据库版本不兼容核对官方支持的数据库版本
接口返回 401/403未登录或权限不足完成租户初始化和认证
接口返回 404路径前缀随版本变化查看启动日志确认 context path
端口冲突8080/8443 被占用修改配置中的端口
内存不足JVM 堆太小调整 Gradle 或容器的 JVM 参数

11. 上手建议

  • 先 API 后源码：不要一上来就读源码，先用 Postman 把业务链路跑通，建立业务直觉。
  • 小数据起步：先用少量测试数据验证流程，避免大批量数据增加调试难度。
  • 关注版本差异：Fineract 版本迭代较快，网上的中文教程可能对应旧版本，遇到配置项对不上时优先查官方仓库。
  • 安全前置：即使是本地实验，也不要长期使用默认密码；生产部署必须上 HTTPS、强认证和审计。
  • 区分两条线：Apache Fineract（单体/模块化）和 Apache Fineract CN（微服务化）是两条不同的技术路线，选型时先确认自己要走哪条。
7
Apache Fineract
Apache Fineract是一款开源核心银行平台，为各类金融服务提供灵活、可扩展的基础架构。通过开放可靠的银行技术，它降低了各类机构与创新者服务普惠人群及无银行账户群体的门槛。
2026-10-16
10
目录