alcibiadesc/happy-balance

💰 Happy Balance - 个人财务追踪工具

镜像概述

Happy Balance是一款以隐私为核心的开源个人财务追踪工具，区别于Fintonic、Mint等云服务应用，它可完全部署在你的自有基础设施上，财务数据永不离开你的控制范围。其核心原则包括：隐私优先、极简设计、零跟踪、开源透明。

核心功能

基础功能

• 📊 支出追踪：分类记录所有支出
• 📈 可视化分析：直观图表展示财务状况
• 🏷️ 智能分类：AI驱动的交易自动分类
• 💱 多币种支持：适配不同货币的收支管理
• 🌐 多语言：支持英文和西班牙文
• 🌙 暗黑模式：护眼设计
• 📱 响应式布局：适配桌面、平板和移动端

技术特性

• 🔐 JWT认证：安全的用户会话管理
• 👥 多用户支持：基于角色的访问控制（管理员、用户、查看者）
• 📁 CSV导入：支持银行交易数据导入（兼容N26格式）
• 🔄 实时更新：界面即时同步数据
• 🐳 Docker就绪：通过Docker Compose轻松部署

银行导入兼容性

• N26：完全支持N26 CSV导出格式
• 通用CSV：可自定义配置适配其他银行

使用场景

1. 个人日常记账：记录每日收支，清晰掌握消费习惯
2. 家庭财务管理：多用户协作管理家庭共同收支
3. 多币种跟踪：适用于跨境工作或旅行的用户管理不同货币资产
4. 预算规划：通过可视化分析制定合理的预算方案

配置说明

Docker部署示例

方式1：直接运行镜像

bash
docker run -d \
  --name happy-balance \
  -p 5173:3000 \
  -e VITE_API_URL=http://localhost:3004/api \
  alcibiadesc/happy-balance:latest

方式2：Docker Compose部署

yaml
version: "3.8"

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: 你的密码
      POSTGRES_DB: happy_balance

  backend:
    build: ./backend
    environment:
      DATABASE_URL: postgresql://postgres:你的密码@postgres:5432/happy_balance
      JWT_ACCESS_SECRET: 至少32位的密钥
    ports:
      - "3004:3004"

  frontend:
    build: .
    environment:
      VITE_API_URL: http://localhost:3004/api
    ports:
      - "5173:5173"

环境变量配置

在根目录创建.env文件，配置以下变量：

env
# 后端配置
DATABASE_URL=postgresql://用户:密码@localhost:5432/happy_balance
JWT_ACCESS_SECRET=至少32位的密钥
JWT_REFRESH_SECRET=至少32位的密钥
ADMIN_USERNAME=admin
ADMIN_PASSWORD=安全密码

# 前端配置
VITE_API_URL=http://localhost:3004/api

默认凭证

• 用户名：admin
• 密码：admin123
  ⚠️ 生产环境请立即修改默认凭证！

开源协议：GPL v3
注意：本项目为实验性版本，可能存在bug，生产环境使用前请充分测试。 ===END===