markbase/docs/EMPTY_DIRECTORY_COMPLETE_GUIDE.md

空目录上传完整指南

问题说明

webkitdirectory限制：

• HTML5标准：浏览器只选择文件
• 空目录不包含在fileInput.files中
• 无法上传完全空的目录

解决方案：.keep标记文件

原理：

• 在每个空目录中添加.keep文件（0字节）
• webkitdirectory会上传包含.keep的目录
• 目录结构完整保留

---

完整工作流程

步骤1：准备源目录

# 查看源目录结构
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脚本

# 一键添加.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：验证准备结果

# 查看所有.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：上传文件夹

# 打开Web界面
https://download.accusys.ddns.net/upload

# 选择文件夹
1. 点击"Select Folder"
2. 选择整个"AccuSys Downloads"文件夹
3. 自动上传所有文件（包括.keep）

# 上传结果：
- ✅ 所有文件上传成功
- ✅ 所有空目录保留（包含.keep）
- ✅ 目录结构完整

---

步骤5：验证上传结果

# 查看上传文件列表
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）

#!/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"

---

高级用法

批量处理多个目录

# 处理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（可选）

# 如果需要删除.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 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支持：

# 上传空文件
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)