Zoeille/picsou-finance
GitHub: Zoeille/picsou-finance
Picsou 是一款自托管个人财务仪表板，通过聚合同步银行、证券及加密货币账户数据来实现净资产追踪与深度分析。
Stars: 419 | Forks: 35
# Picsou
**自托管个人财务仪表板**
在一个地方追踪银行账户、证券经纪、加密货币和净资产。
[](LICENSE)
[新手入门](#getting-started) · [功能](#features) · [开发](#development) · [安全](SECURITY.md)
## 免责声明
## 功能
- **账户聚合** — 银行账户（LEP、PEA、Livret、活期账户）、证券经纪、加密货币钱包、链上地址、债务/贷款
- **银行同步** — Enable Banking（PSD2/OAuth，2000+ 欧盟银行）。
- **证券经纪同步** — 通过 WebSocket 或 CSV 导入接入 Trade Republic
- **加密货币** — Binance 交易所同步，链上 BTC/ETH/SOL 地址追踪
- **实时价格** — CoinGecko（加密货币），Yahoo Finance（股票/ETF）
- **安全洞察** — 在持仓详情弹窗中，提供每个持仓的资产类型检测以及 ETF 构成分析（主要持仓、国家和行业分布）
- **净资产追踪** — 历史快照、堆叠面积图、按账户划分的明细
- **储蓄目标** — 带有截止日期的目标，支持跨账户的进度追踪
- **多成员家庭** — 一个管理员可管理多个配置文件（儿童、配偶）。支持按资源共享（`NONE` / `ALL` / `MANUAL`），可选择通过激活链接将受管理的配置文件升级为完整登录账户。
- **2FA + 记住我** — 每个用户可选的 TOTP，10 个一次性恢复代码，带有轮换 token 的 90 天“记住我” cookie，“信任此设备”以跳过 TOTP，支持在设置中按会话撤销。
- **GDPR 数据导出** — 自助 ZIP 导出（JSON + 按实体划分的 CSV），需通过重新身份验证，频率限制为每小时 5 次。
- **Finary 导入** — CSV 导入或直接 API 同步
- **i18n** — 英语和法语
- **深色模式** — 系统/浅色/深色模式，支持无闪烁主题切换
## 架构
```
┌──────────────────┐ ┌───────────────────────┐ ┌────────────┐
│ React Frontend │────▶│ Spring Boot Backend │────▶│ PostgreSQL │
│ (Vite/Bun) │◀────│ (Tomcat :8080) │ │ (:5432) │
└──────────────────┘ └───────────┬────────────┘ └────────────┘
│
┌──────────────┼──────────────┬──────────────┐
▼ ▼ ▼ ▼
Enable Banking CoinGecko Yahoo Finance Trade Republic
(PSD2/OAuth) (crypto) (stocks/ETF) (WebSocket)
```
- **端口与适配器** — `BankConnectorPort`、`PriceProviderPort`、`TradeRepublicPort`、`BoursoPort` 等。无需修改业务逻辑即可更换提供商。
- **双层身份** — `AppUser`（身份验证） → `FamilyMember`（领域）。每个实体都由 `member_id` 限定范围；管理员可以通过 `?memberId=X` 代表受管理的配置文件执行操作。
- **Flyway** — 版本化数据库迁移
- **JWT 认证** — HttpOnly cookie，SameSite=Lax（兼容 Safari iOS），refresh token 轮换
- **2FA (TOTP)** — 可选，带有哈希恢复代码和受信任设备的 cookie
- **AES-256-GCM** — 对静态 API 密钥（Binance、TOTP 密钥、银行会话 token）进行强制加密
- **速率限制** — 在登录、MFA 验证、同步 endpoint 和数据导出环节使用 Bucket4j
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| 后端 | Java 21, Spring Boot 3.4, Maven |
| 前端 | React 19, TypeScript 5.9, Vite 7, Tailwind v4, Bun |
| 数据库 | PostgreSQL 16, Flyway |
| 运行时 | Docker (Nginx + Spring Boot + supervisor) |
## 新手入门
### 前置条件
- [Docker](https://docs.docker.com/get-docker/) & Docker Compose v2
- （可选）一个用于银行同步的 [Enable Banking](https://enablebanking.com/) 账户
### 1. 克隆
```
git clone https://github.com/Zoeille/picsou-finance.git
cd picsou-finance
```
### 2. 运行（零配置）
Picsou 会将预构建的多架构（amd64/arm64）镜像发布到 GitHub Container Registry，因此无需编译：
| 镜像 | 包 |
|-------|---------|
| `ghcr.io/zoeille/picsou-finance` | [picsou-finance](https://github.com/users/Zoeille/packages/container/package/picsou-finance) — 应用（前端 + 后端） |
| `ghcr.io/zoeille/picsou-finance/tr-auth` | [picsou-finance/tr-auth](https://github.com/users/Zoeille/packages/container/package/picsou-finance%2Ftr-auth) — Trade Republic 认证 sidecar |
```
docker compose -f docker/docker-compose.yml pull # fetch the published images from GHCR
docker compose -f docker/docker-compose.yml up -d
```
首次启动时，入口程序会自动生成 `JWT_SECRET`、`CRYPTO_ENCRYPTION_KEY` 和 `POSTGRES_PASSWORD`（持久化存储在 `picsou_data` 卷的 `/data/.secrets/` 目录下）。打开 http://localhost:8080 — **设置向导**将引导您完成管理员凭据、CORS 以及（可选的）Enable Banking 的配置。
### 3. 高级配置（可选）
如果您希望预先设置所有内容（CI、外部密钥管理器等）：
```
cp docker/.env.example docker/.env
```
| 变量 | 设置时机 | 描述 |
|----------|-------------|-------------|
| `POSTGRES_PASSWORD` | 覆盖自动生成 | 强随机密码 |
| `JWT_SECRET` | 覆盖自动生成 | `openssl rand -base64 48` |
| `CRYPTO_ENCRYPTION_KEY` | 覆盖自动生成 | `openssl rand -base64 32` |
| `APP_USERNAME` / `APP_PASSWORD_HASH` | 跳过向导 | `htpasswd -bnBC 12 "" YOUR_PASSWORD \| tr -d ':\r\n'` |
| `ALLOWED_ORIGINS` | 非本地主机 | 例如 `http://your-nas-ip:8080` |
| `SECURE_COOKIES` | 纯 HTTP | 如果前端没有 TLS，设为 `false` |
| `ENABLEBANKING_*` | 跳过向导 | 来自您的 [Enable Banking dashboard](https://enablebanking.com/) |
| `BOURSO_AUTH_URL` | 自定义 sidecar | 默认为 `http://bourso-auth:8001` |
### 4. Enable Banking 密钥设置（可选）
```
mkdir -p docker/secrets
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out docker/secrets/enablebanking.pem
openssl rsa -pubout -in docker/secrets/enablebanking.pem -out enablebanking_public.pem
```
将 `enablebanking_public.pem` 上传到您的 Enable Banking dashboard。
## 开发
### 后端
```
cd backend
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn spring-boot:run -Dspring-boot.run.profiles=dev # Requires PostgreSQL on :5432
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn test # Run tests
```
后端 Maven 在执行 `validate` 阶段时会强制要求 Java 21；在本地运行后端命令之前，请将 `JAVA_HOME` 指向 JDK 21 安装目录。
### 前端
```
cd frontend
bun install # Install dependencies
bun run dev # Dev server on :5173 (proxies /api/* → localhost:8080)
bun run build # TypeScript check + Vite build
bunx vitest run # Unit tests
```
## 安全
有关漏洞报告政策，请参阅 [SECURITY.md](SECURITY.md)。
## 许可证
[Apache 2.0 + Commons Clause](LICENSE) — 可免费用于个人使用和托管服务。未经许可，禁止用于商业 SaaS。标签：个人财务, 加密货币, 占用监测, 域名枚举, 家庭理财, 测试用例, 自托管, 请求拦截, 资产管理, 银行账户同步