346 lines
6.0 KiB
Markdown
346 lines
6.0 KiB
Markdown
# 部署指南
|
||
|
||
> 本文档提供个人记账与预算管理系统的部署方案，包括本地部署、服务器部署、数据库备份与恢复。
|
||
|
||
---
|
||
|
||
## 一、本地部署（开发环境）
|
||
|
||
### 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
|