apache/fineract

Apache Fineract: 小额***平台

!https://github.com/apache/fineract/actions/workflows/build-mariadb.yml/badge.svg?branch=develop !Docker Hub !https://github.com/apache/fineract/actions/workflows/publish-dockerhub.yml/badge.svg !Technical Debt

镜像概述和主要用途

Fineract是一个成熟的开放API平台，提供可靠、健壮且经济实惠的核心银行解决方案，专为向全球30亿未被充分服务和无银行账户人群提供服务的机构设计。该平台支持机构高效管理账户、交易和客户数据，通过开放API实现与第三方系统的集成，满足小额和普惠的业务需求。

核心功能和特性

• 开放API架构：支持第三方系统集成，提供灵活的接口扩展能力
• 成熟稳定：经过实践验证的核心银行功能，确保***交易的可靠性
• 经济实惠：降低***机构的技术门槛和运营成本
• 多租户支持：通过租户数据库隔离实现多机构共享平台
• 灵活部署：支持Docker容器化部署、Kubernetes集群部署及传统JAR/WAR部署
• 安全可靠：严格的安全标准和数据保护机制
• 高性能：支持大规模账户管理，通过远程分区加速批处理作业
• 多数据库兼容：支持MariaDB、PostgreSQL等主流数据库

使用场景和适用范围

• 小额*机构**：社区银行、信用合作社、小额贷款公司
• 普惠项目**：服务农村和低收入人群的**服务项目
• 科技企业：需要核心银行功能的创新产品
• 非组织(NGO)：提供 inclusion 服务的公益组织
• 大型*机构**：作为服务未被充分服务客户群体的独立业务线

详细使用方法和配置说明

系统要求

• Java：≥ 21（推荐Azul Zulu JVM）
• 数据库：MariaDB 11.5.2（推荐使用容器化部署）

数据库容器化部署示例

bash
# 启动MariaDB容器
docker run --name mariadb-11.5 -p 3306:3306 -e MARIADB_ROOT_PASSWORD=mysql -d mariadb:11.5.2

# 停止并删除容器（数据将丢失，仅用于开发环境）
docker rm -f mariadb-11.5

注意：默认容器数据存储在容器内部，删除容器后数据将丢失。生产环境需配置持久化存储，详见https://hub.docker.com/_/mariadb%E3%80%82

Docker和Docker Compose部署

前提条件

• 安装Docker和Docker Compose
• （可选）Podman及Podman Compose替代方案

部署步骤

1. 克隆代码仓库

bash
# Linux/macOS
git clone https://github.com/apache/fineract.git && cd fineract

# Windows
git clone https://github.com/apache/fineract.git --config core.autocrlf=input && cd fineract

2. 构建Docker镜像

bash
./gradlew :fineract-provider:jibDockerBuild -x test

3. 安装Loki日志驱动（可选）

bash
docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

4. 启动服务栈

bash
docker compose -f docker-compose-development.yml up -d

5. 访问服务

• API服务：https://localhost:8443/fineract-provider/
• 健康检查：等待https://localhost:8443/fineract-provider/actuator/health返回`{"status":"UP"}`
• Web UI：http://localhost:9090/?baseApiUrl=https://localhost:8443/fineract-provider&tenantIdentifier=default
• 默认登录：用户名mifos，密码password

注意：首次访问需在浏览器中接受API的自签名SSL证书，否则UI可能显示误导性错误。

日志和监控

• 日志文件位置：PROJECT_ROOT/build/fineract/logs
• Java Flight Recorder输出：.jfr文件可通过IntelliJ或Azul Mission Control分析

文件权限配置

若遇到Docker Compose文件权限问题，需修改PROJECT_ROOT/config/docker/env/fineract-common.env中的FINERACT_USER和FINERACT_GROUP：

bash
# 获取当前用户ID和组ID
id -u ${USER}
id -g ${USER}

本地开发环境设置

初始化数据库

bash
./gradlew createDB -PdbName=fineract_tenants
./gradlew createDB -PdbName=fineract_default

启动开发服务器

bash
./gradlew devRun

构建JAR文件

1. 构建自包含JAR

bash
./gradlew clean bootJar

生成的JAR文件位于：fineract-provider/build/libs

2. 下载JDBC驱动

bash
wget https://dlm.mariadb.com/4174416/Connectors/java/connector-java-3.5.2/mariadb-java-client-3.5.2.jar

3. 启动JAR

bash
java -Dloader.path=. -jar fineract-provider/build/libs/fineract-provider.jar

环境变量配置（租户数据库连接）

bash
export FINERACT_HIKARI_PASSWORD=verysecret
export FINERACT_HIKARI_JDBC_URL=jdbc:mariadb://localhost:3306/fineract_tenants?serverTimezone=UTC&useLegacyDatetimeCode=false&sessionVariables=time_zone='-00:00'
# 其他环境变量...
java -jar fineract-provider.jar

数据库时区配置

Fineract 1.7.0+版本采用UTC时间存储，需确保：

• 应用运行在UTC时区（Docker镜像默认已配置）
• 数据库服务器运行在UTC时区
• JDBC连接串包含时区参数：

serverTimezone=UTC&useLegacyDatetimeCode=false&sessionVariables=time_zone='-00:00'

迁移注意：若从非UTC时区环境迁移，需调整历史数据时区偏移，避免数据读取错误。

连接池配置

通过环境变量配置Hikari连接池，前缀为FINERACT_HIKARI_*，主要参数包括：

• FINERACT_HIKARI_JDBC_URL：JDBC连接URL
• FINERACT_HIKARI_USERNAME：数据库用户名
• FINERACT_HIKARI_PASSWORD：数据库密码
• FINERACT_HIKARI_MAXIMUM_POOL_SIZE：最大连接数（默认10）
• FINERACT_HIKARI_CONNECTION_TIMEOUT：连接超时时间（默认30000ms）

完整配置参数见https://github.com/brettwooldridge/HikariCP#configuration-knobs-baby

SSL配置

详见官方文档：HTTPS配置

Tomcat配置

通过环境变量调整Tomcat性能参数，主要包括：

• FINERACT_SERVER_TOMCAT_MAX_HTTP_FORM_POST_SIZE：最大POST大小（默认2MB）

完整配置参考Spring Boot文档

Kubernetes部署

常规集群部署

bash
git clone https://github.com/apache/fineract.git && cd fineract/kubernetes
./kubectl-startup.sh

Minikube本地集群部署

bash
# 启动Minikube
minikube start

# 部署Fineract
cd fineract/kubernetes && ./kubectl-startup.sh

# 获取访问URL
minikube service fineract-server --url --https

# 健康检查
http --verify=no --timeout 240 --check-status get $(minikube service fineract-server --url --https)/fineract-provider/actuator/health

# 查看日志
kubectl logs deployment/fineract-server

# 停止并清理
./kubectl-shutdown.sh
minikube ssh
sudo rm -rf /mnt/data/

外部消息代理配置

支持ActiveMQ（JMS）和Kafka，用于外部业务事件通知和Spring Batch远程分区作业。

ActiveMQ配置

yaml
# docker-compose示例片段
environment:
  FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_ENABLED: "true"
  FINERACT_REMOTE_JOB_MESSAGE_HANDLER_SPRING_EVENTS_ENABLED: "false"
  FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_BROKER_URL: "tcp://activemq:61616"

Kafka配置

支持PLAINTEXT无认证模式及AWS MSK IAM认证，完整配置见官方文档

安全注意事项

• 发现安全漏洞请私下报告
• 开发和部署安全详情：[***]

代码规范与质量

• Checkstyle：通过config/checkstyle/checkstyle.xml定义代码规范
• Spotless：自动格式化代码，执行./gradlew spotlessApply修复格式问题
• 代码覆盖率：执行./gradlew clean build jacocoTestReport生成覆盖率报告，位于build/code-coverage

文档构建

bash
./gradlew doc

依赖工具：Ghostscript、Graphviz（详见.github/workflows/build-documentation.yml）

版本与许可证

• 最新稳定版：https://github.com/apache/fineract/tree/develop
• 变更日志：https://github.com/apache/fineract/blob/develop/CHANGELOG.md
• 许可证：Apache License Version 2.0，详见https://github.com/apache/fineract/blob/develop/APACHE_LICENSETEXT.md

API文档

• 传统API文档：/fineract-provider/legacy-docs/apiLive.htm（运行时访问）
• Swagger UI：/fineract-provider/swagger-ui/index.html（在线演示）
• 客户端代码生成：支持基于OpenAPI规范的Swagger Codegen

社区资源

• 开发者邮件列表：[***]
• JIRA任务看板：[***]
• Wiki文档：[***]
• 常见问题：[***]