EZBOOKKEEPING Docker 容器化部署指南

概述

EZBOOKKEEPING是一款轻量级、自托管的个人财务管理应用，具有友好的用户界面和强大的记账功能。该应用设计资源占用低且高度可扩展，既能在树莓派等小型设备上流畅运行，也能扩展到NAS、微型服务器甚至大型集群环境。

作为一款开源应用，EZBOOKKEEPING特别注重隐私保护和用户控制权，提供了桌面和移动设备的优化界面，并支持PWA（渐进式Web应用），可添加到移动设备主屏幕，提供接近原生应用的体验。

EZBOOKKEEPING的核心优势包括：

开源且自托管，确保财务数据隐私与控制
轻量级设计，在低资源环境下也能高效运行
安装部署简单，支持Docker容器化部署
跨平台兼容，支持Windows、macOS、Linux系统及多种硬件架构
提供AI驱动的功能，如收据图像识别和MCP协议支持
强大的记账功能，包括多级账户和分类管理
多语言和多货币支持，适应全球化需求

本文档将详细介绍如何通过Docker容器化方式部署EZBOOKKEEPING，从环境准备到功能测试，帮助用户快速搭建属于自己的个人财务管理系统。

环境准备

Docker环境安装

部署EZBOOKKEEPING容器前，需要先安装Docker环境。推荐使用以下一键安装脚本，适用于主流Linux发行版：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

注意：执行上述命令可能需要管理员权限（sudo）。安装过程中会自动配置Docker所需的依赖环境和服务。

安装完成后，可以通过以下命令验证Docker是否正常运行：

bash
docker --version
docker info

若输出Docker版本信息和系统信息，则说明Docker环境安装成功。

启动Docker服务

安装完成后，确保Docker服务已启动并设置为开机自启：

bash
# 启动Docker服务
sudo systemctl start docker

# 设置Docker开机自启
sudo systemctl enable docker

# 验证Docker服务状态
sudo systemctl status docker

镜像准备

拉取EZBOOKKEEPING镜像

使用以下命令通过轩辕镜像加速地址拉取最新版本的EZBOOKKEEPING镜像：

bash
docker pull xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

验证镜像

拉取完成后，可使用以下命令查看本地镜像列表，确认EZBOOKKEEPING镜像已成功下载：

bash
docker images | grep ezbookkeeping

若输出类似以下信息，则说明镜像拉取成功：

xxx.xuanyuan.run/mayswind/ezbookkeeping   latest    xxxxxxxx    2 weeks ago    300MB

查看镜像标签

如需使用特定版本的EZBOOKKEEPING，可访问EZBOOKKEEPING镜像标签列表查看所有可用标签，然后使用相应标签拉取特定版本：

bash
docker pull xxx.xuanyuan.run/mayswind/ezbookkeeping:特定标签

容器部署

基础部署

对于快速体验或测试环境，可使用以下基础命令启动EZBOOKKEEPING容器：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

参数说明：

-d: 后台运行容器
--name ezbookkeeping: 指定容器名称为ezbookkeeping
-p 8080:8080: 端口映射，将容器内8080端口映射到主机8080端口

持久化部署

为确保数据持久化，建议挂载数据卷到容器中。通常EZBOOKKEEPING需要持久化存储的目录包括数据目录和配置目录：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/data:/app/data \
  -v /data/ezbookkeeping/config:/app/config \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

参数说明：

-v /data/ezbookkeeping/data:/app/data: 将主机/data/ezbookkeeping/data目录挂载到容器内/app/data目录，用于持久化应用数据
-v /data/ezbookkeeping/config:/app/config: 将主机/data/ezbookkeeping/config目录挂载到容器内/app/config目录，用于持久化配置文件

自定义配置部署

对于生产环境，建议通过环境变量自定义关键配置，如数据库连接信息、端口设置等：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/data:/app/data \
  -v /data/ezbookkeeping/config:/app/config \
  -e DB_TYPE=sqlite \
  -e DB_PATH=/app/data/ezbookkeeping.db \
  -e PORT=8080 \
  -e TZ=Asia/Shanghai \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

环境变量说明：

DB_TYPE: 数据库类型，支持sqlite、mysql、postgresql
DB_PATH: SQLite数据库文件路径（仅当DB_TYPE为sqlite时有效）
PORT: 应用监听端口
TZ: 时区设置

使用外部数据库部署

EZBOOKKEEPING支持MySQL和PostgreSQL等外部数据库，提高数据可靠性和性能。以下是使用MySQL数据库的部署示例：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/config:/app/config \
  -e DB_TYPE=mysql \
  -e DB_HOST=mysql-host \
  -e DB_PORT=3306 \
  -e DB_NAME=ezbookkeeping \
  -e DB_USER=ezbookuser \
  -e DB_PASSWORD=your_secure_password \
  -e PORT=8080 \
  -e TZ=Asia/Shanghai \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

注意：使用外部数据库时，需确保数据库服务已提前部署并创建好相应的数据库和用户权限。

验证容器状态

容器启动后，可使用以下命令检查容器运行状态：

bash
docker ps | grep ezbookkeeping

若输出类似以下信息，则说明容器正在正常运行：

xxxxxxxx    xxx.xuanyuan.run/mayswind/ezbookkeeping:latest    "docker-entrypoint.s…"   5 minutes ago    Up 5 minutes    0.0.0.0:8080->8080/tcp    ezbookkeeping

功能测试

访问应用界面

容器成功启动后，打开浏览器访问以下地址：

http://服务器IP:8080

若看到EZBOOKKEEPING的登录或注册页面，则说明应用部署成功。

基础功能测试

注册管理员账户

首次访问应用时，通常需要注册管理员账户。按照界面提示完成注册流程，创建管理员账号和密码。

创建测试数据

登录后，可进行以下基础功能测试：

创建账户（如现金账户、银行卡账户等）
添加交易记录（收入或支出）
查看仪表盘数据统计
测试分类管理功能

移动端访问测试

EZBOOKKEEPING提供移动端优化界面，可使用手机浏览器访问相同地址，测试移动端适配效果。对于支持PWA的浏览器，还可尝试将应用添加到手机主屏幕，体验接近原生应用的使用感受。

查看应用日志

若遇到访问问题，可通过查看容器日志排查故障：

bash
docker logs ezbookkeeping

或实时查看日志：

bash
docker logs -f ezbookkeeping

正常启动的日志应包含类似以下信息：

[INFO] Starting EZBOOKKEEPING application...
[INFO] Using SQLite database: /app/data/ezbookkeeping.db
[INFO] Server started on port 8080
[INFO] EZBOOKKEEPING is ready to use

API访问测试

如果需要集成或开发，可以使用curl命令测试API访问：

bash
curl -I http://服务器IP:8080/api/health

若返回状态码200，则说明API服务正常。

生产环境建议

安全加固

使用HTTPS加密

生产环境中，建议配置HTTPS加密以保护数据传输安全。可通过以下两种方式实现：

使用反向代理：在容器前部署Nginx或Traefik等反向代理服务器，由代理服务器处理HTTPS加密
直接配置SSL：通过环境变量或配置文件，直接在EZBOOKKEEPING应用中配置SSL证书

Nginx反向代理配置示例：

nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}

强化密码策略

设置强密码，包含大小写字母、数字和特殊字符
定期更换管理员密码
启用两因素认证（2FA）增强账户安全

网络访问控制

限制访问IP，仅允许信任的IP地址访问管理界面
使用防火墙限制端口访问，只开放必要的服务端口

性能优化

资源配置

根据实际使用情况调整容器资源限制：

bash
docker run -d \
  --name ezbookkeeping \
  --memory=1g \
  --memory-swap=2g \
  --cpus=0.5 \
  -p 8080:8080 \
  -v /data/ezbookkeeping/data:/app/data \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

参数说明：

--memory=1g: 限制容器使用最大内存为1GB
--memory-swap=2g: 限制容器使用的swap空间
--cpus=0.5: 限制容器使用的CPU资源

使用外部数据库

对于数据量较大或对性能有较高要求的场景，建议使用外部MySQL或PostgreSQL数据库，而非默认的SQLite：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/config:/app/config \
  -e DB_TYPE=postgresql \
  -e DB_HOST=db-host \
  -e DB_PORT=5432 \
  -e DB_NAME=ezbookkeeping \
  -e DB_USER=ezbookuser \
  -e DB_PASSWORD=your_secure_password \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

数据备份策略

定期备份数据

配置定期备份数据卷中的文件，可使用cron任务实现自动化备份：

bash
# 创建备份脚本 backup-ezbookkeeping.sh
#!/bin/bash
BACKUP_DIR="/data/backups/ezbookkeeping"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# 备份数据目录
docker exec ezbookkeeping tar czf - /app/data > $BACKUP_DIR/ezbookkeeping_data_$TIMESTAMP.tar.gz

# 保留最近30天的备份
find $BACKUP_DIR -name "ezbookkeeping_data_*.tar.gz" -type f -mtime +30 -delete

设置执行权限并添加到crontab：

bash
chmod +x backup-ezbookkeeping.sh
echo "0 2 * * * /path/to/backup-ezbookkeeping.sh" >> /etc/crontab

备份验证

定期验证备份文件的完整性和可恢复性，确保在数据丢失时能够有效恢复。

监控与告警

容器监控

使用Prometheus和Grafana监控容器运行状态，或使用简单的监控脚本检查容器状态：

bash
#!/bin/bash
# 检查容器是否运行
if ! docker inspect -f '{{.State.Running}}' ezbookkeeping > /dev/null 2>&1; then
    echo "EZBOOKKEEPING容器未运行，尝试重启..."
    docker start ezbookkeeping
    # 可添加邮件或其他告警通知
fi

应用健康检查

配置健康检查，及时发现并处理应用异常：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/data:/app/data \
  --health-cmd "curl -f http://localhost:8080/api/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

高可用性配置

对于对可用性要求较高的场景，可考虑以下方案：

多实例部署：部署多个EZBOOKKEEPING实例，通过负载均衡分发请求
数据库高可用：配置数据库主从复制或集群，避免单点故障
自动恢复：结合进程管理工具或容器编排平台，实现故障自动恢复

使用Docker Compose可简化多容器部署：

yaml
# docker-compose.yml
version: '3'
services:
  ezbookkeeping:
    image: xxx.xuanyuan.run/mayswind/ezbookkeeping:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ezbook_data:/app/data
      - ezbook_config:/app/config
    environment:
      - TZ=Asia/Shanghai
      - DB_TYPE=postgresql
      - DB_HOST=db
      - DB_PORT=5432
      - DB_NAME=ezbookkeeping
      - DB_USER=ezbookuser
      - DB_PASSWORD=your_secure_password
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=ezbookkeeping
      - POSTGRES_USER=ezbookuser
      - POSTGRES_PASSWORD=your_secure_password

volumes:
  ezbook_data:
  ezbook_config:
  postgres_data:

故障排查

常见问题解决

容器无法启动

端口冲突：检查8080端口是否已被其他服务占用

bash
netstat -tulpn | grep 8080

若已占用，可修改端口映射：

bash
docker run -d --name ezbookkeeping -p 8081:8080 xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

权限问题：检查挂载目录权限是否足够

bash
chmod -R 777 /data/ezbookkeeping

数据库连接失败：检查数据库服务是否可用，连接参数是否正确

bash
# 测试MySQL连接
mysql -h db-host -P 3306 -u ezbookuser -p

# 测试PostgreSQL连接
psql -h db-host -p 5432 -U ezbookuser -d ezbookkeeping

应用访问异常

查看应用日志：

bash
docker logs ezbookkeeping

检查容器IP和端口映射：

bash
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ezbookkeeping
docker port ezbookkeeping

检查防火墙设置：

bash
# 查看防火墙规则
ufw status
# 或
firewall-cmd --list-all

数据丢失问题

确认是否使用数据卷：检查容器是否正确挂载了数据卷

bash
docker inspect -f '{{ .Mounts }}' ezbookkeeping

检查备份策略：确认备份是否正常执行，必要时从备份恢复
检查文件系统：检查主机文件系统是否有错误或空间不足
```
bash
df -h
```

高级故障排查

进入容器内部

如需深入排查，可进入容器内部检查：

bash
docker exec -it ezbookkeeping /bin/sh

启用调试日志

通过设置环境变量启用详细日志：

bash
docker run -d \
  --name ezbookkeeping \
  -p 8080:8080 \
  -v /data/ezbookkeeping/data:/app/data \
  -e LOG_LEVEL=debug \
  xxx.xuanyuan.run/mayswind/ezbookkeeping:latest

网络问题诊断

使用网络诊断工具检查连接：

bash
# 安装网络工具
docker exec -it ezbookkeeping apk add --no-cache curl net-tools

# 检查DNS解析
docker exec -it ezbookkeeping nslookup google.com

# 检查网络连接
docker exec -it ezbookkeeping curl -v http://www.baidu.com

参考资源

官方文档与资源

EZBOOKKEEPING镜像文档（轩辕）
EZBOOKKEEPING镜像标签列表
项目GitHub仓库：https://github.com/mayswind/ezbookkeeping
官方演示：https://ezbookkeeping-demo.mayswind.net
官方文档：
- 英文
- 中文 (简体)

Docker相关资源

Docker官方文档：https://docs.docker.com/
Docker Compose文档：https://docs.docker.com/compose/
Docker Hub上的EZBOOKKEEPING镜像：https://hub.docker.com/r/mayswind/ezbookkeeping

总结

本文详细介绍了EZBOOKKEEPING的Docker容器化部署方案，从环境准备、镜像拉取、容器部署到功能测试，涵盖了从入门到生产环境的完整部署流程。EZBOOKKEEPING作为一款轻量级、自托管的个人财务管理应用，凭借其开源特性、低资源占用和丰富功能，成为个人财务管理的理想选择。

通过容器化部署，用户可以快速搭建属于自己的财务系统，同时保持系统的灵活性和可维护性。生产环境中，建议关注数据安全、备份策略和性能优化，以确保系统稳定可靠运行。

关键要点：

使用一键脚本可快速部署Docker环境
通过轩辕镜像加速可提升EZBOOKKEEPING镜像下载速度
生产环境中应配置数据持久化和定期备份
安全加固措施（如HTTPS配置、强密码策略）对保护财务数据至关重要
外部数据库和资源限制配置可提升系统性能和可靠性

后续建议：

深入学习EZBOOKKEEPING的高级特性，如AI收据识别和财务分析功能
根据个人需求定制账户结构和分类体系，优化记账流程
探索API集成可能性，实现与银行账单、电子支付等系统的数据同步
定期关注项目更新，及时升级以获取新功能和安全修复
参与社区讨论，分享使用经验并获取技术支持

通过合理配置和使用EZBOOKKEEPING，您可以更好地管理个人财务，掌握消费习惯，实现财务目标。如有任何问题或建议，欢迎查阅官方文档或参与项目社区交流。

EZBOOKKEEPING Docker 容器化部署指南

概述

环境准备

Docker环境安装

启动Docker服务

镜像准备

拉取EZBOOKKEEPING镜像

验证镜像

查看镜像标签

容器部署

基础部署

持久化部署

自定义配置部署

使用外部数据库部署

验证容器状态

功能测试

访问应用界面

基础功能测试

注册管理员账户

创建测试数据

移动端访问测试

查看应用日志

API访问测试

生产环境建议

安全加固

使用HTTPS加密

强化密码策略

网络访问控制

性能优化

资源配置

使用外部数据库

数据备份策略

定期备份数据

备份验证

监控与告警

容器监控

应用健康检查

高可用性配置

故障排查

常见问题解决

容器无法启动

应用访问异常

数据丢失问题

高级故障排查

进入容器内部

启用调试日志

网络问题诊断

参考资源

官方文档与资源

Docker相关资源

相关技术文章

总结

免责声明