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

拆分api接口文档

Browse Source
This commit is contained in:
Ubuntu
2025-12-26 15:16:32 +00:00
parent b5548991e7
commit f484912d8a
18 changed files with 1102 additions and 5682 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/前后端调试说明/API文档/02-Data-Ingestion服务.md → Docs/前后端调试说明/API-DataIngestion服务.md
+17 -9
View File
@@ -2,20 +2,24 @@
**基础URL**: `http://localhost:8001`
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [健康检查](#1-健康检查)
2. [RapidAPI 同步](#2-同步-rapidapi-端点)
3. [RapidAPI 测试](#3-测试-rapidapi-端点)
4. [OpenAPI 解析](#4-解析-openapi-规范)
5. [APILLAMA 处理](#5-apillama-处理-api-文档)
6. [工具生成](#6-生成工具定义)
7. [工具管理](#7-获取工具列表)
8. [统计信息](#10-获取统计信息)
9. [缓存管理](#11-清除缓存)
10. [Prometheus Metrics](#12-prometheus-metrics)
2. [同步 RapidAPI 端点](#2-同步-rapidapi-端点)
3. [测试 RapidAPI 端点](#3-测试-rapidapi-端点)
4. [解析 OpenAPI 规范](#4-解析-openapi-规范)
5. [APILLAMA 处理 API 文档](#5-apillama-处理-api-文档)
6. [生成工具定义](#6-生成工具定义)
7. [获取工具列表](#7-获取工具列表)
8. [获取特定工具定义](#8-获取特定工具定义)
9. [删除工具](#9-删除工具)
10. [获取统计信息](#10-获取统计信息)
11. [清除缓存](#11-清除缓存)
12. [Prometheus Metrics](#12-prometheus-metrics)
---
@@ -399,3 +403,7 @@ curl -X POST "http://localhost:8001/cache/clear"
curl -X GET "http://localhost:8001/metrics"
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/03-MCP-Server服务.md → Docs/前后端调试说明/API-MCPServer服务.md
+35 -16
View File
@@ -4,19 +4,36 @@
> **说明**: MCP Server在容器内运行在端口8000，通过Docker映射到主机端口8002。
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
### MCP Server 基础
1. [健康检查](#1-健康检查)
2. [Agent 管理](#agent-管理)
3. [工具执行](#5-执行-agent-工具)
4. [MCP 监控 API](#mcp-监控-api)
5. [WebSocket API](#websocket-api)
2. [注册 Agent](#2-注册-agent)
3. [获取 Agent 列表](#3-获取-agent-列表)
4. [获取特定 Agent](#4-获取特定-agent)
5. [执行 Agent 工具](#5-执行-agent-工具)
6. [获取工具列表](#6-获取工具列表)
7. [Prometheus Metrics](#7-prometheus-metrics)
### MCP 监控 API
8. [获取系统性能指标](#8-获取系统性能指标)
9. [获取服务统计信息](#9-获取服务统计信息)
10. [获取性能趋势数据](#10-获取性能趋势数据)
11. [获取系统告警](#11-获取系统告警)
12. [获取监控仪表盘聚合](#12-获取监控仪表盘聚合)
### WebSocket API
13. [MCP Protocol WebSocket](#13-mcp-protocol-websocket)
---
## 1. 健康检查
## MCP Server 基础
### 1. 健康检查
**GET** `/health`
@@ -43,8 +60,6 @@ curl -X GET "http://localhost:8002/health"
---
## Agent 管理
### 2. 注册 Agent
**POST** `/agents`
@@ -169,7 +184,7 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b"
---
## 5. 执行 Agent 工具
### 5. 执行 Agent 工具
**POST** `/agents/{agent_id}/execute`
@@ -230,7 +245,7 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b"
---
## 6. 获取工具列表
### 6. 获取工具列表
**GET** `/tools`
@@ -243,7 +258,7 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b"
---
## 7. Prometheus Metrics
### 7. Prometheus Metrics
**GET** `/metrics`
@@ -260,7 +275,7 @@ curl -X GET "http://localhost:8002/metrics"
**基础URL**: `http://localhost:8002/api/v1/monitoring`
### 1. 获取系统性能指标
### 8. 获取系统性能指标
**GET** `/api/v1/monitoring/metrics`
@@ -300,7 +315,7 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/metrics"
---
### 2. 获取服务统计信息
### 9. 获取服务统计信息
**GET** `/api/v1/monitoring/stats`
@@ -338,7 +353,7 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/stats?service=all"
---
### 3. 获取性能趋势数据
### 10. 获取性能趋势数据
**GET** `/api/v1/monitoring/trends`
@@ -373,7 +388,7 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/trends?metric=executions&pe
---
### 4. 获取系统告警
### 11. 获取系统告警
**GET** `/api/v1/monitoring/alerts`
@@ -405,7 +420,7 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/alerts?severity=warning"
---
### 5. 获取监控仪表盘聚合
### 12. 获取监控仪表盘聚合
**GET** `/api/v1/monitoring/dashboard`
@@ -440,7 +455,7 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/dashboard"
## WebSocket API
### MCP Protocol WebSocket
### 13. MCP Protocol WebSocket
**WebSocket URL**: `ws://localhost:8002/ws/{agent_name_or_id}`
@@ -485,3 +500,7 @@ ws.onmessage = (event) => {
}
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/08-供应商管理.md → Docs/前后端调试说明/API-供应商管理.md
+7 -52
View File
@@ -2,7 +2,7 @@
**基础URL**: `http://localhost:8002/api/providers`
> **权限说明**: 需要管理员权限
> 返回 [API接口文档](./API接口文档.md)
---
@@ -63,17 +63,17 @@
}
```
**provider可选值**: `openai`, `anthropic`, `azure`, `google`, `aws`
**请求参数说明**:
- `name` (string, 必需): 供应商显示名称
- `provider` (string, 必需): 供应商类型标识
- `provider` (string, 必需): 供应商类型
- `apiUrl` (string, 必需): API基础URL
- `apiKey` (string, 必需): API密钥
- `supportedModels` (array, 必需): 支持的模型列表
- `rpm` (int, 可选): 每分钟请求数限制
- `tpm` (int, 可选): 每分钟Token数限制
**provider可选值**: `openai`, `anthropic`, `azure`, `google`, `aws`
**响应示例**:
```json
{
@@ -132,15 +132,6 @@
}
```
**请求参数说明**:
- `name` (string, 可选): 供应商显示名称
- `provider` (string, 可选): 供应商类型标识
- `apiUrl` (string, 可选): API基础URL
- `apiKey` (string, 可选): 新的API密钥
- `supportedModels` (array, 可选): 支持的模型列表
- `rpm` (int, 可选): 每分钟请求数限制
- `tpm` (int, 可选): 每分钟Token数限制
**响应示例**:
```json
{
@@ -185,55 +176,19 @@
}
```
**失败响应示例**:
**连接失败响应示例**:
```json
{
"success": false,
"data": {
"status": "failed",
"latency": null,
"message": "连接超时: API响应超过5秒"
"message": "API密钥无效"
}
}
```
---
## 供应商类型说明
| 供应商 | provider值 | 说明 |
|--------|-----------|------|
| OpenAI | `openai` | GPT系列模型 |
| Anthropic | `anthropic` | Claude系列模型 |
| Azure OpenAI | `azure` | Azure托管的OpenAI模型 |
| Google | `google` | Gemini系列模型 |
| AWS Bedrock | `aws` | AWS托管的各类模型 |
---
## 使用示例
### 添加新供应商
```bash
curl -X POST "http://localhost:8002/api/providers/models/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
"name": "OpenAI",
"provider": "openai",
"apiUrl": "https://api.openai.com/v1",
"apiKey": "sk-xxxxx",
"supportedModels": ["gpt-4o", "gpt-4o-mini"],
"rpm": 3500,
"tpm": 90000
}'
```
### 测试连接
```bash
curl -X POST "http://localhost:8002/api/providers/models/provider-uuid-1/test" \
-H "Authorization: Bearer $TOKEN"
```
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API-前端集成与测试.md
+449
View File
@@ -0,0 +1,449 @@
# 前端集成与测试
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [前端集成示例](#前端集成示例)
- [JavaScript/TypeScript](#javascripttypescript)
- [Python](#python)
2. [完整 API 测试流程](#完整-api-测试流程)
- [测试脚本](#测试脚本)
3. [预置测试账号](#预置测试账号)
---
## 前端集成示例
### JavaScript/TypeScript
```typescript
// 健康检查
const healthCheck = async () => {
const response = await fetch('http://localhost:8001/health');
const data = await response.json();
console.log(data);
};
// 登录获取Token
const login = async (email: string, password: string, role: string) => {
const response = await fetch('http://localhost:8002/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password, role })
});
const data = await response.json();
return data.data.token;
};
// 使用Token访问API
const getDashboard = async (token: string) => {
const response = await fetch('http://localhost:8002/api/user/dashboard/stats', {
headers: { 'Authorization': `Bearer ${token}` }
});
return await response.json();
};
// 完整使用示例
const main = async () => {
try {
// 1. 健康检查
await healthCheck();
// 2. 登录
const token = await login('user@test.com', 'User@123456', 'user');
console.log('登录成功，获取Token');
// 3. 获取仪表板数据
const dashboard = await getDashboard(token);
console.log('仪表板数据:', dashboard);
} catch (error) {
console.error('错误:', error);
}
};
main();
```
### React Hook 示例
```typescript
import { useState, useEffect } from 'react';
interface UseAuthReturn {
token: string | null;
user: any;
login: (email: string, password: string, role: string) => Promise<void>;
logout: () => void;
isLoading: boolean;
error: string | null;
}
export const useAuth = (): UseAuthReturn => {
const [token, setToken] = useState<string | null>(localStorage.getItem('token'));
const [user, setUser] = useState<any>(null);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const login = async (email: string, password: string, role: string) => {
setIsLoading(true);
setError(null);
try {
const response = await fetch('http://localhost:8002/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password, role })
});
const data = await response.json();
if (data.success) {
setToken(data.data.token);
setUser(data.data.user);
localStorage.setItem('token', data.data.token);
} else {
throw new Error(data.message || '登录失败');
}
} catch (err: any) {
setError(err.message);
throw err;
} finally {
setIsLoading(false);
}
};
const logout = () => {
setToken(null);
setUser(null);
localStorage.removeItem('token');
};
return { token, user, login, logout, isLoading, error };
};
```
### API 请求封装
```typescript
const API_BASE_URL = 'http://localhost:8002';
interface ApiResponse<T> {
success: boolean;
data?: T;
message?: string;
}
class ApiClient {
private token: string | null = null;
setToken(token: string) {
this.token = token;
}
private async request<T>(
endpoint: string,
options: RequestInit = {}
): Promise<ApiResponse<T>> {
const headers: HeadersInit = {
'Content-Type': 'application/json',
...options.headers,
};
if (this.token) {
headers['Authorization'] = `Bearer ${this.token}`;
}
const response = await fetch(`${API_BASE_URL}${endpoint}`, {
...options,
headers,
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || '请求失败');
}
return response.json();
}
// GET 请求
async get<T>(endpoint: string): Promise<ApiResponse<T>> {
return this.request<T>(endpoint, { method: 'GET' });
}
// POST 请求
async post<T>(endpoint: string, data?: any): Promise<ApiResponse<T>> {
return this.request<T>(endpoint, {
method: 'POST',
body: data ? JSON.stringify(data) : undefined,
});
}
// PUT 请求
async put<T>(endpoint: string, data?: any): Promise<ApiResponse<T>> {
return this.request<T>(endpoint, {
method: 'PUT',
body: data ? JSON.stringify(data) : undefined,
});
}
// DELETE 请求
async delete<T>(endpoint: string): Promise<ApiResponse<T>> {
return this.request<T>(endpoint, { method: 'DELETE' });
}
}
export const apiClient = new ApiClient();
```
---
### Python
```python
import requests
BASE_URL = 'http://localhost:8002'
# 登录
def login(email: str, password: str, role: str) -> str:
"""登录并返回Token"""
response = requests.post(
f'{BASE_URL}/api/auth/login',
json={'email': email, 'password': password, 'role': role}
)
response.raise_for_status()
return response.json()['data']['token']
# 使用Token访问API
def get_dashboard(token: str) -> dict:
"""获取仪表板数据"""
response = requests.get(
f'{BASE_URL}/api/user/dashboard/stats',
headers={'Authorization': f'Bearer {token}'}
)
response.raise_for_status()
return response.json()
# API 客户端类
class TaijiApiClient:
def __init__(self, base_url: str = BASE_URL):
self.base_url = base_url
self.token = None
def login(self, email: str, password: str, role: str) -> dict:
"""登录"""
response = requests.post(
f'{self.base_url}/api/auth/login',
json={'email': email, 'password': password, 'role': role}
)
response.raise_for_status()
data = response.json()
if data['success']:
self.token = data['data']['token']
return data
def _request(self, method: str, endpoint: str, **kwargs) -> dict:
"""发送请求"""
headers = kwargs.pop('headers', {})
if self.token:
headers['Authorization'] = f'Bearer {self.token}'
response = requests.request(
method,
f'{self.base_url}{endpoint}',
headers=headers,
**kwargs
)
response.raise_for_status()
return response.json()
def get(self, endpoint: str) -> dict:
return self._request('GET', endpoint)
def post(self, endpoint: str, data: dict = None) -> dict:
return self._request('POST', endpoint, json=data)
def put(self, endpoint: str, data: dict = None) -> dict:
return self._request('PUT', endpoint, json=data)
def delete(self, endpoint: str) -> dict:
return self._request('DELETE', endpoint)
# 使用示例
if __name__ == '__main__':
client = TaijiApiClient()
# 登录
client.login('user@test.com', 'User@123456', 'user')
# 获取仪表板
dashboard = client.get('/api/user/dashboard/stats')
print(dashboard)
```
---
## 完整 API 测试流程
以下是一个完整的 API 测试流程示例，涵盖从超级管理员登录到创建渠道、创建租户、分配资源的全过程。
### 测试脚本
```bash
#!/bin/bash
# 完整 API 测试流程
echo "=== 1. 超级管理员登录 ==="
ADMIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}')
echo $ADMIN_RESPONSE | python3 -m json.tool
ADMIN_TOKEN=$(echo $ADMIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])")
echo "管理员Token获取成功"
echo ""
echo "=== 2. 创建渠道 ==="
CHANNEL_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/admin/channels/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{
"name": "测试渠道Alpha",
"email": "channel-alpha@test.com",
"password": "Channel@123456",
"commissionRate": 10.0
}')
echo $CHANNEL_RESPONSE | python3 -m json.tool
echo ""
echo "=== 3. 渠道管理员登录 ==="
CHANNEL_LOGIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}')
echo $CHANNEL_LOGIN_RESPONSE | python3 -m json.tool
CHANNEL_TOKEN=$(echo $CHANNEL_LOGIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])")
echo "渠道Token获取成功"
echo ""
echo "=== 4. 创建租户 ==="
TENANT_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/channel/tenants/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{
"name": "张三",
"email": "zhangsan@company.com",
"password": "User@123456",
"subscriptionTier": "pro"
}')
echo $TENANT_RESPONSE | python3 -m json.tool
TENANT_ID=$(echo $TENANT_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['id'])")
echo "租户ID: $TENANT_ID"
echo ""
echo "=== 5. 为租户分配资源 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/resources" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{
"agents": [
{"agentId": "通用助手", "quantity": 5},
{"agentId": "代码助手", "quantity": 3}
],
"models": [
{"modelName": "OpenAI", "rpm": 100, "tpm": 100000}
]
}' | python3 -m json.tool
echo ""
echo "=== 6. 更新租户计费设置 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/billing" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"subscriptionTier": "pro", "discount": 10.0}' | python3 -m json.tool
echo ""
echo "=== 7. 设置授信额度 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"creditLimit": 10000.0}' | python3 -m json.tool
echo ""
echo "=== 8. 为租户充值 ==="
curl -s -X POST "http://localhost:8002/api/channel/tenants/${TENANT_ID}/recharge" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"amount": 5000.0}' | python3 -m json.tool
echo ""
echo "=== 9. 租户登录验证 ==="
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}' | python3 -m json.tool
echo ""
echo "=== 10. 查看渠道下的租户列表 ==="
curl -s "http://localhost:8002/api/channel/tenants" \
-H "Authorization: Bearer $CHANNEL_TOKEN" | python3 -m json.tool
echo ""
echo "=== API测试完成 ==="
```
---
## 预置测试账号
系统初始化时会创建以下测试账号：
| 角色 | 邮箱 | 密码 | 登录role参数 | 可执行操作 |
|------|------|------|-------------|-----------|
| 超级管理员 | superadmin@taiji-ai.com | Admin@123456 | super_admin | 创建管理员、创建渠道、全部管理 |
| 计费管理员 | billing@taiji-ai.com | Admin@123456 | billing_admin | 创建渠道、管理租户、计费操作（完整写入权限） |
| 运维管理员 | ops@taiji-ai.com | Admin@123456 | operations_admin | 查看概览、监控、计费（只读权限） |
| 渠道 | default@channel.com | Channel@123456 | channel | 创建租户、管理租户资源 |
| 测试用户 | user@test.com | User@123456 | user | 使用平台服务 |
> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user
### 快速登录命令
```bash
# 超级管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}'
# 计费管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"billing@taiji-ai.com","password":"Admin@123456","role":"billing_admin"}'
# 运维管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"ops@taiji-ai.com","password":"Admin@123456","role":"operations_admin"}'
# 渠道管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"default@channel.com","password":"Channel@123456","role":"channel"}'
# 租户用户登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"user@test.com","password":"User@123456","role":"user"}'
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/05-渠道合作伙伴.md → Docs/前后端调试说明/API-渠道合作伙伴.md
+196 -4
View File
@@ -2,15 +2,31 @@
**基础URL**: `http://localhost:8002/api/channel`
> **权限说明**: 需要渠道管理员(channel_admin)或更高权限登录
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [租户管理相关](#租户管理相关)
2. [资源申请相关](#资源申请相关)
3. [计费统计相关](#计费统计相关)
### 租户管理相关
1. [获取租户列表](#1-获取租户列表)
2. [创建租户](#2-创建租户)
3. [分配租户资源](#3-分配租户资源)
4. [更新租户计费设置](#4-更新租户计费设置)
5. [为租户充值](#5-为租户充值)
6. [设置租户授信额度](#6-设置租户授信额度)
### 资源申请相关
7. [申请资源](#7-申请资源)
### 计费统计相关
8. [获取渠道计费统计](#8-获取渠道计费统计)
### 供应商管理相关 ✨ **新增**
9. [获取可用供应商列表](#9-获取可用供应商列表)
10. [申请使用供应商](#10-申请使用供应商)
11. [获取供应商申请列表](#11-获取供应商申请列表)
12. [获取已授权供应商列表](#12-获取已授权供应商列表)
---
@@ -335,3 +351,179 @@ curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
}
```
---
## 供应商管理相关 ✨ **新增**
### 9. 获取可用供应商列表
**GET** `/api/channel/providers`
获取所有可用的模型供应商列表，并标注渠道是否已获得使用授权。
**响应示例**:
```json
{
"success": true,
"data": {
"providers": [
{
"id": "provider-uuid-1",
"name": "OpenAI",
"provider": "openai",
"supportedModels": ["gpt-4", "gpt-4o-mini"],
"rpm": 3500,
"tpm": 90000,
"status": "active",
"hasAccess": true,
"accessStatus": "active",
"rpmLimit": 1000,
"tpmLimit": 50000,
"pendingApplication": false
},
{
"id": "provider-uuid-2",
"name": "Anthropic",
"provider": "anthropic",
"supportedModels": ["claude-3-opus", "claude-3-sonnet"],
"rpm": 2000,
"tpm": 80000,
"status": "active",
"hasAccess": false,
"accessStatus": null,
"rpmLimit": null,
"tpmLimit": null,
"pendingApplication": true
}
]
}
}
```
**响应字段说明**:
- `hasAccess` (bool): 是否已获得授权使用该供应商
- `accessStatus` (string|null): 授权状态，可选值：`active`, `suspended`, `expired`
- `rpmLimit` (int|null): 渠道的每分钟请求数限制
- `tpmLimit` (int|null): 渠道的每分钟Token数限制
- `pendingApplication` (bool): 是否有待审批的申请
---
### 10. 申请使用供应商
**POST** `/api/channel/providers/apply`
申请使用某个模型供应商，需要管理员审批后才能使用。
**请求体**:
```json
{
"providerId": "provider-uuid-2",
"requestedRpm": 1000,
"requestedTpm": 50000,
"reason": "我们需要使用Claude模型来处理复杂的文档分析任务，预计每日调用量约500次。"
}
```
**请求参数说明**:
- `providerId` (string, 必需): 供应商ID
- `requestedRpm` (int, 可选): 申请的每分钟请求数限制
- `requestedTpm` (int, 可选): 申请的每分钟Token数限制
- `reason` (string, 必需): 申请理由，10-500字符
**curl示例**:
```bash
curl -s -X POST "http://localhost:8002/api/channel/providers/apply" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{
"providerId": "provider-uuid-2",
"requestedRpm": 1000,
"requestedTpm": 50000,
"reason": "我们需要使用该模型来处理复杂的文档分析任务"
}'
```
**响应示例**:
```json
{
"success": true,
"data": {
"id": "application-uuid-1",
"providerId": "provider-uuid-2",
"providerName": "Anthropic",
"status": "pending"
},
"message": "申请已提交，等待管理员审批"
}
```
---
### 11. 获取供应商申请列表
**GET** `/api/channel/providers/applications`
获取渠道的供应商使用申请列表。
**查询参数**:
- `status` (string, 可选): 状态筛选，可选值：`pending`, `approved`, `rejected`
**响应示例**:
```json
{
"success": true,
"data": {
"applications": [
{
"id": "application-uuid-1",
"providerId": "provider-uuid-2",
"providerName": "Anthropic",
"requestedRpm": 1000,
"requestedTpm": 50000,
"reason": "需要使用Claude模型处理文档分析任务",
"status": "pending",
"createdAt": "2025-12-26T10:00:00Z",
"reviewedAt": null,
"reviewReason": null
}
]
}
}
```
---
### 12. 获取已授权供应商列表
**GET** `/api/channel/providers/access`
获取渠道已获得授权的供应商列表。
**响应示例**:
```json
{
"success": true,
"data": {
"accessList": [
{
"id": "access-uuid-1",
"providerId": "provider-uuid-1",
"providerName": "OpenAI",
"provider": "openai",
"supportedModels": ["gpt-4", "gpt-4o-mini"],
"status": "active",
"rpmLimit": 1000,
"tpmLimit": 50000,
"approvedAt": "2025-12-20T15:30:00Z",
"expiresAt": null
}
]
}
}
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/04-用户侧平台.md → Docs/前后端调试说明/API-用户侧平台.md
+31 -8
View File
@@ -2,18 +2,37 @@
**基础URL**: `http://localhost:8002/api/user`
> **权限说明**: 需要租户用户(user)或更高权限登录
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [概览相关](#概览相关)
2. [服务网关相关](#服务网关相关)
3. [数据与工具相关](#数据与工具相关)
4. [代理工厂相关](#代理工厂相关)
5. [编排中心相关](#编排中心相关)
6. [计费与资源相关](#计费与资源相关)
### 概览相关
1. [获取仪表板统计](#1-获取仪表板统计)
2. [获取Agent活动数据](#2-获取agent活动数据)
### 服务网关相关
3. [选择网关类型](#3-选择网关类型)
4. [创建网关API](#4-创建网关api)
5. [获取网关API列表](#5-获取网关api列表)
6. [获取网关监控数据](#6-获取网关监控数据)
### 数据与工具相关
7. [生成工具](#7-生成工具)
8. [创建数据模板](#8-创建数据模板)
### 代理工厂相关
9. [获取平台Agent列表](#9-获取平台agent列表)
10. [部署Agent](#10-部署agent)
### 编排中心相关
11. [创建工作流](#11-创建工作流)
### 计费与资源相关
12. [获取余额信息](#12-获取余额信息)
13. [充值余额](#13-充值余额)
14. [获取计费历史](#14-获取计费历史)
---
@@ -314,7 +333,7 @@
}
```
> **注意**: 工作流最多支持3个节点。
**注意**: 工作流最多支持3个节点。
**响应示例**:
```json
@@ -425,3 +444,7 @@
}
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/07-计费与资源管理.md → Docs/前后端调试说明/API-计费与资源管理.md
+43 -7
View File
@@ -4,17 +4,49 @@
> **权限说明**: 以下接口需要管理员权限（super_admin、billing_admin、operations_admin）
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [配额管理](#配额管理)
2. [资源监控](#资源监控)
3. [事件管理](#事件管理)
4. [追踪管理](#追踪管理)
5. [审计日志](#审计日志)
6. [供应商健康检查](#供应商健康检查)
7. [模型定价管理](#模型定价管理)
### 配额管理
1. [获取用户配额信息](#1-获取用户配额信息)
2. [获取渠道配额信息](#2-获取渠道配额信息)
3. [获取配额预警列表](#3-获取配额预警列表)
4. [确认配额预警](#4-确认配额预警)
5. [解决配额预警](#5-解决配额预警)
### 资源监控
6. [获取平台资源概览](#6-获取平台资源概览)
7. [获取用户资源使用汇总](#7-获取用户资源使用汇总)
8. [获取资源使用趋势](#8-获取资源使用趋势)
9. [获取Agent资源统计](#9-获取agent资源统计)
### 事件管理
10. [获取待处理事件](#10-获取待处理事件)
11. [重试失败事件](#11-重试失败事件)
12. [获取事件统计](#12-获取事件统计)
### 追踪管理
13. [获取执行追踪详情](#13-获取执行追踪详情)
14. [查询追踪记录](#14-查询追踪记录)
15. [获取追踪统计](#15-获取追踪统计)
### 审计日志
16. [查询审计日志](#16-查询审计日志)
17. [获取审计日志汇总](#17-获取审计日志汇总)
18. [获取用户活动历史](#18-获取用户活动历史)
### 供应商健康检查
19. [获取所有供应商健康状态](#19-获取所有供应商健康状态)
20. [获取供应商健康详情](#20-获取供应商健康详情)
21. [执行供应商健康检查](#21-执行供应商健康检查)
### 模型定价管理
22. [获取模型定价列表](#22-获取模型定价列表)
23. [创建/更新模型定价](#23-创建更新模型定价)
24. [计算模型调用成本](#24-计算模型调用成本)
---
@@ -786,3 +818,7 @@ curl -X POST "http://localhost:8002/api/billing-admin/pricing/calculate?model_na
}
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/01-认证与授权.md → Docs/前后端调试说明/API-认证模块.md
+16 -112
View File
@@ -1,86 +1,23 @@
# 认证与授权 API
# 认证模块 API
**基础URL**: `http://localhost:8002/api/auth`
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [认证方式](#认证方式)
2. [权限角色](#权限角色)
3. [权限矩阵](#权限矩阵)
4. [认证模块 API](#认证模块-api)
5. [豁免路径](#豁免路径)
1. [用户登录](#1-用户登录)
2. [用户登出](#2-用户登出)
3. [刷新Token](#3-刷新token)
4. [修改密码](#4-修改密码)
5. [获取API密钥信息](#5-获取api密钥信息)
6. [重新生成API密钥](#6-重新生成api密钥)
---
## 认证方式
系统支持两种认证方式：
### 1. JWT Bearer Token认证
- 通过 `/api/auth/login` 登录获取token
- 在请求头中携带: `Authorization: Bearer <token>`
- Token有效期: 24小时
### 2. API Key认证
- 通过 `/api/auth/keys/info` 获取API密钥
- 在请求头中携带: `X-API-Key: <api-key>`
- API Key格式: `sk-xxxx...`
---
## 权限角色
系统支持以下角色：
| 角色 | 说明 | 登录role参数 |
|------|------|-------------|
| super_admin | 超级管理员 | super_admin |
| billing_admin | 计费管理员 | billing_admin |
| operations_admin | 运维管理员 | operations_admin |
| channel_admin | 渠道管理员 | channel |
| provider_admin | 供应商管理员 | provider |
| user | 租户用户 | user |
---
## 权限矩阵
| 操作 | super_admin | billing_admin | operations_admin | channel_admin |
|------|:-----------:|:-------------:|:----------------:|:-------------:|
| **管理员管理** |
| 查看管理员列表 | ✅ | ❌ | ❌ | ❌ |
| 创建管理员 | ✅ | ❌ | ❌ | ❌ |
| 删除管理员 | ✅ | ❌ | ❌ | ❌ |
| **渠道管理** |
| 查看渠道列表 | ✅ | ✅ | ✅ | ❌ |
| 创建渠道 | ✅ | ✅ | ❌ | ❌ |
| 编辑渠道 | ✅ | ✅ | ❌ | ❌ |
| 删除渠道 | ✅ | ✅ | ❌ | ❌ |
| **资源管理** |
| 查看资源 | ✅ | ✅ | ✅ | ✅ |
| 分配资源 | ✅ | ✅ | ❌ | ✅ |
| 配置Agent | ✅ | ✅ | ❌ | ❌ |
| **计费管理** |
| 查看计费记录 | ✅ | ✅ | ✅ | ✅ |
| 执行充值 | ✅ | ✅ | ❌ | ✅ |
| **监控** |
| 查看系统监控 | ✅ | ✅ | ✅ | ❌ |
| 查看Agent状态 | ✅ | ✅ | ✅ | ❌ |
| **申请审批** |
| 查看申请 | ✅ | ✅ | ✅ | ❌ |
| 审批申请 | ✅ | ✅ | ❌ | ❌ |
> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user
---
## 认证模块 API
### 1. 用户登录
## 1. 用户登录
**POST** `/api/auth/login`
@@ -161,7 +98,7 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
### 2. 用户登出
## 2. 用户登出
**POST** `/api/auth/logout`
@@ -178,7 +115,7 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
### 3. 刷新Token
## 3. 刷新Token
**POST** `/api/auth/refresh`
@@ -198,7 +135,7 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
### 4. 修改密码
## 4. 修改密码
**PUT** `/api/auth/password`
@@ -223,7 +160,7 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
### 5. 获取API密钥信息
## 5. 获取API密钥信息
**GET** `/api/auth/keys/info`
@@ -247,7 +184,7 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
### 6. 重新生成API密钥
## 6. 重新生成API密钥
**POST** `/api/auth/keys/regenerate`
@@ -269,38 +206,5 @@ curl -s -X POST "http://localhost:8002/api/auth/login" \
---
## 豁免路径
以下路径无需认证即可访问：
- `/health` - 健康检查
- `/metrics` - Prometheus指标
- `/docs` - Swagger文档
- `/redoc` - ReDoc文档
- `/openapi.json` - OpenAPI规范
- `/api/auth/login` - 登录接口
---
## 使用示例
### 使用JWT Token
```bash
# 1. 登录获取token
TOKEN=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"admin@taiji-ai.com","password":"admin123","role":"user"}' \
| jq -r '.data.token')
# 2. 使用token访问API
curl -X GET "http://localhost:8002/api/user/dashboard/stats" \
-H "Authorization: Bearer $TOKEN"
```
### 使用API Key
```bash
curl -X GET "http://localhost:8002/api/user/dashboard/stats" \
-H "X-API-Key: sk-aBcD1234EfGh5678IjKl9012MnOp3456"
```
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/API文档/06-超级管理员.md → Docs/前后端调试说明/API-超级管理员.md
+224 -12
View File
@@ -2,20 +2,55 @@
**基础URL**: `http://localhost:8002/api/admin`
> **权限说明**: 需要超级管理员(super_admin)、计费管理员(billing_admin)或运维管理员(operations_admin)登录
> 返回 [API接口文档](./API接口文档.md)
---
## 目录
1. [概览相关](#概览相关)
2. [管理员管理相关](#管理员管理相关)
3. [渠道管理相关](#渠道管理相关)
4. [申请审批相关](#申请审批相关)
5. [资源管理相关](#资源管理相关)
6. [监控相关](#监控相关)
7. [计费相关（三维度）](#计费相关三维度)
8. [前端集成补充接口](#前端集成补充接口)
### 概览相关
1. [获取平台统计](#1-获取平台统计)
### 管理员管理相关
2. [获取管理员列表](#2-获取管理员列表)
3. [创建管理员](#3-创建管理员)
4. [删除管理员](#4-删除管理员)
### 渠道管理相关
5. [获取渠道列表](#5-获取渠道列表)
6. [创建渠道](#6-创建渠道)
7. [更新渠道信息](#7-更新渠道信息)
8. [删除渠道](#8-删除渠道)
9. [获取渠道资源分配](#9-获取渠道资源分配)
10. [统一管理渠道资源](#10-统一管理渠道资源)
### 申请审批相关
11. [获取所有申请](#11-获取所有申请)
12. [审批申请](#12-审批申请)
### 资源管理相关
13. [获取所有模型供应商](#13-获取所有模型供应商)
14. [获取所有Agent资源](#14-获取所有agent资源)
15. [删除Agent资源](#15-删除agent资源)
16. [更新Agent资源配置](#16-更新agent资源配置)
### 监控相关
17. [监控Agent健康状态](#17-监控agent健康状态)
### 计费相关（三维度）
18. [获取三维度计费统计](#18-获取三维度计费统计)
### 供应商申请审批相关 ✨ **新增**
19. [获取供应商申请列表（管理员视图）](#19-获取供应商申请列表管理员视图)
20. [审批供应商申请](#20-审批供应商申请)
21. [获取所有渠道供应商授权列表](#21-获取所有渠道供应商授权列表)
22. [更新渠道供应商授权](#22-更新渠道供应商授权)
23. [撤销渠道供应商授权](#23-撤销渠道供应商授权)
### 前端集成补充接口
24. [获取可用角色列表](#24-获取可用角色列表)
25. [供应商统计（展示用）](#25-供应商统计展示用)
26. [后台简易渠道统计](#26-后台简易渠道统计)
---
@@ -336,6 +371,7 @@ curl -X DELETE "http://localhost:8002/api/admin/channels/channel-uuid-1" \
**GET** `/api/admin/channels/{channel_id}/resources`
**路径参数**:
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| channel_id | string (UUID) | 是 | 渠道ID |
@@ -362,6 +398,7 @@ curl -X DELETE "http://localhost:8002/api/admin/channels/channel-uuid-1" \
```
**响应字段说明**:
| 字段 | 类型 | 描述 |
|------|------|------|
| id | string | 渠道ID |
@@ -661,11 +698,178 @@ curl -X PUT "http://localhost:8002/api/admin/resources/agents/agent-uuid-1/confi
---
## 供应商申请审批相关 ✨ **新增**
### 19. 获取供应商申请列表（管理员视图）
**GET** `/api/admin/providers/applications`
获取所有渠道的供应商使用申请列表。
**查询参数**:
- `status` (string, 可选): 状态筛选，可选值：`pending`, `approved`, `rejected`
- `channel_id` (string, 可选): 渠道ID筛选
**响应示例**:
```json
{
"success": true,
"data": {
"applications": [
{
"id": "application-uuid-1",
"channelId": "channel-uuid-1",
"channelName": "合作渠道A",
"providerId": "provider-uuid-2",
"providerName": "Anthropic",
"providerType": "anthropic",
"requestedRpm": 1000,
"requestedTpm": 50000,
"reason": "需要使用Claude模型处理文档分析任务",
"status": "pending",
"createdAt": "2025-12-26T10:00:00Z",
"reviewedAt": null,
"reviewReason": null
}
]
}
}
```
---
### 20. 审批供应商申请
**PUT** `/api/admin/providers/applications/{application_id}/review`
审批渠道的供应商使用申请。批准后会自动创建渠道供应商授权记录。
**请求体**:
```json
{
"approved": true,
"reason": "审批通过，已授权使用",
"rpmLimit": 1000,
"tpmLimit": 50000
}
```
**请求参数说明**:
- `approved` (bool, 必需): 是否批准
- `reason` (string, 可选): 审批意见
- `rpmLimit` (int, 可选): 批准的RPM限制，不填则使用供应商默认值
- `tpmLimit` (int, 可选): 批准的TPM限制，不填则使用供应商默认值
**curl示例**:
```bash
curl -s -X PUT "http://localhost:8002/api/admin/providers/applications/application-uuid-1/review" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{
"approved": true,
"reason": "审批通过",
"rpmLimit": 1000,
"tpmLimit": 50000
}'
```
**响应示例**:
```json
{
"success": true,
"message": "供应商使用申请已批准"
}
```
---
### 21. 获取所有渠道供应商授权列表
**GET** `/api/admin/providers/access`
获取所有渠道的供应商授权列表。
**查询参数**:
- `channel_id` (string, 可选): 渠道ID筛选
- `provider_id` (string, 可选): 供应商ID筛选
- `status` (string, 可选): 状态筛选，可选值：`active`, `suspended`, `expired`
**响应示例**:
```json
{
"success": true,
"data": {
"accessList": [
{
"id": "access-uuid-1",
"channelId": "channel-uuid-1",
"channelName": "合作渠道A",
"providerId": "provider-uuid-1",
"providerName": "OpenAI",
"providerType": "openai",
"status": "active",
"rpmLimit": 1000,
"tpmLimit": 50000,
"approvedAt": "2025-12-20T15:30:00Z",
"expiresAt": null,
"createdAt": "2025-12-20T15:30:00Z"
}
]
}
}
```
---
### 22. 更新渠道供应商授权
**PUT** `/api/admin/providers/access/{access_id}`
更新渠道的供应商授权配置。可用于暂停、恢复或更新限制。
**查询参数**:
- `status` (string, 可选): 状态，可选值：`active`, `suspended`, `expired`
- `rpm_limit` (int, 可选): 每分钟请求数限制
- `tpm_limit` (int, 可选): 每分钟Token数限制
**curl示例**:
```bash
# 暂停渠道的供应商授权
curl -s -X PUT "http://localhost:8002/api/admin/providers/access/access-uuid-1?status=suspended" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
**响应示例**:
```json
{
"success": true,
"message": "授权信息已更新"
}
```
---
### 23. 撤销渠道供应商授权
**DELETE** `/api/admin/providers/access/{access_id}`
撤销渠道的供应商使用授权。将授权状态设为 `suspended`。
**响应示例**:
```json
{
"success": true,
"message": "授权已撤销"
}
```
---
## 前端集成补充接口
为了保证前端在轻量集成场景下可以持续迭代，`services/mcp-server/app/routes/frontend_integration.py` 还暴露了一组直接以 `/api` 前缀对外的超级管理员辅助接口，数据保存在内存 store 中，适合 UI 预览与模拟，调用仍需超级管理员身份。
### 19. 获取可用角色列表
### 24. 获取可用角色列表
**GET** `/api/admin/roles`
@@ -678,7 +882,9 @@ curl -X PUT "http://localhost:8002/api/admin/resources/agents/agent-uuid-1/confi
}
```
### 20. 供应商统计（展示用）
---
### 25. 供应商统计（展示用）
**GET** `/api/admin/providers/stats`
@@ -699,7 +905,9 @@ curl -X PUT "http://localhost:8002/api/admin/resources/agents/agent-uuid-1/confi
}
```
### 21. 后台简易渠道统计
---
### 26. 后台简易渠道统计
**GET** `/api/admin/channels/backend/stats`
@@ -713,3 +921,7 @@ curl -X PUT "http://localhost:8002/api/admin/resources/agents/agent-uuid-1/confi
}
```
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试说明/APILLAMA_OpenRouter集成说明.md
-247
View File
@@ -1,247 +0,0 @@
# APILLAMA OpenRouter 集成说明
**版本**: v1.2.1
**最后更新**: 2025年12月22日
## 概述
APILLAMA 处理器已更新为使用 OpenRouter API 调用 Llama 3.1 8B Instruct 模型，无需本地部署模型。这大大简化了部署和维护工作。
## 模型信息
- **模型**: `meta-llama/llama-3.1-8b-instruct`
- **提供商**: OpenRouter
- **模型页面**: https://openrouter.ai/meta-llama/llama-3.1-8b-instruct
- **上下文长度**: 131,072 tokens
- **定价**:
- 输入: $0.02/M tokens
- 输出: $0.03/M tokens
## 配置
### 环境变量
在 `.env` 文件中配置以下变量：
```bash
# OpenRouter API 配置（用于APILLAMA）
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
# APILLAMA 模型配置
APILLAMA_MODEL_ID=meta-llama/llama-3.1-8b-instruct
APILLAMA_MAX_TOKENS=2048
APILLAMA_TEMPERATURE=0.3
APILLAMA_TOP_P=0.9
```
### 获取 OpenRouter API Key
1. 访问 https://openrouter.ai/
2. 注册/登录账户
3. 在 Dashboard 中创建 API Key
4. 将 API Key 添加到 `.env` 文件
## 功能特性
### 1. LLM 增强处理
当配置了 OpenRouter API Key 时，APILLAMA 处理器会：
- 使用 Llama 3.1 8B Instruct 模型分析 API 文档
- 自动生成结构化的 schema（支持 Pydantic、JSON Schema、OpenAPI 格式）
- 增强 API 描述，使其更清晰和全面
- 提取和规范化参数定义
- 生成示例请求和响应
### 2. Fallback 机制
如果未配置 OpenRouter API Key 或 API 调用失败，系统会自动回退到基于规则的处理方式，确保服务始终可用。
### 3. 缓存机制
- 处理结果会缓存到 Redis（24小时）
- 相同输入的重复请求会直接返回缓存结果
- 大大减少 API 调用成本
## 使用示例
### API 调用
```bash
curl -X POST "http://localhost:8001/apillama/process" \
-H "Content-Type: application/json" \
-d '{
"api_doc": {
"title": "Weather API",
"description": "Get weather information",
"endpoints": [
{
"path": "/weather",
"method": "GET",
"parameters": [
{
"name": "location",
"type": "string",
"required": true
}
]
}
]
},
"context": {
"service": "Weather service",
"version": "1.0"
},
"output_format": "json_schema"
}'
```
### 响应格式
```json
{
"processed": true,
"output_format": "json_schema",
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name"
}
},
"required": ["location"]
},
"description": "Enhanced API description...",
"parameters": [
{
"name": "location",
"type": "string",
"description": "City name",
"required": true
}
],
"examples": [
{
"name": "basic_example",
"description": "Basic example request",
"value": {
"location": "Beijing"
}
}
],
"processing_time": 1.23,
"confidence_score": 0.95,
"completeness_score": 0.90
}
```
## 支持的输出格式
1. **Pydantic**: Python Pydantic 模型定义
2. **JSON Schema**: JSON Schema 格式
3. **OpenAPI**: OpenAPI 3.0 格式
## 性能优化
### 1. 缓存策略
- 所有处理结果都会缓存
- 缓存键基于输入内容的 MD5 哈希
- 缓存时间：24小时
### 2. 请求优化
- 使用异步 HTTP 客户端
- 超时设置：60秒
- 自动重试机制（在 fallback 中）
### 3. 成本控制
- 通过缓存减少 API 调用
- 可配置 max_tokens 限制输出长度
- 使用 temperature 和 top_p 控制生成质量
## 监控和日志
### 健康检查
```bash
curl http://localhost:8001/health
```
检查 `apillama` 服务状态：
- `healthy`: OpenRouter API 正常
- `unknown`: 未配置 API Key（使用 fallback）
- `unhealthy`: API 连接失败
### Prometheus Metrics
- `data_ingestion_apillama_processing_total`: 处理总数（按状态）
- `data_ingestion_apillama_processing_duration_seconds`: 处理耗时
- `data_ingestion_cache_hits_total`: 缓存命中（类型：apillama）
- `data_ingestion_cache_misses_total`: 缓存未命中（类型：apillama）
### 日志
查看服务日志：
```bash
docker-compose logs -f data-ingestion | grep APILLAMA
```
## 故障排查
### 问题 1: "OpenRouter API key not provided"
**原因**: 未配置 `OPENROUTER_API_KEY` 环境变量
**解决**:
1. 在 `.env` 文件中添加 `OPENROUTER_API_KEY`
2. 重启服务：`docker-compose restart data-ingestion`
### 问题 2: API 调用失败
**原因**:
- API Key 无效
- 网络连接问题
- OpenRouter 服务不可用
**解决**:
- 系统会自动回退到 fallback 模式
- 检查 API Key 是否有效
- 检查网络连接
### 问题 3: 处理结果不理想
**原因**:
- Prompt 可能需要优化
- 模型参数需要调整
**解决**:
- 调整 `APILLAMA_TEMPERATURE`（默认 0.3）
- 调整 `APILLAMA_TOP_P`（默认 0.9）
- 增加 `APILLAMA_MAX_TOKENS`（默认 2048）
## 最佳实践
1. **配置 API Key**: 确保在 `.env` 文件中配置有效的 OpenRouter API Key
2. **监控成本**: 定期检查 OpenRouter 使用情况，通过缓存减少调用
3. **优化 Prompt**: 根据实际需求调整 prompt 模板
4. **使用缓存**: 充分利用 Redis 缓存，避免重复处理
5. **错误处理**: 系统已实现 fallback 机制，确保服务可用性
## 相关链接
- [OpenRouter 官网](https://openrouter.ai/)
- [Llama 3.1 8B Instruct 模型页面](https://openrouter.ai/meta-llama/llama-3.1-8b-instruct)
- [OpenRouter API 文档](https://openrouter.ai/docs)
- [项目文档](../README.md)
## 更新日志
- **2025-12-22**: 集成 OpenRouter API，使用 Llama 3.1 8B Instruct 模型
- **之前**: 使用本地部署模型（已废弃）
Docs/前后端调试说明/API接口文档.md
+23 -3991
View File
File diff suppressed because it is too large Load Diff
Docs/前后端调试说明/API文档/09-通用规范.md
-240
View File
@@ -1,240 +0,0 @@
# 通用规范
本文档定义了API的通用响应格式、错误码和业务规则。
---
## 目录
1. [通用响应格式](#通用响应格式)
2. [错误码说明](#错误码说明)
3. [业务规则](#业务规则)
---
## 通用响应格式
所有API端点（除非另有说明）返回以下格式：
### 成功响应
**基础格式**:
```json
{
"success": true,
"data": {},
"message": "操作成功"
}
```
### 错误响应（FastAPI默认）
```json
{
"detail": "错误描述"
}
```
### 标准包装响应（SuccessResponse）
```json
{
"success": true,
"message": "操作成功",
"data": {},
"timestamp": "2025-12-25T05:10:00Z"
}
```
### 分页响应格式
```json
{
"success": true,
"data": {
"total": 150,
"page": 1,
"pageSize": 20,
"totalPages": 8,
"items": []
}
}
```
---
## 错误码说明
### HTTP 状态码
| HTTP 状态码 | 错误码 | 说明 |
|------------|--------|------|
| 400 | `BAD_REQUEST` | 请求参数错误 |
| 401 | `UNAUTHORIZED` | 未授权 |
| 403 | `FORBIDDEN` | 禁止访问 |
| 404 | `NOT_FOUND` | 资源不存在 |
| 409 | `CONFLICT` | 资源冲突 |
| 422 | `VALIDATION_ERROR` | 数据验证失败 |
| 429 | `TOO_MANY_REQUESTS` | 请求过于频繁 |
| 500 | `INTERNAL_ERROR` | 服务器内部错误 |
| 503 | `SERVICE_UNAVAILABLE` | 服务不可用 |
### 业务错误码
| 错误码 | 说明 |
|--------|------|
| `INVALID_CREDENTIALS` | 用户名或密码错误 |
| `TOKEN_EXPIRED` | Token已过期 |
| `INSUFFICIENT_BALANCE` | 余额不足 |
| `QUOTA_EXCEEDED` | 配额超限 |
| `RATE_LIMIT_EXCEEDED` | 速率限制超限 |
| `RESOURCE_NOT_FOUND` | 资源未找到 |
| `PERMISSION_DENIED` | 权限不足 |
### 错误响应示例
```json
{
"detail": {
"code": "INSUFFICIENT_BALANCE",
"message": "账户余额不足，当前余额: 10.00，需要: 25.00",
"data": {
"balance": 10.00,
"required": 25.00
}
}
}
```
---
## 业务规则
### EU计算规则
**EU (Execution Unit)** 是系统的基本计费单位：
- **1 EU = 10秒调用时间**
- **不足10秒按1 EU计算**
- **计算公式**: `EU = CEILING(duration_seconds / 10)`
**示例**:
```
5秒 -> 1 EU
10秒 -> 1 EU
15秒 -> 2 EU
60秒 -> 6 EU
125秒 -> 13 EU
```
### 计费价格
EU单价根据用户订阅等级自动确定：
| 档位 | 订阅等级 | EU 单价 | 核心定位 |
|------|---------|---------|----------|
| **入门级（Starter）** | `free` / `starter` | **$0.015 / EU** | 拉新、试用、轻 Agent |
| **专业级（Pro）** | `pro` | **$0.02 / EU** | 主力商业用户 |
| **企业级（Enterprise）** | `enterprise` | **$0.03 / EU** | 高复杂度 / 高 SLA |
**价格计算示例**：
```
用户订阅等级: pro
调用时长: 45秒
EU数量: CEILING(45 / 10) = 5 EU
费用: 5 EU × $0.02 = $0.10
```
### 余额与授信
**可用额度计算**:
```
可用额度 = 账户余额 + 授信额度
```
**消费规则**:
1. 优先扣除账户余额
2. 余额不足时使用授信额度
3. 授信额度用完后服务暂停
### 速率限制
| 等级 | RPM (每分钟请求数) | TPM (每分钟Token数) |
|------|-------------------|---------------------|
| free | 20 | 20,000 |
| pro | 60 | 60,000 |
| enterprise | 200 | 200,000 |
### 资源配额默认值
| 资源类型 | 默认值 | 最大值 |
|---------|--------|--------|
| CPU (核心) | 2.0 | 64 |
| 内存 (GB) | 4.0 | 256 |
| 最大实例数 | 5 | 1000 |
---
## 时间格式
所有时间字段使用 **ISO 8601** 格式：
```
2025-12-25T05:10:00Z
2025-12-25T05:10:00+08:00
```
### 时间查询参数
- `startTime` / `start_date`: 查询起始时间
- `endTime` / `end_date`: 查询结束时间
**示例**:
```bash
curl "http://localhost:8002/api/user/billing/history?startTime=2025-12-01T00:00:00Z&endTime=2025-12-31T23:59:59Z"
```
---
## 分页参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `page` | int | 1 | 页码，从1开始 |
| `pageSize` / `page_size` | int | 20 | 每页数量 |
| `skip` | int | 0 | 跳过的记录数 |
| `limit` | int | 100 | 返回的最大记录数 |
---
## 排序参数
| 参数 | 说明 |
|------|------|
| `sort_by` | 排序字段 |
| `sort_order` | 排序方向：`asc` / `desc` |
---
## 导出功能
支持导出的接口通常提供 `export` 参数：
| 格式 | 说明 |
|------|------|
| `excel` | Excel格式 (.xlsx) |
| `csv` | CSV格式 |
| `pdf` | PDF格式 |
**导出响应示例**:
```json
{
"success": true,
"data": {
"fileUrl": "https://exports.taiji-ai.com/user-uuid/excel/billing_20251225123000.xlsx",
"format": "excel",
"expiresAt": "2025-12-26T12:30:00Z"
}
}
```
Docs/前后端调试说明/API文档/10-开发指南.md
-351
View File
@@ -1,351 +0,0 @@
# 开发指南
本文档提供API开发和集成的指南，包括交互式文档、代码示例、测试流程和测试账号信息。
---
## 目录
1. [交互式 API 文档](#交互式-api-文档)
2. [前端集成示例](#前端集成示例)
3. [完整 API 测试流程](#完整-api-测试流程)
4. [预置测试账号](#预置测试账号)
5. [注意事项](#注意事项)
6. [更新日志](#更新日志)
---
## 交互式 API 文档
### Swagger UI
- Data Ingestion: `http://localhost:8001/docs`
- MCP Server: `http://localhost:8002/docs`
### ReDoc
- Data Ingestion: `http://localhost:8001/redoc`
- MCP Server: `http://localhost:8002/redoc`
### OpenAPI JSON
- Data Ingestion: `http://localhost:8001/openapi.json`
- MCP Server: `http://localhost:8002/openapi.json`
---
## 前端集成示例
### JavaScript/TypeScript
```typescript
// 健康检查
const healthCheck = async () => {
const response = await fetch('http://localhost:8001/health');
const data = await response.json();
console.log(data);
};
// 登录获取Token
const login = async (email: string, password: string, role: string) => {
const response = await fetch('http://localhost:8002/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password, role })
});
const data = await response.json();
return data.data.token;
};
// 使用Token访问API
const getDashboard = async (token: string) => {
const response = await fetch('http://localhost:8002/api/user/dashboard/stats', {
headers: { 'Authorization': `Bearer ${token}` }
});
return await response.json();
};
// 完整示例
async function main() {
const token = await login('admin@taiji-ai.com', 'Admin@123456', 'super_admin');
const dashboard = await getDashboard(token);
console.log('Dashboard:', dashboard);
}
```
### Python
```python
import requests
BASE_URL = 'http://localhost:8002'
# 登录
def login(email: str, password: str, role: str) -> str:
response = requests.post(
f'{BASE_URL}/api/auth/login',
json={'email': email, 'password': password, 'role': role}
)
return response.json()['data']['token']
# 使用Token访问API
def get_dashboard(token: str) -> dict:
response = requests.get(
f'{BASE_URL}/api/user/dashboard/stats',
headers={'Authorization': f'Bearer {token}'}
)
return response.json()
# 创建渠道
def create_channel(token: str, name: str, email: str, password: str) -> dict:
response = requests.post(
f'{BASE_URL}/api/admin/channels/create',
headers={'Authorization': f'Bearer {token}'},
json={
'name': name,
'email': email,
'password': password,
'commissionRate': 10.0
}
)
return response.json()
# 使用示例
if __name__ == '__main__':
token = login('superadmin@taiji-ai.com', 'Admin@123456', 'super_admin')
dashboard = get_dashboard(token)
print('Dashboard:', dashboard)
```
### cURL
```bash
# 设置基础URL
BASE_URL="http://localhost:8002"
# 登录获取Token
TOKEN=$(curl -s -X POST "$BASE_URL/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}' \
| jq -r '.data.token')
echo "Token: $TOKEN"
# 使用Token访问API
curl -s "$BASE_URL/api/user/dashboard/stats" \
-H "Authorization: Bearer $TOKEN" | jq
```
---
## 完整 API 测试流程
以下是一个完整的 API 测试流程示例，涵盖从超级管理员登录到创建渠道、创建租户、分配资源的全过程。
### 测试脚本
```bash
#!/bin/bash
# 完整 API 测试流程
echo "=== 1. 超级管理员登录 ==="
ADMIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}')
echo $ADMIN_RESPONSE | python3 -m json.tool
ADMIN_TOKEN=$(echo $ADMIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])")
echo "管理员Token获取成功"
echo ""
echo "=== 2. 创建渠道 ==="
CHANNEL_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/admin/channels/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{
"name": "测试渠道Alpha",
"email": "channel-alpha@test.com",
"password": "Channel@123456",
"commissionRate": 10.0
}')
echo $CHANNEL_RESPONSE | python3 -m json.tool
echo ""
echo "=== 3. 渠道管理员登录 ==="
CHANNEL_LOGIN_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}')
echo $CHANNEL_LOGIN_RESPONSE | python3 -m json.tool
CHANNEL_TOKEN=$(echo $CHANNEL_LOGIN_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['token'])")
echo "渠道Token获取成功"
echo ""
echo "=== 4. 创建租户 ==="
TENANT_RESPONSE=$(curl -s -X POST "http://localhost:8002/api/channel/tenants/create" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{
"name": "张三",
"email": "zhangsan@company.com",
"password": "User@123456",
"subscriptionTier": "pro"
}')
echo $TENANT_RESPONSE | python3 -m json.tool
TENANT_ID=$(echo $TENANT_RESPONSE | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['id'])")
echo "租户ID: $TENANT_ID"
echo ""
echo "=== 5. 为租户分配资源 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/resources" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{
"agents": [
{"agentId": "通用助手", "quantity": 5},
{"agentId": "代码助手", "quantity": 3}
],
"models": [
{"modelName": "OpenAI", "rpm": 100, "tpm": 100000}
]
}' | python3 -m json.tool
echo ""
echo "=== 6. 更新租户计费设置 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/billing" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"subscriptionTier": "pro", "discount": 10.0}' | python3 -m json.tool
echo ""
echo "=== 7. 设置授信额度 ==="
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"creditLimit": 10000.0}' | python3 -m json.tool
echo ""
echo "=== 8. 为租户充值 ==="
curl -s -X POST "http://localhost:8002/api/channel/tenants/${TENANT_ID}/recharge" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CHANNEL_TOKEN" \
-d '{"amount": 5000.0}' | python3 -m json.tool
echo ""
echo "=== 9. 租户登录验证 ==="
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}' | python3 -m json.tool
echo ""
echo "=== 10. 查看渠道下的租户列表 ==="
curl -s "http://localhost:8002/api/channel/tenants" \
-H "Authorization: Bearer $CHANNEL_TOKEN" | python3 -m json.tool
echo ""
echo "=== API测试完成 ==="
```
---
## 预置测试账号
系统初始化时会创建以下测试账号：
| 角色 | 邮箱 | 密码 | 登录role参数 | 可执行操作 |
|------|------|------|-------------|-----------|
| 超级管理员 | superadmin@taiji-ai.com | Admin@123456 | super_admin | 创建管理员、创建渠道、全部管理 |
| 计费管理员 | billing@taiji-ai.com | Admin@123456 | billing_admin | 创建渠道、管理租户、计费操作（完整写入权限） |
| 运维管理员 | ops@taiji-ai.com | Admin@123456 | operations_admin | 查看概览、监控、计费（只读权限） |
| 渠道 | default@channel.com | Channel@123456 | channel | 创建租户、管理租户资源 |
| 测试用户 | user@test.com | User@123456 | user | 使用平台服务 |
> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user
---
## 注意事项
1. **端口映射**:
- Data Ingestion: 容器8000 → 主机8001
- MCP Server: 容器8000 → 主机8002
2. **CORS**: 当前配置允许所有来源，生产环境需要限制
3. **认证**: `/api/*` 路径需要认证（除login等豁免路径）
4. **限流**: 建议在生产环境添加限流保护
5. **超时设置**: 建议设置合理的请求超时时间
---
## 更新日志
- **v2.6.0** (2025-12-26): **新增计费与资源管理API**
- ✅ 新增配额管理API（用户配额、渠道配额、配额预警）
- ✅ 新增资源监控API（平台概览、用户资源、使用趋势、Agent统计）
- ✅ 新增事件管理API（待处理事件、重试失败、事件统计）
- ✅ 新增追踪管理API（执行追踪详情、追踪查询、追踪统计）
- ✅ 新增审计日志API（日志查询、汇总统计、用户活动历史）
- ✅ 新增供应商健康检查API（健康状态、健康详情、手动检查）
- ✅ 新增模型定价管理API（定价列表、创建/更新定价、成本计算）
- ✅ 新增数据模型：TokenBlacklist、ResourceUsage、QuotaAlert、ModelPricing、ProviderHealthCheck、AgentTrace、BillingEvent
- ✅ 增强JWT认证：登出时将Token加入黑名单
- **v2.5.0** (2025-12-26): **权限系统重构**
- ✅ 重新设计权限系统，区分计费管理员和运维管理员
- ✅ billing_admin（计费管理员）：完整写入权限（创建渠道、管理租户、计费操作、审批申请）
- ✅ operations_admin（运维管理员）：只读权限（仅查看和监控）
- ✅ 更新权限矩阵表格
- ✅ 更新接口权限验证逻辑
- ✅ 更新预置测试账号说明
- **v2.4.0** (2025-12-26): **新增管理员管理接口**
- ✅ 添加 GET /api/admin/admins - 获取管理员列表（仅超级管理员可用）
- ✅ 添加 POST /api/admin/admins/create - 创建管理员（支持billing_admin/operations_admin角色）
- ✅ 添加 DELETE /api/admin/admins/{admin_id} - 删除管理员（软删除）
- ✅ 区分 super_admin（超级管理员）权限
- ✅ 更新超级管理员API接口编号
- **v2.3.0** (2025-12-25): **新增管理接口**
- ✅ 添加 PUT /api/admin/channels/{channel_id} - 更新渠道信息
- ✅ 添加 DELETE /api/admin/channels/{channel_id} - 删除渠道（软删除）
- ✅ 添加 DELETE /api/admin/resources/agents/{agent_id} - 删除Agent资源（软删除）
- ✅ 添加 PUT /api/admin/resources/agents/{agent_id}/config - 更新Agent资源配置
- ✅ 更新超级管理员API接口编号
- **v2.2.0** (2025-12-25): **完整API测试验证**
- ✅ 添加完整API测试流程示例
- ✅ 更新所有curl命令示例
- ✅ 添加预置测试账号说明
- ✅ 完善请求参数说明
- ✅ 添加渠道登录响应示例
- ✅ 验证所有接口可用性
- **v2.1.0** (2025-12-25): **基于实际代码重写**
- ✅ 根据实际代码完全重写文档
- ✅ 修正所有端口信息（8001, 8002）
- ✅ 更新认证机制说明
- ✅ 完善实际实现的端点文档
- ✅ 移除未实现的占位接口
- ✅ 添加实际响应示例
- ✅ 更新业务规则和认证说明
- ✅ 添加前端集成示例
- **v2.0.0** (2025-12-25): 基于需求文档的完整实现
- **v1.3.0** (2025-12-24): 增加占位API文档
- **v1.2.0** (2025-12-22): 初始版本
---
## 相关文档
- 完整需求文档: [BACKEND_REQUIREMENTS.md](../../../BACKEND_REQUIREMENTS.md)
- 实现总结: [BACKEND_IMPLEMENTATION_SUMMARY.md](../../../BACKEND_IMPLEMENTATION_SUMMARY.md)
- 部署指南: [services/mcp-server/DEPLOY_AZURE.md](../../../services/mcp-server/DEPLOY_AZURE.md)
- 快速开始: [QUICK_START.md](../../../QUICK_START.md)
Docs/前后端调试说明/API文档/README.md
-111
View File
@@ -1,111 +0,0 @@
# taiji-AI-PAD API 接口文档
**版本**: v2.6.0
**更新时间**: 2025年12月26日
**基础URL**:
- Data Ingestion 服务: `http://localhost:8001` (容器内8000→主机8001)
- MCP Server 服务: `http://localhost:8002` (容器内8000→主机8002)
- API Gateway: `http://localhost:80`
- LiteLLM Gateway: `http://localhost:4000`
> **重要说明**: 本文档基于实际代码生成并经过完整API测试验证。所有端点均已实现并确认可用。
---
## 📋 文档索引
| 文档 | 说明 | 适用角色 |
|------|------|---------|
| [01-认证与授权](./01-认证与授权.md) | JWT认证、API Key认证、权限说明 | 所有角色 |
| [02-Data-Ingestion服务](./02-Data-Ingestion服务.md) | API同步、OpenAPI解析、工具生成 | 开发者 |
| [03-MCP-Server服务](./03-MCP-Server服务.md) | Agent管理、工具执行、监控、WebSocket | 开发者 |
| [04-用户侧平台](./04-用户侧平台.md) | 仪表板、网关、工具、Agent部署、计费 | 租户用户 |
| [05-渠道合作伙伴](./05-渠道合作伙伴.md) | 租户管理、资源分配、计费统计 | 渠道管理员 |
| [06-超级管理员](./06-超级管理员.md) | 平台统计、渠道管理、审批、监控 | 超级管理员 |
| [07-计费与资源管理](./07-计费与资源管理.md) | 配额、资源监控、事件、追踪、审计 | 计费管理员 |
| [08-供应商管理](./08-供应商管理.md) | 模型供应商CRUD、连接测试 | 管理员 |
| [09-通用规范](./09-通用规范.md) | 响应格式、错误码、业务规则 | 所有角色 |
| [10-开发指南](./10-开发指南.md) | 集成示例、测试流程、测试账号 | 开发者 |
---
## 🔐 快速认证
### 获取Token
```bash
# 超级管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"superadmin@taiji-ai.com","password":"Admin@123456","role":"super_admin"}'
# 渠道管理员登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"channel-alpha@test.com","password":"Channel@123456","role":"channel"}'
# 租户用户登录
curl -s -X POST "http://localhost:8002/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"zhangsan@company.com","password":"User@123456","role":"user"}'
```
### 使用Token
```bash
curl -X GET "http://localhost:8002/api/user/dashboard/stats" \
-H "Authorization: Bearer $TOKEN"
```
---
## 👥 角色与权限概览
| 角色 | 说明 | 登录role参数 |
|------|------|-------------|
| super_admin | 超级管理员 | super_admin |
| billing_admin | 计费管理员 | billing_admin |
| operations_admin | 运维管理员 | operations_admin |
| channel_admin | 渠道管理员 | channel |
| provider_admin | 供应商管理员 | provider |
| user | 租户用户 | user |
> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user
---
## 🌐 交互式文档
| 服务 | Swagger UI | ReDoc | OpenAPI JSON |
|------|-----------|-------|--------------|
| Data Ingestion | [docs](http://localhost:8001/docs) | [redoc](http://localhost:8001/redoc) | [openapi.json](http://localhost:8001/openapi.json) |
| MCP Server | [docs](http://localhost:8002/docs) | [redoc](http://localhost:8002/redoc) | [openapi.json](http://localhost:8002/openapi.json) |
---
## 📝 更新日志
- **v2.6.0** (2025-12-26): 新增计费与资源管理API
- **v2.5.0** (2025-12-26): 权限系统重构
- **v2.4.0** (2025-12-26): 新增管理员管理接口
- **v2.3.0** (2025-12-25): 新增管理接口
- **v2.2.0** (2025-12-25): 完整API测试验证
- **v2.1.0** (2025-12-25): 基于实际代码重写
详细更新日志请查看 [10-开发指南](./10-开发指南.md#更新日志)
---
## 📚 相关文档
- 完整需求文档: [BACKEND_REQUIREMENTS.md](../../../BACKEND_REQUIREMENTS.md)
- 实现总结: [BACKEND_IMPLEMENTATION_SUMMARY.md](../../../BACKEND_IMPLEMENTATION_SUMMARY.md)
- 部署指南: [services/mcp-server/DEPLOY_AZURE.md](../../../services/mcp-server/DEPLOY_AZURE.md)
- 快速开始: [QUICK_START.md](../../../QUICK_START.md)
---
**文档版本**: v2.6.0
**最后更新**: 2025年12月26日
**维护者**: taiji-AI-PAD 项目组
Docs/前后端调试说明/完整重新部署报告.md
-351
View File
@@ -1,351 +0,0 @@
# Taiji AI-PAD 完整重新部署报告
**部署日期**: 2025年12月25日
**部署类型**: 完整重新部署(所有镜像)
**部署版本**: v2.1.1
---
## 📊 部署结果
| 指标 | 结果 |
|------|------|
| **部署状态** | ✅ 成功 |
| **服务总数** | 8 个 |
| **健康服务** | 8 个 |
| **测试成功率** | **100%** (40/40) |
| **部署时间** | ~5分钟 |
---
## 🔧 部署过程
### 1. 发现的问题
#### 问题1: psycopg2编译失败
**错误信息**:
```
Error: pg_config executable not found
```
**原因**: `data-ingestion`服务使用`psycopg2`而不是`psycopg2-binary`,需要编译但缺少PostgreSQL开发包
**解决方案**:
- 修改`services/data-ingestion/requirements.txt`
- 将`psycopg2`改为`psycopg2-binary==2.9.9`
#### 问题2: 缺少PostgreSQL数据库服务
**错误信息**:
```
relation "users" does not exist
```
**原因**: docker-compose.yml中没有配置PostgreSQL数据库服务,但mcp-server和data-ingestion都需要连接数据库
**解决方案**:
- 在docker-compose.yml中添加PostgreSQL服务配置
- 配置数据库初始化脚本
- 添加健康检查
- 添加服务依赖关系
---
## 🚀 新增服务
### PostgreSQL 数据库
```yaml
postgres:
image: postgres:15-alpine
container_name: taiji-postgres
ports:
- "5432:5432"
environment:
- POSTGRES_USER=taiji_user
- POSTGRES_PASSWORD=taiji_pass
- POSTGRES_DB=taiji_db
volumes:
- postgres_data:/var/lib/postgresql/data
- ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql
networks:
- taiji-network
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U taiji_user -d taiji_db"]
interval: 10s
timeout: 5s
retries: 5
```
**功能**:
- 提供持久化数据存储
- 自动执行初始化SQL脚本
- 健康检查确保数据库就绪
- 数据卷持久化存储
---
## 📦 部署的服务
| 服务 | 镜像 | 端口 | 状态 | 健康检查 |
|------|------|------|------|---------|
| **postgres** | postgres:15-alpine | 5432 | ✅ 运行中 | ✅ 健康 |
| **nats** | nats:2.10-alpine | 4222, 6222, 8222 | ✅ 运行中 | - |
| **litellm-gateway** | taiji-ai-pad-litellm-gateway | 4000 | ✅ 运行中 | ✅ 健康 |
| **data-ingestion** | taiji-ai-pad-data-ingestion | 8001 | ✅ 运行中 | ✅ 健康 |
| **mcp-server** | taiji-ai-pad-mcp-server | 8002 | ✅ 运行中 | ✅ 健康 |
| **api-gateway** | nginx:alpine | 80, 443 | ✅ 运行中 | - |
| **prometheus** | prom/prometheus:latest | 9090 | ✅ 运行中 | - |
| **grafana** | grafana/grafana:latest | 3000 | ✅ 运行中 | - |
---
## 🔄 部署步骤
### 1. 停止所有服务
```bash
cd /home/taiji/tools/taiji-AI-PAD
sudo docker compose down
```
### 2. 修复依赖问题
- 修改`services/data-ingestion/requirements.txt`
- 添加PostgreSQL服务配置到`docker-compose.yml`
### 3. 重新构建镜像
```bash
sudo docker compose build
```
**构建结果**:
- ✅ data-ingestion镜像构建成功
- ✅ mcp-server镜像构建成功
- ✅ litellm-gateway镜像构建成功
### 4. 启动所有服务
```bash
sudo docker compose up -d
```
**启动结果**:
- ✅ 8个容器全部成功启动
- ✅ 所有健康检查通过
- ✅ 网络配置正常
- ✅ 数据卷创建成功
### 5. 验证部署
```bash
python3 scripts/test_all_apis.py
```
**测试结果**:
- ✅ 40项测试全部通过
- ✅ 成功率100%
- ✅ 所有API端点正常工作
---
## 📊 测试覆盖
### 通过的测试 (40/40)
#### Data Ingestion 服务 (6/6)
- ✅ 健康检查
- ✅ 获取统计信息
- ✅ 获取工具列表
- ✅ 获取Prometheus指标
- ✅ 同步RapidAPI端点
- ✅ APILLAMA处理API文档
#### MCP Server 基础服务 (3/3)
- ✅ 健康检查
- ✅ 获取Prometheus指标
- ✅ 获取工具列表
#### Agent 管理 (4/4)
- ✅ 获取Agent列表
- ✅ 创建Agent
- ✅ 获取特定Agent
- ✅ 执行Agent工具
#### 认证模块 (4/4)
- ✅ 管理员登录
- ✅ 渠道管理员登录
- ✅ 供应商登录
- ✅ 标准用户登录
#### 用户侧平台 (7/7)
- ✅ 获取仪表板统计
- ✅ 获取Agent活动数据
- ✅ 选择网关类型
- ✅ 获取网关API列表
- ✅ 获取网关监控数据
- ✅ 获取平台Agent列表
- ✅ 获取余额信息
#### 渠道合作伙伴 (3/3)
- ✅ 获取渠道仪表板统计
- ✅ 获取租户列表
- ✅ 获取渠道计费统计
#### 超级管理员 (7/7)
- ✅ 获取平台统计
- ✅ 获取渠道列表
- ✅ 获取所有申请
- ✅ 获取所有模型供应商
- ✅ 获取所有Agent资源
- ✅ 监控Agent健康状态
- ✅ 获取三维度计费统计
#### 供应商管理 (1/1)
- ✅ 获取模型供应商列表
#### MCP 监控 (5/5)
- ✅ 获取系统性能指标
- ✅ 获取服务统计信息
- ✅ 获取性能趋势数据
- ✅ 获取系统告警
- ✅ 获取监控仪表盘聚合
---
## 📈 系统性能
### 资源使用
```json
{
"cpu_usage_percent": 30.0,
"memory_usage_percent": 30.0,
"memory_used_mb": 9110.47,
"memory_total_mb": 32047.15,
"disk_usage_percent": 14.4,
"disk_used_gb": 17.70,
"disk_total_gb": 122.95
}
```
### 服务统计
```json
{
"active_agents": 1,
"total_executions_24h": 1,
"daily_active_users": 0,
"total_users": 4
}
```
---
## 📝 修改的文件
### 1. services/data-ingestion/requirements.txt
```diff
- psycopg2
+ psycopg2-binary==2.9.9
```
### 2. docker-compose.yml
- ✅ 添加PostgreSQL服务配置
- ✅ 添加健康检查
- ✅ 配置数据卷
- ✅ 更新服务依赖关系
### 3. services/mcp-server/app/routes/agents.py
- ✅ 修复测试用户创建（添加必需字段）
### 4. services/mcp-server/app/routes/frontend_integration.py
- ✅ 修复渠道登录（添加channelId到JWT token）
### 5. scripts/test_all_apis.py
- ✅ 修复execution_id重复问题
- ✅ 添加Prometheus指标非JSON处理
---
## 🎯 验证清单
### 基础设施
- ✅ PostgreSQL数据库运行正常
- ✅ Redis缓存可用
- ✅ NATS消息队列运行
- ✅ 网络配置正确
- ✅ 数据卷持久化
### 服务健康
- ✅ 所有容器运行中
- ✅ 健康检查通过
- ✅ 端口映射正确
- ✅ 服务间通信正常
### 功能验证
- ✅ 数据库表创建成功
- ✅ 认证系统工作正常
- ✅ Agent CRUD操作正常
- ✅ 计费系统记录正确
- ✅ 监控指标采集正常
---
## 🔒 安全配置
### 数据库安全
- ✅ 使用环境变量配置密码
- ✅ 数据库仅在内部网络访问
- ✅ 启用健康检查
### 网络安全
- ✅ 使用独立网络隔离
- ✅ 仅必要端口暴露
- ✅ 使用内部DNS解析
---
## 📚 后续建议
### 1. 生产环境准备
- [ ] 配置外部PostgreSQL数据库
- [ ] 配置Redis集群
- [ ] 启用HTTPS
- [ ] 配置域名和SSL证书
- [ ] 设置备份策略
### 2. 监控和日志
- [ ] 配置Prometheus告警规则
- [ ] 设置Grafana仪表板
- [ ] 配置日志聚合
- [ ] 设置日志轮转
### 3. 性能优化
- [ ] 数据库连接池优化
- [ ] Redis缓存策略优化
- [ ] 配置负载均衡
- [ ] 优化镜像大小
### 4. 安全加固
- [ ] 定期更新镜像
- [ ] 配置防火墙规则
- [ ] 启用审计日志
- [ ] 配置密钥轮转
---
## ✅ 结论
本次完整重新部署成功完成：
1. ✅ 修复了所有依赖问题
2. ✅ 添加了PostgreSQL数据库服务
3. ✅ 所有镜像重新构建成功
4. ✅ 8个服务全部运行正常
5. ✅ 40项测试全部通过(100%成功率)
6. ✅ 系统性能稳定
**系统已完全就绪,可以正常使用！**
---
**部署人员**: AI Assistant
**审核人员**: 待定
**下次维护时间**: 根据需要
**紧急联系**: 见运维手册
Docs/前后端调试说明/环境变量配置说明.md
-169
View File
@@ -1,169 +0,0 @@
# taiji-AI-PAD 环境变量配置说明
**版本**: v1.2.1
**最后更新**: 2025年12月22日
## 📋 概述
为了简化配置管理，所有 API Key 和敏感信息现在统一在 `.env` 文件中管理。您只需要在一个地方填写所有密钥，无需在多个配置文件中重复填写。
## 🚀 快速开始
### 1. 创建环境变量文件
如果项目中没有 `.env` 文件，请复制模板：
```bash
cp .env.example .env
```
### 2. 编辑 `.env` 文件
打开 `.env` 文件，填写您的实际 API Key：
```bash
nano .env
# 或使用您喜欢的编辑器
```
### 3. 配置项说明
#### 必需配置项
| 配置项 | 说明 | 示例 |
|--------|------|------|
| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | `sk-or-v1-...` |
| `RAPIDAPI_KEY` | RapidAPI 密钥 | `33902cc39dmsh...` |
| `LITELLM_MASTER_KEY` | LiteLLM 主密钥 | `sk-taiji-master-key` |
#### 可选配置项
| 配置项 | 说明 | 何时需要 |
|--------|------|----------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | 使用 OpenAI 模型时 |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 使用 Claude 模型时 |
| `LANGFUSE_*` | Langfuse 监控配置 | 启用监控功能时 |
## 📝 当前配置的密钥位置
### ✅ 已统一管理的密钥
以下密钥现在都在 `.env` 文件中：
1. **OpenRouter API Key** - 用于模型网关
2. **RapidAPI Key** - 用于数据接入服务
3. **LiteLLM Master Key** - 用于模型网关认证
### 📍 配置文件位置
- **`.env`** - 实际环境变量文件（包含真实密钥，已加入 .gitignore）
- **`.env.example`** - 配置模板文件（可提交到 Git）
- **`docker-compose.yml`** - 使用 `${VAR}` 语法引用环境变量
## 🔧 如何添加新的 API Key
### 步骤 1: 在 `.env` 文件中添加
```bash
# 在 .env 文件中添加
NEW_API_KEY=your-new-api-key-here
```
### 步骤 2: 在 `docker-compose.yml` 中引用
```yaml
services:
your-service:
environment:
- NEW_API_KEY=${NEW_API_KEY}
```
### 步骤 3: 在代码中读取
```python
import os
api_key = os.getenv("NEW_API_KEY", "")
```
## 🔒 安全注意事项
1. **⚠️ 永远不要提交 `.env` 文件到 Git**
- `.env` 文件已在 `.gitignore` 中
- 只提交 `.env.example` 作为模板
2. **生产环境建议**
- 使用密钥管理服务（如 AWS Secrets Manager）
- 使用环境变量注入（如 Kubernetes Secrets）
- 定期轮换 API Key
3. **权限控制**
- 确保 `.env` 文件权限为 `600`（仅所有者可读写）
```bash
chmod 600 .env
```
## 📊 配置项清单
### 当前已配置的密钥
- ✅ OpenRouter API Key
- ✅ RapidAPI Key
- ✅ LiteLLM Master Key
### 可选配置的密钥
- ⚪ OpenAI API Key（如需要直接使用 OpenAI）
- ⚪ Anthropic API Key（如需要直接使用 Anthropic）
- ⚪ Langfuse 监控密钥（如需要启用监控）
## 🧪 验证配置
配置完成后，验证环境变量是否正确加载：
```bash
# 检查环境变量
docker-compose config | grep -E "OPENROUTER|RAPIDAPI|LITELLM"
# 重启服务以应用新配置
docker-compose restart litellm-gateway data-ingestion
# 检查服务健康状态
curl http://localhost:4000/health # LiteLLM Gateway
curl http://localhost:8001/health # Data Ingestion
```
## 📚 相关文档
- [Docker Compose 环境变量文档](https://docs.docker.com/compose/environment-variables/)
- [项目 README](../README.md)
- [测试准备说明](./测试准备说明.md)
## ❓ 常见问题
### Q: 为什么需要 `.env` 文件？
A: `.env` 文件可以：
- 集中管理所有密钥
- 避免在代码中硬编码敏感信息
- 方便不同环境使用不同配置
- 提高安全性（不提交到 Git）
### Q: 如何在不同环境使用不同配置？
A: 可以创建多个环境文件：
- `.env.development` - 开发环境
- `.env.production` - 生产环境
- `.env.testing` - 测试环境
然后使用：
```bash
docker-compose --env-file .env.production up
```
### Q: 忘记填写某个 Key 会怎样？
A: 如果某个环境变量未设置，Docker Compose 会使用空字符串或默认值。服务可能会启动失败或功能受限。请检查服务日志：
```bash
docker-compose logs service-name
```
services/mcp-server/models.py
+2 -2
View File
@@ -266,8 +266,8 @@ class Channel(BaseModel, Base):
password_hash = Column(String(255), nullable=False)
commission_rate = Column(sa.Numeric(5, 2), default=0)
channel_credit = Column(sa.Numeric(12, 2), default=0) # 渠道授信额度
custom_agent_cpu = Column(sa.Numeric(5, 2), default=2) # 自定义Agent CPU
custom_agent_memory = Column(sa.Numeric(5, 2), default=4) # 自定义Agent 内存（GB）
custom_agent_cpu = Column(sa.Numeric(12, 2), default=2) # 自定义Agent CPU
custom_agent_memory = Column(sa.Numeric(12, 2), default=4) # 自定义Agent 内存（GB）
status = Column(String(20), default="active")
# 关联关系
services/mcp-server/scripts/migrate_numeric_fields.py
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env python3
"""
数据库迁移脚本：修复 channels 表的 custom_agent_cpu 和 custom_agent_memory 字段精度
问题：原字段定义为 NUMERIC(5,2)，最大只能存储 999.99
修复：将字段改为 NUMERIC(12,2)，支持更大的值
使用方法：
docker exec -it taiji-mcp-server python scripts/migrate_numeric_fields.py
"""
import asyncio
import os
import sys
# 添加项目根目录到路径
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from sqlalchemy import text
from sqlalchemy.ext.asyncio import create_async_engine
async def migrate():
"""执行数据库迁移"""
database_url = os.getenv(
"DATABASE_URL",
"postgresql+asyncpg://postgres:postgres@db:5432/taiji_mcp"
)
print(f"连接数据库: {database_url.split('@')[1] if '@' in database_url else database_url}")
engine = create_async_engine(database_url, echo=True)
async with engine.begin() as conn:
print("\n=== 开始迁移 ===\n")
# 修改 custom_agent_cpu 字段精度
print("1. 修改 custom_agent_cpu 字段: NUMERIC(5,2) -> NUMERIC(12,2)")
await conn.execute(text("""
ALTER TABLE channels
ALTER COLUMN custom_agent_cpu TYPE NUMERIC(12, 2)
"""))
print(" ✓ custom_agent_cpu 已更新\n")
# 修改 custom_agent_memory 字段精度
print("2. 修改 custom_agent_memory 字段: NUMERIC(5,2) -> NUMERIC(12,2)")
await conn.execute(text("""
ALTER TABLE channels
ALTER COLUMN custom_agent_memory TYPE NUMERIC(12, 2)
"""))
print(" ✓ custom_agent_memory 已更新\n")
print("=== 迁移完成 ===")
await engine.dispose()
if __name__ == "__main__":
asyncio.run(migrate())