Apache Fineract 1.15.0 Docker Compose 部署指南

使用 Docker Compose 一条命令部署 Apache Fineract 1.15.0 与 MariaDB 11，涵盖官方镜像的 MariaDB 驱动缺失适配、覆盖 entrypoint、数据库初始化、JVM 堆内存限定（256–512MB）、端口映射与 REST 全链路验证，并给出等价 docker run 方式。部署流程在 Ubuntu 22.04 + Docker 环境实测通过。

Apache FineractApache Fineract2026/10/11

Apache Fineract 1.15.0 Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Apache Fineract 1.15.0（开源核心银行/数字金融服务平台）与 MariaDB 数据库，涵盖官方镜像缺失 MariaDB JDBC 驱动的适配、覆盖 entrypoint、数据库初始化、JVM 堆内存限定、端口映射与 REST 全链路业务验证，并给出等价的 docker run 方式。部署流程在 Ubuntu 22.04 + Docker（Compose v2）环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Docker 版本：Docker Engine（含 Compose v2 插件）
  • 组件版本：Apache Fineract 1.15.0
  • 应用镜像：apache/fineract:latest（详见镜像选型说明）
  • 数据库镜像：mariadb:11
  • 编排目录：/opt/data/ops/fineract-compose
  • 网络：compose 项目自定义 bridge 网络 fineract-net
  • 端口映射：8443（应用 HTTPS，上下文 /fineract-provider）
  • 服务名：fineract（应用）、mariadb（数据库）
  • 默认管理员：mifos / password；租户标识固定 default
  • 数据库账号：root / q1w2e3r4
  • JVM 堆：-Xmx512m -Xms256m

二、镜像选型说明

镜像版本说明
apache/fineract:latest（本文实测）实测该标签当前为 1.16.0-SNAPSHOT（develop 分支快照，内置 JDK 25 / Zulu25.36，classpath 仅含 postgresql-42.7.13.jar）官方镜像不锁版本且不含 MariaDB 驱动，需卷挂载驱动并覆盖 entrypoint
自构建 1.15.0 镜像Apache Fineract 1.15.0由官方二进制发行包 apache-fineract-bin-1.15.0.tar.gz 构建，可精确锁定 1.15.0 与本文档版本一致（推荐生产使用）
mariadb:1111.8.9-MariaDB元数据库，需启用 utf8mb4

💡 说明：官方镜像 latest 会漂移且仅含 PostgreSQL 驱动。若要求与《Ubuntu 22.04 安装 Apache Fineract 1.15.0 指南》版本严格一致，建议以 apache-fineract-bin-1.15.0.tar.gz 自构建镜像后替换 image 字段；本文实测流程以 apache/fineract:latest 打通全链路。

三、前置条件

  • 已安装 Docker Engine 与 Docker Compose 插件：docker --version && docker compose version
  • 宿主机已规划部署目录 /opt/data/ops/fineract-compose
  • 可访问 Maven 镜像以下载 MariaDB JDBC 驱动

四、部署步骤

4.1 创建部署目录与文件清单

mkdir -p /opt/data/ops/fineract-compose
cd /opt/data/ops/fineract-compose

目录结构：

fineract-compose/
├── docker-compose.yml
├── driver/mariadb-java-client-3.5.3.jar     # 官方镜像缺失的 MariaDB 驱动
└── initdb/01-create-default-db.sql          # 初始化 fineract_default 库

4.2 准备 MariaDB JDBC 驱动

官方镜像 classpath 不含 MariaDB 驱动，需自备并卷挂载：

mkdir -p /opt/data/ops/fineract-compose/driver
cd /opt/data/ops/fineract-compose/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

实测回显：

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

4.3 数据库初始化脚本

保存为 /opt/data/ops/fineract-compose/initdb/01-create-default-db.sql：

CREATE DATABASE IF NOT EXISTS fineract_default CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
GRANT ALL PRIVILEGES ON fineract_default.* TO 'root'@'%';
FLUSH PRIVILEGES;

💡 说明：fineract_tenants 由 compose 的 MARIADB_DATABASE 环境变量创建；fineract_default 由本初始化脚本创建。两库的 schema 均由应用首次启动时 Liquibase 自动迁移。

4.4 编写 docker-compose.yml

保存为 /opt/data/ops/fineract-compose/docker-compose.yml：

services:
  mariadb:
    image: mariadb:11
    container_name: fineract-compose-db
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: fineract_tenants
      TZ: UTC
    command:
      - "--character-set-server=utf8mb4"
      - "--collation-server=utf8mb4_general_ci"
      - "--innodb-snapshot-isolation=OFF"
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d:ro
      - fineract-db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 30
    networks: [fineract-net]

  fineract:
    image: apache/fineract:latest
    container_name: fineract-compose-app
    restart: unless-stopped
    depends_on:
      mariadb:
        condition: service_healthy
    entrypoint:
      - "/bin/sh"
      - "-c"
      - "exec java -Xmx512m -Xms256m -cp /opt/driver/mariadb-java-client-3.5.3.jar:$$(cat /app/jib-classpath-file) -Duser.home=/tmp -Duser.timezone=UTC -Dfile.encoding=UTF-8 org.apache.fineract.ServerApplication"
    environment:
      FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME: org.mariadb.jdbc.Driver
      FINERACT_HIKARI_JDBC_URL: jdbc:mariadb://mariadb:3306/fineract_tenants
      FINERACT_HIKARI_USERNAME: root
      FINERACT_HIKARI_PASSWORD: q1w2e3r4
      FINERACT_DEFAULT_TENANTDB_HOSTNAME: mariadb
      FINERACT_DEFAULT_TENANTDB_PORT: "3306"
      FINERACT_DEFAULT_TENANTDB_UID: root
      FINERACT_DEFAULT_TENANTDB_PWD: q1w2e3r4
      FINERACT_DEFAULT_TENANTDB_NAME: fineract_default
      FINERACT_DEFAULT_TENANTDB_IDENTIFIER: default
      TZ: UTC
    volumes:
      - ./driver:/opt/driver:ro
    ports:
      - "8443:8443"
    networks: [fineract-net]

volumes:
  fineract-db-data:

networks:
  fineract-net:
    driver: bridge

⚠️ 注意：entrypoint 覆盖为 java -cp /opt/driver/mariadb-java-client-3.5.3.jar:$(cat /app/jib-classpath-file) ... org.apache.fineract.ServerApplication，将 MariaDB 驱动前置到 classpath，并以 -Xmx512m -Xms256m 限定 JVM 堆。$$(...) 中的双美元符用于在 compose 层转义 shell 命令替换。

4.5 启动

cd /opt/data/ops/fineract-compose
docker compose up -d

实测回显：

 Network fineract-compose_fineract-net Created
 Volume fineract-compose_fineract-db-data Created
 Container fineract-compose-db Created
 Container fineract-compose-app Created
 Container fineract-compose-db Started
 Container fineract-compose-db Waiting
 Container fineract-compose-db Healthy
 Container fineract-compose-app Started

查看服务状态：

docker compose ps

实测回显：

NAME                   IMAGE                    SERVICE   STATUS                    PORTS
fineract-compose-app   apache/fineract:latest   fineract  Up                        0.0.0.0:8443->8443/tcp
fineract-compose-db    mariadb:11               mariadb   Up (healthy)              3306/tcp

4.6 启动日志与健康检查

docker compose logs fineract | grep -E 'Tomcat started|Started ServerApplication'

实测回显：

2026-10-11 12:59:51.075 - INFO 1 [default] --- [main] TomcatWebServer : Tomcat started on port 8443 (https) with context path '/fineract-provider'
2026-10-11 12:59:51.081 - INFO 1 [default] --- [main] ServerApplication : Started ServerApplication in 114.875 seconds (process running for 115.404)

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

实测回显：

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

4.7 REST 业务验证

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

管理员登录：

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}

新建客户：

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":"Compose","lastname":"Client",
  "externalId":"CLI-CMP-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-CMP-001"}

新建贷款产品：

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":"Compose Loan","shortName":"CMPL","currencyCode":"USD",
  "digitsAfterDecimal":2,"inMultiplesOf":0,"principal":2000,"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}

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

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":2000,"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（状态 200 Approved）与 command=disburse（状态 300 Active）完成审批与放款。

4.8 验证堆参数与数据库版本

应用进程堆参数：

docker exec fineract-compose-app sh -c 'cat /proc/1/cmdline | tr "\0" " "'

实测回显：

java -Xmx512m -Xms256m -cp /opt/driver/mariadb-java-client-3.5.3.jar:... org.apache.fineract.ServerApplication

数据库版本与字符集：

docker exec fineract-compose-db mariadb -uroot -pq1w2e3r4 -N -e "SELECT VERSION(); SHOW VARIABLES LIKE 'character_set_server';"

实测回显：

11.8.9-MariaDB-ubu2404
character_set_server  utf8mb4

结论：Docker Compose（MariaDB 11.8.9 + Fineract 镜像）一键部署成功，宿主机 :8443 健康检查 UP，业务链路（登录/建客户/建贷款产品/建贷款账户/放款）全部通过。

五、数据持久化说明

  • fineract-db-data 命名卷持久化 MariaDB 数据目录 /var/lib/mysql，容器重建后库数据保留。
  • initdb/ 目录以只读挂载到 /docker-entrypoint-initdb.d，仅在数据卷为空（首次初始化）时执行。

💡 说明：若需将数据库文件落到宿主机指定路径，可将命名卷替换为绑定挂载，如 - ./data/db:/var/lib/mysql，并确保宿主机目录属主与容器内 mysql 用户一致。

六、常用环境变量表

环境变量实测值说明
FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAMEorg.mariadb.jdbc.Driver数据源驱动类
FINERACT_HIKARI_JDBC_URLjdbc:mariadb://mariadb:3306/fineract_tenants租户库连接串（服务名 mariadb）
FINERACT_HIKARI_USERNAME / FINERACT_HIKARI_PASSWORDroot / q1w2e3r4数据源账号
FINERACT_DEFAULT_TENANTDB_HOSTNAME / _PORTmariadb / 3306默认租户库地址
FINERACT_DEFAULT_TENANTDB_NAMEfineract_default默认租户库名
FINERACT_DEFAULT_TENANTDB_IDENTIFIERdefault租户标识
MARIADB_ROOT_PASSWORDq1w2e3r4MariaDB root 密码
MARIADB_DATABASEfineract_tenants初始创建的租户库
TZUTC时区

七、常用配置参数说明

配置说明
image: mariadb:11数据库镜像
command: --character-set-server=utf8mb4强制服务器字符集 utf8mb4
command: --innodb-snapshot-isolation=OFF关闭快照隔离（规避迁移期锁表问题）
entrypoint: java -cp <driver>:$(cat /app/jib-classpath-file)将 MariaDB 驱动前置到 classpath
-Xmx512m -Xms256mJVM 堆限定（256–512MB）
ports: "8443:8443"应用 HTTPS 端口映射
depends_on: condition: service_healthy等待数据库健康后再启动应用

更多参数见《Apache Fineract 1.15.0 配置参数详解》。

八、等价 docker run 运行方式

不加 Compose，可用单条 docker run 启动应用：

docker run -d --name fineract-compose-app --network fineract-net \
  -p 8443:8443 \
  -v /opt/data/ops/fineract-compose/driver:/opt/driver:ro \
  -e FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME=org.mariadb.jdbc.Driver \
  -e FINERACT_HIKARI_JDBC_URL='jdbc:mariadb://mariadb:3306/fineract_tenants' \
  -e FINERACT_HIKARI_USERNAME=root -e FINERACT_HIKARI_PASSWORD=q1w2e3r4 \
  -e FINERACT_DEFAULT_TENANTDB_HOSTNAME=mariadb -e FINERACT_DEFAULT_TENANTDB_PORT=3306 \
  -e FINERACT_DEFAULT_TENANTDB_UID=root -e FINERACT_DEFAULT_TENANTDB_PWD=q1w2e3r4 \
  -e FINERACT_DEFAULT_TENANTDB_NAME=fineract_default -e FINERACT_DEFAULT_TENANTDB_IDENTIFIER=default \
  --entrypoint "/bin/sh" apache/fineract:latest \
  -c "exec java -Xmx512m -Xms256m -cp /opt/driver/mariadb-java-client-3.5.3.jar:\$(cat /app/jib-classpath-file) -Duser.home=/tmp org.apache.fineract.ServerApplication"

💡 说明：--network fineract-net 需先创建 bridge 网络（docker network create fineract-net），并先以 mariadb:11 启动名为 mariadb 的数据库容器。

九、常用运维命令

# 停止并移除容器（保留数据卷）
cd /opt/data/ops/fineract-compose
docker compose down

# 停止并连带移除数据卷
docker compose down -v

# 后台启动
docker compose up -d

# 查看应用日志
docker compose logs -f fineract

# 重启服务
docker compose restart fineract

十、常见问题（FAQ）

Q1：应用启动报找不到 MariaDB 驱动 / No suitable driver。

官方镜像 classpath 仅含 postgresql 驱动。需卷挂载 mariadb-java-client-3.5.3.jar 并覆盖 entrypoint，将其前置到 classpath。

Q2：迁移报 Incorrect string value '\xE2\x82\xA1'。

数据库字符集不是 utf8mb4。确认 command 中带 --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci，并保证 initdb 脚本以 utf8mb4 建库。

Q3：应用在数据库就绪前启动导致连接失败。

depends_on 已配置 condition: service_healthy，等待 healthcheck.sh --connect --innodb_initialized 通过后再启动应用。

Q4：$$(cat /app/jib-classpath-file) 未展开。

compose 中 $ 需转义为 $$；若在 shell 直接执行 docker run，改用 \$(...)。

十一、参考链接

  • 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 配置参数详解》《Apache Fineract 1.15.0 常用 CLI 命令与工具详解》。