taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity

更新租户配额

Browse Source
This commit is contained in:
zhanggangyong
2026-01-12 16:47:41 +00:00
parent 3d5fd1f843
commit 1154b4e7ae
5 changed files with 1927 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/项目文档/渠道租户资源分配查看接口文档.md
+748
View File
@@ -0,0 +1,748 @@
# 渠道租户资源分配查看接口文档
> **版本**: 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)
- 初始版本
- 实现超级管理员查看渠道租户资源分配接口
- 实现渠道管理员查看租户资源分配汇总接口