feat: 个人记账与预算管理系统 MVP 初始版本

2026-04-28 22:57:38 +08:00
commit d2b2e9887a
88 changed files with 29512 additions and 0 deletions
@@ -0,0 +1,345 @@
+# 部署指南
+
+> 本文档提供个人记账与预算管理系统的部署方案，包括本地部署、服务器部署、数据库备份与恢复。
+
+---
+
+## 一、本地部署（开发环境）
+
+### 1.1 前置条件
+
+- 安装 Node.js 18+：https://nodejs.org/
+- 安装 Git：https://git-scm.com/
+
+### 1.2 克隆项目
+
+```bash
+git clone <your-repo-url>
+cd personal-finance-budget-system
+```
+
+### 1.3 配置环境变量
+
+**后端**：
+
+```bash
+cd backend
+copy .env.example .env   # Windows
+# cp .env.example .env   # macOS/Linux
+```
+
+**前端**：
+
+```bash
+cd frontend
+copy .env.example .env   # Windows
+# cp .env.example .env   # macOS/Linux
+```
+
+### 1.4 安装依赖并启动
+
+```bash
+# 后端
+cd backend
+npm install
+npm run db:generate
+npm run db:push
+npm run dev
+
+# 新开终端，启动前端
+cd frontend
+npm install
+npm run dev
+```
+
+### 1.5 访问应用
+
+- 前端：`http://localhost:5173`
+- 后端 API：`http://localhost:3001`
+- Prisma Studio：`http://localhost:5555`
+
+---
+
+## 二、服务器部署（生产环境）
+
+### 2.1 使用 PM2 部署（推荐）
+
+#### 2.1.1 安装 PM2
+
+```bash
+npm install -g pm2
+```
+
+#### 2.1.2 后端部署
+
+```bash
+cd backend
+
+# 安装生产依赖
+npm install --production
+
+# 配置生产环境变量
+# 编辑 .env 文件，修改数据库路径等
+DATABASE_URL="file:./prod.db"
+PORT=3001
+
+# 生成 Prisma 客户端并推送数据库结构
+npm run db:generate
+npm run db:push
+
+# 使用 PM2 启动服务
+pm2 start src/index.js --name finance-backend
+
+# 设置开机自启
+pm2 save
+pm2 startup
+```
+
+#### 2.1.3 前端部署
+
+```bash
+cd frontend
+
+# 配置生产环境变量
+# 编辑 .env.production
+VITE_API_BASE_URL=http://your-server-ip:3001
+
+# 构建
+npm run build
+
+# 构建产物在 frontend/dist/ 目录
+```
+
+#### 2.1.4 使用 Nginx 托管前端
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # 前端静态文件
+    location / {
+        root /path/to/personal-finance-budget-system/frontend/dist;
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 后端 API 代理（可选，避免跨域）
+    location /api {
+        proxy_pass http://localhost:3001;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+### 2.2 使用 Docker 部署
+
+#### 2.2.1 创建 Dockerfile（后端）
+
+```dockerfile
+# backend/Dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install --production
+
+COPY . .
+
+RUN npm run db:generate
+
+EXPOSE 3001
+
+CMD ["node", "src/index.js"]
+```
+
+#### 2.2.2 创建 docker-compose.yml
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "3001:3001"
+    volumes:
+      - ./backend/prisma:/app/prisma  # 持久化数据库
+    environment:
+      - DATABASE_URL=file:./prod.db
+      - PORT=3001
+    restart: always
+
+  frontend:
+    image: node:20-alpine
+    working_dir: /app
+    volumes:
+      - ./frontend:/app
+    command: sh -c "npm install && npm run build"
+    depends_on:
+      - backend
+```
+
+#### 2.2.3 启动
+
+```bash
+docker-compose up -d
+```
+
+---
+
+## 三、数据库备份与恢复
+
+### 3.1 备份数据库
+
+SQLite 数据库为单文件，直接拷贝即可：
+
+```bash
+# 备份
+cp backend/prisma/dev.db backend/prisma/dev.db.backup.$(date +%Y%m%d)
+
+# 或使用 tar 打包
+tar czf db-backup-$(date +%Y%m%d).tar.gz backend/prisma/dev.db
+```
+
+### 3.2 恢复数据库
+
+```bash
+# 恢复
+cp backend/prisma/dev.db.backup.20260428 backend/prisma/dev.db
+
+# 或从 tar 恢复
+tar xzf db-backup-20260428.tar.gz -C backend/prisma/
+```
+
+### 3.3 导出 SQL（可选）
+
+```bash
+cd backend
+npx prisma db pull   # 从现有数据库拉取 schema
+npx prisma db push   # 推送到新的数据库实例
+```
+
+### 3.4 自动备份脚本
+
+创建定时备份脚本 `backup.sh`：
+
+```bash
+#!/bin/bash
+BACKUP_DIR="./backups"
+DATE=$(date +%Y%m%d_%H%M%S)
+DB_FILE="./backend/prisma/dev.db"
+
+mkdir -p $BACKUP_DIR
+cp $DB_FILE "$BACKUP_DIR/dev.db.$DATE.backup"
+
+# 保留最近 7 天的备份
+find $BACKUP_DIR -name "*.backup" -mtime +7 -delete
+
+echo "备份完成: $BACKUP_DIR/dev.db.$DATE.backup"
+```
+
+添加到 crontab（Linux/macOS）：
+
+```bash
+# 每天凌晨 2 点备份
+0 2 * * * /path/to/backup.sh
+```
+
+---
+
+## 四、常见问题排查
+
+### 4.1 后端启动失败
+
+**问题**: `Error: Cannot find module '@prisma/client'`
+
+**解决**:
+```bash
+cd backend
+npm run db:generate
+```
+
+**问题**: `Error: P1001: Can't reach database server`
+
+**解决**: 检查 `.env` 中的 `DATABASE_URL` 是否正确。
+
+### 4.2 前端构建失败
+
+**问题**: `Type error: Cannot find module '@/services/apiClient'`
+
+**解决**: 检查 `tsconfig.json` 中的 `paths` 配置是否正确。
+
+**问题**: 构建后页面空白
+
+**解决**: 检查 `vite.config.js` 中的 `base` 配置，确保部署路径正确。
+
+### 4.3 API 跨域问题
+
+**问题**: 前端请求后端报 CORS 错误
+
+**解决**:
+1. 确认后端已安装并启用 `cors` 中间件
+2. 生产环境应配置具体的前端域名，而非 `*`
+
+### 4.4 数据库文件权限问题（Linux）
+
+**问题**: `SQLITE_ERROR: unable to open database file`
+
+**解决**:
+```bash
+# 检查权限
+ls -la backend/prisma/dev.db
+
+# 修改权限
+chmod 644 backend/prisma/dev.db
+chown $(whoami) backend/prisma/dev.db
+```
+
+### 4.5 端口被占用
+
+**问题**: `Error: listen EADDRINUSE: address already in use 0.0.0.0:3001`
+
+**解决**:
+```bash
+# 查看占用端口的进程
+# Windows
+netstat -ano | findstr :3001
+taskkill /PID <PID> /F
+
+# Linux/macOS
+lsof -i :3001
+kill -9 <PID>
+```
+
+或修改端口：
+
+```bash
+# 修改 .env
+PORT=3002
+```
+
+---
+
+## 五、生产环境安全检查清单
+
+部署前请确认以下事项：
+
+- [ ] 移除 `/api/init-test-data` 测试接口
+- [ ] 接入 JWT 鉴权，从 Token 解析 userId
+- [ ] CORS 限制为前端域名
+- [ ] 配置请求频率限制（Rate Limit）
+- [ ] 配置 HTTPS 强制
+- [ ] 限制请求体大小（防 DoS）
+- [ ] 数据库文件定期备份
+- [ ] 配置日志监控和告警
+- [ ] 移除 `.env` 文件中的敏感信息（如提交到 Git）
+
+---
+
+**最后更新**: 2026-04-28