云工作空间
📖 适合谁:全员 —— 用桌面客户端（YingClaw）跑任务,需要把本地目录与云端同步、并想集中管理文件与历史的人
📖 阅读时长:8 分钟
📖 一句话:YingCore「端云协作」的云端落点,顶部导航「云工作空间」(路由 /cloud-workspaces) 进入,登录即可看到自己有权访问的空间,所有文件落在对象存储（MinIO）中,工作台里的工作目录就是这里的空间。
它的两套孪生概念:空间(云端目录,本页主体)≠ 文件管理(RAGFlow 原生的知识库文档,与本页无关)。工作台里选的"工作目录"= 本页里的"空间"。
功能全景
看图三句话:客户端直传对象存储（不经过业务服务器）→ 服务端只管元数据（大小/哈希/版本）→ 浏览器能上传下载、也能从回收站救回来。
一、核心价值
- 端云同步零感知:桌面客户端监听本地目录变更,算 SHA-256 → 拿预签名 URL → 直传对象存储,业务服务器不沾字节,带宽成本最低。
- 文件是工作目录的落点:跑完任务的产物自动同步,换台电脑登录同一空间就能接着改,多端接力。
- 误删与覆盖都救得回:回收站保留期内逐项恢复,版本历史记录每次上传的版本,改动可追溯。
- 空间即权限单元:每个空间按"所有者/编辑者/只读"分配角色,权限按空间切,不按文件切。
- 全员可用、零门控:不设管理员门槛,能看到哪些空间由后端按归属与成员关系决定,登录即用。
二、主要能力
空间管理
| 能力 | 说明 | 常用操作 |
|---|---|---|
| 创建空间 | 填名称、描述、容量配额（0 = 不限制）、自动同步开关;创建者自动成为所有者 | 列表页右上「创建」 |
| 删除空间（软删除） | 自定义确认弹窗,后端级联处理:中止后台任务回合 → 删该目录下会话 → 软删空间 → 解绑引用该空间的机器人。需所有者权限 | 卡片右上菜单「删除」 |
| 空间列表 | 居中搜索框（按名称/描述本地过滤） + 4 列响应式卡片栅格;卡片显示角色标签（所有者/编辑者/只读）、最近活动时间、文件数、同步状态 | 居中搜索框按关键字过滤 |
文件能力
| 能力 | 说明 | 常用操作 |
|---|---|---|
| 文件浏览器 | 目录导航、上传、下载、在线预览七类（图片/PDF/文本/JSONL/JSON/视频/音频）;列表含名称、大小、同步状态（目录/已同步/待上传）、世代号 | 双击文件预览/下载 |
| 预签名直传 | 浏览器算 SHA-256 → 建会话 → 直传对象存储 → 服务端复核大小与哈希。字节不过业务服务器 | 工具栏「上传」 |
| 版本历史 | 服务端记录每次上传的版本,支持查看与恢复指定版本（网页上传通常只有 1 个版本,需回滚时找管理员从后台取） | 详情页「版本」标签 |
| 回收站 | 列出已删除对象、显示删除时间与保留提示、支持逐项恢复（保留期内可恢复,过期不可逆） | 详情页「已删除」标签 |
同步与系统目录
| 能力 | 说明 | 常用操作 |
|---|---|---|
| 同步中心 | 自动同步开关（同步策略位）、待上传队列、最近活动、最近变更、错误中心 | 详情页「同步中心」标签 |
| 每日工作记录 | 按日期提交工作日报,幂等（同一天重复提交不会产生多条） | 详情页「工作记录」标签 |
| 系统目录视图 | 会话记录 / Agent 产物 / Agent 产物·记忆 / 冲突文件 / 已删除文件 等虚拟视图 | 详情页左侧目录树 |
三、典型应用场景
- 任务产物集中存放:客户端跑完批量处理任务,产物自动同步到云工作空间。换台电脑也能拿到结果,不用 U 盘拷。
- 多端接力干活:办公室电脑跑了一半,回家用另一台继续——同一空间、同一份文件,接着改。
- 误删抢救:删错文件了?去「已删除文件」面板逐项恢复,在保留期内都救得回来。
- 改动可回溯:文件被覆盖了想找回上一版,走版本历史看指定版本的内容并恢复。
- 工作留痕:每天在「每日工作记录」写一条日报,沉淀"今天在这个目录里做了什么",复盘有据可查。
四、使用指南
1. 入口
| 项 | 说明 |
|---|---|
| 列表页 | /cloud-workspaces |
| 详情页 | /cloud-workspaces/workspace/:workspaceId（点卡片进入） |
| 导航 | 顶部一级导航「云工作空间」,图标为云 |
| 权限 | 不设管理员门控,所有登录用户可见;能看到哪些空间由后端按归属与成员关系决定 |
详情页四个页签:文件浏览器 / 同步中心 / 每日工作记录 / 已删除文件。
2. 创建空间
弹窗字段:名称（必填,最长 200）、描述（多行,最长 2000）、容量配额（数值,0 = 不限制）、自动同步（开关,默认开）→ 「创建」→ 创建者自动成为所有者。
3. 文件操作
上传流程（用户侧无感,出问题时能对上账）:
- 浏览器计算 SHA-256。
- 请求预签名直传地址。
- 浏览器直传对象存储（不经过业务服务器）。
- 通知服务端完成,服务端复核大小与哈希后标记"已同步"。
常见提示（遇到时知道在说什么）:
| 场景 | 文案要点 |
|---|---|
| 直传被拦 | 检查对象存储的 CORS 与反向代理路由 |
| 文件较大 | 仅显示前 512 KB（不是上传失败） |
| 类型不支持 | 下载后查看（不破坏同步） |
| 云端没内容 | 区分"文件是空的"和"内容丢了"两种状态 |
| 同步被暂停 | 提示恢复同步,恢复后写回"已恢复同步" |
4. 删除空间
自定义确认弹窗"确定删除此工作空间?其云端对象将标记删除"→ 后端按顺序级联:中止后台任务回合 → 删该目录下会话 → 软删空间 → 解绑引用该空间的机器人。需所有者权限。
5. 异常处理与回滚
| 问题 | 处理 |
|---|---|
| 直传被浏览器拦截 | 检查对象存储 CORS 与反向代理路由,重试一次 |
| 「已同步」但打不开 | 先怀疑上传没走完（直传被拦或预签名地址拼错）,重新上传一次通常就好 |
| 误删 | 「已删除文件」页签逐项恢复（保留期内） |
| 覆盖想回滚 | 找管理员从后台取版本历史（网页无入口） |
| 同步状态异常 | 「同步中心」看错误中心,待上传队列可重试 |
五、最佳实践
- 云工作空间 ≠ 「文件管理」页：「文件管理」是 RAGFlow 原生的知识库文档管理,跟本页是两套东西,别找错地方。
- 工作台的工作目录 = 云工作空间的空间：工作台里选的"工作目录"就是这里的空间,要接着改上一步的产物,回到同一个空间。
- 容量配额别当成限制来用：当前后端不校验配额,只是展示字段。要做容量治理另想办法（或等后续版本）,不要依赖它来防爆盘。
- 每个空间用一个明确的用途：空间是同步单元,也是权限单元。一个空间混放多个团队/多个项目的文件,权限就没法切。
- 角色按最小权限给：只读角色就够了的人不要给编辑者——编辑者能上传、改名、删文件,删了要靠回收站救。
- 删空间前先确认三件事：① 客户端是否还在同步这个目录;② 里面有没有别的项目在用的文件;③ 空间被机器人绑着当工作目录吗?删空间会级联中止回合、删会话、解绑机器人。
- 回收站不是永久保存：已删除文件在保留期内可恢复。真正重要的东西删之前先下载一份。
- 别指望把云端的文件链接直接发给别人：云工作空间没有分享链接功能。要给别人文件,下载后转发,或把对方加进空间（成员管理请联系管理员,当前页面未提供该界面）。