Beancount-Trans 容器部署指南

部署步骤

步骤 1：准备环境

bash
# 1. 切换到项目目录（根据你的实际情况）
cd ~/projects  # 或任何你想存放的目录

# 2. 克隆项目
git clone https://github.com/dhr2333/Beancount-Trans.git

# 3. 进入项目目录
cd Beancount-Trans

步骤 2：初始化子模块（重要！）

bash
# 初始化所有子模块
git submodule update --init --recursive

# 将子模块切换到 main 分支
git submodule foreach git switch main

# 验证子模块状态
git submodule status

步骤 3：创建持久化卷（推荐）

bash
# 创建 PostgreSQL 数据卷
docker volume create postgres-data

# 创建 Redis 数据卷
docker volume create redis-data

# 查看创建的卷
docker volume ls | grep -E "postgres-data|redis-data"

步骤 4：修改 docker-compose.yml

bash
# 查看当前的 docker-compose.yml
cat docker-compose.yml

# 编辑文件，启用持久化存储
nano docker-compose.yml  # 或 vim / vi

需要修改的部分：

yaml
# docker-compose.yml 的修改示例

# 找到 PostgreSQL 服务配置，取消注释：
beancount-trans-postgres:
  # ... 其他配置 ...
  volumes:
    - postgres:/var/lib/postgresql/data  # 取消这行的注释

# 找到 Redis 服务配置，取消注释：
beancount-trans-redis:
  # ... 其他配置 ...
  volumes:
    - redis:/var/lib/redis/data          # 取消这行的注释

# 在文件末尾的 volumes 部分：
volumes:
  postgres:
    external: true          # 取消注释
    name: postgres-data    # 取消注释
  redis:
    external: true          # 取消注释
    name: redis-data       # 取消注释

步骤 5：启动容器

bash
# 前台启动（查看日志）
docker compose up

# 或后台启动
docker compose up -d

# 查看启动状态
docker compose ps

# 查看日志
docker compose logs -f

配置说明

端口映射

默认配置中：

• Beancount-Trans 服务: 38001 端口
• PostgreSQL: 5432 端口（仅在 Docker 网络内）
• Redis: 6379 端口（仅在 Docker 网络内）

如果需要修改端口，编辑 docker-compose.yml：

yaml
beancount-trans:
  ports:
    - "38001:38001"  # 修改为 "自定义端口:38001"

环境变量配置

如果需要修改配置，可以编辑环境变量：

yaml
beancount-trans:
  environment:
    - DATABASE_URL=postgresql://username:password@beancount-trans-postgres:5432/beancount_trans
    - REDIS_URL=redis://beancount-trans-redis:6379
    - PORT=38001

访问应用

bash
# 应用启动后，通过以下方式访问：
# 本地访问
http://localhost:38001/trans

# 或服务器IP访问（如果端口已开放）
http://你的服务器IP:38001/trans

验证部署

bash
# 1. 检查容器状态
docker compose ps

# 应该看到类似输出：
# NAME                           STATUS              PORTS
# beancount-trans               Up 5 minutes        0.0.0.0:38001->38001/tcp
# beancount-trans-postgres      Up 5 minutes        5432/tcp
# beancount-trans-redis         Up 5 minutes        6379/tcp

# 2. 检查服务是否正常
curl http://localhost:38001/health  # 如果有健康检查端点

# 3. 查看应用日志
docker compose logs beancount-trans

使用说明

上传文件解析

1. 访问 http://localhost:38001/trans
2. 上传支付宝、微信等导出的 CSV 文件
3. 系统会解析并生成 Beancount 格式的交易记录
4. 复制结果到你的 Beancount 账本文件

停止和重启

bash
# 停止服务
docker compose down

# 停止并删除数据卷（慎用！）
docker compose down -v

# 重启服务
docker compose restart

# 查看资源使用
docker compose top

故障排除

问题 1：端口冲突

bash
# 检查端口占用
netstat -tlnp | grep :38001

# 如果端口被占用，修改 docker-compose.yml 中的端口映射

问题 2：子模块初始化失败

bash
# 重新初始化子模块
rm -rf .git/modules/*
git submodule deinit -f .
git submodule update --init --recursive --force

问题 3：数据库连接失败

bash
# 检查 PostgreSQL 日志
docker compose logs beancount-trans-postgres

# 检查应用连接
docker exec -it beancount-trans-beancount-trans-1 sh
# 在容器内执行：
# ping beancount-trans-postgres
# nc -zv beancount-trans-postgres 5432

问题 4：持久化存储权限问题

bash
# 如果 PostgreSQL 启动失败，可能是权限问题
docker volume inspect postgres-data

# 临时解决方案：删除并重新创建
docker compose down -v
docker volume rm postgres-data redis-data
docker volume create postgres-data
docker volume create redis-data
docker compose up -d

升级应用

bash
# 1. 拉取最新代码
git pull origin main

# 2. 更新子模块
git submodule update --init --recursive

# 3. 重启服务
docker compose down
docker compose pull  # 拉取最新镜像
docker compose up -d

备份数据

bash
# 备份 PostgreSQL 数据
docker exec beancount-trans-postgres-1 pg_dumpall -U postgres > backup_$(date +%Y%m%d).sql

# 备份 Redis 数据
docker exec beancount-trans-redis-1 redis-cli SAVE
docker cp beancount-trans-redis-1:/data/dump.rdb ./redis_backup_$(date +%Y%m%d).rdb

完整部署脚本

bash
#!/bin/bash
# deploy_beancount_trans.sh

set -e  # 遇到错误退出

echo "=== Beancount-Trans 部署脚本 ==="

# 1. 克隆项目
echo "1. 克隆项目..."
git clone https://github.com/dhr2333/Beancount-Trans.git || true
cd Beancount-Trans

# 2. 初始化子模块
echo "2. 初始化子模块..."
git submodule update --init --recursive
git submodule foreach git switch main

# 3. 创建数据卷
echo "3. 创建持久化数据卷..."
docker volume create postgres-data 2>/dev/null || echo "postgres-data 卷已存在"
docker volume create redis-data 2>/dev/null || echo "redis-data 卷已存在"

# 4. 启用持久化配置
echo "4. 配置持久化存储..."
cp docker-compose.yml docker-compose.yml.backup

# 使用 sed 自动修改配置文件
sed -i 's|# volumes:|volumes:|' docker-compose.yml
sed -i 's|#   - postgres:/var/lib/postgresql/data|  - postgres:/var/lib/postgresql/data|' docker-compose.yml
sed -i 's|#   - redis:/var/lib/redis/data|  - redis:/var/lib/redis/data|' docker-compose.yml
sed -i 's|#volumes:|volumes:|' docker-compose.yml
sed -i 's|#  postgres:|  postgres:|' docker-compose.yml
sed -i 's|#    external: true|    external: true|' docker-compose.yml
sed -i 's|#    name: postgres-data|    name: postgres-data|' docker-compose.yml
sed -i 's|#  redis:|  redis:|' docker-compose.yml
sed -i 's|#    external: true|    external: true|' docker-compose.yml
sed -i 's|#    name: redis-data|    name: redis-data|' docker-compose.yml

# 5. 启动服务
echo "5. 启动容器..."
docker compose up -d

# 6. 检查状态
echo "6. 检查部署状态..."
sleep 10
docker compose ps

echo "=== 部署完成 ==="
echo "访问地址: http://localhost:38001/trans"
echo "查看日志: docker compose logs -f"

保存为 deploy.sh，然后运行：

bash
chmod +x deploy.sh
./deploy.sh