大文件管理规范

本文档定义了项目中大文件的管理规范、目录结构和最佳实践，确保仓库性能和团队协作效率。

📏 文件大小阈值

LFS 跟踪标准

文件类型	大小阈值	说明
图片文件	> 100KB	文档截图、架构图等
压缩包	所有	编译产物、发布资源
音视频	所有	演示视频、录音文件
设计文件	所有	PSD、AI、Sketch 等
数据文件	> 1MB	数据库文件、数据集

特殊处理

• SVG 文件: 通常保持为文本文件，除非超过 1MB
• 配置文件: 即使较大也不使用 LFS，保持可读性
• 源代码: 绝不使用 LFS，保持版本控制完整性

📁 目录结构规范

project-root/
├── docs/
│   └── images/              # 文档相关图片
│       ├── architecture/    # 架构图、流程图
│       ├── screenshots/     # 功能截图
│       ├── diagrams/       # 技术图表
│       └── assets/         # 其他设计资源
├── .act-artifacts/         # 临时文件（已在 .gitignore 中）
│   ├── output/            # 生成的截图和输出 
│   ├── performance_results/ # 性能测试结果
│   └── builds/            # 编译产物
└── assets/                # 项目资源文件
    ├── media/             # 音视频文件
    └── resources/         # 其他资源文件

📋 文件命名规范

统一命名格式

# 架构图
docs/images/architecture/service-architecture-v2.png
docs/images/architecture/database-schema-diagram.png

# 功能截图  
docs/images/screenshots/ledger-api-demo-240622.png
docs/images/screenshots/bubble-ui-example-240622.png

# 技术图表
docs/images/diagrams/grpc-flow-diagram.png
docs/images/diagrams/concurrent-processing-flow.png

命名原则

1. 使用英文: 便于跨平台兼容
2. 连字符分隔: 避免空格和下划线
3. 包含版本: 重要文件包含版本信息
4. 添加日期: 截图类文件添加日期 (YYMMDD)
5. 描述准确: 文件名能够准确描述内容

🔄 版本管理策略

图片文件版本控制

# 好的做法
architecture-diagram-v1.png
architecture-diagram-v2.png
architecture-diagram-latest.png -> v2.png (符号链接)

# 避免的做法
architecture-diagram-old.png
architecture-diagram-new.png
architecture-diagram-final.png

大文件更新流程

1. 评估必要性: 确认是否需要保留历史版本
2. 版本标记: 为重要更新添加版本标记
3. 清理旧版本: 定期清理不需要的历史版本
4. 文档更新: 同步更新相关文档引用

💰 成本控制策略

GitHub LFS 配额管理

• 免费账户: 1GB 存储 + 1GB/月带宽
• 监控使用量: 定期检查 LFS 存储使用情况
• 优化策略: 及时清理不需要的大文件

最佳实践

1. 压缩优化:

   • PNG 图片使用 pngquant 压缩
   • JPEG 图片控制质量在 80-90%
   • 使用 WebP 格式（兼容性允许时）

2. 外部存储:

   • 考虑使用 CDN 存储常用资源
   • 大型演示视频使用视频平台

3. 定期清理:

   # 查看 LFS 文件列表
   git lfs ls-files
   
   # 检查存储使用情况
   git lfs fsck
   
   # 清理未使用的 LFS 文件
   git lfs prune

🚀 性能优化

克隆优化

# 浅克隆，不下载 LFS 文件
git clone --filter=blob:none --no-checkout <repo-url>
cd <repo>
git sparse-checkout init --cone
git checkout

# 按需下载 LFS 文件
git lfs pull --include="docs/images/screenshots/*"

分支策略

• 功能分支: 避免不必要的大文件
• 发布分支: 包含完整的发布资源
• 开发分支: 只包含开发必需的文件

📝 团队协作规范

提交规范

# 好的提交信息
feat: add architecture diagram for new service
docs: update API screenshots for v2.1
assets: compress product images (reduce 60% size)

# 避免的提交信息
update images
add files
fix stuff

代码审查要点

1. 文件必要性: 检查文件是否确实需要版本控制
2. 文件大小: 确认文件大小符合阈值标准
3. 命名规范: 验证文件命名是否符合规范
4. 目录结构: 确认文件放置在正确目录

冲突处理

LFS 文件冲突解决策略：

# 查看冲突文件
git lfs ls-files

# 选择特定版本
git checkout --ours path/to/file.png    # 保留当前分支版本
git checkout --theirs path/to/file.png  # 保留合并分支版本

# 重新跟踪文件
git add path/to/file.png
git commit -m "resolve: fix LFS file conflict"

🛠️ 工具和脚本

文件压缩脚本

#!/bin/bash
# scripts/compress-images.sh

# 压缩 PNG 图片
find docs/images -name "*.png" -exec pngquant --quality=80-90 --ext .png --force {} \;

# 压缩 JPEG 图片  
find docs/images -name "*.jpg" -exec jpegoptim --max=85 {} \;

echo "图片压缩完成"

LFS 状态检查脚本

#!/bin/bash
# scripts/check-lfs-status.sh

echo "=== Git LFS 状态检查 ==="
echo "LFS 跟踪的文件类型："
git lfs track

echo -e "\n当前 LFS 文件列表："
git lfs ls-files

echo -e "\n存储使用情况："
git lfs fsck

🚨 故障排除

常见问题

1. 文件未被 LFS 跟踪

   # 检查 .gitattributes 配置
   git check-attr filter path/to/file.png
   
   # 重新跟踪文件
   git rm --cached path/to/file.png
   git add path/to/file.png

2. LFS 配额超限

   # 查看大文件占用
   git lfs ls-files --size
   
   # 清理历史 LFS 文件
   git lfs prune --recent

3. 克隆速度慢

   # 使用浅克隆
   git clone --depth=1 <repo-url>
   
   # 按需下载 LFS 文件
   git lfs pull --include="docs/images/current/*"

📊 监控和报告

定期检查清单

• [ ] LFS 存储使用量是否超过 80%
• [ ] 是否有超过 6 个月未使用的大文件
• [ ] 新增大文件是否符合命名规范
• [ ] 团队成员是否了解 LFS 最佳实践

月度报告模板

## LFS 使用情况月报 (YYYY-MM)

### 存储概况
- 总存储使用: X.X GB / Y GB
- 本月新增: X.X GB
- 清理释放: X.X GB

### 文件分布
- 图片文件: XX个 (X.X GB)
- 压缩包: XX个 (X.X GB) 
- 其他: XX个 (X.X GB)

### 建议行动
- [ ] 清理建议
- [ ] 优化建议
- [ ] 成本控制建议

🔗 相关资源

• Git LFS 安装指南
• 项目文档规范
• GitHub LFS 定价

---

最后更新: 2025年6月