taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
c6bab43f12d2e446b6b1c594742bb77b5b87217c
taiji-AI-PAD/Docs/渠道租户资源分配查看接口文档 copy.md
T

749 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 渠道租户资源分配查看接口文档
> **版本**: v1.0.0
> **更新时间**: 2026-01-13
> **说明**: 管理员查看渠道下租户被分配的自定义Agent、平台Agent、模型等资源
---
## 目录
1. [接口概述](#接口概述)
2. [接口1: 超级管理员查看渠道租户资源分配](#接口1-超级管理员查看渠道租户资源分配)
3. [接口2: 渠道管理员查看租户资源分配汇总](#接口2-渠道管理员查看租户资源分配汇总)
4. [数据结构说明](#数据结构说明)
---
## 接口概述
| 接口 | 路径 | 方法 | 权限 | 说明 |
|------|------|------|------|------|
| 接口1 | `/api/admin/channels/{channel_id}/tenants/resources` | GET | super_admin, billing_admin, operations_admin, channel_admin | 超级管理员查看指定渠道的租户资源分配 |
| 接口2 | `/api/channel/tenants/resources/summary` | GET | channel_admin, billing_admin, operations_admin, super_admin | 渠道管理员查看自己渠道的租户资源分配汇总 |
### 权限说明
- **super_admin**: 可查看所有渠道的租户资源分配
- **billing_admin / operations_admin**: 只能查看所属渠道的租户资源分配
- **channel_admin**: 只能查看所属渠道的租户资源分配
---
## 接口1: 超级管理员查看渠道租户资源分配
### 基本信息
| 属性 | 值 |
|------|-----|
| **接口路径** | `GET /api/admin/channels/{channel_id}/tenants/resources` |
| **后端文件** | `services/mcp-server/app/routes/admin.py` |
| **权限要求** | super_admin, billing_admin, operations_admin, channel_admin |
### 请求参数
#### 路径参数 (Path Parameters)
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| channel_id | string (UUID) | 是 | 渠道ID | `6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6` |
#### 请求头 (Headers)
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| Authorization | string | 是 | Bearer Token | `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
### 请求示例
```bash
curl -X GET "http://localhost:8002/api/admin/channels/6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6/tenants/resources" \
-H "Authorization: Bearer $TOKEN"
```
### 响应参数
#### 成功响应 (200 OK)
```json
{
"success": true,
"data": {
"channelId": "string",
"channelName": "string",
"tenants": [
{
"tenantId": "string",
"tenantName": "string",
"tenantEmail": "string",
"status": "string",
"createdAt": "string (ISO 8601)",
"customAgentQuota": {
"cpuQuota": "number",
"memoryQuota": "number",
"cpuUsed": "number",
"memoryUsed": "number",
"agentCount": "integer"
} | null,
"platformAgents": [
{
"templateName": "string",
"podQuota": "integer",
"podUsed": "integer",
"cpuPerPod": "string",
"memoryPerPod": "string"
}
],
"models": [
{
"modelName": "string",
"rpmLimit": "integer",
"tpmLimit": "integer",
"maxBudget": "number | null",
"budgetDuration": "string"
}
]
}
],
"summary": {
"totalTenants": "integer",
"tenantsWithCustomAgents": "integer",
"tenantsWithPlatformAgents": "integer",
"tenantsWithModels": "integer",
"totalCustomAgentCpuQuota": "number",
"totalCustomAgentMemoryQuota": "number",
"totalCustomAgentCpuUsed": "number",
"totalCustomAgentMemoryUsed": "number",
"totalPlatformAgentPodQuota": "integer",
"totalPlatformAgentPodUsed": "integer"
}
},
"message": "获取渠道租户资源分配成功"
}
```
#### 响应字段说明
| 字段路径 | 类型 | 说明 |
|----------|------|------|
| `data.channelId` | string | 渠道ID |
| `data.channelName` | string | 渠道名称 |
| `data.tenants` | array | 租户资源列表 |
| `data.tenants[].tenantId` | string | 租户ID |
| `data.tenants[].tenantName` | string | 租户名称 |
| `data.tenants[].tenantEmail` | string | 租户邮箱 |
| `data.tenants[].status` | string | 租户状态 (active/suspended) |
| `data.tenants[].createdAt` | string | 创建时间 (ISO 8601格式) |
| `data.tenants[].customAgentQuota` | object/null | 自定义Agent配额，无配额时为null |
| `data.tenants[].customAgentQuota.cpuQuota` | number | CPU配额上限（核心数） |
| `data.tenants[].customAgentQuota.memoryQuota` | number | 内存配额上限（GB） |
| `data.tenants[].customAgentQuota.cpuUsed` | number | 已使用CPU（核心数） |
| `data.tenants[].customAgentQuota.memoryUsed` | number | 已使用内存（GB） |
| `data.tenants[].customAgentQuota.agentCount` | integer | 已创建的自定义Agent数量 |
| `data.tenants[].platformAgents` | array | 平台Agent配额列表 |
| `data.tenants[].platformAgents[].templateName` | string | 模板名称 |
| `data.tenants[].platformAgents[].podQuota` | integer | Pod配额数量 |
| `data.tenants[].platformAgents[].podUsed` | integer | 已使用Pod数量 |
| `data.tenants[].platformAgents[].cpuPerPod` | string | 每个Pod的CPU配置 |
| `data.tenants[].platformAgents[].memoryPerPod` | string | 每个Pod的内存配置 |
| `data.tenants[].models` | array | 模型配额列表 |
| `data.tenants[].models[].modelName` | string | 模型名称 |
| `data.tenants[].models[].rpmLimit` | integer | RPM限制（每分钟请求数） |
| `data.tenants[].models[].tpmLimit` | integer | TPM限制（每分钟Token数） |
| `data.tenants[].models[].maxBudget` | number/null | 最大预算 |
| `data.tenants[].models[].budgetDuration` | string | 预算周期 (monthly/daily) |
| `data.summary` | object | 汇总统计 |
| `data.summary.totalTenants` | integer | 租户总数 |
| `data.summary.tenantsWithCustomAgents` | integer | 有自定义Agent配额的租户数 |
| `data.summary.tenantsWithPlatformAgents` | integer | 有平台Agent配额的租户数 |
| `data.summary.tenantsWithModels` | integer | 有模型配额的租户数 |
| `data.summary.totalCustomAgentCpuQuota` | number | 总自定义Agent CPU配额 |
| `data.summary.totalCustomAgentMemoryQuota` | number | 总自定义Agent内存配额 |
| `data.summary.totalCustomAgentCpuUsed` | number | 总已使用CPU |
| `data.summary.totalCustomAgentMemoryUsed` | number | 总已使用内存 |
| `data.summary.totalPlatformAgentPodQuota` | integer | 总平台Agent Pod配额 |
| `data.summary.totalPlatformAgentPodUsed` | integer | 总已使用Pod数 |
### 实际响应示例
```json
{
"success": true,
"data": {
"channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6",
"channelName": "66",
"tenants": [
{
"tenantId": "b0d02105-55f8-41a7-b09a-bba8f49a9d62",
"tenantName": "xiaohei",
"tenantEmail": "xiaohei@qq.com",
"status": "active",
"createdAt": "2026-01-11T17:08:36.521982",
"customAgentQuota": {
"cpuQuota": 10.0,
"memoryQuota": 20.0,
"cpuUsed": 0.0,
"memoryUsed": 0.0,
"agentCount": 0
},
"platformAgents": [],
"models": []
},
{
"tenantId": "b00a7b8e-9e8b-463d-9593-a3b4d0006778",
"tenantName": "55",
"tenantEmail": "55@55.com",
"status": "active",
"createdAt": "2026-01-09T05:46:46.806711",
"customAgentQuota": {
"cpuQuota": 8.0,
"memoryQuota": 8.0,
"cpuUsed": 3.0,
"memoryUsed": 5.0,
"agentCount": 5
},
"platformAgents": [
{
"templateName": "echo_agent",
"podQuota": 3,
"podUsed": 2,
"cpuPerPod": "100m",
"memoryPerPod": "256Mi"
}
],
"models": [
{
"modelName": "taiji/gpt-4o-mini",
"rpmLimit": 10,
"tpmLimit": 10,
"maxBudget": 500.0,
"budgetDuration": "monthly"
},
{
"modelName": "taiji/gpt-5",
"rpmLimit": 100,
"tpmLimit": 100,
"maxBudget": 500.0,
"budgetDuration": "monthly"
}
]
},
{
"tenantId": "61069bec-2aca-465c-aa58-cebf9b1851a7",
"tenantName": "22",
"tenantEmail": "22@22.com",
"status": "active",
"createdAt": "2026-01-09T10:32:23.684369",
"customAgentQuota": null,
"platformAgents": [
{
"templateName": "code_agent",
"podQuota": 1,
"podUsed": 0,
"cpuPerPod": "100m",
"memoryPerPod": "256Mi"
}
],
"models": [
{
"modelName": "taiji/gpt-5",
"rpmLimit": 100,
"tpmLimit": 100,
"maxBudget": 500.0,
"budgetDuration": "monthly"
}
]
}
],
"summary": {
"totalTenants": 3,
"tenantsWithCustomAgents": 2,
"tenantsWithPlatformAgents": 2,
"tenantsWithModels": 2,
"totalCustomAgentCpuQuota": 18.0,
"totalCustomAgentMemoryQuota": 28.0,
"totalCustomAgentCpuUsed": 3.0,
"totalCustomAgentMemoryUsed": 5.0,
"totalPlatformAgentPodQuota": 4,
"totalPlatformAgentPodUsed": 2
}
},
"message": "获取渠道租户资源分配成功"
}
```
### 错误响应
| HTTP状态码 | 错误说明 | 响应示例 |
|------------|----------|----------|
| 400 | 无效的渠道ID格式 | `{"success": false, "detail": "无效的渠道ID格式"}` |
| 403 | 权限不足（渠道管理员只能查看所属渠道） | `{"success": false, "detail": "只能查看所属渠道的租户资源"}` |
| 404 | 渠道不存在 | `{"success": false, "detail": "渠道不存在"}` |
---
## 接口2: 渠道管理员查看租户资源分配汇总
### 基本信息
| 属性 | 值 |
|------|-----|
| **接口路径** | `GET /api/channel/tenants/resources/summary` |
| **后端文件** | `services/mcp-server/app/routes/channel.py` |
| **权限要求** | channel_admin, billing_admin, operations_admin, super_admin |
### 请求参数
#### 查询参数 (Query Parameters)
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| channel_id | string (UUID) | 条件必填 | 渠道ID（超级管理员必填，其他管理员自动使用所属渠道） | `6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6` |
#### 请求头 (Headers)
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| Authorization | string | 是 | Bearer Token | `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
### 请求示例
**渠道管理员请求（自动使用所属渠道）**:
```bash
curl -X GET "http://localhost:8002/api/channel/tenants/resources/summary" \
-H "Authorization: Bearer $CHANNEL_ADMIN_TOKEN"
```
**超级管理员请求（需要指定channel_id）**:
```bash
curl -X GET "http://localhost:8002/api/channel/tenants/resources/summary?channel_id=6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6" \
-H "Authorization: Bearer $SUPER_ADMIN_TOKEN"
```
### 响应参数
#### 成功响应 (200 OK)
```json
{
"success": true,
"data": {
"channelId": "string",
"channelName": "string",
"channelQuota": {
"customAgentQuota": {
"cpuQuota": "number",
"memoryQuota": "number",
"cpuAllocated": "number",
"memoryAllocated": "number"
} | null,
"platformAgents": [
{
"templateName": "string",
"podQuota": "integer",
"podUsed": "integer",
"cpuPerPod": "string",
"memoryPerPod": "string"
}
],
"models": ["string"]
},
"tenants": [
{
"tenantId": "string",
"tenantName": "string",
"tenantEmail": "string",
"status": "string",
"subscriptionTier": "string",
"balance": "number",
"createdAt": "string (ISO 8601)",
"customAgentQuota": {...} | null,
"platformAgents": [...],
"models": [...]
}
],
"summary": {
"totalTenants": "integer",
"tenantsWithCustomAgents": "integer",
"tenantsWithPlatformAgents": "integer",
"tenantsWithModels": "integer",
"totalCustomAgentCpuQuota": "number",
"totalCustomAgentMemoryQuota": "number",
"totalCustomAgentCpuUsed": "number",
"totalCustomAgentMemoryUsed": "number",
"totalPlatformAgentPodQuota": "integer",
"totalPlatformAgentPodUsed": "integer",
"totalModelsAllocated": "integer"
}
},
"message": "获取渠道租户资源分配成功"
}
```
#### 响应字段说明（额外字段）
此接口在接口1的基础上，增加以下字段：
| 字段路径 | 类型 | 说明 |
|----------|------|------|
| `data.channelQuota` | object | 渠道自身的配额信息（用于对比） |
| `data.channelQuota.customAgentQuota` | object/null | 渠道的自定义Agent配额 |
| `data.channelQuota.customAgentQuota.cpuQuota` | number | 渠道CPU配额上限 |
| `data.channelQuota.customAgentQuota.memoryQuota` | number | 渠道内存配额上限 |
| `data.channelQuota.customAgentQuota.cpuAllocated` | number | 已分配给租户的CPU总量 |
| `data.channelQuota.customAgentQuota.memoryAllocated` | number | 已分配给租户的内存总量 |
| `data.channelQuota.platformAgents` | array | 渠道的平台Agent配额列表 |
| `data.channelQuota.models` | array | 渠道被分配的模型列表 |
| `data.tenants[].subscriptionTier` | string | 租户订阅等级 (free/pro/enterprise) |
| `data.tenants[].balance` | number | 租户余额 |
| `data.summary.totalModelsAllocated` | integer | 总分配模型数 |
### 实际响应示例
```json
{
"success": true,
"data": {
"channelId": "6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6",
"channelName": "66",
"channelQuota": {
"customAgentQuota": {
"cpuQuota": 8.0,
"memoryQuota": 8.0,
"cpuAllocated": 8.0,
"memoryAllocated": 8.0
},
"platformAgents": [
{
"templateName": "echo_agent",
"podQuota": 3,
"podUsed": 0,
"cpuPerPod": "100m",
"memoryPerPod": "256Mi"
}
],
"models": [
"gpt-4o"
]
},
"tenants": [
{
"tenantId": "b0d02105-55f8-41a7-b09a-bba8f49a9d62",
"tenantName": "xiaohei",
"tenantEmail": "xiaohei@qq.com",
"status": "active",
"subscriptionTier": "free",
"balance": 0,
"createdAt": "2026-01-11T17:08:36.521982",
"customAgentQuota": {
"cpuQuota": 10.0,
"memoryQuota": 20.0,
"cpuUsed": 0.0,
"memoryUsed": 0.0,
"agentCount": 0
},
"platformAgents": [],
"models": []
},
{
"tenantId": "b00a7b8e-9e8b-463d-9593-a3b4d0006778",
"tenantName": "55",
"tenantEmail": "55@55.com",
"status": "active",
"subscriptionTier": "free",
"balance": 100.0,
"createdAt": "2026-01-09T05:46:46.806711",
"customAgentQuota": {
"cpuQuota": 8.0,
"memoryQuota": 8.0,
"cpuUsed": 3.0,
"memoryUsed": 5.0,
"agentCount": 5
},
"platformAgents": [
{
"templateName": "echo_agent",
"podQuota": 3,
"podUsed": 2,
"cpuPerPod": "100m",
"memoryPerPod": "256Mi"
}
],
"models": [
{
"modelName": "taiji/gpt-4o-mini",
"rpmLimit": 10,
"tpmLimit": 10,
"maxBudget": 500.0,
"budgetDuration": "monthly"
},
{
"modelName": "taiji/gpt-5",
"rpmLimit": 100,
"tpmLimit": 100,
"maxBudget": 500.0,
"budgetDuration": "monthly"
}
]
},
{
"tenantId": "61069bec-2aca-465c-aa58-cebf9b1851a7",
"tenantName": "22",
"tenantEmail": "22@22.com",
"status": "active",
"subscriptionTier": "free",
"balance": 50.0,
"createdAt": "2026-01-09T10:32:23.684369",
"customAgentQuota": null,
"platformAgents": [
{
"templateName": "code_agent",
"podQuota": 1,
"podUsed": 0,
"cpuPerPod": "100m",
"memoryPerPod": "256Mi"
}
],
"models": [
{
"modelName": "taiji/gpt-5",
"rpmLimit": 100,
"tpmLimit": 100,
"maxBudget": 500.0,
"budgetDuration": "monthly"
}
]
}
],
"summary": {
"totalTenants": 3,
"tenantsWithCustomAgents": 2,
"tenantsWithPlatformAgents": 2,
"tenantsWithModels": 2,
"totalCustomAgentCpuQuota": 18.0,
"totalCustomAgentMemoryQuota": 28.0,
"totalCustomAgentCpuUsed": 3.0,
"totalCustomAgentMemoryUsed": 5.0,
"totalPlatformAgentPodQuota": 4,
"totalPlatformAgentPodUsed": 2,
"totalModelsAllocated": 3
}
},
"message": "获取渠道租户资源分配成功"
}
```
### 错误响应
| HTTP状态码 | 错误说明 | 响应示例 |
|------------|----------|----------|
| 400 | 超级管理员未提供channel_id | `{"success": false, "detail": "超级管理员必须提供 channel_id 参数"}` |
| 400 | 无效的渠道ID格式 | `{"success": false, "detail": "无效的渠道ID格式"}` |
| 400 | 无法获取渠道ID | `{"success": false, "detail": "无法获取渠道ID"}` |
| 404 | 渠道不存在 | `{"success": false, "detail": "渠道不存在"}` |
---
## 数据结构说明
### 租户状态 (status)
| 值 | 说明 |
|----|------|
| `active` | 活跃状态 |
| `suspended` | 已暂停 |
| `inactive` | 已停用 |
### 订阅等级 (subscriptionTier)
| 值 | 说明 |
|----|------|
| `free` | 免费版 |
| `pro` | 专业版 |
| `enterprise` | 企业版 |
### 预算周期 (budgetDuration)
| 值 | 说明 |
|----|------|
| `monthly` | 月度预算 |
| `daily` | 每日预算 |
### CPU/内存格式
| 格式 | 说明 | 示例 |
|------|------|------|
| CPU (millicores) | Kubernetes CPU格式 | `100m` = 0.1核, `500m` = 0.5核 |
| Memory (MiB/GiB) | Kubernetes 内存格式 | `256Mi` = 256MB, `2Gi` = 2GB |
---
## 使用场景
### 场景1: 超级管理员审查渠道资源使用情况
超级管理员需要了解某个渠道下所有租户的资源使用情况，以便进行资源规划和调整。
```bash
# 查看渠道 "66" 的所有租户资源分配
curl -X GET "http://localhost:8002/api/admin/channels/6e6fc470-76f8-4bb1-8ea4-625dc5b12bc6/tenants/resources" \
-H "Authorization: Bearer $SUPER_ADMIN_TOKEN"
```
### 场景2: 渠道管理员查看配额使用对比
渠道管理员需要了解自己渠道的配额分配情况，以及与租户实际分配的对比。
```bash
# 渠道管理员查看租户资源分配汇总（包含渠道配额对比）
curl -X GET "http://localhost:8002/api/channel/tenants/resources/summary" \
-H "Authorization: Bearer $CHANNEL_ADMIN_TOKEN"
```
### 场景3: 分析资源利用率
通过 summary 字段，可以快速分析资源利用率：
- **自定义Agent CPU利用率** = `totalCustomAgentCpuUsed / totalCustomAgentCpuQuota`
- **自定义Agent内存利用率** = `totalCustomAgentMemoryUsed / totalCustomAgentMemoryQuota`
- **平台Agent Pod利用率** = `totalPlatformAgentPodUsed / totalPlatformAgentPodQuota`
---
## 前端调用示例
### JavaScript/TypeScript
```typescript
// 超级管理员查看渠道租户资源分配
async function getChannelTenantsResources(channelId: string): Promise<TenantsResourcesResponse> {
const response = await fetch(
`${API_BASE_URL}/api/admin/channels/${channelId}/tenants/resources`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
}
);
return response.json();
}
// 渠道管理员查看租户资源分配汇总
async function getChannelTenantsResourcesSummary(channelId?: string): Promise<TenantsResourcesSummaryResponse> {
const url = channelId
? `${API_BASE_URL}/api/channel/tenants/resources/summary?channel_id=${channelId}`
: `${API_BASE_URL}/api/channel/tenants/resources/summary`;
const response = await fetch(url, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
});
return response.json();
}
```
### TypeScript 类型定义
```typescript
interface CustomAgentQuota {
cpuQuota: number;
memoryQuota: number;
cpuUsed: number;
memoryUsed: number;
agentCount: number;
}
interface PlatformAgentQuota {
templateName: string;
podQuota: number;
podUsed: number;
cpuPerPod: string;
memoryPerPod: string;
}
interface ModelQuota {
modelName: string;
rpmLimit: number;
tpmLimit: number;
maxBudget: number | null;
budgetDuration: string;
}
interface TenantResource {
tenantId: string;
tenantName: string;
tenantEmail: string;
status: 'active' | 'suspended' | 'inactive';
createdAt: string;
subscriptionTier?: string;
balance?: number;
customAgentQuota: CustomAgentQuota | null;
platformAgents: PlatformAgentQuota[];
models: ModelQuota[];
}
interface ResourceSummary {
totalTenants: number;
tenantsWithCustomAgents: number;
tenantsWithPlatformAgents: number;
tenantsWithModels: number;
totalCustomAgentCpuQuota: number;
totalCustomAgentMemoryQuota: number;
totalCustomAgentCpuUsed: number;
totalCustomAgentMemoryUsed: number;
totalPlatformAgentPodQuota: number;
totalPlatformAgentPodUsed: number;
totalModelsAllocated?: number;
}
interface ChannelQuota {
customAgentQuota: {
cpuQuota: number;
memoryQuota: number;
cpuAllocated: number;
memoryAllocated: number;
} | null;
platformAgents: PlatformAgentQuota[];
models: string[];
}
interface TenantsResourcesResponse {
success: boolean;
data: {
channelId: string;
channelName: string;
tenants: TenantResource[];
summary: ResourceSummary;
};
message: string;
}
interface TenantsResourcesSummaryResponse {
success: boolean;
data: {
channelId: string;
channelName: string;
channelQuota: ChannelQuota;
tenants: TenantResource[];
summary: ResourceSummary;
};
message: string;
}
```
---
## 更新日志
### v1.0.0 (2026-01-13)
- 初始版本
- 实现超级管理员查看渠道租户资源分配接口
- 实现渠道管理员查看租户资源分配汇总接口
View Git Blame Copy Permalink