工作空间远程共享

将工作空间通过 StorageProvider SDK 共享到 ElevoWorkspace，供其他实例挂载访问

工作空间远程共享

⚠️ 实验性特性：该功能目前处于实验阶段，默认关闭。

功能概述

ElevoWorkspace 共享功能允许您将工作空间通过 StorageProvider SDK 共享到远程 ElevoWorkspace 服务。共享后，其他 ElevoWorkspace 实例可通过 Share ID 挂载访问该工作空间的文件，实现跨团队协作。

核心架构：一个组织维护一个 StorageProvider 连接（SDK 限制），通过 Share 的 sourcePath 区分同一组织下的不同工作空间。

开启功能

该功能默认关闭，需要平台管理员先在管理后台配置：

  1. 进入 管理后台 → 系统配置 → ElevoWorkspace 共享
  2. 打开 启用共享功能（elevoWorkspace.enabled）开关
  3. 配置以下必要信息：
配置项环境变量说明
启用功能ELEVO_WORKSPACE_ENABLED全局开关，类型 boolean，默认 false
gRPC 地址ELEVO_WORKSPACE_SERVER_URLElevoWorkspace gRPC 服务地址（如 172.30.0.188:9090）
HTTP API 地址ELEVO_WORKSPACE_HTTP_URLElevoWorkspace HTTP API 地址（如 http://172.30.0.188:8082）
租户 IDELEVO_WORKSPACE_TENANT_ID预配置的 ElevoWorkspace 租户 UUID
租户 TokenELEVO_WORKSPACE_TENANT_TOKEN租户的 API Token（sk_xxx 格式）

💡 管理后台修改的值优先于环境变量。环境变量可用于设置初始默认值。

SDK 依赖

本功能依赖 @openelevo/workspace-sdk（TypeScript SDK），通过 gRPC 与 ElevoWorkspace Server 通信。

  • npm 包：@openelevo/workspace-sdk@^0.2.1
  • 本地开发：使用 file: 协议指向 ElevoWorkspace 仓库中的 sdk-typescript/ 目录，以获得最新修复（如 StorageProvider 空闲超时死连接检测）
  • 关键机制：StorageProvider 内置 5 分钟空闲超时检测，当服务端崩溃但未关闭 gRPC 流时自动触发重连

前提条件

  • 平台管理员已在系统配置中开启功能并配置好 ElevoWorkspace 连接信息
  • 网络连通：确保本实例能够访问 ElevoWorkspace 服务的 gRPC（默认 9090）和 HTTP API（默认 8082）
  • 您拥有目标工作空间的管理员权限

只有空间管理员有权限开启或关闭共享，普通成员只能查看状态，无法操作开关。

操作步骤

开启共享

  1. 进入目标工作空间，点击左下角 更多设置 打开空间设置弹框
  2. 在基本信息 Tab 中找到远程共享区域（仅在功能开关开启时显示）
  3. 打开共享开关，系统自动执行：
    • 创建/复用组织的 StorageProvider 连接
    • 启动后台 share() 监听
    • 等待 Provider 连接建立（最长 10 秒）
    • 调用 ElevoWorkspace HTTP API 创建 Share 资源
    • 更新数据库状态并写入审计日志
  4. 状态显示为已连接（绿色）即表示共享成功

远程空间共享

关闭共享

  1. 进入目标工作空间，点击左下角 更多设置 打开空间设置弹框
  2. 在基本信息 Tab 中找到远程共享区域
  3. 关闭共享开关
  4. 在确认对话框中点击确认关闭
  5. 系统自动执行：
    • 调用 ElevoWorkspace HTTP API 删除 Share 资源（404 视为已删除）
    • 清空数据库共享状态
    • 检查该组织是否还有其他活跃共享，无则停止 StorageProvider
    • 写入审计日志

⚠️ 注意：关闭共享后，其他 ElevoWorkspace 实例将无法继续访问此工作空间。工作空间本地数据不受影响。

状态说明

前端以 5 秒间隔轮询共享状态（仅在共享开启时），支持以下状态：

状态颜色说明
已连接🟢 绿色StorageProvider 正常运行，远程可访问
重连中🟡 黄色连接中断，SDK 正在自动重新连接
已断开🔴 红色连接失败，请检查网络或联系平台管理员

工作空间列表标识

已开启共享的工作空间在列表页卡片中显示 已共享 标识（绿色 Share2 图标 + 文字），仅空间管理员可见。

审计日志

以下操作会记录到审计日志：

操作审计动作记录内容
开启共享ELEVO_SHARE_START操作人、Share ID、Tenant ID
关闭共享ELEVO_SHARE_STOP操作人、原 Share ID

技术架构

租户模型

  • 使用平台管理员预配置的单一 ElevoWorkspace 租户
  • 租户 ID 和 API Token 通过系统配置（elevoWorkspace.tenantId / elevoWorkspace.tenantToken）管理
  • 一个组织维护一个 StorageProvider 连接，组织内所有工作空间共享该连接

Share 生命周期

  • Share 的 sourcePath 设为工作空间 slug，用于区分同一组织下的不同工作空间
  • Share 的 name 使用工作空间 slug，方便在 ElevoWorkspace 管理后台识别
  • 支持幂等操作：重复开启共享直接返回现有状态（HTTP 200），不会重复创建

并发控制

  • 组织级锁（Promise 链式排队）：确保同一组织只有一个 StorageProvider 被创建
  • 工作空间级锁（Promise 链式排队）：防止同一工作空间的并发开启/关闭操作
  • 使用 Promise 链模式实现，无需外部依赖

故障恢复

  • 服务启动时（onModuleInit）自动查询所有 elevoShareEnabled=true 的工作空间
  • 按组织分组，每个组织恢复一个 StorageProvider 连接
  • 指数退避重试机制（1s → 2s → 4s → 8s → 16s，最多 5 次）
  • 全部重试失败后，自动清除该组织下所有工作空间的共享状态
  • 恢复成功后验证远端 Share 是否仍然存在，不存在则清除 DB 记录

删除清理

  • 工作空间删除：优先清理 ElevoWorkspace 共享（删除远端 Share + 清空 DB），失败不阻塞删除流程
  • 组织删除：批量停止该组织下所有已共享工作空间，失败不阻塞删除流程

版本历史

  • v0.1（2026-03）：初始实现，支持基本共享开关、状态轮询、审计日志
  • v0.2（2026-05）：SDK 依赖更新（死连接检测）、恢复远端验证、409 冲突恢复

常见问题

Q: 为什么我看不到共享开关？

  1. 确认平台管理员已在 管理后台 → 系统配置 → ElevoWorkspace 共享 中开启了功能开关
  2. 功能关闭时，空间设置中不会显示共享选项
  3. 确认 ELEVO_WORKSPACE_ENABLED=true 已生效

Q: 为什么共享状态显示"已断开"？

可能原因：

  1. ElevoWorkspace 服务不可达（检查 gRPC 和 HTTP API 连通性）
  2. 网络连接中断
  3. 租户 Token 过期或无效
  4. StorageProvider 空闲超时（5 分钟无心跳）

解决方案：先尝试关闭共享后重新开启。如仍失败，联系平台管理员检查配置。

Q: 关闭共享后数据会丢失吗？

不会。关闭共享只是断开远程访问连接（删除 ElevoWorkspace 上的 Share 资源），工作空间本地数据完整保留在文件系统中。

Q: 非管理员可以看到共享状态吗？

不可以。共享功能仅对空间管理员可见和可操作，普通成员的设置页面不会显示共享区域。

Q: 工作空间/组织被删除时，共享会自动清理吗？

会。系统内置删除钩子：

  • 删除工作空间时自动停止该工作空间的共享
  • 删除组织时自动停止该组织下所有工作空间的共享
  • 清理失败会记录错误日志，但不阻塞删除流程