Portal能力对接

基于SSO的资源白名单、权限等级与余额能力对接规范

1. 依赖前提

Portal 能力接入依赖 SSO 已完成：

  • 用户必须先通过 SSO 登录，系统拿到 sso_id
  • 系统登录态中需包含 tenantId（可为字符串或 null，具体语义按业务约定）

若 SSO 未接通，Portal 能力无法稳定生效。

2. 能力范围

Portal 接口承载以下业务能力：

  • 资源范围控制：限制用户可见资源（应用/模型等）
  • 权限等级控制：按等级开放能力
  • 余额控制：任务执行前余额校验

3. 开关与策略

3.1 开关配置

变量名必填示例说明
CONFIG_PORTAL_BASE_URL否http://localhost:5001非空启用 Portal；空值关闭 Portal

3.1.1 配置位置

Docker 部署场景下，请在 docker-compose.yml 的 easyai-server 服务 environment 中配置 CONFIG_PORTAL_BASE_URL。

示例（docker-compose）：

services:
  easyai-server:
    environment:
      - CONFIG_PORTAL_BASE_URL=http://portal.example.com

示例：

CONFIG_PORTAL_BASE_URL=http://localhost:5001

3.2 路径语义

  • Portal 关闭：走本地逻辑
  • Portal 开启且用户上下文满足：走 Portal 能力接口
  • Portal 路径失败：fail-closed（不静默回退本地）

4. 时序图

5. 第三方 Portal 接口契约

公共约束：

  • Base URL：CONFIG_PORTAL_BASE_URL
  • platform: 固定 easyai
  • userId: 使用 sso_id
  • tenantId: 作为租户维度

5.1 资源范围接口

  • Method: GET
  • Path: /auth/{platform}/{tenantId}/{userId}/permissions
  • 作用：返回资源白名单，决定用户可访问资源集合

标准响应（app 为应用 ID、agent 为智能体 ID，均为 24 位十六进制 ObjectId 字符串；列表可为空但字段建议始终返回）：

{
  "app": [
    "68edacbf81729885c031b354",
    "68ec576ee9d23941bd51f73e",
    "68ef7173f6c1924d73b07e61"
  ],
  "agent": [
    "68ea036a98106dafab0d5d2d",
    "68ea0fbb20188c9b151c1e8b"
  ]
}

响应字段说明：

字段类型含义
appstring可访问应用（应用 ID）白名单
agentstring可访问智能体（智能体 ID）白名单

约束：

  • key 名称需与系统资源类型字典一致（当前为 app、agent）
  • value 必须是 ID 列表（字符串数组，一般为 MongoDB ObjectId 形式）

5.2 权限等级接口

  • Method: GET
  • Path: /auth/{tenantId}/{userId}/level
  • 作用：返回用户权限等级；用于控制用户可使用的模型等级（例如仅低等级模型、或开放更高算力/更高阶模型），并驱动与等级相关的其他能力过滤

标准响应：

3

响应说明：

返回值类型含义
3（示例）number用户权限等级；数值越大，通常允许访问的模型等级（模型档位）越高，与系统内「等级 → 可访问模型范围」的映射表一致

约束：

  • 必须返回 number，不能返回字符串
  • 等级范围（例如 0~N）及每个等级与可访问模型集的对应关系需双方明确

5.3 余额接口

  • Method: GET
  • Path: /billing/{tenantId}/{userId}/balance
  • 作用：任务执行前余额校验

标准响应：

{
  "balance": 123.45
}

响应字段说明：

字段类型含义
balancenumber当前可用余额

约束：

  • balance 必须为数值类型
  • 计费单位 算力 需与 Easyai 扣费体系一致

6. Portal 对接表单（推荐）

配置项示例说明
platformeasyai固定平台标识
tenantId 规则tenant_a / null租户字段语义
userId 映射sso_id与 SSO id 对齐
resourceType 字典app（应用）、agent（智能体）与权限响应 key 对齐
level 取值规则0~N能力分级标准
balance 单位point / RMB统一计费单位

7. 完成标准

  • Portal 开启后，权限/资源/余额三类能力按接口返回生效
  • Portal 关闭后，不发起 Portal HTTP 调用
  • Portal 路径故障时，系统按 fail-closed 返回明确失败，不静默降级
SSO单点登录对接
第三方系统通过SSO接入Easyai Server的登录流程与契约
任务回调消息契约
draw.progress消息结构、消费约束与回调闭环说明