管理控制台与桌面客户端
两类客户端的职责
Cloud Blox 提供管理控制台和桌面客户端，两者面向不同场景：
- 管理控制台偏向配置、管理、运维和批量文件操作；
- 桌面客户端偏向日常文件浏览、持续传输、同步、冲突处理和离线使用。
两类客户端共享服务端对象、存储桶和权限语义，但认证方式、传输方式和本地持久化策略不同。
flowchart LR
Web[管理控制台] --> AdminAPI[管理 API]
DesktopUI[桌面界面] --> Native[桌面原生核心]
Native --> ClientAPI[客户端协议 API]
AdminAPI --> Platform[Cloud Blox]
ClientAPI --> Platform
Native --> LocalDB[(本地数据库)]
Native --> LocalFS[本地文件系统]
管理控制台
页面领域
管理控制台主要覆盖：
- 登录、注册、找回密码和个人中心；
- 存储桶、文件、媒体处理和 S3 密钥；
- 用户、角色、菜单、部门和字典；
- 存储通道、副本通道、CDN 通道、区域和套餐；
- 队列、任务、计划任务、缓存、备份、清理和系统监控；
- 日志、通知、公告、消息和内容审核；
- 计费、余额、资源包和支付。
动态权限
登录后，控制台根据服务端返回的菜单和权限生成可访问页面。路由、按钮权限和发行版能力共同决定用户能看到和执行的操作。
上传体验
管理控制台提供：
- 文件哈希与秒传检查；
- TUS 断点续传；
- 并行分片；
- 暂停、恢复、取消和重试；
- 上传速度、进度和预计剩余时间；
- 上传完成后的后台通道同步。
浏览器上传任务主要属于当前浏览器会话。长时间上传期间不应随意重启应用或切换节点，除非部署已提供上传会话持久化与请求粘性。
会话模型
控制台使用 Bearer Token 调用管理 API。Token 保存在浏览器持久存储中，因此生产环境必须同时保证：
- 全站 HTTPS；
- 严格的内容安全策略；
- 第三方脚本最小化；
- 管理员浏览器不安装不受信任扩展；
- Access Token 有限有效期和可撤销能力。
桌面客户端
主要功能
桌面客户端面向 macOS 和 Windows，提供：
- 全部文件、最近使用和收藏；
- 手动上传与下载；
- 传输中心；
- 单向和双向同步空间；
- 冲突中心；
- 回收站；
- 设备管理；
- 并发、带宽、开机启动、托盘和主题设置。
当前交付重点是桌面平台。移动端共享部分界面和协议基础，但任意目录持续监听只适用于桌面；移动设备将下载保存在应用沙箱，并通过原生后台传输完成任务，不提供独立的离线文件库。
本地状态
桌面客户端使用本地数据库保存：
- 账号和设备标识；
- 同步空间；
- 服务端增量游标；
- 本地与远端文件快照；
- 上传和下载任务；
- 已完成分片；
- 幂等操作标识；
- 冲突及其处理状态；
- 客户端设置。
界面展示的是本地状态和服务端信息的派生快照，不直接承担文件传输或持久化职责。
文件传输
文件内容由桌面原生核心直接在本地文件系统与服务端之间流式传输：
- 上传先计算内容哈希，再创建或恢复持久分片会话；
- 已完成分片可以复用；
- 同一路径的重复手动上传串行执行；
- 下载使用临时分片文件和 HTTP Range 续传；
- 下载完成后原子替换目标文件；
- 暂停和失败保留临时数据；
- 应用重启后，未完成任务重新进入可调度状态；
- 连续失败达到阈值时自动暂停，等待用户确认恢复。
同步空间
每个同步空间绑定：
- 一个本地目录；
- 一个存储桶；
- 一个远端前缀；
- 上传优先、下载优先或双向模式；
- 默认忽略规则和自定义忽略规则。
同步流程结合文件系统事件和周期对账。首次同步建立基线，后续使用服务端修订游标拉取增量变化。
冲突策略
以下情况会形成冲突：
- 本地和远端在同一基线后都发生变化；
- 写操作携带的基础修订号落后于当前远端；
- 同路径存在无法自动判定的内容差异。
冲突中心支持：
- 保留两份；
- 保留本地；
- 保留远端。
远端写入本地时，客户端会短暂抑制文件系统回声，避免形成“下载后又立即上传”的循环。
认证与设备
桌面客户端使用独立设备会话：
- Access Token 只保存在原生进程内存；
- Refresh Token 定期轮换；
- 服务端只保存 Refresh Token 哈希；
- 用户可以查看和撤销设备；
- 后台传输使用绑定方向和资源范围的短时票据；
- 设备同步前缀限制客户端可访问的对象范围。
桌面系统上的 Refresh Token 使用受限权限的应用数据存储。关键生产环境仍应评估平台凭据库、磁盘加密和终端设备管理要求。
管理控制台与桌面客户端的差异
管理控制台更适合
- 平台和权限配置；
- 存储桶设置；
- 运维监控；
- 批量管理；
- 无需安装客户端的临时访问。
桌面客户端更适合
- 长时间传输；
- 断点续传；
- 大量本地文件；
- 持续同步；
- 离线访问；
- 冲突处理和设备管理。
客户端架构后续重点
- 为浏览器上传会话增加跨重启和跨节点恢复；
- 为管理控制台补充关键流程端到端自动化测试；
- 为桌面客户端建立签名、自动更新和回滚发布链；
- 生产环境默认要求非本机地址使用 HTTPS；
- 评估桌面 Refresh Token 使用平台安全凭据库；
- 对大目录、十万级传输记录和高频文件事件进行容量验证；
- 发布客户端协议兼容矩阵，明确服务端与客户端版本范围。