jaiminpanchal2002/expense-manager
GitHub: jaiminpanchal2002/expense-manager
基于 Spring Boot 与 PostgreSQL 的安全全栈费用管理应用，内置完整的 DevSecOps CI/CD 流水线以保障代码与部署安全。
Stars: 0 | Forks: 0
# 安全费用管理器
[](https://github.com/jaiminpanchal2002/expense-manager/actions/workflows/devsecops.yml)
[](#)
[](#)
[](#)
一个安全的企业级全栈 Web 应用程序，旨在帮助用户跟踪日常支出、监控预算并导出报告，由完整的端到端 **DevSecOps CI/CD pipeline** 提供支持。
* **开发者**: Jaimin Panchal (首席工程师 & DevSecOps 专家) & Purvishaben Desani
* **生产环境 URL**: [在线演示](https://expense-manager-nnor.onrender.com/dashboard)
## 🏗️ 架构图
### 1. 系统架构
该应用程序采用清晰的三层 MVC 架构构建。Spring Boot 后端提供安全的 Web endpoint，通过 Thymeleaf 动态渲染，并与 PostgreSQL 数据库层进行通信。
```
graph TD
User([User Browser]) -->|HTTPS| WebUI[Frontend: Thymeleaf / Bootstrap / HTML5]
WebUI -->|Form Submissions / Requests| Controllers[Spring MVC Controllers]
subgraph Spring Boot Backend
Controllers -->|Data Validation / Security Checks| Security[Spring Security Context]
Security -->|Authorized Requests| Services[Business Services: UserService, ExpenseService]
Services -->|Data Access Object Pattern| Repositories[JPA Repositories]
end
subgraph External integrations
Services -->|REST API / OkHttp| Brevo[Brevo SMTP / Email Service]
end
subgraph Data Store
Repositories -->|JPA/Hibernate / Prepared Statements| Postgres[(PostgreSQL Database)]
end
```
### 2. 数据库实体关系图 (ERD)
数据库采用规范化的 schema 设计，以保持高性能。一个用户可以拥有多笔支出（`1-to-Many`），通过外键约束进行保护并正确建立了索引。
```
erDiagram
USERS {
Long id PK "GENERATED BY DEFAULT AS IDENTITY"
String name "NOT NULL"
String email UK "NOT NULL, UNIQUE"
String password "NOT NULL (BCrypt hashed)"
}
EXPENSES {
Long id PK "GENERATED BY DEFAULT AS IDENTITY"
String title "NOT NULL"
BigDecimal amount "NOT NULL (Precision: 10, Scale: 2)"
String currency "NOT NULL (Default: EUR)"
Category category "ENUM (FOOD, GROCERIES, RENT, etc.)"
LocalDate expenseDate "NOT NULL"
String note
Long user_id FK "NOT NULL REFERENCES USERS(id)"
}
USERS ||--o{ EXPENSES : "owns"
```
### 3. 核心业务流程时序图
此图概述了当用户记录了一笔超出其月度预算的支出时，各组件之间的交互情况，该操作会触发自动化的邮件通知。
```
sequenceDiagram
autonumber
actor User as User (Browser)
participant Ctrl as ExpenseController
participant Service as ExpenseService
participant Repo as ExpenseRepository
participant DB as PostgreSQL
participant Email as EmailService
participant Brevo as Brevo API
User->>Ctrl: POST /expenses (ExpenseRequest)
Ctrl->>Service: create(expenseRequest, user)
Service->>Repo: findByUserAndExpenseDateBetweenOrderByExpenseDateDesc(user, start, end)
Repo->>DB: Query current month expenses
DB-->>Repo: Return List
Repo-->>Service: List of expenses (total: 500 EUR)
Note over Service: Calculates new total (500 + 200 = 700 EUR)
Compares against budget limit (600 EUR)
Limit Exceeded! Service->>Repo: save(new Expense) Repo->>DB: INSERT INTO expenses DB-->>Repo: Success Service->>Email: sendBudgetAlert(email, name, total, limit, month) Email->>Brevo: POST https://api.brevo.com/v3/smtp/email (JSON payload) Brevo-->>Email: 201 Created (Email Sent) Service-->>Ctrl: Saved Expense object Ctrl-->>User: 302 Redirect to /dashboard ``` ### 4. 部署架构 采用容器化环境的高可用托管策略，安全地部署在 Render 上，并完全集成了 SAST、SCA 和 DAST 控制。 ``` graph LR subgraph Git Workspace Dev[Developer] -->|Push Code| Github[GitHub Repository] end subgraph CI/CD Runner Github -->|Triggers| Actions[GitHub Actions] Actions -->|Secrets Detection| Gitleaks[Gitleaks] Actions -->|Run Tests & Build JAR| Maven[Maven Test & Package] Actions -->|Dependency Analysis| Trivy[Trivy SCA Scan] Actions -->|Build Docker Image| Docker[Docker Build] Docker -->|Container Scan| TrivyImg[Trivy Container Scan] end subgraph Registries TrivyImg -->|Secure Push| GHCR[GitHub Container Registry] GHCR -->|Sign Image| Cosign[Cosign Image Signature] end subgraph Production Env (Render) Cosign -->|Trigger Deploy| WebApp[Render Container App] WebApp -->|Encrypted JDBC| RDB[(Render PostgreSQL DB)] end subgraph DAST Verification WebApp -->|Scanned by| OWASP[OWASP ZAP Dynamic Scan] end ``` ## 🛠️ 技术栈 * **后端框架**: Spring Boot (v4.0.6) 与 Java 21 * **数据库**: PostgreSQL (生产环境) & H2 (内存测试) * **前端**: Thymeleaf, HTML5, CSS3, Bootstrap 5 * **安全框架**: Spring Security 6 (BCrypt 密码哈希、会话管理、CSRF 保护和自定义 CSP headers) * **构建工具**: Maven (包含 Wrapper) * **CI/CD 平台**: GitHub Actions * **安全扫描套件**: * **密钥检测**: Gitleaks * **软件组合分析 (SCA)**: Trivy * **容器镜像扫描**: Trivy * **静态应用安全测试 (SAST)**: SonarCloud / Snyk * **供应链安全**: Cosign (镜像签名) * **动态应用安全测试 (DAST)**: OWASP ZAP Baseline Scanner ## ✨ 功能 * **安全身份验证**: 由 Spring Security 提供的强大身份验证流程，保护页面免受未经授权的路由访问。 * **预编译 SQL 查询**: 利用 Spring Data JPA repository 防止 SQL 注入 (SQLi) 攻击。 * **预算跟踪与邮件提醒**: 实时评估月度支出，并通过自动化的 HTTP REST 集成 (Brevo API) 在支出超限时通知用户。 * **支出明细图表**: 直接内置在客户端渲染中的交互式图形仪表板。 * **导出工具**: 快速数据导出功能，支持将报告下载为 CSV，或直接通过邮件发送。 * **生产环境加固 Headers**: 包含 HTTP 响应 header 配置（Content Security Policy、X-Frame-Options: SAMEORIGIN、Referrer-Policy: no-referrer）。 ## 📁 文件夹结构 ``` expense-manager/ ├── .github/ │ └── workflows/ │ └── devsecops.yml # CI/CD & Security Scan Workflow ├── src/ │ ├── main/ │ │ ├── java/com/expense_manager/expense_manager/ │ │ │ ├── config/ # Security Configurations │ │ │ ├── controller/ # Spring MVC Controllers │ │ │ ├── dto/ # Data Transfer Objects │ │ │ ├── entity/ # Database Entity Models │ │ │ ├── repository/ # JPA repositories for PostgreSQL │ │ │ └── service/ # Application Services & Business Logic │ │ └── resources/ │ │ ├── templates/ # Thymeleaf HTML Templates │ │ └── application.properties │ └── test/ # Test Suite (Unit, Integration & API Tests) ├── Dockerfile # Multi-stage Docker build pipeline ├── pom.xml # Maven dependencies build configuration └── README.md # Project Documentation ``` ## 🚀 安装与本地启动 ### 前置条件 * Java 21 SDK * PostgreSQL 数据库服务器（或使用 H2 配置进行本地测试） ### 分步设置 1. **克隆代码库：** git clone https://github.com/jaiminpanchal2002/expense-manager.git cd expense-manager 2. **配置数据库设置：** 打开 `src/main/resources/application.properties` 并配置您的数据库配置文件详细信息： spring.datasource.url=jdbc:postgresql://localhost:5432/expense_db spring.datasource.username=postgres spring.datasource.password=yourpassword # 提供用于 Email 服务告警的 Brevo API key BREVO_API_KEY=your_brevo_api_key 3. **本地编译并运行测试：** 使用 Maven wrapper 运行所有单元、集成和 API 测试： ./mvnw clean test 4. **启动应用程序：** 执行 Spring Boot plugin 启动本地服务器： ./mvnw spring-boot:run 打开浏览器并导航到 `http://localhost:8080` 开始管理支出。 ## 🌐 部署指南 (Docker & Render) 1. **在本地构建 Docker 镜像：** docker build -t expense-manager:latest . 2. **运行本地容器测试：** docker run -p 8080:8080 -e BREVO_API_KEY="your_api_key" expense-manager:latest 3. **在 Render 上进行生产部署：** * 在 Render 上创建一个新的 Web Service 并指向您的代码库。 * 选择 **Docker** 作为环境 runtime。 * 在 Render 仪表板中添加以下环境变量： * `BREVO_API_KEY`: 用于邮件通知的 API 密钥。 * `SPRING_DATASOURCE_URL`: PostgreSQL 连接字符串。 * `SPRING_DATASOURCE_USERNAME`: 数据库用户名。 * `SPRING_DATASOURCE_PASSWORD`: 数据库密码。 * Render 将在 git 推送时自动构建并部署容器。 ## 📑 API 文档 Web 容器暴露了以下 endpoint： ### 身份验证 Endpoint * `GET /login` - 渲染用户登录页面。 * `GET /register` - 渲染注册表单。 * `POST /register` - 提交凭据以注册新用户。 ### 支出管理（受保护） * `GET /dashboard` - 仪表板界面，展示月度图表和当月支出列表。 * `GET /expenses/new` - 渲染添加新支出的表单。 * `POST /expenses` - 处理支出请求 payload。 * `POST /expenses/{id}/delete` - 删除特定的支出记录（包含用户所有权授权检查）。 ### 数据导出（受保护） * `GET /export/csv` - 将当月支出下载为原始 CSV 文件。 * `POST /export/email` - 生成 CSV 报告并将其通过邮件发送到用户的注册收件箱。 ## 💼 案例研究：工程与 DevSecOps 实践 ### 1. 问题与业务需求 在现代应用程序部署中，开发人员的速度往往被放在首位，这经常导致一些小疏忽，例如提交明文 API 凭据、使用存在漏洞的第三方模块，或者部署错误配置的 docker runtime。本项目旨在解决构建安全 Web 应用程序的难题，同时建立严格的自动化门禁 pipeline，以确保每次发布都符合 DevSecOps 模型。 ### 2. 架构与设计决策 为了构建一个零 JavaScript 冗余的高响应界面，选择了 **Thymeleaf** 作为 UI 渲染引擎，将模板动态映射到 MVC controller。使用带有 **PostgreSQL** 的关系型 schema 来构建交易记录，并配置了 **Spring Security** 以拒绝未经身份验证的请求。 #### DevSecOps 分阶段设置： 1. **Gitleaks**: 添加了在意外将 API 密钥（如 Brevo 凭据）推送到 `application.properties` 中时阻止部署的功能。 2. **Trivy 文件扫描**: 扫描已编译的包和文件系统，查找包含安全漏洞的过时库版本。 3. **多阶段 Docker 镜像构建**: 将 runtime 镜像大小保持在 200MB 以下，通过仅发布 Java JRE 而不是 JDK 来最小化攻击面。 4. **Cosign 镜像签名**: 证明容器的真实性，使得未经授权的攻击者无法执行任意的容器替换。 5. **OWASP ZAP Scanner**: 扫描实时的 Render URL，模拟跨站脚本 (XSS) 和注入向量。 ### 3. 面临的挑战与工程解决方案 * **挑战 1：容器环境中的 Maven 构建问题。** * *解决方案*：创建了利用 `eclipse-temurin` 容器缓存的多阶段 Docker 构建 pipeline，以构建独立的编译环境并保持目标容器轻量化。 * **挑战 2：ZAP Scanner 无法在 CI/CD Runner 中访问 localhost。** * *解决方案*：重新设计了 pipeline，将 DAST scanner 指向已部署的 Render 服务器 URL 环境，而不是本地执行的模拟服务器。 * **挑战 3：基础镜像包上的安全漏洞警报。** * *解决方案*：将默认基础镜像升级为仅包含关键包的最小化 JRE 环境（`eclipse-temurin:21-jre`），将 Trivy 安全警告降至零。 ### 4. 指标与最终成果 * **测试覆盖率**: 逻辑块的覆盖率达到 85%。 * **零安全违规**: Gitleaks scanner 确认零密钥泄露。 * **100% 安全的容器**: 由 Cosign 验证的 Docker 镜像签名，证明了供应链执行的安全性。 ## 🗺️ 路线图 - [ ] 实现 Kubernetes 部署描述符。 - [ ] 通过 TOTP 添加多因素身份验证 (MFA)。 - [ ] 集成 Terraform 模板，用于自动化配置云数据库。 - [ ] 设置 Prometheus 和 Grafana 仪表板以监控应用程序 runtime 统计信息。 ## 📄 许可证 基于 [MIT License](LICENSE) 授权。
Compares against budget limit (600 EUR)
Limit Exceeded! Service->>Repo: save(new Expense) Repo->>DB: INSERT INTO expenses DB-->>Repo: Success Service->>Email: sendBudgetAlert(email, name, total, limit, month) Email->>Brevo: POST https://api.brevo.com/v3/smtp/email (JSON payload) Brevo-->>Email: 201 Created (Email Sent) Service-->>Ctrl: Saved Expense object Ctrl-->>User: 302 Redirect to /dashboard ``` ### 4. 部署架构 采用容器化环境的高可用托管策略，安全地部署在 Render 上，并完全集成了 SAST、SCA 和 DAST 控制。 ``` graph LR subgraph Git Workspace Dev[Developer] -->|Push Code| Github[GitHub Repository] end subgraph CI/CD Runner Github -->|Triggers| Actions[GitHub Actions] Actions -->|Secrets Detection| Gitleaks[Gitleaks] Actions -->|Run Tests & Build JAR| Maven[Maven Test & Package] Actions -->|Dependency Analysis| Trivy[Trivy SCA Scan] Actions -->|Build Docker Image| Docker[Docker Build] Docker -->|Container Scan| TrivyImg[Trivy Container Scan] end subgraph Registries TrivyImg -->|Secure Push| GHCR[GitHub Container Registry] GHCR -->|Sign Image| Cosign[Cosign Image Signature] end subgraph Production Env (Render) Cosign -->|Trigger Deploy| WebApp[Render Container App] WebApp -->|Encrypted JDBC| RDB[(Render PostgreSQL DB)] end subgraph DAST Verification WebApp -->|Scanned by| OWASP[OWASP ZAP Dynamic Scan] end ``` ## 🛠️ 技术栈 * **后端框架**: Spring Boot (v4.0.6) 与 Java 21 * **数据库**: PostgreSQL (生产环境) & H2 (内存测试) * **前端**: Thymeleaf, HTML5, CSS3, Bootstrap 5 * **安全框架**: Spring Security 6 (BCrypt 密码哈希、会话管理、CSRF 保护和自定义 CSP headers) * **构建工具**: Maven (包含 Wrapper) * **CI/CD 平台**: GitHub Actions * **安全扫描套件**: * **密钥检测**: Gitleaks * **软件组合分析 (SCA)**: Trivy * **容器镜像扫描**: Trivy * **静态应用安全测试 (SAST)**: SonarCloud / Snyk * **供应链安全**: Cosign (镜像签名) * **动态应用安全测试 (DAST)**: OWASP ZAP Baseline Scanner ## ✨ 功能 * **安全身份验证**: 由 Spring Security 提供的强大身份验证流程，保护页面免受未经授权的路由访问。 * **预编译 SQL 查询**: 利用 Spring Data JPA repository 防止 SQL 注入 (SQLi) 攻击。 * **预算跟踪与邮件提醒**: 实时评估月度支出，并通过自动化的 HTTP REST 集成 (Brevo API) 在支出超限时通知用户。 * **支出明细图表**: 直接内置在客户端渲染中的交互式图形仪表板。 * **导出工具**: 快速数据导出功能，支持将报告下载为 CSV，或直接通过邮件发送。 * **生产环境加固 Headers**: 包含 HTTP 响应 header 配置（Content Security Policy、X-Frame-Options: SAMEORIGIN、Referrer-Policy: no-referrer）。 ## 📁 文件夹结构 ``` expense-manager/ ├── .github/ │ └── workflows/ │ └── devsecops.yml # CI/CD & Security Scan Workflow ├── src/ │ ├── main/ │ │ ├── java/com/expense_manager/expense_manager/ │ │ │ ├── config/ # Security Configurations │ │ │ ├── controller/ # Spring MVC Controllers │ │ │ ├── dto/ # Data Transfer Objects │ │ │ ├── entity/ # Database Entity Models │ │ │ ├── repository/ # JPA repositories for PostgreSQL │ │ │ └── service/ # Application Services & Business Logic │ │ └── resources/ │ │ ├── templates/ # Thymeleaf HTML Templates │ │ └── application.properties │ └── test/ # Test Suite (Unit, Integration & API Tests) ├── Dockerfile # Multi-stage Docker build pipeline ├── pom.xml # Maven dependencies build configuration └── README.md # Project Documentation ``` ## 🚀 安装与本地启动 ### 前置条件 * Java 21 SDK * PostgreSQL 数据库服务器（或使用 H2 配置进行本地测试） ### 分步设置 1. **克隆代码库：** git clone https://github.com/jaiminpanchal2002/expense-manager.git cd expense-manager 2. **配置数据库设置：** 打开 `src/main/resources/application.properties` 并配置您的数据库配置文件详细信息： spring.datasource.url=jdbc:postgresql://localhost:5432/expense_db spring.datasource.username=postgres spring.datasource.password=yourpassword # 提供用于 Email 服务告警的 Brevo API key BREVO_API_KEY=your_brevo_api_key 3. **本地编译并运行测试：** 使用 Maven wrapper 运行所有单元、集成和 API 测试： ./mvnw clean test 4. **启动应用程序：** 执行 Spring Boot plugin 启动本地服务器： ./mvnw spring-boot:run 打开浏览器并导航到 `http://localhost:8080` 开始管理支出。 ## 🌐 部署指南 (Docker & Render) 1. **在本地构建 Docker 镜像：** docker build -t expense-manager:latest . 2. **运行本地容器测试：** docker run -p 8080:8080 -e BREVO_API_KEY="your_api_key" expense-manager:latest 3. **在 Render 上进行生产部署：** * 在 Render 上创建一个新的 Web Service 并指向您的代码库。 * 选择 **Docker** 作为环境 runtime。 * 在 Render 仪表板中添加以下环境变量： * `BREVO_API_KEY`: 用于邮件通知的 API 密钥。 * `SPRING_DATASOURCE_URL`: PostgreSQL 连接字符串。 * `SPRING_DATASOURCE_USERNAME`: 数据库用户名。 * `SPRING_DATASOURCE_PASSWORD`: 数据库密码。 * Render 将在 git 推送时自动构建并部署容器。 ## 📑 API 文档 Web 容器暴露了以下 endpoint： ### 身份验证 Endpoint * `GET /login` - 渲染用户登录页面。 * `GET /register` - 渲染注册表单。 * `POST /register` - 提交凭据以注册新用户。 ### 支出管理（受保护） * `GET /dashboard` - 仪表板界面，展示月度图表和当月支出列表。 * `GET /expenses/new` - 渲染添加新支出的表单。 * `POST /expenses` - 处理支出请求 payload。 * `POST /expenses/{id}/delete` - 删除特定的支出记录（包含用户所有权授权检查）。 ### 数据导出（受保护） * `GET /export/csv` - 将当月支出下载为原始 CSV 文件。 * `POST /export/email` - 生成 CSV 报告并将其通过邮件发送到用户的注册收件箱。 ## 💼 案例研究：工程与 DevSecOps 实践 ### 1. 问题与业务需求 在现代应用程序部署中，开发人员的速度往往被放在首位，这经常导致一些小疏忽，例如提交明文 API 凭据、使用存在漏洞的第三方模块，或者部署错误配置的 docker runtime。本项目旨在解决构建安全 Web 应用程序的难题，同时建立严格的自动化门禁 pipeline，以确保每次发布都符合 DevSecOps 模型。 ### 2. 架构与设计决策 为了构建一个零 JavaScript 冗余的高响应界面，选择了 **Thymeleaf** 作为 UI 渲染引擎，将模板动态映射到 MVC controller。使用带有 **PostgreSQL** 的关系型 schema 来构建交易记录，并配置了 **Spring Security** 以拒绝未经身份验证的请求。 #### DevSecOps 分阶段设置： 1. **Gitleaks**: 添加了在意外将 API 密钥（如 Brevo 凭据）推送到 `application.properties` 中时阻止部署的功能。 2. **Trivy 文件扫描**: 扫描已编译的包和文件系统，查找包含安全漏洞的过时库版本。 3. **多阶段 Docker 镜像构建**: 将 runtime 镜像大小保持在 200MB 以下，通过仅发布 Java JRE 而不是 JDK 来最小化攻击面。 4. **Cosign 镜像签名**: 证明容器的真实性，使得未经授权的攻击者无法执行任意的容器替换。 5. **OWASP ZAP Scanner**: 扫描实时的 Render URL，模拟跨站脚本 (XSS) 和注入向量。 ### 3. 面临的挑战与工程解决方案 * **挑战 1：容器环境中的 Maven 构建问题。** * *解决方案*：创建了利用 `eclipse-temurin` 容器缓存的多阶段 Docker 构建 pipeline，以构建独立的编译环境并保持目标容器轻量化。 * **挑战 2：ZAP Scanner 无法在 CI/CD Runner 中访问 localhost。** * *解决方案*：重新设计了 pipeline，将 DAST scanner 指向已部署的 Render 服务器 URL 环境，而不是本地执行的模拟服务器。 * **挑战 3：基础镜像包上的安全漏洞警报。** * *解决方案*：将默认基础镜像升级为仅包含关键包的最小化 JRE 环境（`eclipse-temurin:21-jre`），将 Trivy 安全警告降至零。 ### 4. 指标与最终成果 * **测试覆盖率**: 逻辑块的覆盖率达到 85%。 * **零安全违规**: Gitleaks scanner 确认零密钥泄露。 * **100% 安全的容器**: 由 Cosign 验证的 Docker 镜像签名，证明了供应链执行的安全性。 ## 🗺️ 路线图 - [ ] 实现 Kubernetes 部署描述符。 - [ ] 通过 TOTP 添加多因素身份验证 (MFA)。 - [ ] 集成 Terraform 模板，用于自动化配置云数据库。 - [ ] 设置 Prometheus 和 Grafana 仪表板以监控应用程序 runtime 统计信息。 ## 📄 许可证 基于 [MIT License](LICENSE) 授权。
标签：DevSecOps, PostgreSQL, PyVis, Spring Boot, 上游代理, 全栈应用, 域名枚举, 无摄像头检测, 测试用例, 请求拦截, 财务管理