Ubuntu 22.04 安装 ezbookkeeping 2.1.0 指南

目标：面向需要在 Ubuntu 22.04 服务器上以官方二进制方式部署 ezBookkeeping v2.1.0 的读者，提供在线安装与离线安装两套完整方案，覆盖下载校验、部署目录规划、运行账户创建、systemd 托管、服务验证与管理员建号，并附 2.0.1→2.1.0 升级演练实测。全部命令与回显在 Ubuntu 22.04.4 LTS 实机逐条执行采集。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
软件版本	ezBookkeeping v2.1.0（2026-10-15 发布，commit ff168cf）
安装介质	官方发布包 ezbookkeeping-v2.1.0-linux-amd64.tar.gz（24213816 字节）
SHA-256	0383338c5c26d91d36ff010e3cede326ee3d3bc8edbf3d6499ad589121dbf73d
安装目录	/usr/local/bin/ezbookkeeping
监听端口	8080（默认）
运行账户	ezbookkeeping（系统用户，实测 uid=999）
关联文档	《ezbookkeeping 2.1.0 介绍与选型指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 配置参数详解》、《ezbookkeeping 2.1.0 常用 CLI 命令与工具详解》

二、版本选型与前置条件

2.1 版本选择

截至 2026-10-23，官方 GitHub Releases 最新稳定版为 v2.1.0。v2.x 相比 1.x 有配置节更名等 Breaking Change（详见配置详解篇），新部署直接选 2.1.0；存量 1.x 环境请先读官方 Release Notes 再规划升级。本文以 v2.1.0 amd64 包为准，ARM 服务器将介质名中 amd64 替换为 arm64（下载地址同构）。

2.2 系统要求与前置条件

官方系统要求为 1 核 CPU / 512MB 内存起步（官方文档 System Requirements），实测服务进程空闲内存仅 9.0MB（systemctl status 输出），低配虚拟机可从容运行。前置条件清单：

一台 Ubuntu 22.04 服务器（物理机/虚拟机均可）；
具备 sudo 权限的账户；
在线方案需访问 GitHub Releases 的网络（国内网络建议使用代理，见第八章 Q1 的实测排障）；
无需预装数据库——默认使用内置 SQLite；如需 MySQL/PostgreSQL 请先备好数据库实例；
规划好 8080 端口未被占用（ss -tlnp | grep 8080 确认）。

三、在线安装方案（官方二进制包）

3.1 方案说明

从官方 GitHub Releases 直接下载预编译二进制包，解压到 /usr/local/bin/ezbookkeeping，创建专用系统账户，配置后交由 systemd 托管。这是官方文档推荐的标准安装方式，无需任何编译工具链。

3.2 下载与校验

cd /tmp
curl -fL -o ezbookkeeping-v2.1.0-linux-amd64.tar.gz \
  https://github.com/mayswind/ezbookkeeping/releases/download/2.1.0/ezbookkeeping-v2.1.0-linux-amd64.tar.gz

下载完成后必须校验（官方 Releases 页公布 SHA-256）：

$ sha256sum ezbookkeeping-v2.1.0-linux-amd64.tar.gz
0383338c5c26d91d36ff010e3cede326ee3d3bc8edbf3d6499ad589121dbf73d  ezbookkeeping-v2.1.0-linux-amd64.tar.gz

$ ls -la ezbookkeeping-v2.1.0-linux-amd64.tar.gz
-rw-r--r-- 1 root root 24213816 Oct 23 04:48 ezbookkeeping-v2.1.0-linux-amd64.tar.gz

校验通过标准：哈希值与官方一致、文件大小为 24213816 字节。哈希不一致或体积明显偏小（实测曾出现 6127616 字节的截断包，解压报 unexpected EOF，见第八章 Q1）必须重新下载。

3.3 解压部署

$ tar -xzf ezbookkeeping-v2.1.0-linux-amd64.tar.gz -C /usr/local/bin/
$ mv /usr/local/bin/ezbookkeeping-linux-amd64 /usr/local/bin/ezbookkeeping
$ ls /usr/local/bin/ezbookkeeping/
LICENSE  conf  data  ezbookkeeping  log  public  storage  templates

包内实测清单（tar -tzf 节选）：主二进制 ezbookkeeping、默认配置 conf/ezbookkeeping.ini、前端静态资源 public/、多语言模板 templates/，以及运行时自动生成的 data/、log/、storage/ 空目录。

版本确认：

$ /usr/local/bin/ezbookkeeping/ezbookkeeping --version
ezBookkeeping version 2.1.0 (commit ff168cf)

3.4 运行账户与目录准备

按官方建议创建同名系统用户与用户组，并把安装目录归属给它：

useradd -r -s /usr/sbin/nologin -M -c "ezBookkeeping service" ezbookkeeping
chown -R ezbookkeeping:ezbookkeeping /usr/local/bin/ezbookkeeping

实测账户信息：

$ id ezbookkeeping
uid=999(ezbookkeeping) gid=999(ezbookkeeping) groups=999(ezbookkeeping)

-r 创建系统账户（UID 从 999 起分配），-s /usr/sbin/nologin 禁止该账户交互登录，-M 不建家目录。

3.5 初始配置

生成登录密钥并写入配置（密钥确定后不可更换，见配置详解篇 5.1 节）：

KEY=$(/usr/local/bin/ezbookkeeping/ezbookkeeping security gen-secret-key | awk '{print $3}')
echo "生成的密钥（妥善保存）: $KEY"
sed -i "s|^secret_key =.*|secret_key = $KEY|" /usr/local/bin/ezbookkeeping/conf/ezbookkeeping.ini

再按需修改站点域名：

sed -i "s|^domain =.*|domain = ezbookkeeping.example.com|" \
  /usr/local/bin/ezbookkeeping/conf/ezbookkeeping.ini

确认关键项：

$ grep -E "^(domain|secret_key)" /usr/local/bin/ezbookkeeping/conf/ezbookkeeping.ini
domain = ezbookkeeping.example.com
secret_key = XQVSAVbi4aBIEspR7CTTPXIH0ALSHxVk

其余配置项（数据库切换 MySQL/PG、SMTP 邮件、对象存储等）见《ezbookkeeping 2.1.0 配置参数详解》，最小化安装保持默认即可。

3.6 systemd 托管

官方文档建议在 Debian/Ubuntu 放置于 /lib/systemd/system/。创建服务单元：

cat > /lib/systemd/system/ezbookkeeping.service <<'EOF'
[Unit]
Description=ezBookkeeping is an open source, powerful, self-hosted personal finance app that is easy to use.
After=syslog.target
After=network.target
After=mariadb.service mysqld.service postgresql.service

[Service]
Type=simple
User=ezbookkeeping
Group=ezbookkeeping
WorkingDirectory=/usr/local/bin/ezbookkeeping
ExecStart=/usr/local/bin/ezbookkeeping/ezbookkeeping server run
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

该单元即官方提供的样例配置（路径为实测默认安装路径）。WorkingDirectory 必须是安装目录——CLI 子命令按工作目录解析默认配置路径（坑点见第八章 Q3）。

加载并设置开机自启：

systemctl daemon-reload
systemctl enable ezbookkeeping

实测输出：

Synchronizing state of ezbookkeeping.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing: /usr/lib/systemd/systemd-sysv-install enable ezbookkeeping

启动服务：

systemctl start ezbookkeeping

3.7 服务验证与管理员建号

验证三连：

$ systemctl is-active ezbookkeeping
active

$ systemctl is-enabled ezbookkeeping
enabled

$ curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8080/
HTTP 200

资源占用实测：

$ systemctl status ezbookkeeping --no-pager
● ezbookkeeping.service - ezBookkeeping is an open source, powerful, self-hosted personal finance app that is easy to use.
     Loaded: loaded (/lib/systemd/system/ezbookkeeping.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-23 05:17:23 UTC; 2s ago
   Main PID: 3034 (ezbookkeeping)
      Tasks: 9 (limit: 4579)
     Memory: 9.0M
        CPU: 31ms
     CGroup: /system.slice/ezbookkeeping.service
             └─3034 /usr/local/bin/ezbookkeeping/ezbookkeeping server run

浏览器访问 http://<服务器IP>:8080/ 即可打开登录页。创建管理员账户（推荐 CLI 方式，随后可在网页关闭自助注册）：

cd /usr/local/bin/ezbookkeeping
sudo -u ezbookkeeping ./ezbookkeeping userdata user-add \
  -n admin -m admin@example.com -i admin -p 'q1w2e3r4' -c CNY

实测输出（节选）：

[Uid] 3849848393941647360
[Username] admin
[Email] admin@example.com
[DefaultCurrency] CNY

用 admin 账户登录网页完成初始化分类与账户设置即可开始记账。

四、离线安装方案（内网环境）

4.1 方案说明

ezBookkeeping 官方不提供 apt 仓库，安装介质就是同一个 tar.gz 包，因此离线安装与在线安装的差异仅在于介质获取路径：在外网机下载并校验，通过内网允许的渠道（U 盘/堡垒机/内部文件服务）拷入目标服务器，其余步骤与第三章完全一致。

4.2 外网机下载与校验

在外网机执行第三章 3.2 节的下载与 sha256sum 校验，确认哈希 0383338c…dbf73d 与大小 24213816 字节后，将包与哈希值一并转移。

4.3 内网机部署差异点

# 假设包已拷入内网机 /tmp
cd /tmp
sha256sum ezbookkeeping-v2.1.0-linux-amd64.tar.gz   # 内网机复验哈希
tar -xzf ezbookkeeping-v2.1.0-linux-amd64.tar.gz -C /usr/local/bin/

后续 3.3–3.7 节步骤原样执行。离线环境的两点补充：①无法访问 GitHub 时，security gen-secret-key 等本地操作不受影响；②若需切换 MySQL/PostgreSQL 数据库，驱动已内置于二进制，无需额外联网安装依赖。

五、多方案对比与选择建议

维度	在线安装（第三章）	离线安装（第四章）	容器编排（B2 篇）
版本	v2.1.0 官方二进制	v2.1.0 官方二进制	mayswind/ezbookkeeping:2.1.0 镜像
是否需联网	需访问 GitHub Releases	目标机无需联网	需拉取镜像（可离线导入）
安装方式	tar.gz 解压 + systemd	同左，介质外带	docker compose
服务托管	systemd（官方样例单元）	systemd	restart 策略
监听端口	8080	8080	8080（可映射任意宿主端口）
升级方式	替换包 + database update	同左	pull 新镜像重建容器
适用场景	常规服务器部署	内网隔离/保密环境	已有容器化运维体系

选择建议：常规 Ubuntu 服务器选在线安装；内网隔离环境选离线安装；已有 Docker 运维体系的团队选 Compose 部署篇。三方案数据层完全兼容（同一 SQLite/MySQL 后端），可随运维体系演进平滑迁移。

六、升级演练（2.0.1 → 2.1.0 实测）

ezBookkeeping 无独立数据目录设计（数据、配置都在安装目录内），升级即替换程序文件。以下为一次完整的跨小版本升级演练实测（v2.0.1 安装于 /opt/ezb-upgrade-test，端口 8081）：

# 1. 下载新版包并校验（v2.0.1 包 sha256: 36e19299164063749a0cd717b82890789caec6f49d2c309483c8e92aace8583b）
cd /tmp
curl -fL -o ezbookkeeping-v2.1.0-linux-amd64.tar.gz \
  https://github.com/mayswind/ezbookkeeping/releases/download/2.1.0/ezbookkeeping-v2.1.0-linux-amd64.tar.gz
sha256sum ezbookkeeping-v2.1.0-linux-amd64.tar.gz
# 0383338c5c26d91d36ff010e3cede326ee3d3bc8edbf3d6499ad589121dbf73d  （与官方一致）

# 2. 停服务
systemctl stop ezbookkeeping

# 3. 备份当前程序与数据（数据无价，必做）
cd /opt/ezb-upgrade-test
tar -czf /tmp/ezb-backup-v2.0.1.tar.gz conf data ezbookkeeping storage

# 4. 解压新版并替换程序文件（保留 conf 与 data）
tar -xzf /tmp/ezbookkeeping-v2.1.0-linux-amd64.tar.gz -C /tmp/ezb-new/
cp /tmp/ezb-new/ezbookkeeping-linux-amd64/ezbookkeeping /opt/ezb-upgrade-test/
cp -r /tmp/ezb-new/ezbookkeeping-linux-amd64/public/. /opt/ezb-upgrade-test/public/
cp -r /tmp/ezb-new/ezbookkeeping-linux-amd64/templates/. /opt/ezb-upgrade-test/templates/
chown -R ezbookkeeping:ezbookkeeping /opt/ezb-upgrade-test

# 5. 启动（auto_update_database=true 时自动迁移表结构；也可手动执行）
systemctl start ezbookkeeping
# 手动维护方式：cd /opt/ezb-upgrade-test && sudo -u ezbookkeeping ./ezbookkeeping database update

升级后验证实测：--version 输出 ezBookkeeping version 2.1.0 (commit ff168cf)，curl http://localhost:8081/ 返回 HTTP 200，原有用户数据登录可用，database update 复检输出 all tables maintained successfully。

升级红线：secret_key 在 conf 中未动，这是数据可用的前提；跨大版本（1.x→2.x）前必须阅读官方 Release Notes（v2.1.0 的 [llm]→[ai] 配置节更名即属此类）。

七、配置说明

最小化安装只需两处改动（均在 3.5 节完成）：[security] secret_key（安全密钥）与 [server] domain（站点域名）。常用进阶配置速查：

需求	配置节	关键项
换 MySQL/PostgreSQL	[database]	type / host / name / user / passwd
开启邮箱验证、找回密码	[mail]	enable_smtp / smtp_host / from_address
关闭自助注册（家庭自用推荐）	[user]	enable_register = false 后用 CLI user-add 建号
开放 API 令牌	[security]	enable_api_token = true
反向代理后获取真实 IP	[security]	trusted_proxy_ips 加入代理网段

全部 23 个配置节的默认值与逐项说明见《ezbookkeeping 2.1.0 配置参数详解》。

八、常见问题（FAQ）

Q1：curl 下载中断，解压报 gzip: stdin: unexpected EOF

实测踩坑：首次下载只得到 6127616 字节（完整包 24213816 字节），tar 解压时报 unexpected EOF。根因是网络链路对大文件下载不稳定。处理：加 -C -（断点续传）重试，或配置代理下载（实测经 HTTP 代理完整取得 24213816 字节，哈希校验通过）。下载后必须做 3.2 节的双项校验（哈希 + 字节数）再解压。

Q2：启动报 bind: address already in use

8080 端口被占用。ss -tlnp | grep 8080 找到占用进程，或改 conf/ezbookkeeping.ini 中 [server] http_port 后重启服务。

Q3：CLI 命令报 cannot get default configuration path, because stat /conf/ezbookkeeping.ini: no such file or directory

CLI 按当前工作目录解析默认配置路径（<CWD>/conf/ezbookkeeping.ini）。固定做法：cd /usr/local/bin/ezbookkeeping 后再执行，或显式加 --conf-path /usr/local/bin/ezbookkeeping/conf/ezbookkeeping.ini。systemd 单元中的 WorkingDirectory 就是为此而设。

Q4：启动日志显示 SecretKeyNoSet: true 有什么影响

secret_key 未设置时功能可用但属官方明示的不安全状态（密码哈希与会话签名使用空密钥）。若已有用户数据，此时补设密钥会导致既有用户无法登录——正确做法是首次启动前（3.5 节）就设置好。

Q5：网页打不开但服务 active

按顺序排查：curl http://localhost:8080/ 在本机测（本机通则是防火墙，ufw status 检查）；本机不通则 journalctl -u ezbookkeeping -n 50 看启动日志中监听地址是否被改为 127.0.0.1。

Q6：忘记 admin 密码

另一管理员可用 userdata user-modify-password -n admin -p <新密码> 重置；仅有一个管理员时，用 userdata user-session-new -n admin -t api -e 3600 签发临时令牌走 API 改密。命令细节见《ezbookkeeping 2.1.0 常用 CLI 命令与工具详解》。

九、卸载与清理

# 1. 停止并取消自启
systemctl disable --now ezbookkeeping

# 2. 备份或转移数据（记账数据无价，务必先备份）
tar -czf /root/ezbookkeeping-final-backup.tar.gz \
  /usr/local/bin/ezbookkeeping/conf /usr/local/bin/ezbookkeeping/data \
  /usr/local/bin/ezbookkeeping/storage

# 3. 删除程序与数据
rm -rf /usr/local/bin/ezbookkeeping

# 4. 删除服务单元与运行账户
rm -f /lib/systemd/system/ezbookkeeping.service
systemctl daemon-reload
userdel ezbookkeeping

确认干净：systemctl list-units | grep ezbookkeeping 无输出、id ezbookkeeping 报 no such user。

十、参考链接

官方二进制安装文档：https://ezbookkeeping.mayswind.net/installation_binary
系统要求：https://ezbookkeeping.mayswind.net/system_requirements
v2.1.0 Releases 下载页（含 SHA-256）：https://github.com/mayswind/ezbookkeeping/releases/tag/2.1.0
站内关联阅读：《ezbookkeeping 2.1.0 介绍与选型指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 配置参数详解》、《ezbookkeeping 2.1.0 常用 CLI 命令与工具详解》

以上全部命令与回显均在 Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）实测采集，实测日期 2026-10-23。