ert/draw

Fork 0

Files

ert 1f669143cc first commit

2025-09-18 23:34:55 +08:00

9.6 KiB

Raw Permalink Blame History

抽奖系统部署文档

1. 项目简介

本项目是一个基于 React + TypeScript + Vite 技术栈开发的学号抽奖系统，为学校活动提供公平、透明的抽奖服务。系统采用前端单页应用架构，使用 SQLite 本地数据库存储数据，支持离线缓存和实时同步功能。

主要功能特性

多级奖项设置：支持一、二、三等奖及特别奖的灵活配置
学号抽奖：基于12位学号的公平抽奖机制
实时动画：炫酷的抽奖动画效果和撒花庆祝
数据统计：完整的中奖记录和数据分析
离线缓存：网络异常时仍可正常运行
管理后台：奖项配置、数据查看、系统设置
响应式设计：适配不同屏幕尺寸

2. 环境要求

系统要求

操作系统：Windows 10+、macOS 10.15+、Linux (Ubuntu 18.04+)
浏览器：Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
屏幕分辨率：推荐 1920×1080 或更高

软件依赖

Node.js：版本 18.19.1 或更高 (推荐使用 LTS 版本)
npm：版本 9.0+ (随 Node.js 安装)
Git：用于代码克隆和版本管理

硬件要求

内存：最低 4GB RAM，推荐 8GB+
存储空间：至少 1GB 可用空间
网络：开发时需要网络连接下载依赖

3. 安装步骤

3.1 克隆项目代码

# 克隆项目到本地
git clone <项目仓库地址>
cd draw

# 或者直接下载项目压缩包并解压

3.2 安装项目依赖

# 安装所有依赖包
npm install

# 如果安装速度慢，可以使用国内镜像
npm install --registry=https://registry.npmmirror.com

3.3 数据库初始化

项目使用 SQLite 数据库，首次运行时会自动创建数据库文件：

# 数据库文件位置：./lottery.db
# 初始化脚本位置：./src/database/init.sql

数据库包含以下表结构：

system_config：系统配置表
prize_config：奖项配置表
lottery_record：抽奖记录表
student：学生信息表

3.4 环境配置检查

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

# 检查 TypeScript 编译
npm run check

4. 配置说明

4.1 端口配置

默认开发服务器端口为 5173，可在 vite.config.ts 中修改：

export default defineConfig({
  server: {
    port: 5173,
    host: true, // 允许外部访问
    open: true  // 自动打开浏览器
  }
})

4.2 数据库配置

数据库配置位于 src/database/database.ts：

// SQLite 数据库文件路径
const DB_PATH = './lottery.db'

// 数据库连接选项
const options = {
  verbose: console.log, // 开发环境日志
  fileMustExist: false  // 自动创建数据库
}

4.3 系统默认配置

管理员密码：admin123 (首次登录后可修改)
最大抽奖次数：每个学号限制 1 次
学号隐私保护：默认隐藏第 3-6 位数字
奖项等级：支持 1-4 级奖项设置

5. 运行和启动

5.1 开发环境启动

# 启动开发服务器
npm run dev

# 服务器启动后访问地址
# 本地访问：http://localhost:5173
# 局域网访问：http://[本机IP]:5173

5.2 生产环境构建

# 构建生产版本
npm run build

# 构建文件输出到 dist 目录
# 可以部署到任何静态文件服务器

5.3 预览生产构建

# 预览生产构建结果
npm run preview

# 访问地址：http://localhost:4173

5.4 代码检查和格式化

# TypeScript 类型检查
npm run check

# ESLint 代码检查
npm run lint

6. 生产环境部署

6.1 静态文件部署

构建项目：
```
npm run build
```
部署 dist 目录到以下任一服务器：
- Nginx：配置静态文件服务和 SPA 路由
- Apache：启用 mod_rewrite 支持 SPA
- Vercel：直接部署，自动配置
- Netlify：拖拽部署，零配置

6.2 Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;
    
    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # 安全头设置
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
}

6.3 Docker 部署

创建 Dockerfile：

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建和运行：

# 构建镜像
docker build -t lottery-system .

# 运行容器
docker run -d -p 80:80 --name lottery lottery-system

6.4 宝塔面板部署

上传项目文件到网站根目录
安装 Node.js：在宝塔面板安装 Node.js 环境

构建项目：

cd /www/wwwroot/your-site
npm install
npm run build

配置网站：将网站根目录指向 dist 文件夹
设置伪静态：添加 SPA 路由规则

7. 常见问题和解决方案

7.1 安装依赖问题

问题：npm install 失败或速度慢

解决方案：

# 清理缓存
npm cache clean --force

# 使用国内镜像
npm config set registry https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm
cnpm install

7.2 端口占用问题

问题：端口 5173 被占用

解决方案：

# 查看端口占用
netstat -ano | findstr :5173

# 杀死占用进程
taskkill /PID <进程ID> /F

# 或修改端口
npm run dev -- --port 3000

7.3 数据库权限问题

问题：SQLite 数据库创建失败

解决方案：

# 检查目录权限
ls -la lottery.db

# 修改权限 (Linux/macOS)
chmod 666 lottery.db
chmod 755 .

7.4 构建失败问题

问题：TypeScript 编译错误

解决方案：

# 检查类型错误
npm run check

# 更新依赖
npm update

# 重新安装
rm -rf node_modules package-lock.json
npm install

7.5 浏览器兼容性问题

问题：在旧版浏览器中功能异常

解决方案：

升级浏览器到支持的版本
检查控制台错误信息
确保启用 JavaScript

7.6 网络连接问题

问题：局域网无法访问

解决方案：

# 启动时绑定所有网络接口
npm run dev -- --host 0.0.0.0

# 检查防火墙设置
# Windows: 允许 Node.js 通过防火墙
# Linux: sudo ufw allow 5173

8. 项目结构说明

draw/
├── public/                 # 静态资源目录
│   └── favicon.svg        # 网站图标
├── src/                   # 源代码目录
│   ├── components/        # React 组件
│   │   ├── ConfettiEffect.tsx    # 撒花效果组件
│   │   ├── LotteryAnimation.tsx  # 抽奖动画组件
│   │   ├── PrizeDisplay.tsx      # 奖项展示组件
│   │   └── ...                   # 其他组件
│   ├── pages/             # 页面组件
│   │   ├── Home.tsx       # 首页/登录页
│   │   ├── Lottery.tsx    # 抽奖主界面
│   │   ├── Admin.tsx      # 管理后台
│   │   └── ...            # 其他页面
│   ├── database/          # 数据库相关
│   │   ├── database.ts    # 数据库连接
│   │   └── init.sql       # 初始化脚本
│   ├── services/          # 业务服务
│   │   ├── lotteryService.ts     # 抽奖逻辑
│   │   ├── cacheService.ts       # 缓存服务
│   │   └── ...                   # 其他服务
│   ├── store/             # 状态管理
│   │   └── index.ts       # Zustand 状态
│   ├── hooks/             # 自定义 Hooks
│   ├── contexts/          # React Context
│   ├── types.ts           # TypeScript 类型定义
│   └── main.tsx           # 应用入口
├── .trae/                 # 项目文档
│   └── documents/         # 需求和架构文档
├── lottery.db             # SQLite 数据库文件
├── package.json           # 项目配置和依赖
├── vite.config.ts         # Vite 构建配置
├── tsconfig.json          # TypeScript 配置
├── tailwind.config.js     # Tailwind CSS 配置
└── README.md              # 项目说明

核心文件说明

App.tsx：应用主组件，包含路由配置
main.tsx：应用入口，挂载 React 应用
database.ts：SQLite 数据库操作封装
lotteryService.ts：抽奖核心业务逻辑
types.ts：全局 TypeScript 类型定义
index.css：全局样式和 Tailwind CSS 导入

重要配置文件

vite.config.ts：开发服务器和构建配置
tsconfig.json：TypeScript 编译选项
tailwind.config.js：CSS 框架配置
package.json：项目元信息和脚本命令

技术支持

如遇到部署问题，请检查：

环境版本：确保 Node.js 版本符合要求
依赖安装：确保所有依赖正确安装
端口占用：确保端口未被其他程序占用
权限设置：确保有足够的文件读写权限
网络连接：确保网络连接正常

更多技术细节请参考项目文档目录下的需求文档和架构文档。

项目版本：v1.0.0
最后更新：2024年12月
技术栈：React 18 + TypeScript + Vite + SQLite

9.6 KiB Raw Permalink Blame History Unescape Escape

抽奖系统部署文档

1. 项目简介

主要功能特性

2. 环境要求

系统要求

软件依赖

硬件要求

3. 安装步骤

3.1 克隆项目代码

3.2 安装项目依赖

3.3 数据库初始化

3.4 环境配置检查

4. 配置说明

4.1 端口配置

4.2 数据库配置

4.3 系统默认配置

5. 运行和启动

5.1 开发环境启动

5.2 生产环境构建

5.3 预览生产构建

5.4 代码检查和格式化

6. 生产环境部署

6.1 静态文件部署

6.2 Nginx 配置示例

6.3 Docker 部署

6.4 宝塔面板部署

7. 常见问题和解决方案

7.1 安装依赖问题

7.2 端口占用问题

7.3 数据库权限问题

7.4 构建失败问题

7.5 浏览器兼容性问题

7.6 网络连接问题

8. 项目结构说明

核心文件说明

重要配置文件

技术支持

9.6 KiB

Raw Permalink Blame History