文件领取管理系统 (FileSend)

一个现代化的文件管理与领取系统，支持用户注册、文件上传、文件领取、管理员管理等功能。系统采用前后端分离架构，提供完整的文件生命周期管理。

🌟 项目亮点

• 现代化架构: 前后端分离，RESTful API设计
• 权限管理: 基于角色的访问控制（RBAC）
• 文件安全: 文件加密存储，访问权限控制
• 用户体验: 响应式设计，支持移动端
• 扩展性强: 模块化设计，易于扩展

🚀 功能特性

用户端功能

• ✅ 用户注册与登录（JWT认证）
• ✅ 查看可领取文件列表
• ✅ 每日文件领取配额管理
• ✅ 文件下载与预览
• ✅ 个人资料管理
• ✅ 分类筛选与搜索
• ✅ 文件领取历史记录

管理端功能

• ✅ 用户管理（创建、编辑、删除、激活/停用）
• ✅ 文件上传与管理（支持批量上传）
• ✅ 分类管理（支持层级分类）
• ✅ 权限管理（用户分类权限控制）
• ✅ 文件状态管理（可领取/已领取/过期）
• ✅ 数据统计分析（图表展示）
• ✅ 系统配置管理
• ✅ 操作日志记录

系统特性

• 📊 实时数据统计
• 🔒 文件访问权限控制
• 📱 响应式设计
• 🔄 文件状态自动管理
• 📧 邮件通知（可扩展）
• 🗂️ 文件分类管理

🛠️ 技术栈

后端技术栈

技术	版本	用途
Flask	2.3.x	Web框架
SQLAlchemy	2.0.x	ORM数据库工具
Flask-JWT-Extended	4.5.x	JWT身份验证
Flask-CORS	4.0.x	跨域支持
Flask-Mail	0.9.x	邮件服务
Werkzeug	2.3.x	WSGI工具集
MySQL	8.0+	主数据库
Redis	7.0+	缓存与会话存储

前端技术栈

技术	版本	用途
React	18.2.x	前端框架
React Router	6.8.x	路由管理
Axios	1.4.x	HTTP客户端
Bootstrap	5.3.x	UI框架
React Bootstrap	2.8.x	React组件库
Chart.js	4.3.x	图表库
React Icons	4.10.x	图标库

📋 系统要求

最低配置

• 操作系统: Windows 10 / Ubuntu 20.04 / macOS 10.15
• 内存: 4GB RAM
• 存储: 10GB 可用空间
• 网络: 稳定的互联网连接

推荐配置

• 操作系统: Windows 11 / Ubuntu 22.04 / macOS 12+
• 内存: 8GB RAM
• 存储: 50GB 可用空间（用于文件存储）
• 网络: 高速宽带连接

软件依赖

• Python: 3.8+
• Node.js: 16+
• MySQL: 8.0+
• Redis: 7.0+
• Git: 最新版本

🚀 快速开始

方法一：Docker部署（推荐）

1. 克隆项目

git clone <repository-url>
cd filesend

2. 环境配置

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件
nano .env  # 或使用其他编辑器

3. Docker部署

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 初始化数据库

# 进入后端容器
docker-compose exec backend bash

# 初始化数据库
python -m flask db init
python -m flask db migrate -m "Initial migration"
python -m flask db upgrade

# 创建管理员账户
python -m flask create-admin

方法二：传统部署

1. 环境准备

安装Python依赖

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 安装依赖
cd backend
pip install -r requirements.txt

安装Node.js依赖

cd frontend
npm install

安装数据库

# MySQL安装（Ubuntu）
sudo apt update
sudo apt install mysql-server

# Redis安装（Ubuntu）
sudo apt install redis-server

# 启动服务
sudo systemctl start mysql
sudo systemctl start redis-server

2. 数据库配置

创建数据库

-- 登录MySQL
mysql -u root -p

-- 创建数据库
CREATE DATABASE filesend CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户并授权
CREATE USER 'filesend'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON filesend.* TO 'filesend'@'localhost';
FLUSH PRIVILEGES;

配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件，设置数据库连接信息
nano .env

3. 启动服务

启动后端服务

cd backend

# 初始化数据库
python -m flask db init
python -m flask db migrate -m "Initial migration"
python -m flask db upgrade

# 创建管理员账户
python -m flask create-admin

# 启动开发服务器
python run.py

启动前端服务

cd frontend

# 启动开发服务器
npm start

# 或构建生产版本
npm run build

⚙️ 配置说明

环境变量配置

基础配置

# 应用配置
FLASK_ENV=production
FLASK_DEBUG=False
SECRET_KEY=your-secret-key-here

# 数据库配置
DATABASE_URL=mysql+pymysql://username:password@localhost:3306/filesend
SQLALCHEMY_DATABASE_URI=mysql+pymysql://username:password@localhost:3306/filesend

# Redis配置
REDIS_URL=redis://localhost:6379/0

# 文件存储配置
UPLOAD_FOLDER=backend/app/uploads
MAX_CONTENT_LENGTH=16777216  # 16MB

邮件配置（可选）

MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password

JWT配置

JWT_SECRET_KEY=your-jwt-secret-key
JWT_ACCESS_TOKEN_EXPIRES=3600  # 1小时
JWT_REFRESH_TOKEN_EXPIRES=86400  # 24小时

Nginx配置（生产环境）

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

    # 前端静态文件
    location / {
        root /path/to/filesend/frontend/build;
        index index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    # API代理
    location /api/ {
        proxy_pass http://127.0.0.1:5000/;
        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;
    }

    # 文件上传
    client_max_body_size 50M;
}

📊 数据库初始化

创建管理员账户

# 使用Flask命令创建管理员
python -m flask create-admin

# 按提示输入管理员信息
# 用户名: admin
# 邮箱: admin@example.com
# 密码: (设置安全密码)

初始化分类数据

# 运行初始化脚本
python -m flask init-categories

# 或手动添加分类
python -m flask shell
>>> from app.models import Category
>>> category = Category(name="文档", description="各类文档文件")
>>> category.save()

🔧 开发指南

项目结构

filesend/
├── backend/                    # 后端代码
│   ├── app/
│   │   ├── __init__.py        # 应用初始化
│   │   ├── models.py          # 数据模型
│   │   ├── routes/            # API路由
│   │   │   ├── auth.py        # 认证相关
│   │   │   ├── admin.py       # 管理端API
│   │   │   ├── user.py        # 用户端API
│   │   │   └── files.py       # 文件相关API
│   │   └── uploads/           # 文件存储目录
│   ├── requirements.txt       # Python依赖
│   └── run.py                # 启动脚本
├── frontend/                  # 前端代码
│   ├── src/
│   │   ├── components/        # 通用组件
│   │   ├── pages/            # 页面组件
│   │   ├── services/         # API服务
│   │   └── utils/            # 工具函数
│   ├── package.json          # Node.js依赖
│   └── nginx.conf            # Nginx配置
├── config/                   # 配置文件
├── logs/                     # 日志文件
└── docker-compose.yml        # Docker配置

开发环境设置

后端开发

# 安装开发依赖
pip install -r requirements.txt
pip install pytest pytest-cov black flake8

# 代码格式化
black .

# 代码检查
flake8 .

# 运行测试
pytest

前端开发

# 安装开发依赖
npm install
npm install --save-dev @testing-library/react

# 启动开发服务器
npm start

# 运行测试
npm test

# 构建生产版本
npm run build

📚 API文档

认证相关

• POST /api/auth/register - 用户注册
• POST /api/auth/login - 用户登录
• POST /api/auth/logout - 用户登出
• POST /api/auth/refresh - 刷新令牌

文件管理

• GET /api/files - 获取文件列表
• POST /api/files/upload - 上传文件
• GET /api/files/<id> - 获取文件详情
• PUT /api/files/<id> - 更新文件信息
• DELETE /api/files/<id> - 删除文件
• POST /api/files/<id>/claim - 领取文件

用户管理

• GET /api/users - 获取用户列表（管理员）
• POST /api/users - 创建用户（管理员）
• PUT /api/users/<id> - 更新用户信息
• DELETE /api/users/<id> - 删除用户

分类管理

• GET /api/categories - 获取分类列表
• POST /api/categories - 创建分类
• PUT /api/categories/<id> - 更新分类
• DELETE /api/categories/<id> - 删除分类

🐛 常见问题

安装问题

Python版本不兼容

# 检查Python版本
python --version

# 如果版本过低，使用pyenv安装新版本
pyenv install 3.10.0
pyenv global 3.10.0

MySQL连接失败

# 检查MySQL服务状态
sudo systemctl status mysql

# 重启MySQL服务
sudo systemctl restart mysql

# 检查防火墙设置
sudo ufw status

Redis连接失败

# 检查Redis服务状态
sudo systemctl status redis

# 重启Redis服务
sudo systemctl restart redis

# 测试Redis连接
redis-cli ping

运行问题

端口占用

# 检查端口占用
sudo netstat -tulpn | grep :5000
sudo netstat -tulpn | grep :3000

# 终止占用进程
sudo kill -9 <PID>

文件上传失败

# 检查上传目录权限
ls -la backend/app/uploads/
chmod 755 backend/app/uploads/

# 检查文件大小限制
# 修改backend/config.py中的MAX_CONTENT_LENGTH

跨域问题

# 检查CORS配置
# 确保backend/app/__init__.py中已配置CORS
from flask_cors import CORS
CORS(app)

性能优化

数据库优化

-- 添加索引
CREATE INDEX idx_files_status ON files(status);
CREATE INDEX idx_files_category ON files(category_id);
CREATE INDEX idx_files_created ON files(created_at);

-- 优化查询
EXPLAIN SELECT * FROM files WHERE status = 'available';

缓存配置

# 在backend/config.py中添加缓存配置
CACHE_TYPE = 'redis'
CACHE_REDIS_URL = 'redis://localhost:6379/0'
CACHE_DEFAULT_TIMEOUT = 300

🔍 监控与日志

日志配置

# backend/config.py
import logging
from logging.handlers import RotatingFileHandler

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s %(levelname)s %(name)s %(message)s',
    handlers=[
        RotatingFileHandler('logs/filesend.log', maxBytes=10485760, backupCount=5),
        logging.StreamHandler()
    ]
)

健康检查

# 创建健康检查脚本
#!/bin/bash
# health_check.sh

# 检查后端服务
curl -f http://localhost:5000/api/health || exit 1

# 检查数据库
mysql -u filesend -p -e "SELECT 1" filesend || exit 1

# 检查Redis
redis-cli ping || exit 1

echo "All services are healthy"

📞 技术支持

联系方式

• 邮箱: support@filesend.com
• 文档: 官方文档
• 社区: GitHub Issues

更新日志

查看 CHANGELOG.md 了解版本更新历史。

🤝 贡献指南

如何贡献

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

代码规范

• 使用 Black 格式化Python代码
• 使用 ESLint 检查JavaScript代码
• 遵循 PEP 8 Python编码规范
• 遵循 Airbnb JavaScript Style Guide

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Flask - 优秀的Python Web框架
• React - 现代前端框架
• Bootstrap - 响应式UI框架
• MySQL - 可靠的关系型数据库
• Redis - 高性能缓存数据库

---

Made with ❤️ by the FileSend Team