文件管理使用指南

管理分享文件、生成直链/代理链、设置密码/到期/访问次数。

1. 能做什么

• 上传与创建分享：通过“上传”页或后台文件管理，生成 slug、直链/代理链、二维码。
• 安全控制：可选密码、到期时间、最大查看次数；支持代理/直链切换。
• 查看与预览：公开/非公开文件查看页、原始下载、Office 在线预览（支持签名直链或代理）。
• 管理操作：列表/搜索、批量删除（含可选删除存储对象）、更新元信息（备注、密码、到期、次数、代理开关）。

2. 创建与上传

1. 进入前台“上传”页或后台“文件管理”。
2. 选择存储配置（默认使用当前默认存储），上传文件。
3. 可选设置：
   • slug：自定义短链接（需唯一，允许字母数字/-/_/.）。
   • 密码：访问需密码，代理链接会自动带上 password 参数便于分享。
   • 到期时间：到期后自动删除。
   • 最大查看次数：用完即删。
   • 是否使用代理：开启后走后端中转/签名，隐藏源站直链。
4. 提交后获得：预览链接、下载链接、代理链接、二维码。

3. 访问方式

• 公开/非公开查看页：/file/{slug}（公开）或受权限控制的后台视图。
• 原始下载/预览：/api/file-download/{slug}、/api/file-view/{slug}；有密码需在查询参数带上 password。
• Office 预览：/api/office-preview/{slug}，会生成一次性（或签名）直链/代理。
• 代理 vs 直链：开启代理时走后端域名；关闭则使用存储预签名直链。

4. 管理操作

• 搜索/筛选：按创建者（管理员）、关键字。
• 批量删除：可选删除记录或记录+存储对象；失败项逐条返回。
• 更新元信息：备注、密码、到期、最大查看次数、是否公开、是否使用代理。
• 查看明文密码：管理员在后台可查看已设置的文件密码（用于复核分享）。
• 缓存刷新：删除/更新后缓存会自动失效；如列表异常可在后台“缓存清理”手动刷新。

5. 权限与范围

• 管理员：全量管理，能删除记录及存储对象，不受公开/非公开限制。
• API Key：需要文件权限位（FILE_SHARE/FILE_MANAGE），只能管理自己创建的文件；访问受 basic_path 与权限控制。
• 公开/非公开：非公开文件对未授权访问者返回“未找到/无权限”。

6. 常见场景

• 一次性下载：设置最大查看次数=1 或短期到期 + 代理签名。
• 隐藏源站：开启代理 + 签名时间，分享后台域名链接而非存储直链。
• 公开素材库：关闭代理、无密码，方便直链引用；配合 basic_path 限制到 /public。
• 安全回收：定期使用“批量删除”或“清理过期”保持库干净。

7. 故障排查

• 链接报 403/404：检查是否非公开、密码是否正确、或已过期/次数用尽。
• 直链失效：签名过期，重新生成；或切换代理模式。
• 看不到文件：确认 API Key 的 basic_path 覆盖路径，权限位完整。
• 删除未生效：若选择“仅删除记录”，存储对象仍在；需选择同时删除对象。

---