Fava 1.30.16 介绍与选型指南

目标：本篇是 Fava（Beancount Web 界面）的认知入口——讲清它是什么、在 Beancount 生态中处于什么位置、核心架构与功能特性、与 Firefly III/GnuCash/hledger 等同类记账工具相比值不值得选。本篇为纯认知篇，全部数据于 2026-10-23 通过官方渠道联网溯源取得（来源与查询日期逐项标注，见"一、环境信息"），未做本机实测；部署实操、配置与命令实测见本专栏后续各篇。

一、环境信息

本篇为认知篇，不依赖本机实验环境。下列信息全部于 2026-10-23 通过官方渠道联网实查取得，正文引用处均标注来源：

💡 说明：版本号以官方 GitHub Releases 为准。查询日（2026-10-23）当天最新稳定条目为 v1.30.16；本专栏全部 5 篇文档统一以该版本为基准。GitHub 上另有一条 "Nightly" 自动构建发布通道，属滚动构建不属稳定版，选型时应避开。

二、软件概述

Fava 是复式记账工具 Beancount 的官方 Web 界面，由 Beancount 组织（beancount/fava）同一团队维护，定位是"给纯文本账本一个可视化的驾驶舱"：账本仍是一个或多个 .beancount 纯文本文件（版本可 git 管理、可用任何编辑器编辑），Fava 负责把它实时渲染成损益表、资产负债表、日记账等报表，并提供查询、编辑、导入、校验等日常操作入口。

💡 技术拓展：复式记账（Double-Entry Bookkeeping）不止 Beancount 一种实现，常见流派对比——

流派	代表工具	记账载体	特点
纯文本复式记账	Beancount、ledger、hledger	.beancount/.ledger 纯文本文件	版本可控、透明可审计，门槛在学习语法
数据库型复式记账	Firefly III、Bigcapital、GnuCash	MySQL/PostgreSQL/嵌入式数据库	表单式录入、上手快，数据在库内不可直接读
云同步型复式记账	Actual Budget	本地 SQLite + 端到端加密同步	强调预算与多端同步
单式记账	ezBookkeeping、Firefly III 也可单式	数据库	只记流水，不要求每笔借贷平衡

Fava 本身不做账——账本数据的解析、平衡校验全部由 Beancount 引擎完成；Fava 只做展示与交互。本文选 Beancount + Fava 组合，理由：账本即纯文本、引擎校验严格（任何一笔不平的交易都无法通过校验），适合希望"记账数据像代码一样管理"的用户。

理解 Fava 的三个关键词：

• 零数据库：Fava 与 Beancount 都不使用数据库，账本就是文本文件；备份等于备份文件，迁移等于拷贝文件。
• 实时重载：账本文件被编辑器修改保存后，Fava 检测到变化即自动重新加载（底层用 watchfiles 监听），无需重启服务。
• 单用户无认证：Fava 自身没有登录/多用户体系（有 --incognito 数字遮挡与 --read-only 只读模式，但没有账号密码），公网部署必须配合反向代理加 Basic Auth 等外部认证。

三、核心架构

Fava 是一个典型的"Python 后端 + 前端单页应用（SPA）"两层结构，与 Beancount 引擎同进程协作：

浏览器（Svelte SPA 前端）
   │  HTML 首屏 + JSON API（/api/income_statement 等）
   ▼
Fava Web 服务（Flask + Cheroot，Python 单进程）
   │  实时加载 / 文件监听（watchfiles）
   ▼
Beancount 引擎（beancount 3.x + beanquery 查询引擎）
   │  解析、复式平衡校验、BQL 查询
   ▼
账本文件（*.beancount 纯文本，可 include 拆分多文件）

各层职责与实测证据（依据 2026-10-23 官方仓库与文档溯源）：

• 前端 SPA：Fava 1.30 起前端由 Svelte 框架构建（官方 Changelog v1.30 明确记载 "upgrades Svelte"），页面数据不再由服务端模板渲染，而是浏览器加载首屏后通过 JSON 接口取数——这解释了为什么用 curl 抓取报表页 HTML 时只能看到薄薄一层壳。
• Web 服务层：基于 Flask 与 Cheroot（Python WSGI 服务器），单进程即可服务；启动日志固定输出一行 Starting Fava on http://0.0.0.0:5000。
• 查询引擎：1.30 起 BQL 查询由独立的 beanquery 包提供（Changelog v1.30："Beancount query support is now provided by the beanquery package"），Fava 网页里的 Query 页与命令行 bean-query 共用同一引擎。
• 兼容性边界：自 v1.30.13（2026-05-19）起 Fava 放弃 Beancount v2 支持（Changelog 明确 "drops support for Beancount version 2"），导入器需迁移到 beangulp——选型时必须装 Beancount 3.x，本专栏统一使用 beancount 3.2.3。

四、功能特性

依据官方文档站与 Changelog 归纳（2026-10-23 溯源），Fava 的功能围绕"账本的日常使用闭环"展开：

💡 说明：Fava 的表格导出依赖 fava[excel] extra（官方文档安装节说明），未安装时页面导出 Excel 的能力不可用（服务端元数据 have_excel: false）。需要 Excel 导出时用 pip install "fava[excel]" 安装。

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

以下给出从安装到看到报表的最短路径（命令与回显为 v1.30.16 真实安装形态，完整逐步实测见本专栏 B1 篇）：

# 1. 安装（推荐 pipx，官方文档推荐方式）
pipx install fava
# 输出要点：installed package fava 1.30.16, installed using Python 3.10.12

# 2. 准备最小账本 hello.beancount
cat > hello.beancount <<'EOF'
option "title" "我的第一本账"
option "operating_currency" "CNY"

2026-01-01 open Assets:Bank
2026-01-01 open Expenses:Food

2026-01-12 * "超市" "周末采购"
  Expenses:Food  386.50 CNY
  Assets:Bank
EOF

# 3. 启动
fava -H 0.0.0.0 -p 5000 hello.beancount
# 输出：Starting Fava on http://0.0.0.0:5000

浏览器访问 http://<服务器IP>:5000/，会 302 重定向到 /<账本标题>/income_statement/——注意 Fava 的账本 URL 取自账本里 option "title" 的值而非文件名。至此账本、报表、编辑器全部就绪。

六、适用场景与限制

适合的场景：

• 个人/家庭长期记账，希望账本进 git、可 diff、可审计的用户；
• 已在使用 Beancount/ledger 文本账本、需要补一个可视化与查询层的用户；
• 需要在自有服务器上掌握全部数据、不愿把账目交给第三方 SaaS 的用户；
• 有批量导入需求（银行账单 CSV/OFX → beangulp 导入器）且愿意写少量 Python 配置的用户。

限制与注意（选型前必须知晓）：

1. 无内置认证：没有账号体系，公网部署必须自配反向代理认证（Basic Auth / OAuth2 Proxy 等），这一点与 Firefly III 自带登录形成鲜明对比。
2. 单用户：不支持多用户隔离，一个 Fava 实例服务一本（或几本）账。
3. 录入门槛：账本语法（open/balance/交易平衡规则）有学习成本，表格录入能力弱于数据库型工具；Fava 网页端的新增交易是辅助，主力录入仍是文本编辑。
4. 不直连银行：银行账单获取完全依赖导入器生态，无自动拉取。
5. Python 3.10+：服务器需 Python ≥ 3.10（PyPI requires_python），Ubuntu 20.04 自带 3.8 不满足，需先装新 Python。

七、同类选型对比（量化）

2026-10-23 经 shields.io 徽章与官方渠道实查的同类工具量化对比：

选型解读：

• 要数据库表单式记账 + 多用户登录 → Firefly III（社区最大、功能全）或 Actual Budget（更现代的预算体验）；两者 stars 是 Fava 的 10 倍量级，本质是"数据库记账"赛道的头部。
• 要桌面离线记账 → GnuCash，无需服务器。
• 要纯文本账本 → Beancount+Fava、hledger+hledger-web、ledger 三选一：ledger 无 Web 界面纯 CLI；hledger 是 Haskell 单二进制；Beancount+Fava 的差异化在于最严格的复式校验（balance 断言、引擎级平衡检查）、BQL 查询语言与 Python 导入器生态，且 MIT 许可对二次开发最友好。
• Fava 的定位：它不是"入门记账 App"，而是"账本工程师的工作台"——接受文本账本的门槛，换取完全的数据主权与可审计性。

八、参考链接

1. Fava 官网与文档：https://beancount.github.io/fava/
2. Fava 源码仓库：https://github.com/beancount/fava/
3. Fava Changelog：https://beancount.github.io/fava/changelog.html
4. PyPI 项目页（版本与 Python 要求）：https://pypi.org/project/fava/
5. Beancount 官方文档：https://beancount.github.io/docs/
6. 本专栏部署实测篇：《Ubuntu 22.04 安装 Fava 1.30.16 指南》
7. 本专栏容器化部署篇：《Fava 1.30.16 Docker Compose 部署指南》