Fava 1.30.16 配置参数详解

Fava 1.30.16 三层配置体系实测详解：fava_options 全量默认值快照、custom "fava-option" 指令逐项验证（语言/默认页/未过期指示器）、fava 启动参数与 FAVA_* 环境变量、--prefix 多账本前缀与 --incognito 隐身模式行为，附配置不生效排查思路。

Fava财务记账配置2026/10/23

Fava 1.30.16 配置参数详解

目标：讲清 Fava 1.30.16 的三层配置体系——账本内的 Beancount option 指令、账本内的 custom "fava-option" 指令、fava 命令行参数与环境变量——逐项给出语法、真实默认值与实测验证结果。全部配置项均在 Ubuntu 22.04 + Fava 1.30.16 环境实测（配置改动后通过服务端元数据 JSON 或行为验证确认生效）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS，Python 3.10.12
  • 组件版本：fava 1.30.16、beancount 3.2.3、beanquery 0.2.0（venv 安装于 /opt/fava/venv）
  • 测试账本：/opt/ledger/example.beancount（账本标题「个人复式记账示例账本」，Web 端口 5000，systemd 托管）
  • 验证手段：账本页首屏 JSON（<script id="ledger-data"> 内含 fava_options 全量值）、bean-doctor 工具、curl 行为验证

💡 说明：Fava 没有独立配置文件——所有配置分布在三处：账本文本内的 option 指令（Beancount 侧）、账本文本内的 fava-option 自定义指令（Fava 侧）、进程启动参数/环境变量（服务侧）。这是文本账本理念的自然延伸：配置与账本同文件、同版本管理。

二、前置条件

以下示例均基于已安装并可运行的 Fava（安装与 systemd 托管步骤见文末参考链接的安装篇）。账本可通过 bean-doctor print-options 查看解析后的 Beancount 选项：

bean-doctor print-options /opt/ledger/example.beancount | head -6

实测输出：

account_current_conversions: Conversions:Current
account_current_earnings: Earnings:Current
account_previous_balances: Opening-Balances
account_previous_conversions: Conversions:Previous
account_previous_earnings: Earnings:Previous
account_rounding: None

Beancount 全部可选 option 可用 bean-doctor list-options 列出（实测共 29 个），每个带官方释义；本文只详解与 Fava 使用体验直接相关的部分。

三、参数查看与修改方式

三类参数的查看与修改入口：

参数类别写在哪里查看方式修改后生效方式
Beancount option账本文件顶部 option "名" "值"bean-doctor print-options <账本>保存文件，Fava 自动重载
Fava fava-option账本文件内 2026-01-01 custom "fava-option" "名" "值"网页首屏 ledger-data JSON 的 fava_options 字段保存文件，Fava 自动重载
启动参数/环境变量fava 命令行或 systemd 单元fava --help重启 fava 进程（systemd 场景 systemctl restart fava）

网页侧验证配置是否生效的可靠方法：浏览器开发者工具查看页面源码中 id="ledger-data" 的 JSON，其中 fava_options 对象包含全部 Fava 配置的当前值；Beancount 选项则在同 JSON 的 options 字段。

四、参数总览

4.1 fava-option 全量默认值（服务端实测快照）

以下为 Fava 1.30.16 在默认账本下返回的 fava_options 完整键值（实测照抄，language 因测试账本设为 zh，默认值实为 "en"）：

{
  "account_journal_include_children": true,
  "auto_reload": false,
  "collapse_pattern": [],
  "conversion_currencies": [],
  "currency_column": 61,
  "default_file": null,
  "default_page": "income_statement/",
  "fiscal_year_end": {"day": 31, "month": 12},
  "import_config": null,
  "import_dirs": [],
  "indent": 2,
  "insert_entry": [],
  "invert_gains_losses_colors": false,
  "invert_income_liabilities_equity": false,
  "language": "zh",
  "locale": "en",
  "show_accounts_with_zero_balance": true,
  "show_accounts_with_zero_transactions": true,
  "show_closed_accounts": false,
  "show_metadata_indicators": true,
  "sidebar_show_queries": 5,
  "upcoming_events": 7,
  "uptodate_indicator_grey_lookback_days": 60,
  "use_external_editor": false
}

💡 说明：have_excel: false 表示未安装 fava[excel] extra 时的 Excel 导出能力状态；incognito 字段不在 fava_options 里，由启动参数 --incognito 决定（实测 false/true 会原样出现在同一 JSON 中，见 6.3 节）。

4.2 启动参数总览

fava --help 实测输出（完整）：

Usage: fava [OPTIONS] [FILENAMES]...

  Start Fava for FILENAMES on http://<host>:<port>.

  If the `BEANCOUNT_FILE` environment variable is set, Fava will use the files
  (delimited by ';' on Windows and ':' on POSIX) given there in addition to
  FILENAMES.

  Note you can also specify command-line options via environment variables
  with the `FAVA_` prefix. For example, `--host=0.0.0.0` is equivalent to
  setting the environment variable `FAVA_HOST=0.0.0.0`.

Options:
  -p, --port <port>   The port to listen on.  [default: 5000]
  -H, --host <host>   The host to listen on.  [default: localhost]
  --prefix TEXT       Set an URL prefix.
  --incognito         Run in incognito mode and obscure all numbers.
  --read-only         Run in read-only mode, disable any change through Fava.
  -d, --debug         Turn on debugging.
  --profile           Turn on profiling. Implies --debug.
  --profile-dir PATH  Output directory for profiling data.
  --poll-watcher      Use old polling-based watcher.
  --version           Show the version and exit.
  --help              Show this message and exit.

五、核心参数分类详解

5.1 账本级 Beancount option（影响引擎与报表口径）

（1）title —— 账本标题（同时决定 Web URL）

option "title" "个人复式记账示例账本"

作用：账本显示名，且决定 Fava 的账本 URL 路径（实测 URL 为标题的 URL 编码：/%E4%B8%AA%E4%BA%BA%E5%A4%8D%E5%BC%8F%E8%AE%B0%E8%B4%A6%E7%A4%BA%E4%BE%8B%E8%B4%A6%E6%9C%AC/income_statement/）。改标题 = 改 URL，收藏夹与反代规则需同步更新。

（2）operating_currency —— 主币种

option "operating_currency" "CNY"

作用：报表列与图表以该币种为主口径展示，可多次声明多个主币种。不设置时仅按商品（commodity）原样显示。

（3）render_commas —— 千分位显示

option "render_commas" "TRUE"

作用：让 Fava 界面与导出中的金额带千分位（15,000.00）。这是 Beancount 全局显示选项，Fava 前端渲染时读取；不影响账本文件本身的数字写法。

（4）include —— 多文件拆分

option "include" "accounts.beancount"
option "include" "2026/*.beancount"

作用：把大账本拆成多文件（年度/分类），Fava 监听所有被 include 的文件，任一保存即重载。default_file fava-option（见 5.2）配合决定"新增交易写回哪个文件"。

5.2 账本级 fava-option（Fava 界面行为）

语法固定为带日期的 custom 指令：2026-01-01 custom "fava-option" "<选项名>" "<值>"。以下各选项均在本机实测验证。

（1）language —— 界面语言

2026-01-01 custom "fava-option" "language" "zh"

实测验证：设置后服务端 ledger-data JSON 中 "language": "zh"，界面导航/报表标题渲染为中文。支持代码：zh（中文）、en、de、fr、ja、ko、fi 等（1.30.13 起翻译在 Weblate 维护并新增韩语，1.30.16 新增芬兰语）。

（2）default-page —— 默认落地页

2026-01-01 custom "fava-option" "default-page" "journal/"

实测验证：设为 journal/ 后 ledger-data 返回 "default_page": "journal/"（默认值 income_statement/），访问账本根路径时落到日记账页。常用取值：income_statement/、balance_sheet/、trial_balance/、journal/。

（3）uptodate-indicator-grey-lookback-days —— 更新指示器宽限期

2026-01-01 custom "fava-option" "uptodate-indicator-grey-lookback-days" "90"

实测验证：ledger-data 返回 "uptodate_indicator_grey_lookback_days": 90（默认 60）。作用：账户旁的"最新余额是否核对过"指示器，在最后一条 balance 断言超过 N 天后转灰提醒，按对账频率调整。

（4）show-accounts —— 侧边栏账户树精简

2026-01-01 custom "fava-option" "show-accounts" "TRUE"

作用：控制侧边栏是否显示完整账户树（配合 show_accounts_with_zero_balance 等开关过滤零余额/零交易账户，二者默认 true）。

（5）insert-entry —— 新增交易的落点规则

2026-01-01 custom "fava-option" "insert-entry" "Assets:Bank:Card" "/opt/ledger/2026.beancount"

作用：网页里给某账户新增交易时写入指定文件（配合 include 拆分账本）。未配置时由 default-file 指定（默认 null，即账本主文件）。

（6）journal-show —— 日记账默认展示的交易类型

2026-01-01 custom "fava-option" "journal-show" "transaction"
2026-01-01 custom "fava-option" "journal-show" "balance"

作用：日记账页默认勾选的条目类型（transaction/balance/open/close/note/document 等），页面内仍可临时切换。

（7）collapse-pattern —— 账户树折叠规则

2026-01-01 custom "fava-option" "collapse-pattern" "Income:.*"

作用：按正则把匹配的账户子树默认折叠，报表过深时常用。

⚠️ 注意：fava-option 的选项名写错不会让 fava 拒绝加载，而是进页面顶部错误列表。实测写一个不存在的选项后 ledger-data 的 errors 字段返回：

{"message": "Failed to parse fava-option entry: Unknown option `不存在的选项`", "source": {"filename": "/opt/ledger/config-test.beancount", "lineno": 48}, "type": "OptionError"}

看到红条时先检查选项名拼写（官方选项名用连字符小写形式，JSON 键为下划线形式）。

（8）导入相关：import-config 与 import-dirs

2026-01-01 custom "fava-option" "import-config" "/opt/ledger/import_config.py"
2026-01-01 custom "fava-option" "import-dirs" "/opt/ledger/inbox"

作用：接入 beangulp 导入器体系后，网页 Import 页列出识别的账单供预览导入。默认均空（实测 import_config: null、import_dirs: []）。

5.3 启动参数与环境变量（服务侧）

（1）-H/--host 与 -p/--port：默认 localhost:5000。远程访问必须 -H 0.0.0.0。systemd 部署写在 ExecStart 里：

ExecStart=/opt/fava/venv/bin/fava -H 0.0.0.0 -p 5000 /opt/ledger/example.beancount

（2）--prefix —— 子路径部署。实测以 --prefix /fava 启动后，页面仅可经 http://<host>:5001/fava/<账本URL>/... 正常访问（curl 返回 200），适合挂在反向代理统一域名的子路径下（如 https://finance.example.com/fava/）。

（3）--read-only —— 只读模式。禁用一切经 Fava 的写操作（网页新增/修改交易、Source 编辑器保存均被禁）。用于把账本以"查询台"形态开放时的安全兜底。

（4）--incognito —— 隐身模式（数字遮挡）。实测启动后服务端把 incognito: true 下发给前端，界面所有金额以遮挡形式展示（原始数字不出现在渲染层），用于截图/演示不泄露账目。验证手段（同账本两种模式首屏 JSON 对比）：

正常模式："incognito":false
隐身模式："incognito":true

（5）-d/--debug、--profile、--profile-dir：调试与性能分析开关，--profile 隐含 --debug，分析数据写入 --profile-dir 目录。日常运维关闭。

（6）--poll-watcher：改用旧的轮询方式监听文件变化。默认基于 watchfiles 的事件监听在网络文件系统（NFS）上不可靠时启用此兜底。

（7）环境变量等价：所有 --xxx 参数可用 FAVA_XXX 环境变量设置（--host ⇔ FAVA_HOST）。账本文件另支持 BEANCOUNT_FILE。实测 FAVA_HOST=0.0.0.0 FAVA_PORT=5003 fava /opt/ledger/example.beancount 启动日志：

Starting Fava on http://0.0.0.0:5003

实测 BEANCOUNT_FILE=/opt/ledger/example.beancount fava -H 0.0.0.0 -p 5004（命令行不写账本路径）同样正常加载账本并响应 302。多账本用 : 分隔：BEANCOUNT_FILE=/ledger/a.beancount:/ledger/b.beancount。

六、生产配置模板

6.1 账本头部模板（个人自托管场景，2C4G 服务器即可）

option "title" "家庭账本"
option "operating_currency" "CNY"
option "render_commas" "TRUE"

;; 界面与行为
2026-01-01 custom "fava-option" "language" "zh"
2026-01-01 custom "fava-option" "default-page" "journal/"
2026-01-01 custom "fava-option" "uptodate-indicator-grey-lookback-days" "90"

;; 账本拆分（按年）
option "include" "2026.beancount"

;; 导入器（可选）
;; 2026-01-01 custom "fava-option" "import-config" "/opt/ledger/import_config.py"
;; 2026-01-01 custom "fava-option" "import-dirs" "/opt/ledger/inbox"

6.2 systemd 启动模板（安全基线）

[Unit]
Description=Fava - web interface for Beancount
After=network.target

[Service]
Type=simple
User=root
ExecStart=/opt/fava/venv/bin/fava --read-only -H 127.0.0.1 -p 5000 /opt/ledger/family.beancount
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

要点：仅本机访问（-H 127.0.0.1）由前置 Nginx 反代并加 Basic Auth 对外；需要网页编辑账本时再去掉 --read-only。Fava 内存占用实测约 32MB，无需内存参数调优。

七、常见问题（FAQ）

Q1：改了账本里的 fava-option，页面没变化？ 确认两点：指令日期格式合法（2026-01-01 custom "fava-option" ...）、选项名拼写正确（写错会进页面 errors 而非静默失败，见 5.2（7）实测回显）。仍不生效则 systemctl restart fava 强制重载。

Q2：option "title" 改了之后旧 URL 打不开？ Fava 的账本 URL 由 title 决定（实测行为），改标题即换 URL，直接访问根路径 / 会 302 到新地址。外部书签与反代路径需同步更新。

Q3：界面还是英文，language 选项写了 zh 但没生效？ 检查该行是否写在被加载的账本内（include 体系下 fava-option 放在任意被包含文件均生效）；检查 custom 指令的日期是否合法；确认浏览器无强缓存（Ctrl+F5）。生效与否以首屏 ledger-data JSON 的 language 字段为准（实测 "language": "zh" 即已生效）。

Q4：--incognito 模式下数字全部变遮挡了，导出 CSV 也会遮挡吗？ 遮挡由前端渲染层实现（服务端下发 incognito 标志），网页展示与页面内导出均受影响；绕过界面直接用 bean-query 命令行不受影响。

Q5：选项在哪里能看到"全部可用清单"？ Beancount 侧：bean-doctor list-options（实测 29 项，含官方释义）；Fava 侧：本篇 4.1 节快照即 1.30.16 全量键，官方文档 Help 页为权威来源。

八、参考链接

  1. Fava 官方帮助（选项权威文档）：https://beancount.github.io/fava/help.html
  2. Beancount Options 参考：https://beancount.github.io/docs/beancount_options_reference.html
  3. Fava Changelog：https://beancount.github.io/fava/changelog.html
  4. 本专栏安装篇：《Ubuntu 22.04 安装 Fava 1.30.16 指南》
  5. 本专栏命令详解篇：《Fava 1.30.16 常用 CLI 命令与工具详解》