使用 Docker 与 ezBookkeeping 快速搭建美观的个人记账系统

简介

个人记账应用多如牛毛，但许多应用都只兼容单一平台，如果你同时使用安卓和 iOS 设备，管理财务就会变得非常麻烦。

今天介绍的 ezBookkeeping 可以解决这一痛点，它是一款轻量、自托管（self-hosted） 的个人记账应用，界面友好，功能强大。

而且部署起来非常简单！只要你有 Docker，一行命令就能搞定。而且它对硬件要求极低，无论是树莓派、NAS 还是云端服务器，都能稳定运行。

在开始前，可以在这里查看在线演示：https://ezbookkeeping-demo.mayswind.net

ezbookkeeping-demo-preview

ezBookkeeping 主要特点

ezBookkeeping 是一款使用 Go 与 Vue 编写的开源个人记账应用：GitHub 项目地址，目前有 1.4k 的 Stars。

  • 开源 & 自托管： 专为隐私与数据自主而设计
  • 轻量 & 快速： 性能优化，即便在资源有限的设备上也运行流畅
  • 安装简单： 支持 Docker
  • 现代且友好的用户界面： 针对手机与桌面优化的 UI，支持 PWA
  • AI 驱动： 支持 MCP
  • 强大的记账功能：
    • 二级账户与分类结构
    • 支持为交易添加图片附件
    • 记录交易地理位置并在地图上展示
    • 支持周期性交易
    • 高级筛选、搜索、数据可视化与分析功能
  • 本地化与国际化支持 ：多语言与多币种支持、
  • 安全可靠： 两步认证 (2FA)、登录频次限制、应用锁
  • 数据导入/导出：支持 CSV、OFX、QFX、QIF、IIF、Camt.053、MT940、GnuCash、FireFly III、Beancount、随手记、支付宝以及微信账单 等多种格式

我们将使用 Docker 与 Docker Compose 来快速搭建 ezBookkeeping。

一、环境准备

在开始之前，需要拥有一个自己的 VPS 或是支持 Docker 容器的 NAS 系统。

1. 安装 Docker 和 Docker Compose

这是我们容器化部署的基础。如果你的服务器尚未安装，可以参考以下教程。

延伸阅读: 在 Debian 12 中安装 Docker 以及 Docker Compose

2. 准备域名

为了通过 HTTPS 安全地访问你的记账应用，你需要一个域名，并将其解析到你的服务器 IP。

3. 创建项目目录

为 ezBookkeeping 创建一个专用的目录，用于存放配置文件和数据。

1
mkdir -p /opt/ezbookkeeping

二、使用 Docker Compose 部署

创建 compose.yml 文件

在项目目录 (/opt/ezbookkeeping) 中，创建一个名为 compose.yml 的文件。

1
2
3
cd /opt/ezbookkeeping

vim compose.yml

我们将使用 sqlite 作为数据库存储，在开始前需要创建对应的文件夹并设置权限：

1
2
mkdir -p ./data ./log ./storage
chown -R 1000:1000 ./data ./log ./storage

然后创建 compose.yaml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
services:
  ezbookkeeping:
    image: mayswind/ezbookkeeping:latest
    container_name: ezbookkeeping
    restart: unless-stopped
    ports:
      - 127.0.0.1:8080:8080 # 仅监听本地端口，由反向代理访问
    environment:
      - "EBK_SERVER_DOMAIN=https://ez.yourdomain.com" # 将这里替换为你的实际域名
      - "EBK_SERVER_ENABLE_GZIP=true"
      - "EBK_LOG_MODE+file"
      # 务必修改为一个随机字符串
      - "EBK_SECURITY_SECRET_KEY=its_should_be_a_random_string" 
    volumes:
      - ./data:/ezbookkeeping/data
      - ./storage:/ezbookkeeping/storage
      - ./log:/ezbookkeeping/log
      - /etc/localtime:/etc/localtime:ro

可以使用下面命令生成一个 32 位的随机字符串设置 EBK_SECURITY_SECRET_KEY

1
openssl rand -hex 16

配置解析:

  • ports: 将容器的 8080 端口映射到主机的 127.0.0.1:8080。127.0.0.1 表示 ezBookkeeping 只能通过本机（或反向代理）访问，增强安全性。
  • environment:
    • EBK_SERVER_DOMAIN : 设置需要使用的域名，必须是 https:// 开头。
    • EBK_SECURITY_SECRET_KEY: 用于加密令牌的安全密钥，务必修改为一个足够长且随机的字符串。
  • volumes: 将 ezBookkeeping 的数据、附件和日志持久化存储在主机当前目录下的对应文件夹中，确保容器更新或重建后数据不会丢失。

ports 可以先设置为 "8080:8080"，在容器启动后确认可以正常访问再设置为 "127.0.0.1:8080:8080"

容器中的默认路径：

  • 配置文件 ：/ezbookkeeping/conf/ezbookkeeping.ini
  • 数据库文件（使用 sqlite3 数据库）： /ezbookkeeping/data/ezbookkeeping.db
  • 日志文件 ：/ezbookkeeping/log/ezbookkeeping.log
  • 对象存储根路径 ：/ezbookkeeping/storage/

启动服务

在 compose.yml 文件所在目录中，执行以下命令来拉取镜像并启动服务：

1
docker compose up -d

在 ports 设置中如果未指定为 127.0.0.1:8080 则可以访问 http://ip:8080 进行访问 ezBookkeeping 的 Web 界面

三、配置 Nginx 反向代理

为了安全地通过 HTTPS 访问你的记账应用，强烈建议使用 Nginx 等反向代理工具。

以下是一个 Nginx 的配置示例。你需要为你的域名申请一个 SSL 证书（例如通过 Let’s Encrypt）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# /etc/nginx/sites-enable/ez.yourdomain.com.conf
server {
    listen 80;
    server_name ez.yourdomain.com;

    # 将所有 HTTP 请求重定向到 HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name ez.yourdomain.com;

    # SSL 证书路径 (请替换为你的实际路径)
    ssl_certificate /path/to/your/fullchain.pem;
    ssl_certificate_key /path/to/your/privkey.pem;

    # 安全相关的 SSL 设置 (推荐)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注意：

  • 将 ez.yourdomain.com 替换为你的实际域名。
  • 将 SSL 证书路径 /path/to/your/fullchain.pem 和 /path/to/your/privkey.pem 替换为你的证书文件实际存放的路径。

测试并重载 Nginx 配置：

1
2
nginx -t
nginx -s reload

四、开始使用

现在，你可以通过浏览器访问 https://ez.yourdomain.com 来打开你的专属记账应用了。

首次访问时，会打开登录界面，我们看点击 创建新账户 进行注册。

ezbookkeeping-login

创建账户后，可以选择是否使用预设分类，完成之后，就可以开始记录你的第一笔交易了！

五、导入 Firefly III 数据

我之前使用的是另一个开源的记账系统 Firefly III ，主要是被 ezBookkeeping 的界面吸引，因此决定体验一段时间。

项目 Firefly III ezBookkeeping
界面 紧凑，传递信息更多 美观，现代化
分类 不区分支出、收入或是转账类别 需要设置二级分类
多货币 分开显示 按照汇率兑换加和显示
报表 支持 支持
资源占用 130MB+ 20MB+

总结是 Firefly III 更为强大，显示多币种货币更直观，录入较为繁琐， ezBookkeeping 则是更轻量化，界面美观，录入方便，甚至支持 MCP

迁移过程

首先我们需要在 ezBookkeeping 中创建与 Firefly III 对应的分类、账户

  • 分类在 ezBookkeeping 中需要放在二级分类内才可以，ezBookkeeping 创建交易时无法选择一级分类

    也可以在导入界面直接批量创建不存在的分类，这时所有分类会创建在一个 默认一级分类 下面

然后获取 Firefly III 的备份数据，在 Firefly III 点击 导出数据 > 导出所有交易 获取 csv 文件

在 ezBookkeeping 交易详情中点击 导入，选择 其他金融应用文件格式 > Firefly III 数据导出文件

对无效的部分进行调整，然后点击导入。

六、关闭注册

如果我们只是个人使用，可以在完成账户注册之后，关闭 ezBookkeeping 的注册功能。

ezBookkeeping 的容器内配置文件位于 /ezbookkeeping/conf/ezbookkeeping.ini ，我们可以在 compose.yml 文件中通过 environment 选项覆盖

1
2
3
environment:
  # 关闭注册
  - "EBK_USER_ENABLE_REGISTER=false"

然后重启服务器

1
2
docker compose down
docker compose up -d

完整的可覆盖配置可以在这里查看 ： ezBookkeeping - 配置

总结

通过 Docker 和 ezBookkeeping，我们只用了几分钟就搭建起一个功能全面、界面美观且数据完全由自己掌控的个人记账系统。相比于市面上的商业记账 App，自托管方案不仅免费，还从根本上保障了你的财务数据隐私。