跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt

Use this file to discover all available pages before exploring further.

UOSE系统通过 Secret Manager 管理外部资源连接。resource 不直接保存密码、token 或证书，而是保存一个不可变 Secret 版本引用。这样可以把资源配置和敏感凭据分离，并支持凭据轮换。

​
Connection Ref

资源通过 connectionRef 引用 Secret 版本。常见形式如下： 
secret://sap%2Fprod%2Fmain?version=1
引用中包含：
  • Secret key：逻辑密钥名称。
  • Version：不可变版本号。
当 Secret 更新时，系统创建新版本，不覆盖旧版本。resource 只有更新到新 connectionRef 后才会读取新凭据。

​
Secret Payload

不同资源类型需要不同 payload。常见字段包括：
  • baseUrl：源系统服务根地址。
  • authMode：认证方式，例如 current_user_oidc、basic、static_bearer、api_key。
  • username、password、token、apiKey：不同认证模式下的凭据。
  • headers：固定请求头，敏感头会被过滤。
  • queryParams：源系统要求的固定查询参数。
  • tls：私有 CA、SNI 或证书校验配置。
  • timeoutMs：源系统请求超时。
Secret payload 必须只放连接相关内容，不应放业务策略或同步范围。这些应放在 resource capabilities 中。

​
当前用户凭据

部分资源支持 current_user_oidc。这种模式使用当前请求用户的 OIDC token 回源访问外部系统，适合需要继承用户权限的场景。 使用时要注意：
  • REST 调用可复用当前登录用户 token。
  • MCP 场景需要显式转发业务用户 token。
  • 后台队列不能长期依赖短期用户 token。
  • 审计中应记录 actor 与任务上下文，不能把 token 写入日志。
如果资源需要稳定后台同步，优先使用静态 API key、服务账号或源系统授权 token。

​
版本化轮换

推荐轮换流程：
  1. 从现有 Secret 版本载入草稿。
  2. 更新 token、密码或证书。
  3. 保存为新版本。
  4. 在资源设置中把 connectionRef 更新到新版本。
  5. 触发一次同步或连接验证。
  6. 确认新版本可用后，再按组织流程停用旧凭据。
版本化设计让线上资源不会因为编辑草稿而立即受影响。

​
安全边界

UOSE 对密钥管理的原则是：
  • Secret payload 不进入 ontology snapshot。
  • password、token、username 等敏感字段不写入 RDF、实体属性或日志。
  • resource 页面只展示 connectionRef，不展示明文凭据。
  • TLS 放宽配置仅用于临时排障，不建议长期生产使用。
  • 连接信息应按资源和环境拆分，避免多个生产资源共用同一高权限密钥。