gerenjizhang/DEPLOY.md

部署指南

本文档提供个人记账与预算管理系统的部署方案，包括本地部署、服务器部署、数据库备份与恢复。

---

一、本地部署（开发环境）

1.1 前置条件

• 安装 Node.js 18+：https://nodejs.org/
• 安装 Git：https://git-scm.com/

1.2 克隆项目

git clone <your-repo-url>
cd personal-finance-budget-system

1.3 配置环境变量

后端：

cd backend
copy .env.example .env   # Windows
# cp .env.example .env   # macOS/Linux

前端：

cd frontend
copy .env.example .env   # Windows
# cp .env.example .env   # macOS/Linux

1.4 安装依赖并启动

# 后端
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

npm install -g pm2

2.1.2 后端部署

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 前端部署

cd frontend

# 配置生产环境变量
# 编辑 .env.production
VITE_API_BASE_URL=http://your-server-ip:3001

# 构建
npm run build

# 构建产物在 frontend/dist/ 目录

2.1.4 使用 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（后端）

# 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

# 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 启动

docker-compose up -d

---

三、数据库备份与恢复

3.1 备份数据库

SQLite 数据库为单文件，直接拷贝即可：

# 备份
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 恢复数据库

# 恢复
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（可选）

cd backend
npx prisma db pull   # 从现有数据库拉取 schema
npx prisma db push   # 推送到新的数据库实例

3.4 自动备份脚本

创建定时备份脚本 backup.sh：

#!/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）：

# 每天凌晨 2 点备份
0 2 * * * /path/to/backup.sh

---

四、常见问题排查

4.1 后端启动失败

问题: Error: Cannot find module '@prisma/client'

解决:

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

解决:

# 检查权限
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

解决:

# 查看占用端口的进程
# Windows
netstat -ano | findstr :3001
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :3001
kill -9 <PID>

或修改端口：

# 修改 .env
PORT=3002

---

五、生产环境安全检查清单

部署前请确认以下事项：

• 移除 /api/init-test-data 测试接口
• 接入 JWT 鉴权，从 Token 解析 userId
• CORS 限制为前端域名
• 配置请求频率限制（Rate Limit）
• 配置 HTTPS 强制
• 限制请求体大小（防 DoS）
• 数据库文件定期备份
• 配置日志监控和告警
• 移除 .env 文件中的敏感信息（如提交到 Git）

---

最后更新: 2026-04-28