# 部署指南

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

---

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

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