Ubuntu 22.04 安装 Fava 1.30.16 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Beancount 复式记账引擎与 Fava 1.30.16 Web 界面，完成示例账本校验、Web 访问验证与 systemd 开机自启托管。全部命令与回显均已在 Ubuntu 22.04.5 LTS（Python 3.10.12）环境逐条实测通过，覆盖 venv/pipx/apt 三种安装方案、升级降级、排障实录与卸载清理。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
架构：x86_64
Python：3.10.12（系统自带）
安装组件：beancount 3.2.3 + fava 1.30.16（2026-08-18 发布，PyPI/GitHub Releases 实查）
安装方案：venv（方案 A）、pipx（方案 B）、apt 发行版仓库（方案 C）
监听端口：5000（Fava 默认）
账本目录：/opt/ledger/
服务托管：systemd 单元 fava.service

💡 说明：Fava 1.30.13 起仅支持 Beancount 3.x（官方 Changelog 明确放弃 Beancount v2），本文统一安装 beancount 3.2.3。

二、前置条件

安装 Fava 前需确认系统满足两项条件：Python 版本达标、包管理工具就绪。

cat /etc/os-release | head -2
python3 --version

实测输出：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
Python 3.10.12

Fava 1.30.16 要求 Python ≥ 3.10（PyPI 元数据 requires_python: >=3.10）。Ubuntu 22.04 自带 3.10 满足要求；若使用 Ubuntu 20.04（Python 3.8）需先通过 deadsnakes PPA 或源码安装 Python 3.10+，否则 pip 安装会直接报版本不满足错误。

更新软件源索引并安装 venv 支撑（方案 A 需要）：

apt-get update
apt-get install -y python3-venv python3-pip

实测输出（末行）：

done.

三、版本选型说明

Fava 的版本获取渠道与当前版本状态（2026-10-23 实查）：

渠道	可得版本	说明
PyPI（`pip install fava`）	1.30.16（最新稳定）	官方推荐渠道，wheel 直接安装
GitHub Releases	v1.30.16（2026-08-18），另有 Nightly 滚动构建	稳定版与 PyPI 同步；Nightly 不建议生产使用
Ubuntu 22.04 apt（universe）	python3-fava 1.20.1-1	2022 年旧版，仅作离线兜底

关键差异解读：生产环境应从 PyPI 安装最新稳定版；apt 仓库的 1.20.1 落后 10 个小版本、且不支持 Beancount 3，只适合"零外网、零 Python 环境"的特殊场景。后续查询最新版本的命令：

pip index versions fava

四、方案 A：venv 虚拟环境安装（推荐，隔离干净）

4.1 方案说明

用 Python 自带 venv 在独立目录 /opt/fava/venv 创建专属虚拟环境，Fava 及其全部依赖装在虚拟环境内，不污染系统 Python。适合所有有 Python 3.10+ 的服务器，是排查依赖冲突最干净的方案。

4.2 创建虚拟环境

python3 -m venv /opt/fava/venv
/opt/fava/venv/bin/pip install --upgrade pip

实测无报错即成功（pip 升级为最新版）。

4.3 安装 beancount 与 fava

/opt/fava/venv/bin/pip install beancount fava

实测输出（尾部，完整依赖链）：

Installing collected packages: pytz, ply, tzdata, typing-extensions, tatsu-lts, soupsieve, six, simplejson, regex, python-magic, more-itertools, mdurl, markupsafe, lxml, itsdangerous, idna, click, chardet, blinker, babel, werkzeug, python-dateutil, markdown-it-py, jinja2, jaraco.functools, exceptiongroup, beautifulsoup4, flask, cheroot, beancount, anyio, watchfiles, flask-babel, beanquery, beangulp, fava

Successfully installed anyio-4.15.1 babel-2.18.0 beancount-3.2.3 beangulp-0.2.0 beanquery-0.2.0 beautifulsoup4-4.15.0 blinker-1.9.0 chardet-7.7.0 cheroot-11.1.2 click-8.5.0 exceptiongroup-1.3.1 fava-1.30.16 flask-3.1.3 flask-babel-4.0.0 idna-3.20 itsdangerous-2.2.0 jaraco.functools-4.6.0 jinja2-3.1.6 lxml-6.1.3 markdown-it-py-4.2.0 markupsafe-3.0.4 mdurl-0.1.2 more-itertools-11.1.0 ply-3.11 python-dateutil-3.0.0 python-magic-0.4.27 pytz-2026.5 regex-2026.9.29 simplejson-3.20.2 six-1.17.0 soupsieve-2.10 tatsu-lts-5.16.0 typing-extensions-4.16.0 tzdata-2026.5 watchfiles-1.3.0 werkzeug-3.1.9

💡 说明：pip install fava 会自动带上 beancount（记账引擎）与 beanquery（BQL 查询引擎）依赖，无需单独安装 beancount；显式写上只是把版本意图表达清楚。

4.4 验证安装

export PATH=/opt/fava/venv/bin:$PATH
fava --version
bean-check --version
bean-query --version

实测输出：

fava, version 1.30.16
Beancount 3.2.3
beanquery 0.2.0, beancount 3.2.3

虚拟环境内可用的命令（ls /opt/fava/venv/bin/ 实测节选）：

bean-check  bean-doctor  bean-example  bean-format  bean-query  fava  flask

⚠️ 注意：Beancount v3 已移除 bean-report 命令（v2 时代的报表工具，功能并入 bean-query 与 Fava 网页查询）。若在旧资料里看到 bean-report，在 3.x 下会得到 command not found。

4.5 创建示例账本

创建账本目录并写入示例账本 /opt/ledger/example.beancount：

mkdir -p /opt/ledger
cat > /opt/ledger/example.beancount <<'EOF'
option "title" "个人复式记账示例账本"
option "operating_currency" "CNY"
option "render_commas" "TRUE"

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

2026-01-01 commodity CNY
2026-01-01 commodity USD

2026-01-01 open Assets:Bank:Card
2026-01-01 open Assets:Cash
2026-01-01 open Expenses:Food
2026-01-01 open Expenses:Transport
2026-01-01 open Expenses:Rent
2026-01-01 open Income:Salary
2026-01-01 open Equity:Opening-Balances

2026-01-01 pad Assets:Bank:Card Equity:Opening-Balances

2026-01-11 balance Assets:Bank:Card 20000.00 CNY

2026-01-10 * "公司" "1 月工资"
  Income:Salary           -15000.00 CNY
  Assets:Bank:Card

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

2026-01-15 * "地铁" "通勤充值"
  Expenses:Transport        100.00 CNY
  Assets:Bank:Card

2026-02-01 * "房东" "2 月房租"
  Expenses:Rent            3500.00 CNY
  Assets:Bank:Card

2026-02-05 * "餐厅" "同事聚餐"
  Expenses:Food             158.00 CNY
  Assets:Cash

2026-02-10 * "银行" "ATM 取现"
  Assets:Cash               500.00 CNY
  Assets:Bank:Card
EOF

用 bean-check 做复式平衡校验（Fava 加载账本前先命令行校验是好习惯）：

bean-check /opt/ledger/example.beancount
echo "bean-check exit=$?"

实测输出：

bean-check exit=0

exit=0 表示账本语法正确、每笔交易借贷平衡。bean-check 无任何输出即无错误，这是 Beancount 系工具的惯例。

4.6 首次运行与 Web 验证

nohup fava -H 0.0.0.0 -p 5000 /opt/ledger/example.beancount > /var/log/fava.log 2>&1 &
sleep 4
cat /var/log/fava.log
curl -s -o /dev/null -w "root HTTP %{http_code}\n" http://127.0.0.1:5000/

实测输出：

Starting Fava on http://0.0.0.0:5000
root HTTP 302

启动日志固定一行 Starting Fava on http://0.0.0.0:5000；
根路径 / 返回 302，重定向到账本首页。Fava 的账本 URL 取自账本内 option "title" 的 URL 编码值（本例为「个人复式记账示例账本」），而不是文件名——直接访问 http://127.0.0.1:5000/example/ 会得到 404，这是新手最常见的困惑点（详见"十一、常见问题"）。

跟随重定向验证报表页：

curl -sL -o /dev/null -w "page HTTP %{http_code}\n" http://127.0.0.1:5000/
curl -sL http://127.0.0.1:5000/ | grep -oE "<title>[^<]*</title>"

实测输出：

page HTTP 200
<title> - 个人复式记账示例账本</title>

HTTP 200 且页面标题出现账本名，说明 Web 服务与账本加载全部正常。浏览器访问 http://<服务器IP>:5000/ 即可看到损益表、资产负债表等完整中文界面（账本内 fava-option "language" "zh" 已指定中文 UI）。

五、方案 B：pipx 安装（官方推荐，命令全局可用）

5.1 方案说明

pipx 为每个 Python 应用创建独立虚拟环境，但把入口命令暴露到全局 ~/.local/bin，兼顾隔离与"敲 fava 即用"。Fava 官方文档推荐该方式。

5.2 安装 pipx 与 fava

apt-get install -y pipx
pipx install fava

实测输出（尾部）：

  installed package fava 1.30.16, installed using Python 3.10.12
  These apps are now globally available
    - fava

注意：pipx 只暴露了 fava 一个命令——bean-* 系列工具在 fava 的依赖里但不作为 app 暴露。需要命令行 bean 工具时单独安装：

pipx install beancount
pipx install beanquery

实测输出（尾部）：

    - bean-check
    - bean-doctor
    - bean-example
    - bean-format
    - treeify

  installed package beanquery 0.2.0, installed using Python 3.10.12
  These apps are now globally available
    - bean-query

5.3 验证与使用

pipx list
ls ~/.local/bin/ | grep -E "fava|bean"
~/.local/bin/fava --version

实测输出：

venvs are in /root/.local/pipx/venvs
apps are exposed on your $PATH at /root/.local/bin
   package fava 1.30.16, installed using Python 3.10.12
    - fava
   package beancount 3.2.3, installed using Python 3.10.12
    - bean-check
    - bean-doctor
    - bean-example
    - bean-format
    - treeify
   package beanquery 0.2.0, installed using Python 3.10.12
    - bean-query
fava
bean-check
bean-doctor
bean-example
bean-format
treeify
bean-query
fava, version 1.30.16

将 ~/.local/bin 加入 PATH（pipx 提示语已给出路径）后即可直接使用 fava 命令，启动方式与方案 A 完全相同：fava -H 0.0.0.0 -p 5000 /opt/ledger/example.beancount。

六、方案 C：apt 发行版仓库安装（离线兜底）

6.1 方案说明

Ubuntu 22.04 universe 仓库收录了 python3-fava，一条 apt 命令装完、系统服务方式管理，但版本停留在 1.20.1（2022 年），不支持 Beancount 3 语法。仅适合完全无外网、且不追求新功能的环境。

6.2 安装与验证

apt-cache policy python3-fava
apt-get install -y python3-fava
/usr/bin/fava --version

实测输出：

python3-fava:
  Installed: (none)
  Candidate: 1.20.1-1
  Version table:
fava, version 1.20.1

⚠️ 注意：apt 版本与 PyPI 版本并存时会同时有 /usr/bin/fava（1.20.1）与虚拟环境/pipx 的 fava（1.30.16），敲命令时以 PATH 顺序决定实际调用哪个。生产环境二选一，不要混装。

七、方案对比与选择建议

维度	A：venv + pip	B：pipx（官方推荐）	C：apt 仓库
版本	最新稳定 1.30.16	最新稳定 1.30.16	1.20.1（旧）
是否需外网	是	是	否（用镜像源即可）
bean-* 工具	全部就绪	需补装 beancount/beanquery	全部就绪（旧版）
命令入口	/opt/fava/venv/bin	~/.local/bin（全局）	/usr/bin
升级	pip install -U fava	pipx upgrade fava	apt upgrade（跟随仓库）
适用	服务器标准做法	个人/多组件共存	无外网兜底

选择建议：默认用方案 B（pipx，官方推荐）；自动化脚本与固定路径部署用方案 A（venv 路径明确）；完全离线才用方案 C。

八、systemd 托管（开机自启）

无论哪种方案安装，长期运行都应交给 systemd。写入服务单元 /etc/systemd/system/fava.service（以方案 A 的 venv 路径为例；pipx 方案把 ExecStart 换成 /root/.local/bin/fava 即可）：

cat > /etc/systemd/system/fava.service <<'EOF'
[Unit]
Description=Fava - web interface for Beancount
After=network.target

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

[Install]
WantedBy=multi-user.target
EOF

单元文件逐项说明：After=network.target 保证网络就绪后再启动；ExecStart 必须写虚拟环境内 fava 的绝对路径；-H 0.0.0.0 让服务监听所有网卡（默认 localhost 只允许本机访问）；Restart=on-failure + RestartSec=3 进程异常退出时 3 秒后自动拉起；WantedBy=multi-user.target 注册为多用户级别自启。

先停掉 4.6 节手动启动的进程（避免端口冲突），再注册并启动服务：

pkill -f 'venv/bin/[f]ava'
systemctl daemon-reload
systemctl enable fava
systemctl start fava
systemctl is-active fava

实测输出：

Created symlink /etc/systemd/system/multi-user.target.wants/fava.service → /etc/systemd/system/fava.service.
active

查看运行状态与资源占用：

systemctl status fava --no-pager -l

实测输出（节选）：

● fava.service - Fava - web interface for Beancount
     Loaded: loaded (/etc/systemd/system/fava.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-23 04:53:40 UTC; 9s ago
   Main PID: 3790 (fava)
      Tasks: 12 (limit: 94371)
     Memory: 32.3M
        CPU: 186ms

Web 复核（systemd 托管后服务仍在 5000 端口）：

curl -sL -o /dev/null -w "page HTTP %{http_code}\n" http://127.0.0.1:5000/

实测输出：

page HTTP 200

enabled + active (running) + HTTP 200 三项齐备，说明开机自启与当前服务均正常。Fava 是纯 Python 轻量服务，实测常驻内存约 32MB，无 Java 进程、无额外内存参数需要调整。

九、升级、降级与多版本管理

# 升级到最新稳定版
/opt/fava/venv/bin/pip install --upgrade fava

# 锁定具体版本（实测从 1.30.16 降到 1.30.15）
/opt/fava/venv/bin/pip install fava==1.30.15
fava --version

实测输出：

fava, version 1.30.15

# 再升回最新版
/opt/fava/venv/bin/pip install fava==1.30.16
fava --version

实测输出：

fava, version 1.30.16

多版本并存：再建一个 venv 目录（如 /opt/fava/venv-129）安装 fava==1.29，两个服务单元指向不同 venv 路径即可并行跑两个版本对比。升级后重启服务使新版本生效：systemctl restart fava。

十、常见问题（FAQ）

Q1：启动后远程浏览器访问不了，本机 curl 正常？ fava 默认 -H localhost 只监听 127.0.0.1。远程访问必须显式 -H 0.0.0.0（systemd 单元的 ExecStart 同理），并放行防火墙端口：ufw allow 5000/tcp。

Q2：访问 http://服务器IP:5000/example/ 返回 404？ Fava 的账本 URL 取自账本内 option "title" 的 URL 编码值而非文件名。本例账本标题为「个人复式记账示例账本」，正确地址是 http://服务器IP:5000/%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/；最省事的做法是直接访问根路径 /，fava 会 302 到正确地址。

Q3：bean-check 报 Unused Pad entry？ pad（补平指令）必须配一条在其之后的 balance 余额断言才有意义——引擎用 pad 把账户余额补到断言值。若 pad 后没有任何 balance 指令，会报错（实测）：

/opt/ledger/example.beancount:15: Unused Pad entry

   2026-01-01 pad Assets:Bank:Card Equity:Opening-Balances

解法：在 pad 之后补一条 2026-01-11 balance Assets:Bank:Card 20000.00 CNY，或删掉 pad。

Q4：账本里 open 指令带金额、数字用下划线分隔报语法错误？ 实测输出：

/opt/ledger/example.beancount:7: syntax error, unexpected MINUS, expecting end of file or EOL
/opt/ledger/example.beancount:7: Invalid token: '_000_000'

Beancount 3 语法中 open 只声明账户不接受金额，数字也不支持 _ 千位分隔（用逗号需配 option "render_commas" 且仅影响显示）。改写为 2026-01-01 open Assets:Bank:Card 与 15000.00 即可。

Q5：端口 5000 被占用启动失败？ ss -ltnp | grep 5000 找到占用进程，或换端口启动：fava -H 0.0.0.0 -p 5001 /opt/ledger/example.beancount。systemd 部署时同步修改单元文件的 -p 参数后 systemctl daemon-reload && systemctl restart fava。

Q6：编辑账本后 Fava 页面没更新？ Fava 用 watchfiles 监听文件变化、默认自动重载。若修改的是被 include 的其他文件而监听未触发，可在 Source 编辑器页保存一次触发重载，或 systemctl restart fava 兜底。

十一、卸载与清理

按安装方案对应清理，逐项执行：

systemctl stop fava
systemctl disable fava
rm /etc/systemd/system/fava.service
systemctl daemon-reload

# 方案 A：删除虚拟环境与账本（确认备份后）
rm -rf /opt/fava /opt/ledger

# 方案 B：pipx 卸载
pipx uninstall fava
pipx uninstall beancount
pipx uninstall beanquery

# 方案 C：apt 卸载
apt-get purge -y python3-fava
apt-get autoremove -y

每步执行后 systemctl is-active fava 应返回 inactive 或 not found，fava --version 应提示 command not found，即卸载干净。

十二、参考链接

Fava 官方安装文档：https://beancount.github.io/fava/usage.html
PyPI 项目页：https://pypi.org/project/fava/
Fava Releases：https://github.com/beancount/fava/releases/
Beancount 官方文档：https://beancount.github.io/docs/
本专栏容器化部署篇：《Fava 1.30.16 Docker Compose 部署指南》
本专栏配置详解篇：《Fava 1.30.16 配置参数详解》