魔教中人 - 海克斯盲盒系统

基于 Django + React 的英雄联盟海克斯盲盒展示和管理系统

功能特性 • 快速开始 • 本地开发 • 常见问题

📋 目录

功能概览
技术栈
系统架构
快速部署
本地开发
API 文档
常见问题
更新日志

🎯 功能概览

用户前端（端口 3000）

✨ Hextech 风格 UI - 游戏化界面设计，沉浸式体验
🔍 智能搜索 - 支持盲盒名称、英雄名称、标签多维度搜索
🏷️ 分类筛选 - 按稀有度、类型快速筛选
📄 智能分页 - 自动省略号显示，优化大数据集浏览
📊 数据统计 - 热度排行榜、历史趋势图表
📝 用户投稿 - 支持用户提交新盲盒，管理员审核
🎮 对局历史 - 查看盲盒在历史对局中的表现

管理后台（端口 8002）

📦 盲盒管理 - CRUD 操作，支持批量编辑
✅ 投稿审核 - 审核用户提交的盲盒，支持批量操作
📅 每日数据录入 - 批量录入每日对局数据（位置、英雄、阵营）
📈 数据看板 - 实时统计、热度排行、趋势分析
🔥 热度计算 - 自动计算盲盒热度，支持多时间段查询
🔐 权限管理 - 基于 Token 的身份认证

后端 API（端口 8000）

🚀 RESTful API - 标准化接口设计
🔒 Token 认证 - 安全的身份验证机制
📊 热度算法 - 基于出现频率和时间衰减的智能计算
🗄️ 数据库支持 - SQLite（开发）/ MySQL（生产）
🔄 自动更新 - 最后出现日期自动维护
📄 动态分页 - 灵活的分页参数配置

🛠️ 技术栈

后端

框架: Django 4.2 + Django REST Framework
数据库: MySQL 8.0 / SQLite 3
认证: Token Authentication
服务器: Gunicorn + Nginx
容器化: Docker + Docker Compose

前端

框架: React 19 + TypeScript
构建工具: Vite 6
样式: TailwindCSS
路由: React Router v6
HTTP 客户端: Axios

管理后台

框架: React 18 + TypeScript
UI 库: Ant Design 5 + Ant Design Pro Components
构建工具: Vite 6
状态管理: React Hooks

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                         Nginx (反向代理)                      │
└─────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
    ┌──────────┐        ┌──────────┐        ┌──────────┐
    │  前端     │        │ 管理后台  │        │  后端API  │
    │  :3000   │        │  :8002   │        │  :8000   │
    │  React   │        │  React   │        │  Django  │
    └──────────┘        └──────────┘        └──────────┘
                                                   │
                                                   ▼
                                            ┌──────────┐
                                            │  MySQL   │
                                            │  数据库   │
                                            └──────────┘

🚀 快速部署

1. 环境要求

Docker: 20.10+
Docker Compose: 2.0+
服务器内存: 2GB+（推荐 4GB）
磁盘空间: 5GB+
操作系统: Linux / macOS / Windows (WSL2)

2. 部署步骤

方式一：本地构建管理后台（推荐）

适用场景: 服务器内存不足 2GB，或构建速度慢

步骤:

本地构建管理后台

cd admin-frontend
npm install
npm run build
zip -r dist.zip dist

上传到服务器

# 使用 scp
scp dist.zip root@your-server:/path/to/blindBox/admin-frontend/

# 或使用 rsync
rsync -avz dist.zip root@your-server:/path/to/blindBox/admin-frontend/

服务器上部署

cd /path/to/blindBox

# 配置环境变量
cp .env.example .env
vim .env  # 修改数据库、域名等配置

# 一键部署
chmod +x build-optimized.sh
./build-optimized.sh

创建管理员账号

docker compose exec backend python manage.py createsuperuser
# 按提示输入用户名、邮箱、密码

方式二：服务器直接构建

适用场景: 服务器内存 2GB+，网络良好

步骤:

克隆项目

git clone https://github.com/ShuaiLeiLu/blindBox.git
cd blindBox

配置环境变量

cp .env.example .env
vim .env

编辑 .env 文件：

# Django 配置
DJANGO_SECRET_KEY=your-random-secret-key-here  # 生成随机密钥
DJANGO_DEBUG=0  # 生产环境设为 0
DJANGO_ALLOWED_HOSTS=your-domain.com,your-server-ip,localhost,127.0.0.1,backend

# 数据库配置（选择一种）
# SQLite（快速测试）
DATABASE_URL=sqlite:////app/db.sqlite3

# MySQL（生产推荐）
# DATABASE_URL=mysql://username:password@host.docker.internal:3306/database_name

# CORS 配置（必须包含前端和管理后台地址）
CORS_ALLOWED_ORIGINS=http://your-domain.com:3000,http://your-domain.com:8002,http://your-server-ip:3000,http://your-server-ip:8002

一键部署

chmod +x build-optimized.sh
./build-optimized.sh

脚本会自动：

检查系统资源
构建 Docker 镜像（后端、前端、管理后台）
启动所有服务
显示服务状态

创建管理员账号

docker compose exec backend python manage.py createsuperuser

验证部署

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 测试 API
curl http://localhost:8000/api/blind-boxes/

3. 访问地址

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

🌐 用户前端: http://服务器IP:3000
🔧 管理后台: http://服务器IP:8002
📡 后端 API: http://服务器IP:8000/api

4. 防火墙配置

云服务器（阿里云、腾讯云等）:

在安全组中开放端口：3000, 8000, 8002

Linux 服务器（iptables）:

sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8002 -j ACCEPT
sudo iptables-save

Linux 服务器（firewalld）:

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --permanent --add-port=8002/tcp
sudo firewall-cmd --reload

5. 常用命令

# 查看服务状态
docker compose ps

# 查看所有日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f admin

# 重启服务
docker compose restart

# 重启特定服务
docker compose restart backend

# 停止服务
docker compose down

# 停止并删除数据卷
docker compose down -v

# 重新构建并启动
docker compose build --no-cache
docker compose up -d

# 进入容器
docker compose exec backend bash
docker compose exec backend python manage.py shell

# 数据库迁移
docker compose exec backend python manage.py makemigrations
docker compose exec backend python manage.py migrate

# 创建管理员
docker compose exec backend python manage.py createsuperuser

# 收集静态文件
docker compose exec backend python manage.py collectstatic --noinput

💻 本地开发

后端开发

安装依赖

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

配置环境变量

cp .env.example .env
vim .env

配置示例：

DJANGO_SECRET_KEY=your-dev-secret-key
DJANGO_DEBUG=1
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=sqlite:///db.sqlite3
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8002

数据库迁移

python manage.py makemigrations
python manage.py migrate

创建超级用户

python manage.py createsuperuser

启动开发服务器

python manage.py runserver
# 访问 http://localhost:8000

运行测试

python manage.py test

前端开发

安装依赖

cd frontend
npm install

配置环境变量

# 创建 .env.local 文件
echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local

启动开发服务器

npm run dev
# 访问 http://localhost:3000

构建生产版本

npm run build
npm run preview  # 预览构建结果

管理后台开发

安装依赖

cd admin-frontend
npm install

配置环境变量

# 创建 .env 文件
echo "VITE_API_BASE_URL=http://localhost:8000" > .env

启动开发服务器

npm run dev
# 访问 http://localhost:8002

构建生产版本

npm run build
# 构建产物在 dist 目录

开发工具推荐

IDE: VSCode / PyCharm / WebStorm
API 测试: Postman / Insomnia
数据库管理: DBeaver / MySQL Workbench
容器管理: Docker Desktop
版本控制: Git + GitHub Desktop

📁 项目结构

blindBox/
├── backend/                    # Django 后端（端口 8000）
│   ├── blindboxes/            # 核心应用
│   │   ├── models.py          # 数据模型（BlindBox, DailyData, Submission）
│   │   ├── views.py           # API 视图
│   │   ├── serializers.py     # 序列化器
│   │   ├── urls.py            # 路由配置
│   │   ├── auth_views.py      # 认证视图
│   │   └── migrations/        # 数据库迁移文件
│   ├── config/                # 项目配置
│   │   ├── settings.py        # Django 设置
│   │   ├── urls.py            # 主路由
│   │   └── pagination.py      # 分页配置
│   ├── logs/                  # 日志目录
│   ├── requirements.txt       # Python 依赖
│   ├── Dockerfile             # Docker 构建文件
│   ├── entrypoint.sh          # 容器启动脚本
│   └── manage.py              # Django 管理脚本
│
├── frontend/                  # 用户前端（端口 3000）
│   ├── components/            # React 组件
│   │   ├── BlindBoxCard.tsx   # 盲盒卡片
│   │   ├── Navbar.tsx         # 导航栏
│   │   ├── StatsView.tsx      # 统计视图
│   │   └── ...
│   ├── pages/                 # 页面组件
│   │   ├── Home.tsx           # 首页
│   │   └── Stats.tsx          # 统计页
│   ├── services/              # API 服务
│   │   └── api.ts             # API 请求封装
│   ├── App.tsx                # 应用入口
│   ├── types.ts               # TypeScript 类型定义
│   ├── constants.ts           # 常量配置
│   ├── Dockerfile             # Docker 构建文件
│   ├── nginx.conf             # Nginx 配置
│   └── package.json           # Node 依赖
│
├── admin-frontend/            # 管理后台（端口 8002）
│   ├── src/
│   │   ├── pages/             # 页面组件
│   │   │   ├── Dashboard/     # 仪表盘
│   │   │   ├── BlindBox/      # 盲盒管理
│   │   │   ├── DailyData/     # 每日数据
│   │   │   ├── Submission/    # 投稿审核
│   │   │   └── Login/         # 登录页
│   │   ├── layouts/           # 布局组件
│   │   ├── components/        # 公共组件
│   │   ├── services/          # API 服务
│   │   ├── types/             # 类型定义
│   │   ├── utils/             # 工具函数
│   │   └── main.tsx           # 应用入口
│   ├── Dockerfile.prod        # 生产环境 Dockerfile
│   ├── nginx.conf             # Nginx 配置
│   ├── vite.config.ts         # Vite 配置
│   └── package.json           # Node 依赖
│
├── docker-compose.yml         # Docker Compose 配置
├── build-optimized.sh         # 优化的构建脚本
├── .env.example               # 环境变量示例
├── .gitignore                 # Git 忽略文件
└── README.md                  # 项目文档

📡 API 文档

认证接口

登出

POST /api/auth/logout/
Authorization: Token your-auth-token

盲盒接口

获取盲盒列表

GET /api/blind-boxes/?page=1&page_size=20&search=关键词

Response:
{
  "count": 100,
  "next": "http://api/blind-boxes/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "盲盒名称",
      "rarity": "LEGENDARY",
      "category": "SKIN",
      "description": "描述",
      "tags": ["标签1", "标签2"],
      "hot_score": 85.5,
      "last_appeared_at": "2026-02-11",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

获取盲盒详情

GET /api/blind-boxes/{id}/

获取盲盒历史对局

GET /api/blind-boxes/{id}/history/

Response:
[
  {
    "date": "2026-02-11",
    "position": "TOP",
    "hero": "剑姬",
    "side": "OUR"
  }
]

热度排行榜

GET /api/blind-boxes/hot-ranking/?period=30d&limit=10

Response:
[
  {
    "id": 1,
    "name": "盲盒名称",
    "hot_score": 95.5,
    "appearance_count": 15
  }
]

每日数据接口

获取数据汇总

GET /api/daily-data/summary/?page=1&page_size=20

获取指定日期数据

GET /api/daily-data/detail-by-date/?date=2026-02-11

批量保存数据

POST /api/daily-data/batch/
Authorization: Token your-auth-token
Content-Type: application/json

[
  {
    "date": "2026-02-11",
    "blind_box": 1,
    "position": "TOP",
    "game_hero": "剑姬",
    "hero_side": "OUR"
  }
]

投稿接口

提交投稿

POST /api/blind-box-submissions/
Content-Type: application/json

{
  "name": "新盲盒",
  "rarity": "EPIC",
  "category": "SKIN",
  "description": "描述",
  "tags": ["标签1"]
}

审核投稿

POST /api/blind-box-submissions/{id}/approve/
Authorization: Token your-auth-token

POST /api/blind-box-submissions/{id}/reject/
Authorization: Token your-auth-token
Content-Type: application/json

{
  "reason": "拒绝原因"
}

❓ 常见问题

1. 管理后台登录失败

问题: 输入用户名密码后提示"用户名或密码错误"

解决方案:

确认已创建管理员账号

docker compose exec backend python manage.py createsuperuser
# 按提示输入用户名、邮箱、密码

检查 CORS 配置 确保 .env 文件中的 CORS_ALLOWED_ORIGINS 包含管理后台地址：

CORS_ALLOWED_ORIGINS=http://your-ip:3000,http://your-ip:8002

查看后端日志

docker compose logs -f backend
# 查看是否有认证相关错误

2. 构建时 CPU/内存占用过高或卡死

问题: 服务器在构建管理后台时 CPU 100%，内存不足

原因:

服务器内存不足 2GB
Node.js 构建过程消耗大量资源
Ant Design Pro 组件库较大

解决方案:

方案一：本地构建（推荐）

# 本地机器上
cd admin-frontend
npm install
npm run build
zip -r dist.zip dist

# 上传到服务器
scp dist.zip root@server:/path/to/blindBox/admin-frontend/

# 服务器上部署
./build-optimized.sh

方案二：增加服务器 Swap

# 创建 2GB Swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 验证
free -h

方案三：升级服务器配置

推荐至少 2核 4GB 内存

3. 端口被占用

问题: 启动时提示端口 3000/8000/8002 已被占用

解决方案:

方案一：修改端口 编辑 docker-compose.yml：

services:
  frontend:
    ports:
      - "3001:80"  # 改为 3001
  backend:
    ports:
      - "8001:8000"  # 改为 8001
  admin:
    ports:
      - "8003:80"  # 改为 8003

方案二：停止占用端口的进程

# 查找占用端口的进程
sudo lsof -i :3000
sudo lsof -i :8000
sudo lsof -i :8002

# 停止进程
sudo kill -9 <PID>

4. 数据库连接失败

问题: 后端启动失败，提示数据库连接错误

解决方案:

使用 SQLite（快速测试）

# .env 文件
DATABASE_URL=sqlite:////app/db.sqlite3

使用 MySQL

# 1. 确保 MySQL 服务运行
sudo systemctl status mysql

# 2. 创建数据库和用户
mysql -u root -p
CREATE DATABASE blindbox_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'blindbox_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON blindbox_db.* TO 'blindbox_user'@'%';
FLUSH PRIVILEGES;

# 3. 配置 .env
DATABASE_URL=mysql://blindbox_user:your_password@host.docker.internal:3306/blindbox_db

5. 前端无法访问后端 API

问题: 前端页面空白或提示网络错误

解决方案:

检查后端是否正常运行

docker compose ps
curl http://localhost:8000/api/blind-boxes/

检查 CORS 配置

# .env 文件
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://your-ip:3000

检查防火墙

# 开放端口
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

6. Docker 镜像构建失败

问题: npm ci 或 pip install 失败

解决方案:

清理缓存重新构建

docker compose down
docker system prune -a
docker compose build --no-cache
docker compose up -d

检查网络连接

# 测试 npm 源
npm config get registry

# 切换国内源
npm config set registry https://registry.npmmirror.com

7. 管理后台白屏

问题: 访问管理后台显示空白页面

解决方案:

检查浏览器控制台
- 按 F12 打开开发者工具
- 查看 Console 和 Network 标签页的错误信息
检查 Nginx 配置

docker compose exec admin cat /etc/nginx/conf.d/default.conf

重新构建管理后台

docker compose build --no-cache admin
docker compose up -d admin

8. 数据迁移失败

问题: python manage.py migrate 报错

解决方案:

# 1. 查看迁移状态
docker compose exec backend python manage.py showmigrations

# 2. 重置迁移（谨慎使用，会删除数据）
docker compose exec backend python manage.py migrate --fake blindboxes zero
docker compose exec backend python manage.py migrate blindboxes

# 3. 如果数据库损坏，重新初始化
docker compose down -v
docker compose up -d
docker compose exec backend python manage.py migrate

9. 热度计算不准确

问题: 盲盒热度显示为 0 或异常值

原因:

没有录入每日数据
热度计算周期设置不当

解决方案:

录入每日数据
- 登录管理后台
- 进入"每日数据"页面
- 批量录入对局数据
手动触发热度计算

docker compose exec backend python manage.py shell
>>> from blindboxes.models import BlindBox
>>> for box in BlindBox.objects.all():
...     box.calculate_hot_score()
...     box.save()

10. 性能优化建议

问题: 系统响应慢，数据加载时间长

优化方案:

启用数据库索引（已默认启用）
使用 Redis 缓存（可选）
CDN 加速静态资源
Nginx 开启 gzip 压缩
数据库查询优化

# 使用 select_related 减少查询次数
BlindBox.objects.select_related('category').all()

# 使用 prefetch_related 优化多对多查询
BlindBox.objects.prefetch_related('tags').all()

技术栈

后端：Django 4.2、Django REST Framework、MySQL/SQLite
前端：React 19、Vite 6、TypeScript、TailwindCSS
管理后台：React 18、Ant Design 5、Ant Design Pro
部署：Docker、Nginx、Gunicorn

更新日志

v1.1.0 (2026-02-11)

修复管理后台登录错误提示不明确的问题
优化构建配置，降低内存占用
修复前端分页只显示7页的问题，添加智能省略号
修复最后出现日期显示错误的问题
清理冗余文档和脚本

v1.0.0

初始版本发布

许可证

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
admin-frontend		admin-frontend
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
build-optimized.sh		build-optimized.sh
docker-compose.yml		docker-compose.yml

ShuaiLeiLu/blindBox

Folders and files

Latest commit

History

Repository files navigation

魔教中人 - 海克斯盲盒系统

📋 目录

🎯 功能概览

用户前端（端口 3000）

管理后台（端口 8002）

后端 API（端口 8000）

🛠️ 技术栈

后端

前端

管理后台

🏗️ 系统架构

🚀 快速部署

1. 环境要求

2. 部署步骤

方式一：本地构建管理后台（推荐）

方式二：服务器直接构建

3. 访问地址

4. 防火墙配置

5. 常用命令

💻 本地开发

后端开发

前端开发

管理后台开发

开发工具推荐

📁 项目结构

📡 API 文档

认证接口

登录

登出

盲盒接口

获取盲盒列表

获取盲盒详情

获取盲盒历史对局

热度排行榜

每日数据接口

获取数据汇总

获取指定日期数据

批量保存数据

投稿接口

提交投稿

审核投稿

❓ 常见问题

1. 管理后台登录失败

2. 构建时 CPU/内存占用过高或卡死

3. 端口被占用

4. 数据库连接失败

5. 前端无法访问后端 API

6. Docker 镜像构建失败

7. 管理后台白屏

8. 数据迁移失败

9. 热度计算不准确

10. 性能优化建议

技术栈

更新日志

v1.1.0 (2026-02-11)

v1.0.0

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages