# file_upload_sys

**Repository Path**: ming_log/file_upload_sys

## Basic Information

- **Project Name**: file_upload_sys
- **Description**: 文件上传系统，适用于高校场景。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件上传系统

面向教师收集学生作业文件的通用上传系统。后端使用 Rust Axum，前端使用 React Vite，数据库默认 SQLite，文件存储使用 MinIO。

## 功能概览

- 管理员、教师、学生三类角色。
- 默认超级管理员：`minglog / minglog666`。
- 管理员可创建管理员、教师、学生；教师可创建学生。
- 支持 `.xlsx` 批量导入学生。
- 教师可创建班级、课程、作业，并设置文件类型、截止时间、文件大小限制。
- 学生可查看自己的作业并上传提交文件。
- 登录失败 5 次后锁定 1 小时。
- 默认密码 `123456` 登录后必须先修改密码。
- 忘记密码支持邮箱验证码；未配置 SMTP 时验证码输出到后端日志。
- 上传文件使用 MinIO 对象存储。

## 项目结构

```text
.
├── apps/
│   ├── api/                # Rust Axum 后端
│   │   ├── migrations/     # SQLite 数据库迁移
│   │   └── src/
│   └── web/                # React Vite 前端
│       ├── public/template # 前端可下载的导入模板
│       └── src/
├── template/               # 原始 Excel 模板
├── .env.example            # 环境变量模板
├── package.json            # 根脚本
├── pnpm-lock.yaml
└── pnpm-workspace.yaml
```

## 环境要求

- Node.js 20+
- pnpm 10+
- Rust 1.94+
- MinIO 或兼容 S3 的对象存储服务

## 配置

复制环境变量模板：

```bash
copy .env.example .env
```

如果使用 PowerShell，也可以执行：

```powershell
Copy-Item .env.example .env
```

关键配置：

```env
DATABASE_URL=sqlite://file_upload_system.db
API_HOST=127.0.0.1
API_PORT=8080
JWT_SECRET=change-me-in-production
WEB_ORIGIN=http://localhost:5173

MINIO_ENDPOINT=http://127.0.0.1:9000
MINIO_REGION=us-east-1
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=file-upload-system

SMTP_HOST=
SMTP_PORT=465
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_FROM=no-reply@example.com
SMTP_TLS=tls
SMTP_ALLOW_INVALID_CERTS=false
```

说明：

- `DATABASE_URL` 默认会在后端工作目录下创建 SQLite 数据库文件。
- `JWT_SECRET` 生产环境必须改成高强度随机值。
- `WEB_ORIGIN` 需要和前端访问地址一致，用于 CORS。
- `MINIO_ENDPOINT` 要填写 MinIO API 地址，通常是 `9000` 端口；`9001` 一般是控制台端口。
- `MINIO_BUCKET` 必须符合 S3 桶名规则，只能使用小写字母、数字和连字符，不能使用下划线。
- `SMTP_TLS` 支持 `auto`、`tls`、`starttls`、`opportunistic`、`none`。常见选择：465 使用 `tls`，587 使用 `starttls`。
- 腾讯企业邮箱部署时优先使用 `465 + tls`，其次使用 `587 + starttls`，不建议继续使用 `25 + none`。
- `SMTP_PASSWORD` 通常应填写邮箱的 SMTP 授权码，而不是网页登录密码。
- `SMTP_FROM` 建议先与 `SMTP_USERNAME` 保持一致，确认企业邮箱允许代发后再改成其他发件地址。
- `SMTP_ALLOW_INVALID_CERTS=true` 只建议本机开发排查证书链问题时临时使用。

## MinIO 准备

确保 MinIO 已启动，并创建 `.env` 中配置的桶：

```text
file-upload-system
```

如果使用默认本机 MinIO：

- API 地址：`http://127.0.0.1:9000`
- 控制台地址：`http://127.0.0.1:9001`
- 默认账号：`minioadmin`
- 默认密码：`minioadmin`

## 启动开发环境

安装依赖：

```bash
pnpm install
```

启动后端：

```bash
pnpm api:dev
```

启动前端：

```bash
pnpm dev:web
```

访问地址：

- 前端：`http://127.0.0.1:5173`
- 后端健康检查：`http://127.0.0.1:8080/api/health`

## 默认账号

系统首次启动后会自动创建超级管理员：

| 类型 | 账号 | 密码 |
| --- | --- | --- |
| 管理员 | `minglog` | `minglog666` |

管理员和教师使用“教师登录”入口，学生使用“学生登录”入口。

## Excel 导入模板

第一行为表头，字段顺序如下：

| 姓名 | 学号 | 学校 | 专业 | 班级 | 邮箱 | 密码 |
| --- | --- | --- | --- | --- | --- | --- |
| 张三 | 20260001 | 明德中学 | 计算机应用 | 一班 | student@example.com | abc12345 |

说明：

- 模板文件在 `template/学生导入模板.xlsx`。
- 前端也提供了可下载模板：`apps/web/public/template/学生导入模板.xlsx`。
- 当前导入模板只用于学生导入。
- `密码` 为空时使用默认密码 `123456`。

## 常用脚本

| 命令 | 说明 |
| --- | --- |
| `pnpm dev:web` | 启动前端开发服务 |
| `pnpm api:dev` | 启动后端 API |
| `pnpm build` | 构建前端 |
| `pnpm test` | 运行前端测试 |
| `pnpm api:test` | 运行后端测试 |

## 验证

后端测试：

```bash
pnpm api:test
```

前端测试：

```bash
pnpm --filter web test
```

前端构建：

```bash
pnpm --filter web build
```

## 常见问题

### MinIO 连接失败

确认 `.env` 中的 `MINIO_ENDPOINT` 是 API 端口，通常不是控制台端口。如果控制台是 `http://127.0.0.1:9001`，API 通常是 `http://127.0.0.1:9000`。

### 桶名无效

S3 兼容桶名不能包含下划线。请使用 `file-upload-system`，不要使用 `file_upload_system`。

### 忘记密码没有收到邮件

如果未配置 `SMTP_HOST`，验证码会输出到后端日志。开发环境可以直接查看 `pnpm api:dev` 的终端输出。