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

本文说明部署版 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、CrossSiteGrantCfg、CrossSiteGrantMirrorSyncSet 和 AllSiteBaseUrls 都是 Studio 后端服务配置文件的顶层配置项，不是在观测云控制台或工作空间中配置。

通过 Launcher 部署的环境，请按以下步骤修改：

1. 登录 Launcher，进入右上角的修改应用配置页面。
2. 找到 Namespace 为 forethought-core、配置名称为 core 的配置项，并勾选修改配置。应用服务配置项手册中将该名称写作 Core，在 Launcher 当前页面中实际显示为小写 core。
3. 在 core 的 YAML 顶层添加或修改本节配置。frontApiServerUrlPrefixFormat 与 CrossSiteGrantCfg 应保持同级，不要放到 CrossSiteGrantCfg 或其他配置项内部。
4. 保存时勾选修改配置后自动重启相关服务，再确认修改。Studio 在进程启动时读取该配置，未重启的进程不会使用新值。

完整的 Launcher 操作和配置定位方式参见应用服务配置项手册 - Studio 后端服务。

安装程序中的配置映射如下，通常不需要直接操作 Kubernetes：

注意：容器内的 config.yaml 来自 ConfigMap 挂载。直接进入 Pod 修改不会形成可持续配置，Pod 重建后还会丢失。请通过 Launcher 修改 core。如果环境由运维系统直接管理 Kubernetes，则应更新 forethought-core Namespace 下的 core ConfigMap，并滚动重启所有挂载 core/config.yaml 的工作负载，不能只重启 front-backend。实际范围以当前安装程序的 core 关联服务清单为准，通常包括 front-backend、open-api、inner、management-backend、core-worker*、core-worker-beat、ai-api、external-api 和 snapshot-server。

配置层级示例：

# core / config.yaml 顶层
frontApiServerUrlPrefixFormat: "https://studio.example.com"

CrossSiteGrantCfg:
  # 完整配置及默认值见下文
  baseUrl: ""

其中，frontApiServerUrlPrefixFormat 需要填写当前站点 Studio front API 可被对端站点访问的实际地址。若当前环境使用平台下发的站点地址配置，请取对应品牌 urls.guance.com 中的 console_api 值，并注意区分观测云与 TrueWatch 品牌；自定义域名环境则填写实际对外暴露的 front API 根地址。

从旧版本升级时，安装程序会把 frontApiServerUrlPrefixFormat 作为 core 的待更新配置展示，其中的中文提示只是占位说明，必须替换为上述实际地址后再保存，不能原样作为配置值使用。

CrossSiteGrantCfg 的四个访问开关已有默认值；issuer、baseUrl、jwksUri 未自定义时会从 frontApiServerUrlPrefixFormat 派生，通常不需要改成具体地址。

certificateDir 只是证书目录路径，不表示要把证书内容写入 core。默认相对路径实际对应容器内的 /config/cloudcare-forethought-backend/sysconfig/cross_site_certificates，该目录来自 Studio 的共享 ft-sysconfig 存储；证书仍需按下文“跨站点证书”要求初始化。

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、定时任务配置、授权方站点连通性和同步任务日志。