# WebShareHub

**Repository Path**: for_ten_years/WebShareHub

## Basic Information

- **Project Name**: WebShareHub
- **Description**: 基于 Flask 的轻量级 Web 文件共享服务器，支持局域网内文件浏览、下载、上传和二维码分享。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌐 WebShareHub

基于 Flask 的轻量级 Web 文件共享服务器，支持局域网内文件浏览、上传、下载、删除和二维码分享。

## ✨ 功能特性

- 📂 **目录浏览** — 以网页形式浏览共享目录，文件夹在前、文件按类型排序
- ⬇️ **文件下载** — 一键下载任意文件
- ⬆️ **文件上传** — 支持上传文件到指定目录，带进度条显示
- 🗑️ **文件/目录删除** — 支持删除文件和递归删除目录，带确认弹窗
- 📱 **二维码分享** — 生成文件下载二维码，手机扫码即下载
- 📋 **文件详情** — 查看文件名、类型、大小、修改时间等元信息
- 🔒 **路径安全** — 防止目录遍历攻击，确保只能访问共享目录内的文件
- 🛡️ **目录级权限控制** — 按目录精细配置上传/下载/删除权限，支持路径继承回退
- 🎨 **现代 UI** — 简洁美观的界面，支持移动端自适应

## 🚀 快速开始

### 环境要求

- Python 3.8+
- pip

### 安装依赖

```bash
pip install flask qrcode[pil]
```

### 配置

编辑项目根目录下的 `config.json`：

```json
{
    "share_dir": "C:\\Users\\YourName\\Videos",
    "default_permissions": {"upload": true, "download": true, "delete": false},
    "permissions": {
        "public": {"upload": true, "download": true, "delete": true},
        "private": {"upload": false, "download": false, "delete": false}
    }
}
```

### 启动

```bash
python app.py
```

启动后访问 `http://localhost:5000` 即可使用。局域网内其他设备可通过 `http://<你的IP>:5000` 访问。

## 📁 项目结构

```
WebShareHub/
├── app.py                  # 应用入口，创建 Flask 实例、注册蓝图、启动服务
├── config.json             # 配置文件（共享目录路径 + 权限规则）
├── core/                   # 核心工具层
│   ├── config_loader.py    #   配置加载器（兼容打包路径）
│   ├── file_types.py       #   文件类型映射、排序权重、格式化
│   ├── logger.py           #   日志系统（控制台 + 滚动文件，C++ 风格接口）
│   ├── path_utils.py       #   路径安全工具（防目录遍历攻击）
│   ├── permissions.py      #   目录级权限引擎（路径继承回退匹配）
│   └── qr_utils.py         #   二维码生成工具（base64 输出）
├── routes/                 # 路由层（Flask 蓝图）
│   ├── dir_routes.py       #   目录浏览路由
│   ├── file_routes.py      #   文件下载路由
│   ├── upload_routes.py    #   文件上传路由
│   └── api_routes.py       #   API 路由（二维码 + 文件详情 + 删除）
├── templates/
│   └── dir.html            # 前端页面（含 CSS + JS）
└── gen_config.bat          # 配置生成脚本
```

## 🔐 权限控制

通过 `config.json` 按目录精细控制上传/下载/删除权限，匹配时从最具体路径向上回退至 `default_permissions`：

```json
{
    "share_dir": "C:\\Users\\Administrator\\Videos",
    "default_permissions": {"upload": true, "download": true, "delete": false},
    "permissions": {
        "public": {"upload": true, "download": true, "delete": true},
        "private": {"upload": false, "download": false, "delete": false}
    }
}
```

> 请求 `private/docs/file.txt` 时，依次查找 `private/docs` → `private` → `default_permissions`，命中即返回。前端会自动禁用无权限的按钮。

## 📦 打包发布

### 方式一：auto-py-to-exe（推荐）

1. 安装 auto-py-to-exe：

```bash
pip install auto-py-to-exe
```

2. 运行：

```bash
auto-py-to-exe
```

3. 在界面中进行以下配置：

| 配置项 | 设置 |
|--------|------|
| Script Location | 选择 `app.py` |
| Onefile / One Directory | 选择 **One Directory** |
| Console Window | **Console Based**（方便查看日志） |

4. ⚠️ **关键步骤 — 添加附加文件**

在 **Additional Files** 区域：

- 点击 **Add Files**
- 选择 `templates/dir.html`
- **Destination** 填写：`templates`

这样打包后 `dir.html` 会被放到 `_internal/templates/` 目录下。

5. 点击 **Convert .py to .exe** 开始打包

### 方式二：PyInstaller 命令行

```bash
pyinstaller WebShareHub.spec
```

打包输出在 `output/WebShareHub/` 目录下。

### 打包后目录结构

```
WebShareHub/
├── WebShareHub.exe
├── config.json              ← 与 exe 同级放置
├── gen_config.bat           ← 可选，用于生成 config.json
└── _internal/
    ├── templates/
    │   └── dir.html
    ├── core/
    └── ...
```

## 🔧 技术栈

- **后端**：Flask（Python Web 框架）
- **前端**：原生 HTML/CSS/JavaScript（无框架依赖）
- **二维码**：qrcode + Pillow
- **打包**：PyInstaller / auto-py-to-exe

## 📄 许可证

本项目基于 [LICENSE](LICENSE) 文件中的许可证发布。