一、ezBookkeeping介绍

1.1 ezBookkeeping简介

ezBookkeeping 是一款轻量级、开源、自托管的个人财务管理应用。它注重隐私与用户控制，界面简洁友好，同时具备强大的记账功能。只需一条 Docker 命令即可快速部署，适用于从树莓派（Raspberry Pi）到 NAS、微型服务器乃至大型集群等多种硬件环境，兼顾低资源消耗与高可扩展性。

1.2 ezBookkeeping主要特点

🔒 隐私与安全

• 开源 & 自托管：完全掌控你的财务数据
• 支持双因素认证（2FA）
• 登录频率限制，防止暴力破解
• 应用锁（支持 PIN 码或 WebAuthn）

⚙️ 部署与兼容性

• 轻量高效：优化性能，可在低配设备（如树莓派）流畅运行
• 一键部署：Docker 原生支持，安装极其简单
• 多数据库支持：SQLite、MySQL、PostgreSQL
• 跨平台：支持 Windows、macOS、Linux
• 多架构兼容：x86、amd64、ARM

💻 用户体验

• 响应式 UI：适配手机与桌面端
• PWA 支持：提供类原生移动应用体验
• 深色模式（Dark Mode）
• 多语言、多币种、多时区支持
• 自定义日期、数字、货币格式
• 自动获取汇率

🧠 智能功能

• AI 驱动的收据图像识别
• 支持 MCP（Model Context Protocol），便于集成大模型/AI 功能

📊 强大的记账能力

• 两级账户与分类体系
• 交易可附加图片（如发票、收据）
• 地理位置记录（集成地图）
• 支持周期性交易（如月租、订阅）
• 高级筛选、搜索、可视化图表与数据分析

🔄 数据互通

• 支持多种格式导入/导出：
  CSV、OFX、QFX、QIF、IIF、Camt.053、MT940、GnuCash、Firefly III、Beancount 等

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署ezBookkeeping个人记账工具。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Tue 2025-12-02 00:51:31 CST; 1min 11s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 75393 (dockerd)
      Tasks: 32
     Memory: 34.1M (peak: 34.8M)
        CPU: 1.248s
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

root@jeven:~# docker -v
Docker version 28.5.0, build 887030f

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven:~# docker compose version
Docker Compose version v2.39.4

四、拉取ezBookkeeping镜像

下载ezBookkeeping镜像，镜像名称为：mayswind/ezbookkeeping:1.2。

docker pull mayswind/ezbookkeeping:1.2

五、部署ezBookkeeping服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/ezbookkeeping/{data,storage,log} && cd /data/ezbookkeeping

• 目录权限设置：

chmod -R 777 /data/ezbookkeeping/

5.2 docker compose方式部署

新建及编辑docker-compose.yaml文件，宿主机映射端口可自行设置，注意防止端口冲突。

vim docker-compose.yaml

version: "3"

services:
  ezbookkeeping:
    image:  mayswind/ezbookkeeping:1.2
    container_name: ezbookkeeping
    restart: always 
    ports:
      - 9660:8080
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./storage:/ezbookkeeping/storage
      - ./log:/ezbookkeeping/log
    #  - ./ezbookkeeping.ini:/ezbookkeeping/conf/ezbookkeeping.ini
    environment:
      - EBK_DATABASE_TYPE=mysql
      - EBK_DATABASE_HOST=mysql:3306
      - EBK_DATABASE_NAME=ezbookkeeping
      - EBK_DATABASE_USER=ezbookkeeping
      - EBK_DATABASE_PASSWD=ezbookkeeping
      - EBK_LOG_MODE=file
      - EBK_SECURITY_SECRET_KEY=its_should_be_a_random_string
      - EBK_MCP_ENABLE_MCP=true
    # depends_on:
    #  mysql:
    #    condition: service_healthy

  mysql:  
    image: mysql:8.0 
    container_name: ezbookkeeping-mysql
    restart: unless-stopped
    volumes:  
        - ./data:/var/lib/mysql
    environment:  
        - MYSQL_DATABASE=ezbookkeeping  
        - MYSQL_USER=ezbookkeeping  
        - MYSQL_PASSWORD=ezbookkeeping  
        - MYSQL_ROOT_PASSWORD=ezbookkeeping
    healthcheck:  
        test: ["CMD", "mysqladmin", "ping", "-p ezbookkeeping"]  
        retries: 3  
        timeout: 5s

5.3 创建ezBookkeeping容器

执行以下命令，创建ezBookkeeping容器。

docker compose up -d

5.4 查看ezBookkeeping容器状态

检查ezBookkeeping容器运行状态，确保ezBookkeeping容器正常启动。

root@jeven:/data/ezbookkeeping# docker compose ps
WARN[0000] /data/ezbookkeeping/docker-compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
NAME                  IMAGE                        COMMAND                   SERVICE         CREATED              STATUSPORTS
ezbookkeeping         mayswind/ezbookkeeping:1.2   "/docker-entrypoint.…"   ezbookkeeping   About a minute ago   Up 47 seconds                 0.0.0.0:9660->8080/tcp, [::]:9660->8080/tcp
ezbookkeeping-mysql   mysql:8.0                    "docker-entrypoint.s…"   mysql           About a minute ago   Up About a minute (healthy)   3306/tcp, 33060/tcp

5.5 检查ezBookkeeping容器日志

检查容器运行日志，确保ezBookkeeping服务正常运行。

docker compose logs

六、访问ezBookkeepinge服务

6.1 访问ezBookkeeping首页

浏览器地址： http://<个人的服务器IP>:9660，访问ezBookkeeping初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 注册ezBookkeeping

在ezBookkeeping账号注册页，我们自行填写账号信息会注册即可。

6.3 记账效果

添加自己的账户信息，就可以添加各项账单事项了，如下所示：

七、总结

通过本次实战，我们成功使用 Docker 快速部署了 ezBookkeeping 个人记账工具，充分体验了其轻量、易用与功能强大的优势。整个部署过程简洁高效，仅需几条命令即可完成服务搭建，极大降低了自托管财务管理的门槛。ezBookkeeping 不仅界面友好、支持多端访问，还具备 AI 识别、多币种、数据导入导出等实用特性，非常适合注重隐私的个人用户。未来可进一步结合 HTTPS、备份策略或 NAS 环境，打造更安全可靠的私人财务管理系统。