March7th 
OSS Hub 前端实现：文件工作台、上传队列与移动端
OSS Hub 前端实现：文件工作台、上传队列与移动端
对象存储管理后台的难点不是把 API 数据放进表格，而是让用户始终知道：
- 当前正在操作哪个 Bucket。
- 自己对这个 Bucket 是只读还是管理员。
- 页面展示的是远端实时对象，还是数据库搜索结果。
- 上传是否真正写入对象存储并完成登记。
- 删除、对账和标签操作会影响哪一层数据。
OSS Hub 前端使用 Vue 3、Pinia、Vue Router 和 Tailwind CSS，把这些状态集中到一个统一工作台中。
前端目录
frontend/src/├── layouts/ # 桌面端布局├── layouts-mobile/ # 移动端布局├── views/ # 桌面端页面├── views-mobile/ # 移动端页面├── components/ # 通用与桌面端组件├── components-mobile/ # 移动端组件├── composables/ # 文件选择、操作、标签等逻辑├── services/ # API、SSO、上传、路径记忆├── stores/ # 登录、云存储、设置├── router/├── styles/└── types/项目没有只依赖响应式 CSS 把桌面页面压缩到手机宽度，而是为关键移动端流程提供独立页面和布局。
登录态管理
auth store 保存：
- access token。
- token 来源：SSO 或 local。
- 当前用户。
- 权限列表。
- 初始化完成状态。
页面刷新后，前端从本地恢复 token，并请求 /api/me 加载用户。如果接口返回未授权，API 层会清理失效 token 并引导重新登录。
SSO 模式下，前端使用授权码 + PKCE：
- 生成 verifier、challenge 和 state。
- 跳转到 SSO 授权端点。
- 回调页校验 state。
- 使用 code 和 verifier 换取 token。
- 保存 token 并加载当前用户。
内置登录则直接提交用户名和密码到 OSS Hub 后端。
当前云存储上下文
cloudStorage store 是整个前端最关键的全局状态之一。
它负责：
- 加载用户可访问的云存储列表。
- 记住当前
cloudStorageId。 - 当旧选择不再可访问时自动回退到第一项。
- 暴露当前存储是否已配置、是否可管理、使用何种 SDK 协议。
当前存储 ID 会随 API 请求发送给后端。这样文件、搜索、上传、标签和管理页都不需要各自维护一份 Bucket 选择逻辑。
路由与权限守卫
桌面端主要路由包括：
//files/search/upload/tags/management/*/guide/*/settings/*路由元信息表达页面要求：
- 是否必须有可用云存储。
- 是否需要当前云存储管理权限。
- 是否只支持阿里云 OSS。
- 是否需要平台管理员权限。
守卫会先确认登录态，再加载可访问云存储，并根据权限和协议做跳转。隐藏菜单只是体验优化，真正的安全检查仍然在后端。
概览工作台
概览页负责给用户建立上下文：
- 当前用户和登录身份。
- 有效权限数量。
- 当前云存储、供应商和 SDK 协议。
- 当前访问角色。
- 根目录文件夹和文件数量。
- 数据库登记文件数量。
- 最近上传文件。
- 常用功能快捷入口。
它不是复杂报表，而是用户进入系统后判断“我在哪里、能做什么”的起点。
文件浏览器
文件浏览页直接呈现对象存储的层级结构。
路径导航
面包屑根据当前对象前缀生成。目录过深时，中间层级会折叠，避免工具栏被路径挤满。
前端还会按云存储记忆最后访问路径。用户在多个 Bucket 之间切换时，可以回到各自上次浏览的位置。
列表与图标视图
文件可以用列表或图标方式展示：
- 列表适合查看完整文件名、大小、时间和状态。
- 图标适合浏览图片和媒体素材。
- 图标模式支持小、中、大三档尺寸。
- 排序方向可以切换。
已登记与未登记
远端对象如果没有数据库索引，会标记为未登记。它仍然可以被浏览、下载或导入，但不会自动拥有系统标签和完整业务元数据。
文件选择
选择逻辑被抽到 composable 中，支持：
- 单选和多选。
- 当前页全选。
Ctrl/Cmd + A切换全选。Delete快捷删除并二次确认。- 批量标签、Object 标签、下载和删除。
文件上下文操作
桌面端提供右键菜单，移动端提供 Action Sheet。两者承载相同的核心能力：
- 打开预览。
- 添加或删除系统标签。
- 管理 Object 标签。
- 复制访问链接。
- 下载。
- 删除。
- 对异常对象重新检查。
把操作入口放在文件上下文中，比让用户先进入详情页再操作更适合高频管理场景。
文件预览抽屉
预览采用抽屉和全屏两种模式。
图片
- 使用短期签名 URL 加载原图。
- 展示尺寸、EXIF、大小、类型和对象信息。
- 阿里云 OSS 可以配置图片处理参数并复制处理后链接。
视频
- 使用浏览器原生视频控件。
- 对不支持的编码提示下载查看。
文本
- 支持 TXT、JSON、Markdown 和常见配置文件。
- 内容只读，避免把对象存储管理后台变成在线编辑器。
- JSON 使用 CodeMirror 提升可读性。
- 后端限制预览大小，避免一次读取超大文本。
搜索页面
搜索页和文件浏览页看起来相似，但数据来源不同。
搜索页支持：
- 文件名、原文件名和 ObjectKey 关键字。
- 路径前缀。
- 系统标签范围和命名空间。
- 多标签组合。
- 创建时间排序。
- 列表和图标视图。
如果搜索时开启远端检查，结果中会直接标记：
- 远端对象缺失。
- 对象大小或 ETag 变化。
- 需要重新检查的问题。
这让用户在搜索结果中就能看到索引是否可信。
上传页面
上传页不是一个简单的文件选择框，而是一套队列状态机。
每个待上传文件会经历：
waiting -> preparing -> uploading -> completing -> success \-> failed页面展示：
- 原文件名和目标 ObjectKey。
- 文件大小。
- 总进度。
- 当前状态和失败原因。
- ACL、存储类型、Object 标签和是否登记。
- 重试、取消、移除和清理成功项。
小文件上传
小文件请求后端创建直传会话，然后使用 XHR PUT 到预签名 URL。XHR 比 fetch 更方便获得上传进度事件。
大文件上传
大文件切换到 multipart：
- 按设置切分 Blob。
- 限制并行分片数量。
- 合并所有分片进度。
- 读取 ETag。
- 失败分片自动重试。
- 保存恢复状态。
- 最后提交完成请求。
用户可以调整分片大小和并行数，但 UI 会限制到安全范围，避免把浏览器或网络压垮。
标签管理
标签页负责系统标签，不直接混入 Object 标签。
系统标签支持：
- 全局范围和当前云存储范围。
- 命名空间。
- 颜色、名称和描述。
- 创建、编辑、软删除和恢复。
- 是否同时删除文件关联的系统设置。
Object 标签则在文件抽屉或预设管理面板中操作，保持概念边界清晰。
管理中心
管理中心按当前云存储展示多个面板。
团队
存储管理员可以为用户分配：
- 当前云存储只读权限。
- 当前云存储管理权限。
平台管理员还可以在设置中管理用户状态和平台权限。
数据问题
显示同步任务和差异问题，提供：
- 分步执行同步。
- 查看运行进度和统计。
- 重新检查缺失对象。
- 导入未登记对象。
- 清理确认缺失的索引。
- 重试失败文件操作。
生命周期
使用结构化表单管理 Bucket 生命周期规则。阿里云 OSS 还支持更多扩展字段，S3 模式则只显示兼容能力。
CORS 与防盗链
CORS 面板帮助配置浏览器直传所需的方法、请求头和暴露头。阿里云 OSS 防盗链面板只在兼容协议下开放。
文件命名和 Object 标签预设
这些设置更接近日常业务规则，因此放在当前云存储的管理上下文中，而不是平台全局设置。
桌面端与移动端分离
移动端不只是桌面表格的缩窄版本。
项目会在启动时检测设备，选择桌面或移动路由：
- 移动端首页直接进入文件浏览。
- 文件列表使用适合触摸的卡片和底部操作栏。
- 右键菜单替换为 Action Sheet。
- 预览使用移动端全屏交互。
- 上传和搜索使用独立移动页面。
- 不适合手机维护的复杂管理能力会提示切换桌面端。
状态与错误体验
前端为页面统一处理：
- 首次加载。
- 空数据。
- 权限不足。
- 没有可访问云存储。
- 云存储尚未配置。
- API 失败与重试。
- 操作成功 Toast。
- 高风险操作确认框。
这些状态看起来不如主功能显眼，但决定了系统在异常情况下是否仍然可理解。
演示流程
下面是一条可以完整展示项目价值的演示路线。
第一步：登录与切换云存储
使用 SSO 或内置管理员登录，在顶部切换两条不同协议的云存储，展示页面内容随当前 Bucket 更新。
第二步：浏览和新建目录
进入文件页：
- 打开一个多层目录。
- 切换列表和图标模式。
- 调整图标大小。
- 新建一个演示目录。
第三步：上传
准备两个文件：
- 一个小图片，用于演示预签名 PUT。
- 一个超过当前阈值的大文件，用于演示分片上传。
观察上传队列、进度、完成登记和文件列表刷新。
第四步：预览与标签
打开图片预览，展示元数据和复制链接。给文件添加一个系统标签和一个 Object 标签。
第五步：搜索
在搜索页组合文件名和系统标签，找到刚刚上传的文件。
第六步：制造并修复数据偏差
在云控制台或测试脚本中直接删除一个已登记对象，再回到 OSS Hub 运行同步：
- 查看
MISSING_OBJECT问题。 - 执行重新检查。
- 确认后清理数据库索引。
也可以直接在 Bucket 中上传一个对象，再展示未登记对象导入。
第七步：权限差异
切换到只读用户：
- 可以浏览、搜索和下载。
- 不能上传、删除或进入存储管理面板。
- 看不到未授权的云存储。
第八步：移动端
使用手机或浏览器设备模拟器打开文件页，展示触摸操作、底部工具栏、Action Sheet 和全屏预览。
前端实现总结
OSS Hub 前端围绕三个上下文展开：
- 身份上下文：我是谁，有哪些平台权限。
- 云存储上下文：我当前在操作哪个 Bucket，具有什么角色。
- 文件上下文：这是远端对象还是数据库索引，当前操作会影响哪一层。
当这三个上下文保持清晰时，多云、标签、直传、对账和权限才不会变成一组互相冲突的按钮。
部分内容可能已过时
OSS Hub 对象存储管理平台
记录 OSS Hub 从项目定位、多云对象存储适配、浏览器直传、索引对账，到 Vue 管理后台、部署和工程化收尾的完整实现。