akopulko/ffiiitc

FireFly III 交易分类服务

镜像概述和主要用途

该Web服务用于执行交易分类，并与FireFly III（一款免费开源的个人财务管理工具）通过Web钩子集成。每当在FireFly III中添加新交易（手动或通过导入工具）时，Web钩子会触发并将交易描述发送至该服务，服务使用朴素贝叶斯分类器对交易进行分类，并更新匹配的类别。

核心功能和特性

• 自动分类机制：采用朴素贝叶斯分类器（基于https://github.com/navossoc/bayesian%E5%BA%93%EF%BC%89%E5%88%86%E6%9E%90%E4%BA%A4%E6%98%93%E6%8F%8F%E8%BF%B0%E5%B9%B6%E9%A2%84%E6%B5%8B%E7%B1%BB%E5%88%AB
• FireFly III集成：通过Web钩子实现实时交互，在交易创建后自动触发分类流程
• 个性化训练：基于用户在FireFly III中手动分类的交易数据构建模型，适配个人交易模式
• 数据持久化：训练后的模型存储在数据卷中，确保服务重启后分类能力保持

使用场景和适用范围

适用于已部署FireFly III的个人用户，需要自动分类交易类别的场景。特别适合已有部分手动分类交易数据（至少1-2条）的用户，以提供初始训练样本。

详细使用方法和配置说明

前置条件

• 运行环境：Docker Desktop或其他容器运行环境
• 依赖服务：FireFly III已按官方文档成功部署并运行
• 训练数据：至少1-2条已导入FireFly III且手动分类的交易记录（用于模型训练，必要条件）
• 访问令牌：在FireFly III中生成个人访问令牌（PAT）：进入选项->个人资料->OAuth，点击创建新令牌

Docker Compose部署

构建镜像

bash
git clone https://github.com/akopulko/ffiiitc.git
cd ffiiitc
docker buildx build --load --platform=linux/amd64 -t ffiiitc:latest .

配置服务

在FireFly III的docker-compose.yml中添加以下配置：

基础配置：

yaml
services:
  fftc:
    image: akopulko/ffiiitc:latest
    hostname: fftc
    networks:
      - firefly_iii
    restart: always
    container_name: ffiiitc
    environment:
      - FF_API_KEY=<YOUR_PAT_GOES_HERE>  # 替换为FireFly III的PAT
      - FF_APP_URL=<FIREFLY_ADDRESS:PORT>  # 替换为FireFly III的地址和端口（如http://localhost:8080）
    volumes:
      - ffiiitc-data:/app/data  # 存储训练模型
    ports:
      - '<EXPOSED_PORT>:8080'  # 替换为暴露的端口（如8081:8080）
    depends_on:
      - app  # 依赖FireFly III的app服务

volumes:
  ffiiitc-data:  # 声明数据卷

敏感信息保护（使用Docker Secrets）：

yaml
secrets:
  ffiiitc-personal-access-token:
    file: "<path/to/secrets>/ffiiitc-personal-access-token"  # 存储PAT的文件路径

services:
  fftc:
    # 其他配置同上
    secrets:
      - "ffiiitc-personal-access-token"
    environment:
      - FF_API_KEY_FILE="/run/secrets/ffiiitc-personal-access-token"  # 从secrets读取PAT
      - FF_APP_URL=<FIREFLY_ADDRESS:PORT>

启动服务

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

Docker命令运行

bash
docker run -d \
  --name='ffiiitc' \
  -e 'FF_API_KEY'='<YOUR_PAT_GOES_HERE>' \
  -e 'FF_APP_URL'='<FIREFLY_ADDRESS:PORT>' \
  -p '<EXPOSED_PORT>:8080' \
  -v '<TRAINED_MODEL_FOLDER>:/app/data:rw' \  # 本地目录映射（如./ffiiitc-data:/app/data）
  'ffiiitc'

FireFly III Web钩子配置

1. 登录FireFly III，进入自动化 -> Web钩子，点击创建新Web钩子
2. 配置参数：
   • 标题：classify
   • 触发器：交易创建后
   • 响应：交易详情
   • 传输格式：json
   • URL：http://fftc:<EXPOSED_PORT>/classify（<EXPOSED_PORT>为docker-compose中配置的暴露端口）
   • 激活：勾选

故障排除

查看日志

通过以下命令查看服务运行日志：

bash
docker compose logs fftc -f

强制训练模型

如需重新训练模型，执行以下命令后重启fftc容器：

bash
curl -i http://localhost:<EXPOSED_PORT>/train

可添加日期参数限制训练数据范围（格式yyyy-mm-dd）：

bash
curl -i "http://localhost:<EXPOSED_PORT>/train?start=2024-01-01&end=2024-06-01"

省略日期参数将使用所有可用交易数据训练。训练结果可通过日志确认。

注：朴素贝叶斯分类器使用https://github.com/navossoc/bayesian%E5%BA%93%EF%BC%8C%E8%AF%A6%E7%BB%86%E8%AE%B8%E5%8F%AF%E4%BF%A1%E6%81%AF%E8%A7%81%E5%85%B6https://github.com/navossoc/bayesian/blob/master/LICENSE%E3%80%82