383 lines
11 KiB
Markdown
383 lines
11 KiB
Markdown
# NAS图片上传系统 - 开发文档
|
||
|
||
> **版本**：v0.3
|
||
> **日期**：2026-04-17
|
||
> **状态**：需求已确认，待开发
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 项目背景
|
||
|
||
需要搭建一个简单的Web应用，允许用户通过手机或电脑访问网站，将图片上传到本地NAS存储中。网站部署在公网实例上，通过内网穿透转发请求到本地NAS。
|
||
|
||
### 1.2 核心需求
|
||
|
||
- 用户通过手机/电脑浏览器访问网站，选择目标文件夹后上传图片
|
||
- 支持多选图片上传，带上传进度条显示
|
||
- 上传完成后显示成功上传的图片列表，方便用户确认是否全部上传成功
|
||
- 文件夹结构：训练营N期 → 25个班级文件夹，用户只能选择不能创建
|
||
- 文件夹自动创建：首次上传时若目标文件夹不存在则自动创建
|
||
- 每个训练营文件夹下有一个MD文档，统计图片数量
|
||
- 无需登录，公开使用（后续考虑加密码保护）
|
||
- 仅上传功能，不提供图片浏览/下载
|
||
- 图片主要为屏幕截图
|
||
|
||
### 1.3 网络架构
|
||
|
||
公网实例通过内网穿透（frp）将请求转发到本地NAS上的服务。服务端直接运行在群晖NAS上。
|
||
|
||
```
|
||
用户手机/电脑 → 公网实例（frp） → 内网穿透 → NAS服务端
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 技术方案
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 层次 | 技术选型 | 说明 |
|
||
|------|----------|------|
|
||
| 后端框架 | Python + Flask | 轻量、开发快、文件操作方便，NAS环境通常支持Python |
|
||
| 前端 | HTML + CSS + JavaScript | 纯静态页面，无需前端构建工具，部署简单 |
|
||
| 图片上传 | XMLHttpRequest | 原生支持上传进度事件 |
|
||
| 文件存储 | NAS本地文件系统 | 直接读写NAS磁盘目录 |
|
||
| 内网穿透 | frp | 将公网请求转发到内网服务 |
|
||
| 配置管理 | .env 文件 | 部署时填写NAS路径、端口等配置 |
|
||
|
||
---
|
||
|
||
## 3. 系统架构
|
||
|
||
### 3.1 整体架构
|
||
|
||
```
|
||
┬── 用户手机/电脑（浏览器）
|
||
│
|
||
├── 公网实例（frp server）
|
||
│
|
||
├── frp client → 内网穿透
|
||
│
|
||
└── 群晖 NAS（Flask + 静态文件）
|
||
├── /api/folders 获取文件夹列表
|
||
├── /api/upload 上传图片
|
||
├── /static/ 前端静态资源
|
||
└── {NAS_DATA_PATH}/ NAS存储目录（.env配置）
|
||
```
|
||
|
||
### 3.2 NAS目录结构
|
||
|
||
```
|
||
{NAS_DATA_PATH}/ ← 通过 .env 配置
|
||
├── 训练营13期/
|
||
│ ├── 统计.md ← 图片数量统计文档
|
||
│ ├── 1班/
|
||
│ ├── 2班/
|
||
│ ├── ...
|
||
│ └── 25班/
|
||
├── 训练营14期/
|
||
│ ├── 统计.md
|
||
│ ├── 1班/
|
||
│ ├── ...
|
||
│ └── 25班/
|
||
└── ...
|
||
```
|
||
|
||
### 3.3 服务端项目结构
|
||
|
||
```
|
||
nas-uploader/
|
||
├── app.py ← Flask主应用
|
||
├── config.py ← 读取 .env 配置
|
||
├── .env ← 部署配置（NAS路径、端口等）
|
||
├── .env.example ← 配置示例文件
|
||
├── requirements.txt ← Python依赖
|
||
├── static/
|
||
│ ├── css/style.css ← 样式文件
|
||
│ ├── js/app.js ← 前端逻辑
|
||
│ └── img/ ← 图标等静态资源
|
||
├── templates/
|
||
│ └── index.html ← 主页面
|
||
└── start.sh ← 启动脚本
|
||
```
|
||
|
||
### 3.4 .env 配置文件
|
||
|
||
```env
|
||
# NAS图片存储根目录（部署时修改为实际路径）
|
||
NAS_DATA_PATH=/volume1/nas_data
|
||
|
||
# 服务端口
|
||
PORT=5000
|
||
|
||
# 允许的图片格式（小写，逗号分隔）
|
||
ALLOWED_EXTENSIONS=jpg,jpeg,png,gif,webp
|
||
|
||
# 单次上传最大文件数量
|
||
MAX_FILES_COUNT=100
|
||
|
||
# 单张图片最大大小（MB）
|
||
MAX_FILE_SIZE_MB=20
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 功能设计
|
||
|
||
### 4.1 文件夹选择功能
|
||
|
||
#### 4.1.1 文件夹获取规则
|
||
|
||
- 后端扫描NAS根目录（`NAS_DATA_PATH`），读取所有"训练营*期"格式的文件夹
|
||
- 每个训练营文件夹下，读取所有"*班"格式的子文件夹
|
||
- 前端以两级联动选择器展示：第一级选训练营，第二级选班级
|
||
- 文件夹列表按名称排序（数字自然排序）
|
||
- **不显示**各班级已有图片数量
|
||
|
||
#### 4.1.2 文件夹自动创建
|
||
|
||
- 当用户选择某个班级并上传图片时，若对应的文件夹不存在，则自动创建
|
||
- 创建逻辑：检查训练营文件夹 → 检查班级文件夹 → 不存在则创建
|
||
- 同时创建对应的统计.md文档（若训练营文件夹是新建的）
|
||
- **新的"训练营N期"文件夹由管理员在NAS上手动创建**，用户不能通过网页创建新训练营
|
||
|
||
### 4.2 图片上传功能
|
||
|
||
#### 4.2.1 上传流程
|
||
|
||
```
|
||
用户选择文件夹 → 点击"选择图片"按钮 → 多选图片 → 点击"开始上传"
|
||
```
|
||
|
||
- 支持的图片格式：JPG、JPEG、PNG、GIF、WEBP（不支持HEIC）
|
||
- 单次上传数量限制：最多100张
|
||
- 单张大小限制：20MB
|
||
- 采用逐张上传策略，每张图片独立显示进度，同时显示总体进度
|
||
|
||
#### 4.2.2 图片命名规则
|
||
|
||
上传后图片按以下格式重命名：
|
||
|
||
```
|
||
训练营{n}期-{x}班-{时间戳}-{随机数}.{扩展名}
|
||
```
|
||
|
||
示例：
|
||
```
|
||
训练营13期-1班-20260417143022-a3f8b2.png
|
||
训练营13期-1班-20260417143022-7c2e91.jpg
|
||
```
|
||
|
||
- `{n}`：训练营期数
|
||
- `{x}`：班级编号
|
||
- `{时间戳}`：精确到秒，格式 `YYYYMMDDHHmmss`
|
||
- `{随机数}`：6位十六进制随机字符串
|
||
- `{扩展名}`：保留原始文件的扩展名
|
||
- 若文件名已存在（极低概率），自动在末尾追加序号：`-a3f8b2-1.png`
|
||
|
||
#### 4.2.3 上传进度显示
|
||
|
||
- 总体进度条：显示已上传完成的数量 / 总数量
|
||
- 单张进度条：每张图片的上传百分比
|
||
- 状态标识：等待中 / 上传中 / 成功 / 失败
|
||
|
||
#### 4.2.4 上传完成反馈
|
||
|
||
- 上传成功后，页面底部显示"已成功上传"图片缩略图列表
|
||
- 每张图片显示：缩略图 + 新文件名 + 上传状态
|
||
- 失败的图片明确标红，显示失败原因，支持"重试"操作
|
||
- 显示摘要信息："成功上传15张，失败 1张"
|
||
|
||
### 4.3 图片统计功能
|
||
|
||
#### 4.3.1 统计.md格式
|
||
|
||
每个训练营文件夹下的统计.md内容格式如下：
|
||
|
||
```markdown
|
||
# 训练营XX期 图片统计
|
||
|
||
更新时间：2026-04-17 14:30:00
|
||
图片总数：156
|
||
|
||
| 班级 | 图片数量 |
|
||
|------|----------|
|
||
| 1班 | 12 |
|
||
| 2班 | 8 |
|
||
| ... | ... |
|
||
| 25班 | 6 |
|
||
```
|
||
|
||
#### 4.3.2 统计更新触发
|
||
|
||
- 每次上传成功后，自动更新对应训练营的统计.md
|
||
- 统计方式：扫描训练营文件夹及其所有子目录，统计图片文件数量
|
||
- 图片文件判定：根据文件扩展名（jpg、jpeg、png、gif、webp）
|
||
- 更新时间记录在文档头部
|
||
|
||
---
|
||
|
||
## 5. API设计
|
||
|
||
### 5.1 获取文件夹列表
|
||
|
||
**GET /api/folders**
|
||
|
||
返回所有训练营及其下的班级文件夹。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"folders": [
|
||
{
|
||
"name": "训练营13期",
|
||
"classes": ["1班", "2班", "3班", "4班", "5班", "...", "25班"]
|
||
},
|
||
{
|
||
"name": "训练营14期",
|
||
"classes": ["1班", "3班"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.2 上传图片
|
||
|
||
**POST /api/upload**
|
||
|
||
接受multipart/form-data格式的图片上传。
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| folder | string | 是 | 训练营名称，如"训练营13期" |
|
||
| class | string | 是 | 班级名称，如"1班" |
|
||
| files | File[] | 是 | 图片文件数组，支持多文件 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"uploaded": [
|
||
{ "filename": "训练营13期-1班-20260417143022-a3f8b2.png", "status": "success" },
|
||
{ "filename": "训练营13期-1班-20260417143023-7c2e91.jpg", "status": "success" }
|
||
],
|
||
"failed": [
|
||
{ "filename": "photo3.bmp", "status": "failed", "reason": "文件格式不支持" }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 前端页面设计
|
||
|
||
### 6.1 页面布局
|
||
|
||
页面采用简洁的单页设计，适配手机和电脑访问（响应式布局）。
|
||
|
||
页面从上到下分为三个区域：
|
||
|
||
#### 6.1.1 顶部：文件夹选择区
|
||
|
||
- 第一行：下拉选择"训练营"（如"训练营13期"）
|
||
- 第二行：下拉选择"班级"（如"1班"）
|
||
- 班级列表根据选中的训练营动态加载
|
||
|
||
#### 6.1.2 中部：图片选择和上传区
|
||
|
||
- "选择图片"按钮：触发文件选择器，支持多选
|
||
- 已选择的图片列表：显示缩略图、文件名、可删除
|
||
- "开始上传"按钮：触发上传操作
|
||
- 进度条：总体进度 + 单张进度
|
||
|
||
#### 6.1.3 底部：上传结果区
|
||
|
||
- 显示成功上传的图片缩略图网格
|
||
- 失败的图片显示红色标记和"重试"按钮
|
||
- 显示摘要信息："成功上传15张，失败 1张"
|
||
|
||
### 6.2 移动端适配
|
||
|
||
- 采用响应式设计，自动适配手机和电脑屏幕
|
||
- 手机端优化：按钮大小适中触摸操作，图片缩略图网格自动调整列数
|
||
- 支持手机原生图片选择器（accept="image/*"）
|
||
|
||
---
|
||
|
||
## 7. 部署方案
|
||
|
||
### 7.1 frp内网穿透配置
|
||
|
||
详见 [frp内网穿透_原理与部署指南.md](./frp内网穿透_原理与部署指南.md)
|
||
|
||
**frpc.toml（NAS侧）关键配置：**
|
||
|
||
```toml
|
||
serverAddr = "你的公网IP"
|
||
serverPort = 7000
|
||
auth.token = "你的认证密码"
|
||
|
||
[[proxies]]
|
||
name = "nas-uploader"
|
||
type = "tcp"
|
||
localIP = "127.0.0.1"
|
||
localPort = 5000
|
||
remotePort = 8080
|
||
```
|
||
|
||
### 7.2 服务启动
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# start.sh
|
||
cd /path/to/nas-uploader
|
||
source venv/bin/activate # 可选：使用虚拟环境
|
||
python app.py
|
||
```
|
||
|
||
### 7.3 部署步骤
|
||
|
||
1. 将项目文件上传到群晖NAS
|
||
2. 复制 `.env.example` 为 `.env`，修改 `NAS_DATA_PATH` 为实际的共享文件夹路径
|
||
3. 安装Python依赖：`pip install -r requirements.txt`
|
||
4. 启动服务：`bash start.sh`
|
||
5. 配置frpc客户端连接到公网服务器
|
||
6. 浏览器访问 `http://公网IP:8080` 验证
|
||
|
||
---
|
||
|
||
## 8. 开发计划
|
||
|
||
| 阶段 | 内容 | 预估工时 |
|
||
|------|------|----------|
|
||
| 第一阶段 | 后端基础：Flask服务 + .env配置 + API + 文件操作 | 2-3小时 |
|
||
| 第二阶段 | 前端页面：文件夹选择 + 图片上传 + 进度条 + 结果展示 | 2-3小时 |
|
||
| 第三阶段 | 统计功能：自动更新统计.md | 1小时 |
|
||
| 第四阶段 | 优化：移动端适配 + 异常处理 + 测试 | 1-2小时 |
|
||
| 第五阶段 | 部署：frp配置 + 群晖NAS部署 + 服务上线 | 0.5小时 |
|
||
|
||
---
|
||
|
||
## 9. 风险与注意事项
|
||
|
||
- **并发上传**：多用户同时上传到同一文件夹时，文件名含时间戳+随机数，冲突概率极低；若冲突则自动追加序号
|
||
- **存储空间**：需关注NAS磁盘空间，建议在上传前检查剩余空间
|
||
- **网络稳定性**：内网穿透可能因网络波动导致上传中断，需支持失败重试
|
||
- **安全性**：当前公开访问无需登录，后续考虑加密码保护；后端必须验证文件类型防止恶意上传
|
||
- **文件类型验证**：后端严格校验文件扩展名和MIME类型，防止上传非图片文件
|
||
|
||
---
|
||
|
||
## 10. 后续规划（暂不实现）
|
||
|
||
- 访问密码保护
|
||
- HTTPS 加密传输
|
||
- 图片浏览/下载功能
|
||
- 管理后台
|