# file_webui

**Repository Path**: spider1462/file_webui

## Basic Information

- **Project Name**: file_webui
- **Description**: 一个基于Flask的简单文件管理Web应用程序，支持文件上传、下载和删除功能。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📂 文件传输 Web 应用

一个轻量级文件传输 Web 应用，支持文件上传、下载、删除及批量操作，具备智能防重名、局域网 IP 自动发现和二维码展示功能。

## ✨ 核心功能

- **📤 文件上传**：支持点击选择和拖拽上传，单文件最大 500MB
- **📥 文件下载**：支持单文件下载和多文件批量打包下载（ZIP 格式）
- **🗑️ 文件删除**：支持单文件删除和多文件批量删除
- **🔢 智能防重名**：上传同名文件时自动追加 `(1)`、`(2)`、`(3)`... 确保文件名唯一，正确保留文件扩展名
- **🌐 局域网 IP 自动发现**：优先匹配 `192.168.x.x` 或 `10.x.x.x` 网段，自动获取局域网访问地址
- **📱 二维码展示**：自动生成局域网访问地址的二维码，方便移动端快速访问
- **🔒 安全防护**：目录穿越攻击防护、文件名安全校验、文件大小限制
- **🖥️ 自动打开浏览器**：程序启动后自动在默认浏览器中打开服务地址

## 🛠️ 技术栈

- **后端**：Python 3.8+、Flask
- **前端**：HTML5、CSS3、JavaScript（原生）、Bootstrap 5
- **依赖库**：
  - `Flask`：Web 框架
  - `qrcode[pil]`：二维码生成
  - `werkzeug`：Web 工具库（安全文件名处理）
  - `zipfile`：ZIP 文件打包
  - `webbrowser`：自动打开浏览器

## 📦 安装与运行

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python app.py
```

服务默认在 `5000` 端口启动，启动后会自动打开浏览器。

### 3. 自定义端口

```bash
# Windows
set FILE_WEB_PORT=8080
python app.py

# Linux / macOS
export FILE_WEB_PORT=8080
python app.py
```

## 📋 使用说明

### 文件上传
1. 点击上传区域或拖拽文件到指定区域
2. 支持多文件同时上传
3. 同名文件会自动重命名（例如 `report.pdf` → `report(1).pdf`）

### 文件下载
- **单文件下载**：点击文件列表中的"下载"按钮
- **批量下载**：勾选多个文件后点击"批量下载"，系统会打包为 ZIP 文件下载

### 文件删除
- **单文件删除**：点击文件列表中的"删除"按钮（需确认）
- **批量删除**：勾选多个文件后点击"批量删除"（需确认，操作不可撤销）

### 局域网访问
1. 程序启动后会在控制台显示局域网访问地址
2. 首页顶部展示二维码，手机扫码即可访问
3. 确保设备在同一局域网内

## 🔧 项目结构

```
file_webui/
├── app.py              # Flask 应用主程序
├── requirements.txt    # Python 依赖清单
├── README.md          # 项目说明文档
├── templates/         # HTML 模板目录
│   └── index.html    # 首页模板
└── uploads/           # 文件存储目录（自动创建）
```

## 🛡️ 安全特性

- **目录穿越防护**：所有文件操作严格限制在 `uploads` 目录内
- **文件名安全校验**：使用 `werkzeug.utils.secure_filename` 处理文件名
- **文件大小限制**：默认单文件最大 500MB，防止磁盘空间耗尽
- **路径验证**：使用 `os.path.realpath()` 验证文件路径合法性
- **错误处理**：完善的异常处理机制，防止服务因单文件错误而崩溃

## ⚙️ 配置说明

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `UPLOAD_FOLDER` | `./uploads` | 文件存储目录 |
| `MAX_CONTENT_LENGTH` | `500MB` | 单文件最大上传大小 |
| `PORT` | `5000` | 服务端口（可通过环境变量 `FILE_WEB_PORT` 修改） |

## 🌐 浏览器兼容性

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
- 移动端浏览器（iOS Safari、Android Chrome）

## 📝 注意事项

1. 上传的文件会永久保存在 `uploads` 目录中，请定期清理不需要的文件
2. 批量删除操作不可撤销，请谨慎操作
3. 大文件上传时请耐心等待，不要重复点击上传按钮
4. 确保防火墙允许服务端口的局域网访问

## 🐛 故障排除

### 无法访问服务
- 检查服务是否正常启动（查看控制台输出）
- 确认防火墙设置允许端口访问
- 验证设备是否在同一局域网内

### 上传失败
- 检查文件大小是否超过 500MB 限制
- 确认文件名不包含非法字符
- 查看磁盘空间是否充足

### 二维码无法扫描
- 检查局域网连接是否正常
- 确认 IP 地址是否正确显示
- 尝试手动输入访问地址

---

> **项目是由 Qwen Code + Qwen3.6 27b-Q4KM 开发** 🤖