Family Accounting Tool v4.29 介绍与选型指南

面向伴侣/家庭共担支出场景的开源家庭记账系统 Family Accounting Tool（facto）v4.29 的定位、架构、功能与量化选型对比指南。

Family Accounting Tool财务记账自托管2026/10/23

Family Accounting Tool v4.29 介绍与选型指南

目标：面向「伴侣/家庭共担支出」场景，介绍开源家庭记账系统 Family Accounting Tool（仓库名 facto）的定位、架构、功能与量化选型对比，帮助读者判断它是否适合自家记账需求。本文数据均来自官方仓库与生态站点，溯源查询日期为 2026-10-23。

一、环境信息

本文为认知与选型篇，全部信息来自联网溯源（来源与查询日期逐项标注），不含本地实测数据。溯源基线如下：

  • 软件：Family Accounting Tool（仓库目录名/进程名 facto）
  • 官方仓库：https://github.com/nymanjens/facto（查询日期 2026-10-23）
  • 最新稳定版：v4.29（GitHub Releases 标记为 Latest，发布于 2026-08-01；下一个标签 v4.30 发布于 2026-08-29，但仅含源码、无编译产物，不构成可安装的稳定版，来源：GitHub Releases 页与 releases.atom）
  • 开源许可：Apache-2.0（来源：仓库 LICENSE 文件与 Awesome Selfhosted 收录条目）
  • 技术栈：Scala 2.12.2 + Play Framework 2.8.20 + Slick 3.3.0 + MySQL Connector/J 5.1.36，前端为 Scala.js + React（scalajs-react 1.2.1）经 webpack 打包（来源：仓库 project/BuildSettings.scala，查询日期 2026-10-23）
  • 运行时要求：Java 11（JDK 11，来源：仓库 README「Installation from release」节）
  • 官方 Docker 镜像：nymanjens/facto（Docker Hub，latest 与 v4.29 标签均更新于 2026-08-01）
  • 社区热度：GitHub Stars 371（来源：shields.io 徽章 API，查询日期 2026-10-23）
  • 收录情况：Awesome Selfhosted「Money, Budgeting and Management」分类收录，条目描述为「Web-based finance management tool for partners with partially shared expenses」（来源：awesome-selfhosted/awesome-selfhosted 仓库 master README，查询日期 2026-10-23）

二、软件概述

Family Accounting Tool 是一个自托管的 Web 记账系统，专为「部分支出共同承担」的家庭或伴侣设计。它把家庭当成一个小型核算主体：每个成员（例如 Alice 与 Bob）有一个个人账户，家庭还有一个共同账户（Common Account），成员定期向共同账户注资（称为 Endowment，份额金），共同支出从共同账户走账。系统在此基础上完成三件核心事情（来源：仓库 README 首节，查询日期 2026-10-23）：

  1. 支出统计：从流水数据中提取有用统计，例如「我们家每个月在食品上花多少钱」；
  2. 内部债务核算：当 Alice 用私房钱垫付了全家的纸巾钱时，系统自动登记「家庭欠 Alice 一笔钱」，成员之间的相互欠款随时可查、可清算；
  3. 现金流核对（Cash Flow）：为每种支付方式（现金、银行卡等）登记实际余额，每一笔交易自动更新余额；定期数一数手里的现金，与系统计算值对账——对不上就说明有漏记的支出或暗藏的银行手续费。

该项目由作者 Jens（GitHub 用户 nymanjens）为自家记账而开发并开源维护，作者在 README 中明确说明：这是一款「要么长期重度使用、要么用一段时间就停」的工具，并提供了邮箱与 GitHub Sponsors 渠道收集反馈（来源：仓库 README「About this project」节）。相比成品化程度高的个人财务软件，它更像一把为「共担支出」场景定制的核算手术刀。

版本节奏方面：Releases 源（releases.atom）显示 2026 年 7 月至 8 月间连续发布 v4.19→v4.30 多个标签，更新频率约为每周至每两周一次，2026-08-01 的 v4.29 是当前 Latest；查询日 2026-10-23 前后约 8 周无新发布，属中等节奏维护（来源：https://github.com/nymanjens/facto/releases.atom，查询日期 2026-10-23）。

三、核心架构

Family Accounting Tool 是单体 Web 应用，一个 JVM 进程 + 一个关系型数据库即可运行。以下架构信息均来自仓库源码（标签 v4.29）与 README，查询日期 2026-10-23。

3.1 技术分层

层技术出处
后端框架Play Framework 2.8.20（Scala 2.12.2）project/BuildSettings.scala
数据访问Slick 3.3.0 + HikariCP 连接池（slick-hikaricp）project/BuildSettings.scala
数据库MariaDB/MySQL（官方推荐，README 安装节）；源码同时捆绑 H2 与 SQLite JDBC 驱动，application.conf 中的 H2 内存库配置为被注释的备选项build.sbt、conf/application.conf
前端Scala.js + React（scalajs-react 1.2.1）+ webpack（scalajs-bundler），同构共享代码放 app/sharedbuild.sbt 多项目定义
实时推送WebSocket（/websocket/hydropush/:updateToken/ 路由），前端另有 localDatabaseWebWorker.js 做本地数据缓存conf/routes（v4.29 源码）
配置体系conf/application.conf（HOCON）+ conf/accounting-config.yml（YAML，声明科目/账户/支付方式/模板/图表）仓库 conf/ 目录

3.2 进程与接口形态

从 v4.29 源码的 conf/routes 可见其 HTTP 接口分三类：

  • 页面路由：/app/* 提供 React 单页应用（登录后使用），/login/、/logout/ 处理会话认证；
  • 内部 API：/scalajsapi/*（POST/GET/WebSocket）为前端 Scala.js 专用的 RPC 通道，依赖登录会话，不对第三方承诺稳定性；
  • 外部 API：/externalapi/* 是一组带 appSecret（取值即 application.conf 中的 play.http.secret.key）鉴权的 REST 端点，覆盖健康检查、余额/流水查询、模板建账、流水增删、汇率登记与批量改名等操作，是二次开发与自动化记账的入口，全部端点的请求格式与实测响应见 《Family Accounting Tool v4.29 API 使用详解》。

启动器为发行包内的 bin/server 脚本（Play Framework 标准启动脚本），支持以 JVM 系统属性形式传入一次性运维动作：-DdropAndCreateNewDb（建表）、-DcreateAdminUser（创建初始管理员）。发行包内还附带 unix-service.sh，可作为 SysV init 服务脚本注册开机自启（来源：仓库 v4.29 根目录 unix-service.sh）。

四、功能特性

以下功能清单整理自仓库 README 与 conf/demo-accounting-config.yml（v4.29），查询日期 2026-10-23：

  • 多成员账户模型：每个家庭成员一个账户，可绑定登录用户（userLoginName），另有家庭共同账户；账户可自定义简称（shorterName/veryShortName）与默认支付方式；
  • 科目（Category）体系：按家庭消费习惯自定义科目（示例配置含 Groceries、Fun、Recurring、One-time、Income、Taxes 等 15 个），其中两类特殊科目：Accounting 科目登记「非真实收支」（如雇主报销），统计月度盈亏时自动忽略；Endowment 科目登记「向共同账户注资」；
  • 支付方式（Money Reservoir）：现金、银行卡、储蓄账户等都是 Reservoir，可分属不同成员、可指定币种（如 GBP）、可隐藏（如不希望出现在界面的储蓄账户），每笔交易必须挂到一个 Reservoir 上，从而实现逐钱包对账；
  • 现金流核对视图：为每个 Reservoir 「Set」实际余额后，系统随交易自动滚动余额；数钱核对一致可勾选确认，不一致即暴露漏账；
  • 交易模板：把重复性记账（取现、注资、工资、日常消费）做成模板，支持双腿平衡交易（zeroSum: true，如「从银行卡取现 50 到钱包」两条腿合计为零）、按登录用户选择性展示（onlyShowForUserLoginNames）、指定展示位置（现金流视图/注资视图/模板列表）与图标；
  • 预定义图表：YAML 中可声明常用图表（如「Alice 的交易趋势」），支持按月/按年聚合与针对特定查询线的绘图；
  • 内部债务与清算：成员间互欠金额自动核算，liquidationDescription 用于清算标记；
  • 多币种与汇率、通胀校正（进阶功能）：Reservoir 可挂外币，系统支持登记汇率测量值（外部 API 亦可写入），并内置「按物价指数修正通胀」的开关（supportInflationCorrections）与「财年起始月」设定（firstMonthOfYear），作者称之为较隐蔽的高级特性（来源：README「About this project」节）；
  • 附件：交易可挂附件（票据照片等），WebSocket 帧上限配置为 100M，暗示附件上传通道容量（play.server.websocket.frame.maxLength = 100M）；
  • 多语言框架：Play i18n 机制内置，v4.29 默认语言包为荷兰语（i18n.langs = ["nl"]，作者母语），界面实际以英文为主。

五、快速开始（最小可用示例）

以下流程逐条摘自官方 README（https://github.com/nymanjens/facto，查询日期 2026-10-23），是作者给出的最短可运行路径；完整依赖链、真实回显与排障实录见 《Ubuntu 22.04 安装 Family Accounting Tool v4.29 指南》 与 《Family Accounting Tool v4.29 Docker Compose 部署指南》。最小流程为：

  1. 服务器安装 Java 11（JDK 11）；
  2. 从 GitHub Releases 下载 v4.29 的「Binaries (compiled files) with demo configuration」压缩包（资产名 release-v4.29.tar.gz）并解压；
  3. 本机准备一个 MariaDB 空库 facto，在解压目录的 conf/application.conf 中按如下形式填写连接串与两个密钥值（play.http.secret.key 与 app.setup.defaultPassword 需自选）：
db.default {
  driver = com.mysql.jdbc.Driver
  url = "jdbc:mysql://localhost/facto?user=mysqluser&password=mysqlpassword"
  slick.profile = "slick.jdbc.MySQLProfile$"
}
  1. 在解压目录内依次执行三条启动命令完成建表、建初始管理员并运行：
bin/server -DdropAndCreateNewDb   # 创建数据库表
bin/server -DcreateAdminUser      # 创建 admin 用户
bin/server                        # 运行应用
  1. 浏览器访问 http://localhost:9000/app/useradministration，使用用户名 admin、密码 changeme 登录（密码由第 3 步的 app.setup.defaultPassword 决定）。

若只想先看看长什么样，官方 README 另给出一条 Docker 演示路径（拉取 nymanjens/facto:latest + mariadb:10.3 的 compose 文件，先执行建库/建用户两个一次性容器再 up）；但作者明确提示 Docker 形态适合体验，生产持久化使用建议走「Installation from release」路线（来源：仓库 README「Installation with Docker (discouraged)」节及 issue #4，查询日期 2026-10-23）。

六、适用场景与限制

6.1 适合谁用

  • 共担支出的伴侣/合租家庭：核心模型（成员账户 + 共同账户 + Endowment + 内部债务）就是为这类场景设计的，这是它区别于一般个人记账软件的最大价值；
  • 想要严格对账纪律的家庭：现金流核对视图强迫你定期数钱对账，能揪出漏记支出与银行暗扣；
  • 愿意花一小时定制 YAML 的极客家庭：科目、账户、模板、图表全部由 accounting-config.yml 声明，改配置文件即重塑系统；
  • 需要自托管与数据私有：整个系统跑在自己服务器上，数据在自家数据库里。

6.2 已知限制（避免选型踩坑）

  • 不连接银行：无银行账单自动同步，一切流水靠手动输入或经外部 API 自动化（来源：README 功能清单中无银行集成，查询日期 2026-10-23）；
  • Docker 形态被作者标注为「discouraged」：官方 compose 仅适合演示，理由见仓库 issue #4（持久化自定义配置与真实数据时应使用发行包方式）；
  • 语言包基本只有英文与荷兰语：无中文界面语言包，中文用户需接受英文界面；
  • 单机形态：Play 单体应用 + 单库，无官方集群方案，家庭规模足够，不适合多组织托管；
  • Java 11 运行时：Play 2.8 世代框架，需自备 JDK 11（新版本 Java 未获官方 README 背书）；
  • 项目为个人业余维护：作者自述按自家需求开发，重度依赖前先评估其维护活跃度（2026 年 7-8 月仍有持续发布，见第二节）。

七、同类选型对比

下表对比 Family Accounting Tool 与四款常见自托管财务/记账软件的量化维度。星数、最新发布版、许可证均通过 shields.io 徽章 API 实查（查询日期 2026-10-23）；语言栈与数据库支持来自各官方仓库/文档；官方 Docker 镜像存在性经 Docker Hub Registry API（HTTP 200 判定）实查。

维度Family Accounting Tool v4.29Firefly III v6.7.9Actual Budget v26.10.0IHateMoney v7.2.1ezBookkeeping v2.1.0
GitHub Stars（2026-10-23）37125k30k1.4k5.8k
许可证Apache-2.0AGPL-3.0MITBSD-2-ClauseMIT
技术栈Scala + Play 2.8PHP（Laravel）Node.js + ReactPython（Flask）Go + Vue
数据库MariaDB/MySQL（推荐）、H2、SQLiteMySQL/PostgreSQL/SQLite内置文件型存储（SQLite 系）SQLite/PostgreSQL/MySQLSQLite/MySQL/PostgreSQL
官方 Docker 镜像nymanjens/facto（存在，作者不推荐生产用）fireflyiii/core（存在）actualbudget/actual-server（存在）ihatemoney/ihatemoney（存在）mayswind/ezbookkeeping（存在）
银行账单自动同步无有（Data Importer 生态）有（GoCardless/SimpleFIN 通道）无无
多成员共担支出/内部债务核算核心设计（成员账户+共同账户+Endowment+清算）支持（多币种、借贷账户可模拟）部分支持（以预算包络为主）支持（共享开销分摊，轻量）弱（个人流水为主）
界面语言英文/荷兰语多语言（含中文）多语言多语言多语言（含中文）
部署重量JVM（Java 11）+ 1 库PHP + 1 库Node + 文件存储Python + 1 库Go 单二进制 + 1 库

关键差异与选型建议（来源均为上表各官方仓库，查询日期 2026-10-23）：

  • 若家里是「部分共同支出、各自也有私房钱」：Family Accounting Tool 的内部债务核算与 Endowment 模型最贴合，选它；IHateMoney 是更轻的分摊替代（适合临时拼伙，不追求逐笔对账）；
  • 若追求银行自动同步与成熟生态：选 Firefly III（功能最全）或 Actual Budget（社区最热、本地优先），Family Accounting Tool 与 ezBookkeeping 均无银行同步；
  • 若追求移动端随手记账体验：ezBookkeeping（Go 单二进制，资源占用小，移动端友好）更合适；Family Accounting Tool 的强项在核算模型而非录入速度；
  • 若在意许可证宽松度：Actual Budget 与 ezBookkeeping 为 MIT，Family Accounting Tool 为 Apache-2.0，均可商用自托管；Firefly III 的 AGPL-3.0 对二次分发的开源义务更严格；
  • 社区规模差异要正视：Family Accounting Tool 的 371 Stars 与 Firefly III（25k）、Actual Budget（30k）不在一个量级，属于「小而美」的个性化工具，遇到问题更多依赖读源码与直接联系作者，而非社区问答。

八、参考链接

  • 官方仓库：https://github.com/nymanjens/facto
  • Releases 页（Latest 为 v4.29）：https://github.com/nymanjens/facto/releases
  • releases.atom 版本源：https://github.com/nymanjens/facto/releases.atom
  • Docker 形态限制讨论（issue #4）：https://github.com/nymanjens/facto/issues/4
  • Docker Hub 镜像页：https://hub.docker.com/r/nymanjens/facto
  • Awesome Selfhosted 收录条目：https://github.com/awesome-selfhosted/awesome-selfhosted
  • 竞品仓库：Firefly III https://github.com/firefly-iii/firefly-iii；Actual Budget https://github.com/actualbudget/actual；IHateMoney https://github.com/spiral-project/ihatemoney；ezBookkeeping https://github.com/mayswind/ezbookkeeping
  • 星数/版本/许可证取证方式：shields.io 徽章 API（https://img.shields.io/github/stars/nymanjens/facto.json 等，查询日期 2026-10-23）