挂载管理使用指南

挂载点相当于虚拟目录才可以映射对应存储路径。按下面三步走即可。

1. 挂载是什么？

挂载点 = 一个存储入口：把某个存储配置（S3/R2/OSS/B2 等）映射到 CloudPaste 的路径树。例如把 R2 的桶 my-bucket 映射成 /r2。
谁能看到？ 取决于权限和 basic_path：管理员全量可见，API Key 用户只在自己 basic_path 内可浏览。
能做什么？ 浏览、上传、重命名、删除、复制、生成直链/代理链，以及 WebDAV 读写。

Tips：挂载点不复制数据，只是“把存储挂到文件系统路径上”。

2. 准备工作

先配置存储：确保在“存储配置”里已添加对应 S3 兼容/其余存储配置并能测试通过。
确认权限：给 API Key 分配挂载权限（MOUNT_* 位）和 basic_path，避免越权。
想好挂载路径：为挂载点起一个在文件系统里出现的目录名，例如 /public、/team-share。

3. 三步快速上手

步骤 1：创建挂载点

进入后台 → 挂载管理 → 新建挂载。
选择存储配置，填写挂载路径（如 /r2），必要时备注（方便区分环境），保存。

步骤 2：可选开关

代理模式：开启后文件访问走后端签名/中转，适合隐藏源站直链（由服务器中转）。
签名时间：配合代理生成临时链接，0 表示永久（不过期的链接）。
默认直链/代理：为该挂载下文件生成的链接指定默认策略。
缓存 TTL：目录列表缓存时间，访问频繁但文件不常变时可提高性能。
启用/停用：is_active 关闭后，挂载对所有用户不可见；可随时再开启。
排序：sort_order 数字越小越靠前，便于把常用挂载置顶。
WebDAV 策略：默认 302_redirect（推荐），如无特殊需求保持默认。

步骤 3：验证

前台“挂载浏览器”访问 /r2 路径，能列出文件即 OK。
如为 API Key，确认 basic_path 覆盖了该挂载路径，否则看不到。
若是图片/多媒体目录，可在挂载浏览器右上角切换到瀑布流模式（槽点位于视图切换按钮），更适合大量不同尺寸图片的预览。

4. 字段释义速查

挂载路径：展示在文件系统中的目录名（必须以 / 开头）。
存储配置：引用哪一条 S3/R2/OSS 配置。
默认使用代理：生成链接时优先走后端代理。
签名过期时间：代理直链的有效期（秒），0 为不过期。
缓存 TTL：目录缓存时间（秒），用于控制列表刷新频率。
WebDAV 策略：WebDAV 访问的行为（如 302 重定向）；保持默认即可。
启用状态：挂载是否对外可见；禁用不会删除数据。
排序：控制在列表中的位置，便于分组导航。

5. 常见场景

公开下载区：挂载 /public，关闭代理，直链访问；配合 basic_path= /public 给访客型 API Key。或者/public/r2,/public/b2这种多存储集合在一个路径下访问
内部资料区：挂载 /internal，开启代理 + 签名 3600 秒，避免直链泄露。
分部门隔离：多个挂载 /ops、/rd，给不同 API Key 不同 basic_path，互相不可见。
暂时下线维护：将挂载停用（is_active=false），维护完再开启，避免暴露半成品数据。

6. 故障排查

看不到挂载：检查 API Key 的 basic_path 与挂载路径是否匹配。
生成链接报错：确认存储配置可用、代理开关与签名时间是否合理。
403/无权限：确认挂载权限位（MOUNT_VIEW/UPLOAD/DELETE 等）已勾选。
列表数据老旧：等待缓存 TTL 过期，或在后台缓存清理里手动刷新（管理员）。

总结：先有“存储配置”，再建“挂载点”，最后用权限和代理/签名把可见范围与访问方式定好。