ezbookkeeping 2.1.0 介绍与选型指南

目标：面向准备自托管个人记账服务的读者，完整介绍 ezBookkeeping v2.1.0 的定位、架构、功能、同类横向对比与选型建议。本文全部信息于 2026-10-23 通过官方渠道联网溯源核实，来源包括 GitHub 官方仓库（mayswind/ezbookkeeping）、官方文档站（ezbookkeeping.mayswind.net）、官方 Releases 页、Docker Hub 与 shields.io 徽章接口，关键数据均在文中标注来源与查询日期。

一、环境信息

本文为认知与选型篇，基于官方公开渠道联网溯源编写，未混入任何推测数据。溯源渠道清单如下：

目标软件关键版本信息（来源：官方 Releases 页，查询日期 2026-10-23）：

• 最新稳定版：v2.1.0，发布于 2026-10-15，对应 commit ff168cf；
• 开源协议：MIT License；
• 开发方：MaysWind（个人开发者），仓库自 2020 年持续开发至今；
• 官方在线演示站：https://ezbookkeeping-demo.mayswind.net 。

二、软件概述

2.1 项目定位

ezBookkeeping（仓库名 ezbookkeeping，程序名 ezBookkeeping）是一个开源、强大、易用的自托管个人记账应用。官方 README 的定位描述为：帮助用户记录日常收支、从多种来源导入数据、快速检索与筛选账单，可使用内置图表分析历史数据，或在 Insights Explorer 中用自定义维度出图；部署极简，"一条 Docker 命令即可启动"；资源占用经过专门优化，可在家庭服务器、NAS、树莓派等低功耗设备上流畅运行（来源：官方 README，查询日期 2026-10-23）。

它的几个鲜明标签：

• 单二进制交付：Go 编译的单一可执行文件内嵌全部前端资源，解压即用；
• 移动优先的双端 UI：桌面版基于 Vuetify，移动版基于 Framework7，均为原生体验的独立界面（非响应式缩放），并支持 PWA 添加到手机主屏；
• 低资源占用：官方对比实测中，空闲内存占用约 25 MiB 量级（详见第七章量化对比）。

2.2 版本演进与发布节奏

官方 Releases 页版本清单（查询日期 2026-10-23）：

从节奏看，该项目 2026 年内保持约 1~2 个月一个功能版本的活跃发布频率，且 v1.x → v2.x 的跨代升级在 2026 年 9 月完成，属于维护非常活跃的阶段。

2.3 v2.1.0 版本要点

官方 v2.1.0 Release Notes（来源：GitHub Releases，查询日期 2026-10-23）关键内容：

• [Breaking] 配置节 llm 更名为 ai：从 v2.0.x 升级时必须同步修改配置文件中的 LLM 相关配置节名（详见本文档体系中的配置篇）；
• 交易日历组件的每日总额默认改为「总流入 / 总流出」口径；
• 导入交易时单条失败不再回滚整批导入；
• 新增功能：波兰语翻译；Insights Explorer 支持 AI 生成自定义图表；新增账户未勾对交易组件；新增白俄罗斯央行、意大利央行、马来西亚央行三个汇率数据源；支持为总览页设置默认交易标签筛选；提供 FreeBSD 预编译包；
• 修复：修复夏令时时区定时交易日期错误、TOTP 验证码可并发复用、DSV 逗号小数坐标导入错误等多处问题。

三、核心架构

3.1 技术栈构成

3.2 部署形态

ezBookkeeping 是一个自包含的 Web 服务进程，不依赖外部中间件即可运行（默认 SQLite + 本地文件存储）。官方支持四种部署形态（来源：官方文档站 Installation 章节，查询日期 2026-10-23）：

1. 二进制直接运行：下载 Release 包解压，./ezbookkeeping server run；
2. systemd 托管：官方提供 service 单元样例，适合裸机/虚拟机长期运行；
3. Docker / Docker Compose：官方镜像 mayswind/ezbookkeeping，支持 linux/amd64、linux/arm64、linux/arm/v6、linux/arm/v7 四种平台（官方 README）；
4. Kubernetes 与 1Panel：官方文档提供 K8s 安装章节，1Panel 为社区支持方式。

进程内部结构：单一进程内包含 Web 服务、静态资源服务、API 服务、定时任务调度器（清理过期令牌、创建定时交易）与对象存储客户端，无独立 worker 进程。

3.3 账务模型

ezBookkeeping 采用「账户余额 + 收付流水」模型：账户（现金、储蓄卡、信用卡、负债等 9 类）维护余额，交易分为余额修改、收入、支出、转账四类，分类强制两级（父分类 + 子分类），每笔交易可挂标签、图片与地理位置。它不是 GnuCash/Beancount 那种严格复式记账软件（无借贷分录概念），属于面向个人日常记账的轻量模型（来源：官方文档功能对比页与 API 数据结构，查询日期 2026-10-23）。

💡 技术拓展：个人记账软件常见的两类账务模型对比——

模型	原理/特点	代表软件	适用人群
收付流水式	账户记余额、交易记收支/转账，录入成本低	ezBookkeeping、钱迹类手机 App	日常快速记账
复式记账式	每笔交易借贷两侧平衡，严谨可审计	GnuCash、Beancount、Ledger	财务精细管控、能接受录入门槛
预算管理式	以预算/信封分配为核心组织收支	Actual Budget	强预算控制诉求

ezBookkeeping 选择收付流水式，理由是面向「随手记一笔」的移动端高频场景；需要严格复式审计的读者应选 GnuCash/Beancount 类工具。

3.4 数据库选型空间

官方支持三种数据库，默认 SQLite（来源：官方配置文档与官方 Docker 安装文档）：

💡 技术拓展：三种后端数据库的取舍——

数据库	运维成本	性能/并发	适用场景
SQLite	零运维，单文件	单机读写，高并发弱	单用户/家庭自用、NAS、树莓派
MySQL / MariaDB	需维护实例	高并发、可远程	家庭多用户、已有 MySQL 栈
PostgreSQL	需维护实例	高并发、功能强	已有 PG 栈或追求更强数据能力

官方明确建议：SQLite 仅用于测试目的，正式使用推荐 MySQL 或 PostgreSQL 以获得更好的性能与稳定性（来源：官方 Docker 安装文档 TIP，查询日期 2026-10-23）。

四、功能特性

以下功能清单整理自官方 README 功能列表与官方功能对比页（查询日期 2026-10-23）：

4.1 记账核心

• 两级分类（父分类 + 子分类），支持内置图标与颜色；
• 每笔交易支持：时间（精确到秒）、时区、10 个标签、9 张图片、地理位置与地图展示、备注；
• 账户支持两级（父账户 + 子账户）、9 种账户类型、信用卡账单日与账单周期筛选；
• 定时交易（模板周期自动记账）、交易模板、自动保存草稿；
• 高级筛选、搜索与可视化分析，Insights Explorer 支持自定义图表维度。

4.2 导入导出

• 导出：CSV / TSV（命令行与界面均可）；
• 导入：除 ezBookkeeping 自有格式外，支持 OFX、QFX、QIF、IIF、Camt.052/053、MT940、GnuCash XML、Firefly III 导出文件、Beancount、随手记（Feidee）三种格式、支付宝（App/Web）、微信账单、京东金融账单等约 18 类来源；CSV/Excel 支持「列映射」与「自定义 JavaScript 脚本」两种处理方式（来源：官方 Export & Import 文档）。

4.3 AI 与 MCP 集成（v2 系列主打）

• 文本识别记账：粘贴一段消费描述文字，由 LLM 解析为交易；
• 票据图片识别记账：拍照小票直接生成交易；
• Insights Explorer 编码助手：用 AI 生成自定义图表脚本；
• 内置 MCP（Model Context Protocol）服务器：AI 客户端可直接读写账本；
• 支持 9 类 LLM 提供方：OpenAI、OpenAI 兼容接口、Anthropic、Anthropic 兼容接口、OpenRouter、Ollama、LM Studio、Google AI 等（来源：官方配置文档 [ai] 配置节）。

4.4 安全与多用户

• 两步认证（2FA，TOTP）、OIDC/Nextcloud/Gitea/GitHub OAuth2 外部登录；
• 登录限速（每 IP/每用户每分钟失败上限）、应用锁（PIN 码 / WebAuthn）；
• 20 个位的功能限制开关（可禁止某用户导出、导入、生成 API Token、使用 MCP 等）；
• API Token（Bearer Token 访问 HTTP API）。

4.5 本地化

• 多语言（含简繁中文）、多币种、多时区；
• 汇率数据源：官方配置支持 16 家央行数据源（欧洲央行、俄罗斯央行、瑞士央行等）+ 用户自定义汇率，自动更新；
• 日期/数字/货币显示格式可自定义。

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

以下为官方 README 与官方文档站给出的最小启动方式（来源：官方 README 与 Installation 文档，查询日期 2026-10-23；完整安装流程见安装部署篇）：

方式一：Docker 单命令

# 官方最新稳定版镜像，默认监听 8080 端口（官方 README 原文命令）
$ docker run -p8080:8080 mayswind/ezbookkeeping

方式二：二进制直接运行

# 从 https://github.com/mayswind/ezbookkeeping/releases 下载最新包，解压后执行（官方 README 原文命令）
$ ./ezbookkeeping server run

启动后通过浏览器访问 http://{服务器地址}:8080/ 即可进入注册页面。官方文档说明：首次运行时系统不会自动创建任何用户，需要在注册页自行注册（注册时仅需选择语言、默认货币与每周起始日），登录后先创建账户（现金、储蓄卡等）即可开始记账（来源：官方 Basic Usage 文档）。

v2.x 系统要求（来源：官方 System Requirements 文档，查询日期 2026-10-23）：

六、适用场景与限制

6.1 适合的场景

1. NAS / 树莓派 / 家庭服务器轻量自托管：官方对比实测空闲内存约 25 MiB、镜像 57.7 MiB（v1.3.2 实测数据，见第七章），对硬件几乎无要求；
2. 手机随手记账：独立移动版 UI + PWA + 小票拍照 AI 识别 + 地理位置，移动体验是同类开源产品中最完整的一档；
3. 从其他记账工具迁移：支持支付宝/微信账单直接导入，以及 Firefly III、GnuCash、Beancount、随手记等格式迁移；
4. AI 工作流集成：内置 MCP 服务器与 API Token，可接入 AI 客户端做自然语言记账与查询。

6.2 明确的限制（官方功能对比页自述）

• 不支持拆分交易（一笔交易拆多类目）；Firefly III 与 Actual Budget 均支持；
• 不支持任意附件，仅支持交易图片（最多 9 张）；
• 无「无服务器模式」（Actual Budget 支持）；
• 每笔交易最多 10 个标签；
• 官方建议 SQLite 仅用于测试，生产推荐 MySQL/PostgreSQL。

七、同类选型对比

7.1 对比对象与口径

选择个人自托管记账领域最常用的两个竞品：Firefly III（PHP，功能最全的传统强项）与 Actual Budget（TypeScript，预算管理派代表）。对比表主体引用官方对比文档（https://ezbookkeeping.mayswind.net/comparison/ ，官方标注对比时间为 2026 年 1 月，对比版本 ezBookkeeping v1.3.2 / Firefly III v6.4.16 / Actual Budget v26.1.0）；社区活跃度数据为本文于 2026-10-23 通过 shields.io 实查的最新值。

7.2 基本信息对比（官方对比文档，2026-01）

关键差异：ezBookkeeping 是三者中唯一同时支持「三种数据库 + 四种对象存储 + AI/MCP + 多地图/汇率源」的，且 MIT 协议对二次分发最宽松（Firefly III 为 AGPL，商用分发需注意传染性）。

7.3 性能量化对比（官方对比文档，2026-01，树莓派 4 实测）

官方测试环境：Raspberry Pi 4（4 GiB 内存，系统盘 USB 外接 Samsung SSD 980），Debian 11，均使用支持 arm64 的官方最小镜像与默认配置，每项测 5 次去高低取 3 次均值：

解读：在资源占用维度 ezBookkeeping 全面领先——镜像体积约为 Firefly III 的 1/14、Actual 的 1/3；空闲内存约为 Firefly III 的 1/3、Actual 的 1/5；启动速度快一个数量级。这是 Go 单二进制 + 内嵌前端架构的直接收益，也是「NAS/树莓派选型」场景的决定性优势。

7.4 功能能力对比要点（官方对比文档，2026-01）

解读：ezBookkeeping 的强项在「记账记录本身的颗粒度」（时间/时区/图片/位置/两级分类）与移动体验；Firefly III 的强项在「财务规则自动化」（规则引擎、拆分交易、利息日期等多日期体系）；Actual Budget 的强项在预算管理与无服务器模式。三者定位差异清晰。

7.5 社区活跃度（2026-10-23 实查，shields.io）

解读：ezBookkeeping 星数绝对值低于两个竞品，但 2026 年内 8 个版本的发布密度、941k 的 Docker 拉取量与 v2.x 的活跃演进表明其社区处于快速成长期；中文原生支持与国内账单（支付宝/微信/京东）直接导入是它对中文用户独有的加分项。

7.6 选型建议

• 如果你的设备是 NAS / 树莓派 / 小内存 VPS，追求低资源占用与手机随手记体验 → ezBookkeeping；
• 如果你需要 规则引擎自动化、拆分交易、多日期财务体系，且不介意 PHP 栈与更高资源占用 → Firefly III；
• 如果你以 预算管理（信封制） 为核心诉求、需要无服务器/局域网优先模式 → Actual Budget；
• 如果你要 AI 识别记账 / MCP 集成 / 自定义图表 → 目前三者中只有 ezBookkeeping 内置这些能力；
• 如果你需要 严格复式记账 → 三者都不合适，考虑 GnuCash / Beancount。

八、参考链接

1. GitHub 官方仓库：https://github.com/mayswind/ezbookkeeping （查询日期 2026-10-23）
2. 官方文档站：https://ezbookkeeping.mayswind.net （查询日期 2026-10-23）
3. 官方功能对比页：https://ezbookkeeping.mayswind.net/comparison/ （对比时间 2026-01，查询日期 2026-10-23）
4. v2.1.0 Release Notes：https://github.com/mayswind/ezbookkeeping/releases/tag/v2.1.0 （查询日期 2026-10-23）
5. 官方系统要求：https://ezbookkeeping.mayswind.net/installation/system_requirements （查询日期 2026-10-23）
6. Docker Hub 镜像页：https://hub.docker.com/r/mayswind/ezbookkeeping （查询日期 2026-10-23）
7. 官方在线演示：https://ezbookkeeping-demo.mayswind.net （查询日期 2026-10-23）
8. shields.io 徽章接口（星数/拉取量/竞品版本实查）：https://img.shields.io （查询日期 2026-10-23）

站内关联阅读（部署与运维四部曲）：《Ubuntu 22.04 安装 ezbookkeeping 2.1.0 指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 配置参数详解》、《ezbookkeeping 2.1.0 常用 CLI 命令与工具详解》。