benkl/firefly-iii-fints-importer

firefly-iii-fints-importer 镜像文档

镜像概述

本工具允许您从FinTS兼容银行导入交易到Firefly III，并提供Web GUI引导整个导入流程。

核心功能与特性

• FinTS银行交易导入：支持从FinTS兼容银行获取财务交易数据
• Web界面引导：直观的Web GUI简化配置与导入过程
• 配置持久化：支持JSON配置文件存储账户信息，避免重复输入
• 无头模式支持：可通过curl或wget实现无浏览器自动化导入
• 交易描述优化：支持正则表达式替换交易描述，自定义显示格式

使用场景

适用于已部署Firefly III的用户，需要将FinTS兼容银行的交易数据自动导入Firefly III进行统一财务管理与分析。

系统要求

• 运行环境：Docker 或（PHP 8.1+ 及 Composer）
• Firefly III：已运行的Firefly III实例
  • 需通过网络被本工具访问
  • 需准备Firefly III个人访问令牌（在个人资料页生成）

使用方法

启动方式

方法1：直接运行（非Docker）

bash
git clone https://github.com/bnw/firefly-iii-fints-importer.git
cd firefly-iii-fints-importer
composer install
php -S 0.0.0.0:8080 app/index.php

方法2：使用Docker Compose（推荐）

bash
git clone https://github.com/bnw/firefly-iii-fints-importer.git
cd firefly-iii-fints-importer
docker-compose up

更新镜像：

bash
docker-compose pull && docker-compose up

方法3：本地构建镜像

修改docker-compose.yml文件，将image: benkl/firefly-iii-fints-importer替换为build: .，然后执行：

bash
git clone https://github.com/bnw/firefly-iii-fints-importer.git
cd firefly-iii-fints-importer
docker-compose up

（构建过程通常需要几分钟）

访问与操作

启动后，访问 http://localhost:8080 并按照Web界面指引完成导入配置。

配置说明

存储配置文件

1. 在data/configurations目录下创建JSON配置文件（参考https://github.com/bnw/firefly-iii-fints-importer/blob/master/data/configurations/example.json%EF%BC%89
2. 启动Web界面后，选择该配置文件加载账户信息
3. 注意：JSON文件中的bank_2fa值对应Web界面中2-factor authentication选项的编号

无头模式配置

通过命令行工具（如curl或wget）执行自动化导入：

bash
# 使用curl
curl -X GET 'http://localhost:8080/?automate=true&config=example.json'

# 使用wget
wget -O - -q 'http://localhost:8080/?automate=true&config=example.json'

参数说明：

• automate=true：启用无头模式
• config=example.json：指定配置文件（位于data/configurations目录）

需确保配置文件中已正确设置choose_account_automation选项

提示

• 交易历史限制：银行通常仅提供最近两年的交易数据。为确保Firefly III中账户余额准确，需在Firefly III中调整账户起始余额。
• 描述自定义：支持通过正则表达式搜索替换交易描述，配置示例见https://github.com/bnw/firefly-iii-fints-importer/blob/master/data/configurations/example.json%E6%88%96https://github.com/bnw/firefly-iii-fints-importer/blob/master/tests/TransactionsToFireflySenderTest.php%E3%80%82

注意事项

• 登录安全：多次FinTS登录失败可能导致银行账户锁定，需联系银行进行解锁操作。
• ING DiBa用户：根据相关 wiki，需每90天登录一次银行网站以维持FinTS访问权限。

截图

!https://raw.githubusercontent.com/bnw/firefly-iii-fints-importer/master/docs/img/screenshots.gif

反馈

本工具测试范围有限，如您的银行不兼容，请https://github.com/bnw/firefly-iii-fints-importer/issues/new%E3%80%82