部署版跨站点授权使用说明¶

本文说明部署版 Studio 如何使用新版本跨站点授权能力。该能力用于两个站点之间建立工作空间数据授权关系，由授权方生成授权 meta，被授权方导入后主动完成认证与后续同步。

使用前提¶

• 部署版服务必须先升级到至少 2026-06-03 发布版本，才支持本文所述的新版本站点间授权方式。
• 授权方和被授权方都需要完成 CrossSiteGrantCfg 站点身份配置与跨站点证书初始化。
• 授权方生成授权包前，需要确认当前服务可被其他站点通过 frontApiServerUrlPrefixFormat 或 CrossSiteGrantCfg.baseUrl 访问。
• 被授权方导入授权包后，会主动访问授权方站点完成认证和同步；授权方不会主动访问被授权方。
• 免费版工作空间不支持该能力。

使用流程¶

1. 授权方生成授权 meta¶

在授权方工作空间调用 生成跨站点授权 meta 接口，传入被授权方工作空间 UUID、授权数据类型、索引和过滤条件。

接口会创建一条授权方 pending 记录并返回完整 meta。调用方需要把完整 meta 交给被授权方导入。该步骤不会主动访问被授权方站点。

2. 被授权方导入授权 meta¶

在被授权方工作空间调用 导入跨站点授权 meta 接口，传入授权方生成的完整 meta。

导入时，后端会完成目标工作空间校验、meta 签名校验、站点关系校验，并主动访问授权方站点完成认证。认证成功后，被授权方本地会创建 mirror 授权记录。

3. 后续管理¶

授权记录创建后，后续业务管理仍沿用跨空间授权接口：

• 通过 /wksp_share/list 查看授权记录。
• 通过 /wksp_share/<uuid>/modify 修改授权范围。
• 通过 /wksp_share/delete 删除或撤销授权。

授权方是授权事实源。被授权方 mirror 记录用于本地展示、工作空间选择器、授权校验和 DQL 查询，状态会通过同步任务逐步收敛。

部署版配置¶

frontApiServerUrlPrefixFormat¶

frontApiServerUrlPrefixFormat 是当前 Studio front API 的外部可访问根地址，例如：

frontApiServerUrlPrefixFormat: "https://studio.example.com"

当 CrossSiteGrantCfg.baseUrl、issuer 或 jwksUri 没有自定义覆盖时，系统会基于该地址派生跨站点授权站点身份。

CrossSiteGrantCfg¶

CrossSiteGrantCfg 控制跨站点协议能力、站点身份和证书加载。

CrossSiteGrantCfg:
  sameOrgAccessEnable: true
  sameOrgBeAccessedEnable: true
  externalOrgAccessEnable: true
  externalOrgBeAccessedEnable: true
  tempAuthCodeTTL: 1800
  issuer: "{}"
  baseUrl: ""
  jwksUri: "{}/api/v1/workspace_data/.well-known/cross-site-jwks.json"
  certificateDir: sysconfig/cross_site_certificates

配置项说明：

站点内跨空间授权不受上述跨站点访问开关影响。

跨站点证书¶

certificateDir 默认是 sysconfig/cross_site_certificates，目录结构如下：

sysconfig/cross_site_certificates/
  current_kid
  private/<kid>.pem
  public/<kid>.pem

证书文件用于 JWS 签名和 JWKS 公钥发现：

• current_kid 指向当前 active key。
• private/<kid>.pem 是当前站点签名私钥。
• public/<kid>.pem 是当前站点验签公钥。
• active 私钥、历史公钥和 current_kid 禁止进入版本控制。

服务升级后需要通过后台升级脚本初始化首套证书；如果需要滚动 key，应保留历史 public key，确保旧签名仍可被验证。

CrossSiteGrantMirrorSyncSet¶

被授权方 mirror 授权记录通过定时任务主动同步授权方最新状态。

CrossSiteGrantMirrorSyncSet:
  isOpen: true
  staleSeconds: 3600
  batchSize: 200
  lockExpireSeconds: 1800
  crontabSet:
    minute: "*/10"

该配置只影响 mirror 同步，不影响授权方事实记录。

同组织站点配置¶

同组织跨站点授权依赖 AllSiteBaseUrls.<brandKey> 解析官方站点 front API 地址。对方站点必须存在于官方站点集合中，并且 meta 中的 baseUrl / jwksUri 需要与官方地址匹配。

不同组织或外部部署版站点不应依赖 AllSiteBaseUrls 推导地址，而应使用 meta 和 mirror 记录中的 baseUrl、issuer、jwksUri 和公钥身份完成校验。

常见问题¶

提示当前站点身份配置不完整¶

检查：

• frontApiServerUrlPrefixFormat 是否配置为外部可访问地址。
• CrossSiteGrantCfg.baseUrl、issuer、jwksUri 是否为空或格式错误。
• certificateDir 下是否存在 current_kid、private/<kid>.pem、public/<kid>.pem。
• 运行进程是否有权限读取证书目录和 key 文件。

导入授权包失败¶

检查：

• 被授权方工作空间是否与 meta 中 targetWorkspaceUUID 一致。
• 授权包是否过期。
• 授权方站点是否可从被授权方访问。
• 双方是否已升级到至少 2026-06-03 发布版本。
• 同组织站点是否已正确配置 AllSiteBaseUrls。
• 不同组织跨站点开关是否允许当前方向访问。

mirror 记录没有及时更新¶

mirror 记录由被授权方主动同步。可检查 CrossSiteGrantMirrorSyncSet.isOpen、定时任务配置、授权方站点连通性和同步任务日志。