Cloud-Index/docs/guide/quickstart.md

title, createTime, permalink

title	createTime	permalink
快速开始	2025/11/09 00:26:55	/guide/quickstart

快速开始

本指南将帮助你快速上手 Cloud Index。

5 分钟快速开始

第 1 步：启动应用

安装完成后，启动应用：

python app.py

你会看到类似的输出：

 * Serving Flask app 'app'
 * Debug mode: off
 * Running on http://127.0.0.1:5000

第 2 步：打开浏览器

访问 http://localhost:5000，你会看到文件管理界面。

第 3 步：浏览文件

主界面显示存储桶/仓库中的文件和文件夹：

• 📁 文件夹 - 点击打开，浏览子文件夹
• 📄 文件 - 点击查看详情或下载
• 🖼️ 图片 - 点击查看预览和缩略图

基本操作

文件浏览

操作	说明
点击文件夹	打开文件夹，查看内容
点击文件名	查看文件详情
右键菜单	显示更多操作选项

文件信息

每个文件显示以下信息：

• 📝 文件名 - 文件的完整名称
• 📏 大小 - 文件大小（自动格式化为 B/KB/MB/GB）
• 📅 修改时间 - 最后修改时间
• 🏷️ 文件类型 - 文件对应的图标

操作菜单

点击文件右侧的菜单按钮（⋮）或右键点击文件，获得以下选项：

如果是文件：

• 📥 下载 - 下载文件到本地
• 🔗 复制链接 - 复制文件的公开访问链接
• 🗑️ 删除 - 删除文件
• ✏️ 重命名 - 重命名文件

如果是文件夹：

• 📂 新建文件夹 - 在当前文件夹创建子文件夹
• ⬆️ 上传文件 - 上传文件到当前文件夹
• ✏️ 重命名 - 重命名文件夹
• 🗑️ 删除 - 删除整个文件夹（包含子文件）

常见任务

上传文件

使用 UI 上传

1. 点击"上传文件"按钮
2. 选择要上传的文件
3. 点击"确认"
4. 等待上传完成

通过拖拽上传

1. 将文件拖到浏览器窗口
2. 选择目标文件夹
3. 放下鼠标，上传开始

下载文件

单个文件下载

1. 点击文件
2. 点击菜单中的"下载"
3. 文件保存到下载文件夹

复制公开链接

1. 点击文件菜单
2. 选择"复制链接"
3. 粘贴链接分享给他人

创建文件夹

1. 在目标位置点击"新建文件夹"
2. 输入文件夹名称
3. 确认创建

移动/复制文件

1. 右键点击文件/文件夹
2. 选择"剪切"或"复制"
3. 导航到目标文件夹
4. 右键选择"粘贴"

删除文件/文件夹

1. 右键点击文件/文件夹
2. 选择"删除"
3. 确认删除

⚠️ 注意: 删除操作不可撤销，请谨慎操作。

图片预览

Cloud Index 对图片文件提供了特殊支持：

• 🖼️ 缩略图显示 - 列表中显示图片缩略图
• 👁️ 图片预览 - 点击图片查看全尺寸预览
• ⚡ 缓存加速 - 缩略图被缓存以加快加载速度
• 📐 自适应大小 - 根据屏幕尺寸自动调整

深色模式

Cloud Index 支持深色模式，点击右上角的主题按钮 🌙/☀️ 切换：

• 🌙 深色模式 - 适合低光环境，保护眼睛
• ☀️ 浅色模式 - 经典亮色主题

响应式设计

应用在所有设备上都能正常使用：

设备	特性
桌面	完整的侧边栏和功能菜单
平板	自适应布局，触屏友好
手机	简化菜单，优化触屏交互

键盘快捷键

快捷键	功能
Ctrl/Cmd + U	上传文件
Ctrl/Cmd + N	新建文件夹
Delete	删除选中项
Escape	关闭弹窗

性能提示

加快加载速度

1. 使用缓存 - 缩略图被自动缓存
2. 减少文件数 - 大文件夹可能加载较慢
3. 选择快速网络 - 使用稳定的网络连接
4. 启用 CDN - 为存储配置 CDN 加速（如 Cloudflare）

上传大文件

对于超过 100MB 的文件：

1. 使用有线网络而不是 WiFi
2. 避免在高峰期上传
3. 确保足够的磁盘空间
4. 完成后验证文件完整性

设置和配置

环境变量设置

编辑 .env 文件配置：

# 选择存储后端
STORAGE_TYPE=r2  # 或 s3, github

# 存储凭证
ACCESS_KEY_ID=your_key
SECRET_ACCESS_KEY=your_secret

# 缩略图缓存时间
THUMB_TTL_SECONDS=3600

详见 环境变量配置

存储后端切换

修改 STORAGE_TYPE 环境变量即可切换存储后端，无需修改代码：

# 使用 Cloudflare R2
STORAGE_TYPE=r2

# 或使用 Amazon S3
STORAGE_TYPE=s3

# 或使用 GitHub 仓库
STORAGE_TYPE=github

重启应用生效：

# 关闭当前应用 (Ctrl+C)
# 重新启动
python app.py

故障排除

文件显示不完整

• 检查存储配置是否正确
• 验证访问凭证是否有效
• 查看浏览器控制台是否有错误信息

上传失败

• 检查文件大小是否超过限制
• 确保网络连接稳定
• 验证存储空间是否充足

缩略图不显示

• 刷新页面重试
• 检查 static/thumbs/ 文件夹权限
• 确保图片格式受支持（JPG, PNG, GIF, WebP）

下一步

• 📖 配置说明 - 了解高级配置
• 🚀 部署指南 - 在生产环境部署
• 💾 存储后端配置 - 配置不同的存储后端

获取帮助

遇到问题？

• 📖 查看 完整文档
• 🐛 提交 Issue
• 💬 在 讨论区 提问

祝你使用愉快！🎉