front-deploy-platform/DEPLOY.md

部署指南

本项目提供多种部署方式，推荐使用 PM2 一键部署，简单快捷。

🚀 方案一：PM2 一键部署（推荐）

最简单的部署方式，适合 VPS、云服务器等场景。

Windows 部署

# 1. 运行部署脚本
.\deploy.ps1

Linux/macOS 部署

# 1. 添加执行权限
chmod +x deploy.sh

# 2. 运行部署脚本
./deploy.sh

部署脚本会自动完成：

1. ✅ 检查并安装必要工具（Node.js、pnpm、PM2）
2. ✅ 安装项目依赖
3. ✅ 构建前后端项目
4. ✅ 创建生产环境配置
5. ✅ 运行数据库迁移
6. ✅ 使用 PM2 启动服务
7. ✅ 配置开机自启动

常用命令

# 查看服务状态
pm2 status

# 查看日志
pm2 logs

# 查看指定服务日志
pm2 logs just-demo-backend
pm2 logs just-demo-frontend

# 重启服务
pm2 restart all
pm2 restart just-demo-backend

# 停止服务
pm2 stop all

# 删除服务
pm2 delete all

访问地址

部署成功后，可通过以下地址访问：

• 前端：http://localhost:5500
• 后端：http://localhost:3000

---

🐳 方案二：Docker Compose 部署

适合需要容器化部署的场景。

1. 创建 Dockerfile

backend/Dockerfile:

FROM node:18-alpine

WORKDIR /app

# 安装 pnpm
RUN npm install -g pnpm

# 复制依赖文件
COPY package.json pnpm-lock.yaml ./

# 安装依赖
RUN pnpm install --prod

# 复制构建产物
COPY dist ./dist
COPY database ./database
COPY knexfile.js ./

# 创建上传目录
RUN mkdir -p uploads

EXPOSE 3000

CMD ["node", "dist/app.js"]

frontend/Dockerfile:

FROM node:18-alpine

WORKDIR /app

# 安装 serve
RUN npm install -g serve

# 复制构建产物
COPY dist ./dist

EXPOSE 5500

CMD ["serve", "dist", "-p", "5500", "-s"]

2. 创建 docker-compose.yml

version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - JWT_SECRET=${JWT_SECRET}
      - FRONTEND_URL=http://localhost:5500
    volumes:
      - ./backend/database:/app/database
      - ./backend/uploads:/app/uploads
    restart: always

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "5500:5500"
    depends_on:
      - backend
    restart: always

3. 部署

# 构建项目
pnpm build

# 启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

---

☁️ 方案三：云平台部署

3.1 Vercel + Railway

前端部署到 Vercel：

1. 在 Vercel 导入项目
2. 设置构建配置：
   • Build Command: cd frontend && pnpm install && pnpm build
   • Output Directory: frontend/dist

后端部署到 Railway：

1. 在 Railway 创建新项目
2. 连接 GitHub 仓库
3. 设置环境变量：

   NODE_ENV=production
   PORT=3000
   JWT_SECRET=your-secret-key
   FRONTEND_URL=your-vercel-url
   

3.2 Render

1. 在 Render 创建 Web Service
2. 后端配置：
   • Build Command: cd backend && pnpm install && pnpm build
   • Start Command: cd backend && node dist/app.js
3. 前端配置：
   • Build Command: cd frontend && pnpm install && pnpm build
   • Publish Directory: frontend/dist

---

📝 生产环境配置

必要的环境变量

在 backend/.env 文件中配置：

NODE_ENV=production
PORT=3000
JWT_SECRET=你的超级密钥-至少32字符
FRONTEND_URL=http://your-frontend-domain.com
UPLOAD_DIR=uploads

生成安全的 JWT_SECRET

# Linux/macOS
openssl rand -base64 32

# Windows PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

---

🔒 安全建议

1. 修改 JWT_SECRET：不要使用默认密钥
2. 配置 HTTPS：使用 nginx + Let's Encrypt
3. 限制文件上传大小：防止恶意上传
4. 定期备份数据库：备份 backend/database/*.sqlite3
5. 配置防火墙：只开放必要端口

---

🌐 使用 Nginx 反向代理（可选）

安装 Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

配置文件

创建 /etc/nginx/sites-available/just-demo:

server {
    listen 80;
    server_name your-domain.com;

    # 前端
    location / {
        proxy_pass http://localhost:5500;
        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;
    }

    # 后端 API
    location /api {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

启用配置

sudo ln -s /etc/nginx/sites-available/just-demo /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

---

🔧 故障排查

服务无法启动

# 查看详细日志
pm2 logs --lines 100

# 检查端口占用
# Linux/macOS
lsof -i :3000

# Windows
netstat -ano | findstr :3000

数据库错误

# 重新运行迁移
cd backend
pnpm migrate:rollback:prod
pnpm migrate:prod

sqlite3 bindings 错误

如果遇到以下错误：

Could not locate the bindings file. Tried:
 → /path/to/sqlite3/build/node_sqlite3.node

这是因为 sqlite3 是原生模块，需要在目标平台重新编译。

快速修复：

# 使用修复脚本（推荐）
chmod +x fix-sqlite3.sh
./fix-sqlite3.sh

手动修复：

# 1. 安装编译工具（根据系统选择）
# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y python3 make g++ build-essential

# CentOS/RHEL
sudo yum install -y python3 make gcc-c++

# Alpine
sudo apk add --no-cache python3 make g++

# 2. 停止服务
pm2 stop just-demo-backend

# 3. 进入 backend 目录并重建 sqlite3
cd backend
rm -rf node_modules/.pnpm/sqlite3@* node_modules/sqlite3
pnpm rebuild sqlite3 || pnpm install sqlite3 --force

# 4. 返回根目录并重启服务
cd ..
pm2 restart just-demo-backend

前端无法访问后端

检查 backend/.env 中的 FRONTEND_URL 配置是否正确。

---

📊 性能优化

1. 启用 PM2 集群模式：充分利用多核 CPU
2. 配置 Nginx 缓存：加快静态资源访问
3. 使用 CDN：加速前端资源加载
4. 定期清理日志：防止日志文件过大

---

🔄 更新部署

# 1. 拉取最新代码
git pull

# 2. 重新构建
pnpm build

# 3. 重启服务
pm2 restart all

# 或使用部署脚本
./deploy.sh

---

📞 技术支持

如遇问题，请检查：

1. Node.js 版本是否 >= 16
2. 端口 3000 和 5500 是否被占用
3. 数据库文件是否有读写权限
4. 环境变量是否配置正确