# 身份主体与用户

点金提供两种接入模式：App 模式（API Key）与 User 模式（智能工作台），适用于不同场景。

## 两种接入模式 

用一句话理解：**User 是"用我们产品的人"，App 是"调我们接口的系统"。**

## App 模式（API Key 接入）

开发者 / ISV 希望将 AI Agent 的能力集成到**自己的系统**中。

| 维度 | 说明 |
| --- | --- |
| 谁在用 | 开发者编写的程序 |
| 接入方式 | 通过 API Key 调用 OpenAPI |
| 身份管理 | 开发者自行创建和维护「身份主体」（Principal），每次 API 调用时指定 |
| 数据隔离 | 按 Principal 隔离，开发者灵活控制 |
| 前端界面 | 客户自己开发 |
| 典型场景 | 客户的 CRM 系统通过 API 接入 Agent 能力，CRM 中每个用户对应一个 Principal |

> App 模式（API Key） 架构示意图（请访问网页版查看完整插图）

### 身份主体（Principal）

在 App 模式下，开发者需要理解一个核心概念：**Principal（身份主体）**。

| 维度 | 说明 |
| --- | --- |
| 职责划分 | **Agent** 决定"用哪个 AI"，**Principal** 决定"数据归谁" |
| 数据隔离 | 每个 Principal 拥有独立的对话历史、附件、权限 |
| 映射关系 | 开发者需自行维护「自己系统用户 ↔ Principal ID」的映射 |
| 创建方式 | `POST /api/principal/create` → 得到 `principalId` |
| 调用方式 | 每次 API 调用时通过 `X-Principal-Id` Header 传入 |

## User 模式（智能工作台访问）

租户希望让自己的员工 / 客户直接使用我们提供的 AI Agent 产品。

| 维度 | 说明 |
| --- | --- |
| 谁在用 | 真实的人（员工、客户等） |
| 接入方式 | 登录智能工作台页面，或通过 IM 渠道（钉钉、企微、飞书）直接使用 |
| 身份管理 | 平台自动管理，用户无感 |
| 数据隔离 | 天然按用户隔离，每人只能看到自己的对话 |
| 前端界面 | 我们提供 |
| 典型场景 | 企业为内部员工开通 AI 助手账号，员工登录即用 |

> User 模式（智能工作台） 架构示意图（请访问网页版查看完整插图）

## 模式对比

| 对比维度 | App 模式 | User 模式 |
| --- | --- | --- |
| 面向角色 | 开发者 / ISV | 终端用户 |
| 接入方式 | API Key | 账号登录（OIDC） |
| 身份管理 | 开发者自主创建维护 Principal | 平台自动管理 |
| 数据隔离 | 按 Principal 隔离，灵活可控 | 天然按用户隔离 |
| 前端界面 | 客户自己开发 | 平台提供 |

## 选型建议

| 客户需求 | 推荐模式 |
| --- | --- |
| "我想让员工直接用起来，不想开发" | User 模式，开通账号即用 |
| "我想把 AI 能力嵌到自己的产品中" | App 模式，通过 API 集成 |
| "两个都要" | 可以同时使用，互不冲突 |

---

## 获取 API Key

3 步在点金租户控制台创建应用并获取 API Key。

> **前置条件：** 已在[「介绍」](/docs/quickstart/intro.md#%E5%BC%80%E9%80%9A%E6%9C%8D%E5%8A%A1)中完成阿里云百炼与通义点金的开通。

### Step 1: 进入租户控制台

进入点金租户控制台，管理你的应用和用户。

[打开租户控制台 →](https://dianjin.biz.aliyun.com/tenant-admin)

### Step 2: 创建应用

在控制台中创建一个应用（App），点击页面右上角的「创建应用」按钮，填写应用名称后点击「创建」。

### Step 3: 创建 API Key

点击应用卡片进入详情，在「API Keys」区域点击「新建」按钮。创建成功后系统将展示 API Key 明文内容。

> **重要**
> 
> API Key 仅在创建时明文展示一次，请务必复制并妥善保存。关闭窗口后将无法再次查看完整密钥。

---

## 创建用户

User 模式下，租户管理员需要为每位真实用户创建账号，用户使用账号密码登录点金工作台。整个流程在租户控制台「用户管理」页面完成。

> **接入流程：** 进入租户控制台 → 用户管理 → 创建用户 → 安全发送登录凭据 → 用户登录工作台

### Step 1: 进入用户管理

登录租户控制台后，在左侧导航选择「用户管理」，即可看到当前租户下的全部用户账号。

[打开租户控制台 →](https://dianjin.biz.aliyun.com/tenant-admin/users)

### Step 2: 点击「创建用户」

在用户管理页面右上角点击「创建用户」按钮，弹出创建表单。

### Step 3: 填写账号信息

表单包含三项内容：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 用户名 | 是 | 用户登录工作台使用的账号；系统会自动追加 `@<当前租户名>` 后缀，租户内不可重复 |
| 昵称 | 否 | 显示在工作台顶部的友好名称，留空时回退为用户名 |
| 密码 | 是 | 必须同时满足：长度 ≥ 8、含大小写字母、含数字、含特殊字符、不包含用户名 |

> 不想自己想密码？点击密码字段右上角的「自动生成」按钮，系统会随机生成一个满足全部规则的强密码并自动填入「确认密码」。

### Step 4: 复制并发送登录凭据

点击「创建」后系统会弹出登录信息卡片，一次性展示完整的用户名、密码与登录地址。

> **重要**
> 
> 密码仅在创建成功的弹窗中明文展示一次，关闭后无法再次查看完整密钥。请通过 IM 等安全渠道把凭据发送给本人，切勿截图发到公开群组。 若密码遗失，可在用户卡片菜单选择「重置密码」重新设置。

### Step 5: 登录点金工作台

收到凭据的用户访问以下地址，输入用户名（含 @租户名 后缀）与密码即可登录。

| 项 | 值 |
| --- | --- |
| 登录地址 | [https://dianjin.fis.aliyuncs.com/finx/chat](https://dianjin.fis.aliyuncs.com/finx/chat) |
| 账号格式 | `<用户名>@<租户名>`，如 `alice@demo` |
| 首次登录 | 建议提示用户尽快通过工作台的「修改密码」入口更换为自己熟悉的密码 |

> 💡 **提示：** 如需管理用户账号，请前往[用户管理页面](https://dianjin.biz.aliyun.com/tenant-admin/users)（注意：这里的用户并非阿里云账号，由您按实际需求创建）。用户收到凭据后，访问[登录页面](https://dianjin.fis.aliyuncs.com/finx/login)即可进入智能工作台。