MarkBase架构升级：Multi-Volume Virtual Tree + Dual-View Management + Git Remote修正
核心功能： - ✅ Categories/Series双视图管理（category_view.rs + import_markdown.rs） - ✅ FUSE Multi-Volume支持（tree_type参数） - ✅ SSH/SFTP/SCP/rsync协议完整实现（4042行） - ✅ NFS/SMB Module Phase 1-3完成 - ✅ Archive Module Phase 1-4完成（2916行） - ✅ Download Center API完整实现 - ✅ S3兼容API实现（560行） Git配置修正： - ✅ 删除错误origin（gitea.momentry.ddns.net） - ✅ 删除m5max128（指向机器名） - ✅ 设置origin = m5max128gitea.momentry.ddns.net/admin/markbase - ✅ 设置m4minigitea = m4minigitea.momentry.ddns.net/warren/markbase 数据清理： - ✅ 删除38个临时SQLite（保留accusys.sqlite、demo.sqlite） - ✅ 删除.bak、test_*.bin、调试脚本等临时文件 - ✅ 删除临时目录（build/、download files/、raid_test/等） - ✅ 更新.gitignore排除临时文件 架构优化： - 52个文件修改，2434行新增，4739行删除 - Workspace成员整合（16个crate） - 数据库状态：accusys.sqlite保留（主demo测试） 远程同步： - ✅ 准备推送到m5max128gitea（远程Gitea） - ✅ 准备推送到m4minigitea（本地Gitea）
This commit is contained in:
Warren
330
docs/EMPTY_DIRECTORY_COMPLETE_GUIDE.md
Normal file
330
docs/EMPTY_DIRECTORY_COMPLETE_GUIDE.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# 空目录上传完整指南
|
||||
|
||||
## 问题说明
|
||||
|
||||
**webkitdirectory限制：**
|
||||
- HTML5标准：浏览器只选择**文件**
|
||||
- 空目录不包含在`fileInput.files`中
|
||||
- 无法上传完全空的目录
|
||||
|
||||
## 解决方案：.keep标记文件
|
||||
|
||||
**原理：**
|
||||
- 在每个空目录中添加`.keep`文件（0字节）
|
||||
- webkitdirectory会上传包含`.keep`的目录
|
||||
- 目录结构完整保留
|
||||
|
||||
---
|
||||
|
||||
## 完整工作流程
|
||||
|
||||
### 步骤1：准备源目录
|
||||
|
||||
```bash
|
||||
# 查看源目录结构
|
||||
tree /path/to/source
|
||||
|
||||
# 示例结构：
|
||||
/path/to/AccuSys Downloads/
|
||||
├── ExaSAN-DAS/
|
||||
│ ├── Model001/
|
||||
│ │ └── readme.pdf # 有文件
|
||||
│ ├── EmptyFolder1/ # 空目录
|
||||
│ └── EmptyFolder2/ # 空目录
|
||||
├── Gamma/
|
||||
│ └── EmptySubFolder/ # 空目录
|
||||
└── T-Share/
|
||||
└── manual.pdf # 有文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤2：运行prepare_upload.sh脚本
|
||||
|
||||
```bash
|
||||
# 一键添加.keep文件
|
||||
bash scripts/prepare_upload.sh "/path/to/AccuSys Downloads"
|
||||
|
||||
# 输出示例：
|
||||
=== Preparing upload for /path/to/AccuSys Downloads ===
|
||||
|
||||
Added .keep in: /path/to/AccuSys Downloads/ExaSAN-DAS/EmptyFolder1
|
||||
Added .keep in: /path/to/AccuSys Downloads/ExaSAN-DAS/EmptyFolder2
|
||||
Added .keep in: /path/to/AccuSys Downloads/Gamma/EmptySubFolder
|
||||
|
||||
=== Preparation complete ===
|
||||
Empty directories: 0
|
||||
Total .keep files: 3
|
||||
|
||||
Ready for webkitdirectory upload
|
||||
All empty directories will be uploaded with .keep files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤3：验证准备结果
|
||||
|
||||
```bash
|
||||
# 查看所有.keep文件
|
||||
find "/path/to/AccuSys Downloads" -name ".keep"
|
||||
|
||||
# 查看完整目录结构
|
||||
tree "/path/to/AccuSys Downloads"
|
||||
```
|
||||
|
||||
**预期结果：**
|
||||
```
|
||||
AccuSys Downloads/
|
||||
├── ExaSAN-DAS/
|
||||
│ ├── Model001/
|
||||
│ │ └── readme.pdf
|
||||
│ ├── EmptyFolder1/
|
||||
│ │ └── .keep ✅ 添加成功
|
||||
│ ├── EmptyFolder2/
|
||||
│ │ └ keep ✅ 添加成功
|
||||
├── Gamma/
|
||||
│ ├── EmptySubFolder/
|
||||
│ │ └ keep ✅ 添加成功
|
||||
└── T-Share/
|
||||
└ manual.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤4：上传文件夹
|
||||
|
||||
```bash
|
||||
# 打开Web界面
|
||||
https://download.accusys.ddns.net/upload
|
||||
|
||||
# 选择文件夹
|
||||
1. 点击"Select Folder"
|
||||
2. 选择整个"AccuSys Downloads"文件夹
|
||||
3. 自动上传所有文件（包括.keep）
|
||||
|
||||
# 上传结果：
|
||||
- ✅ 所有文件上传成功
|
||||
- ✅ 所有空目录保留（包含.keep）
|
||||
- ✅ 目录结构完整
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤5：验证上传结果
|
||||
|
||||
```bash
|
||||
# 查看上传文件列表
|
||||
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.total_files'
|
||||
|
||||
# 查看目录结构（在服务器端）
|
||||
find /Users/accusys/Downloads/accusys -type d
|
||||
|
||||
# 验证.keep文件
|
||||
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.files[] | select(.filename == ".keep")'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## .keep文件说明
|
||||
|
||||
**文件特性：**
|
||||
- 文件名：`.keep`（或`.gitkeep`）
|
||||
- 文件大小：0字节（空文件）
|
||||
- 文件作用：标记空目录存在
|
||||
- SHA256：`e3b0c44298fc1c149afbf4c8996fb924...`（标准空文件hash）
|
||||
|
||||
**保留策略：**
|
||||
- ✅ 上传后保留`.keep`文件
|
||||
- ✅ 不影响其他文件
|
||||
- ✅ 不占用额外空间
|
||||
- ✅ 符合Git标准惯例
|
||||
|
||||
---
|
||||
|
||||
## 脚本源码（prepare_upload.sh）
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# prepare_upload.sh - Prepare directory for upload
|
||||
# Add .keep files in all empty directories
|
||||
|
||||
SOURCE_DIR="$1"
|
||||
|
||||
if [ -z "$SOURCE_DIR" ]; then
|
||||
echo "Usage: bash scripts/prepare_upload.sh <source_directory>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -d "$SOURCE_DIR" ]; then
|
||||
echo "Error: Directory not found: $SOURCE_DIR"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=== Preparing upload for $SOURCE_DIR ==="
|
||||
echo ""
|
||||
|
||||
# Find empty directories and add .keep
|
||||
empty_count=0
|
||||
find "$SOURCE_DIR" -type d -empty | while read dir; do
|
||||
touch "$dir/.keep"
|
||||
empty_count=$((empty_count + 1))
|
||||
echo "Added .keep in: $dir"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== Preparation complete ==="
|
||||
echo "Empty directories: $(find "$SOURCE_DIR" -type d -empty | wc -l)"
|
||||
echo "Total .keep files: $(find "$SOURCE_DIR" -name ".keep" | wc -l)"
|
||||
echo ""
|
||||
echo "Ready for webkitdirectory upload"
|
||||
echo "All empty directories will be uploaded with .keep files"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 高级用法
|
||||
|
||||
### 批量处理多个目录
|
||||
|
||||
```bash
|
||||
# 处理290个文件所在的目录
|
||||
bash scripts/prepare_upload.sh "/path/to/AccuSys Downloads"
|
||||
|
||||
# 处理嵌套空目录（多层）
|
||||
bash scripts/prepare_upload.sh "/path/to/complex/structure"
|
||||
|
||||
# 查看处理结果
|
||||
find "/path/to/AccuSys Downloads" -name ".keep" | wc -l
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 上传后清理.keep（可选）
|
||||
|
||||
```bash
|
||||
# 如果需要删除.keep文件（保留空目录）
|
||||
find /Users/accusys/Downloads/accusys -name ".keep" -delete
|
||||
|
||||
# 注意：删除后目录仍存在，但为空目录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试案例
|
||||
|
||||
**测试目录：** `/tmp/test_upload`
|
||||
|
||||
**原始结构：**
|
||||
```
|
||||
/tmp/test_upload/
|
||||
├── ExaSAN-DAS/
|
||||
│ ├── Model001/readme.txt # 有文件
|
||||
│ ├── Model002/EmptyFolder/ # 空目录
|
||||
│ └ EmptySubFolder/ # 空目录
|
||||
├── Gamma/manual.pdf # 有文件
|
||||
└ T-Share/
|
||||
├── EmptyFolder1/ # 空目录
|
||||
└ EmptyFolder2/ # 空目录
|
||||
```
|
||||
|
||||
**运行脚本：**
|
||||
```bash
|
||||
bash scripts/prepare_upload.sh /tmp/test_upload
|
||||
```
|
||||
|
||||
**处理结果：**
|
||||
```
|
||||
Added .keep in: /tmp/test_upload/T-Share/EmptyFolder2
|
||||
Added .keep in: /tmp/test_upload/T-Share/EmptyFolder1
|
||||
Added .keep in: /tmp/test_upload/ExaSAN-DAS/Model002/EmptyFolder
|
||||
Added .keep in: /tmp/test_upload/ExaSAN-DAS/EmptySubFolder
|
||||
|
||||
Empty directories: 0
|
||||
Total .keep files: 4
|
||||
```
|
||||
|
||||
**最终结构：**
|
||||
```
|
||||
/tmp/test_upload/
|
||||
├── ExaSAN-DAS/
|
||||
│ ├── Model001/readme.txt
|
||||
│ ├── Model002/EmptyFolder/.keep
|
||||
│ ├── EmptySubFolder/.keep
|
||||
├── Gamma/manual.pdf
|
||||
└── T-Share/
|
||||
├── EmptyFolder1/.keep
|
||||
├── EmptyFolder2/.keep
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: .keep文件会影响其他文件吗？
|
||||
**答：** 不会。`.keep`是独立文件，不影响其他文件的上传和下载。
|
||||
|
||||
### Q2: 可以使用其他名称吗？
|
||||
**答：** 可以。常见替代名称：
|
||||
- `.gitkeep`（Git标准）
|
||||
- `.placeholder`
|
||||
- `README.md`（如果需要说明文字）
|
||||
- `.localized`（macOS系统文件）
|
||||
|
||||
### Q3: 上传后.keep文件必须保留吗？
|
||||
**答：** 可选。如果删除`.keep`：
|
||||
- 目录仍然存在（但变为空目录）
|
||||
- 不影响其他文件
|
||||
- 建议保留（作为目录存在标记）
|
||||
|
||||
### Q4: webkitdirectory有其他限制吗？
|
||||
**答：** 有。其他限制：
|
||||
- 无法上传隐藏文件（如`.DS_Store`）← 但MarkBase已支持
|
||||
- 无法上传符号链接
|
||||
- 无法控制上传顺序
|
||||
|
||||
---
|
||||
|
||||
## MarkBase特殊支持
|
||||
|
||||
**已实现功能：**
|
||||
- ✅ 空文件上传（0字节文件）
|
||||
- ✅ `.keep`、`.localized`、`.DS_Store`上传
|
||||
- ✅ 子目录自动创建（`create_dir_all`）
|
||||
- ✅ SHA256校验（包含空文件）
|
||||
- ✅ 无文件大小限制
|
||||
|
||||
**API支持：**
|
||||
```bash
|
||||
# 上传空文件
|
||||
curl -X POST https://download.accusys.ddns.net/api/v2/upload-unlimited/accusys \
|
||||
-F "file=@/tmp/test_upload/ExaSAN-DAS/EmptySubFolder/.keep;filename=ExaSAN-DAS/EmptySubFolder/.keep"
|
||||
|
||||
# 返回：
|
||||
{
|
||||
"ok": true,
|
||||
"filename": "ExaSAN-DAS/EmptySubFolder/.keep",
|
||||
"file_size": 0,
|
||||
"file_hash": "e3b0c44298fc1c149afbf4c8996fb924..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
**最佳实践：**
|
||||
1. ✅ 使用`prepare_upload.sh`一键处理
|
||||
2. ✅ 上传前验证`.keep`文件数量
|
||||
3. ✅ 上传后检查目录结构完整性
|
||||
4. ✅ 保留`.keep`文件（可选）
|
||||
|
||||
**适用场景：**
|
||||
- ✅ AccuSys下载文件（290个文件）
|
||||
- ✅ 产品资料库（多层目录）
|
||||
- ✅ 软件发布包（含空目录）
|
||||
- ✅ 文档管理系统
|
||||
|
||||
---
|
||||
|
||||
**Last Updated：** 2026-06-09 14:45
|
||||
**Version：** 2.8 (Empty Directory Support Complete)
|
||||
Reference in New Issue
Block a user