269 lines
8.2 KiB
Markdown
269 lines
8.2 KiB
Markdown
# server-main 对接清单
|
||
|
||
## 1. 需要在 server-main 增加的内部接口
|
||
|
||
### 1.1 API Key 校验
|
||
|
||
```http
|
||
POST /internal/platform/auth/verify-api-key
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
|
||
{ "apiKey": "sk-..." }
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"sub": "user-id",
|
||
"username": "demo",
|
||
"role": ["user"],
|
||
"tenantId": "tenant-id",
|
||
"gatewayTenantId": "optional-gateway-tenant-id",
|
||
"tenantKey": "team-a",
|
||
"source": "server-main",
|
||
"gatewayUserId": "optional-gateway-user-id",
|
||
"userGroupId": "optional-primary-group-id",
|
||
"userGroupKey": "pro",
|
||
"userGroupKeys": ["pro", "image-plus"],
|
||
"apiKeyId": "key-id",
|
||
"apiKeySecret": "sk-...",
|
||
"apiKeyName": "production-key"
|
||
}
|
||
```
|
||
|
||
### 1.2 文件上传
|
||
|
||
```http
|
||
POST /v1/files/upload
|
||
Authorization: Bearer ${USER_JWT_OR_SK}
|
||
Content-Type: multipart/form-data
|
||
|
||
file=@result.png
|
||
```
|
||
|
||
AI Gateway 不维护独立 OSS 配置，也不向 `server-main` 申请预签名。需要上传本地中间产物、provider 临时 URL 转存、base64 解码结果时，统一组装 multipart 请求调用主服务开放上传接口，并记录主服务返回的 file id / URL / object key。
|
||
|
||
### 1.3 租户同步
|
||
|
||
AI Gateway 在独立模式下自己维护租户；接入 `server-main` 时保存主服务租户/组织同步副本，用于任务隔离、平台可见性、租户级限流和审计。
|
||
|
||
建议新增同步接口：
|
||
|
||
```http
|
||
POST /internal/platform/tenants/sync
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
Idempotency-Key: tenant:${source}:${externalTenantId}:${version}
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"source": "server-main",
|
||
"externalTenantId": "tenant-id",
|
||
"tenantKey": "team-a",
|
||
"name": "Team A",
|
||
"status": "active",
|
||
"planKey": "pro",
|
||
"rateLimitPolicy": {
|
||
"rules": [
|
||
{ "metric": "rpm", "limit": 500, "windowSeconds": 60 },
|
||
{ "metric": "concurrent", "limit": 20, "leaseTtlSeconds": 900 }
|
||
]
|
||
},
|
||
"sourceUpdatedAt": "2026-05-09T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
要求：
|
||
|
||
- Gateway 使用 `source + externalTenantId` 幂等 upsert 到 `gateway_tenants`。
|
||
- 租户禁用后，新任务拒绝入队；已运行任务按任务策略快照继续或由管理员取消。
|
||
- 用户同步必须带可映射的 `tenantId` / `tenantKey`，使任务、用户、用户组、限流和平台可见性都能落到同一租户上下文。
|
||
|
||
### 1.4 用户同步
|
||
|
||
AI Gateway 需要在独立模式下自己维护用户，在接入 `server-main` 时保存主服务用户的同步副本。同步副本只用于模型调用策略、审计、任务归属和用户组解析，不承接主服务余额、订单、充值流水。
|
||
|
||
建议新增同步接口：
|
||
|
||
```http
|
||
POST /internal/platform/users/sync
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
Idempotency-Key: user:${source}:${externalUserId}:${version}
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"source": "server-main",
|
||
"externalUserId": "user-id",
|
||
"username": "demo",
|
||
"displayName": "Demo User",
|
||
"email": "demo@example.com",
|
||
"tenantId": "tenant-id",
|
||
"tenantKey": "team-a",
|
||
"roles": ["user"],
|
||
"status": "active",
|
||
"sourceUpdatedAt": "2026-05-09T12:00:00Z",
|
||
"userGroupKeys": ["pro", "image-plus"]
|
||
}
|
||
```
|
||
|
||
要求：
|
||
|
||
- Gateway 使用 `source + externalUserId` 幂等 upsert 到 `gateway_users`。
|
||
- `status=disabled/locked/deleted` 后，Gateway 应拒绝创建新任务；已运行任务按任务策略快照继续或由管理员取消。
|
||
- 用户角色以主服务返回为准，但 Gateway 可以叠加本地管理角色，二者需要在 `auth_profile` 或 `metadata` 里可审计。
|
||
- 用户组关系可以随用户同步一起带，也可以通过用户组同步接口单独维护，最终都落到 `gateway_user_group_memberships`。
|
||
|
||
### 1.5 用户组与折扣策略同步
|
||
|
||
用户组是跨服务策略：Gateway 需要按用户组执行模型调用折扣、TPM/RPM/并发、队列优先级；`server-main` 需要按用户组执行充值折扣、资源包赠送、余额流水。两边必须保持同一个 `groupKey`。
|
||
|
||
建议新增同步接口：
|
||
|
||
```http
|
||
POST /internal/platform/user-groups/sync
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
Idempotency-Key: ${groupKey}:${version}
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"groupKey": "enterprise",
|
||
"name": "企业组",
|
||
"rechargeDiscountPolicy": {
|
||
"type": "tiered_bonus",
|
||
"tiers": [{ "minAmount": 1000, "bonusRatio": 0.12 }]
|
||
},
|
||
"billingDiscountPolicy": {
|
||
"defaultDiscountFactor": 0.9
|
||
},
|
||
"rateLimitPolicy": {
|
||
"rules": [
|
||
{ "metric": "rpm", "limit": 1200, "windowSeconds": 60 },
|
||
{ "metric": "concurrent", "limit": 50, "leaseTtlSeconds": 900 }
|
||
]
|
||
},
|
||
"memberships": [
|
||
{ "principalType": "user", "principalId": "user-id" },
|
||
{ "principalType": "tenant", "principalId": "tenant-id" }
|
||
]
|
||
}
|
||
```
|
||
|
||
要求：
|
||
|
||
- `server-main` 是充值、余额和订单事实源，负责执行 `rechargeDiscountPolicy`。
|
||
- Gateway 是模型执行事实源，负责执行 `billingDiscountPolicy`、`rateLimitPolicy`、队列和并发策略。
|
||
- 用户登录 / API Key 校验返回 claim 时，建议带上命中的 `userGroupKey` / `userGroupId`；Gateway 也可以根据同步缓存二次解析。
|
||
|
||
### 1.6 任务进度回调到 server-main
|
||
|
||
AI Gateway 不直接替换原业务前端 WebSocket 通道。Gateway 配置任务进度回调地址，所有任务中间状态先写入 Gateway 本地事件表和 callback outbox，再回调给 `server-main`，由 `server-main` 内部推送流程复用原 WebSocket 网关推送给业务前端。
|
||
|
||
```http
|
||
POST /internal/platform/task-progress-callbacks
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
Idempotency-Key: ${taskId}:${seq}
|
||
X-EasyAI-Event-Type: task.progress
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"eventId": "uuid",
|
||
"taskId": "gateway-task-id",
|
||
"externalTaskId": "server-main-task-id",
|
||
"userId": "user-id",
|
||
"tenantId": "tenant-id",
|
||
"apiKeyId": "optional",
|
||
"kind": "images.generations",
|
||
"model": "gpt-image-1",
|
||
"seq": 12,
|
||
"event": "progress",
|
||
"status": "running",
|
||
"phase": "polling",
|
||
"progress": 0.42,
|
||
"message": "Generating video frames",
|
||
"payload": {},
|
||
"createdAt": "2026-05-09T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
`server-main` 处理要求：
|
||
|
||
- 使用 `Idempotency-Key` 或 `taskId + seq` 幂等去重。
|
||
- 根据 `externalTaskId` / `taskId` / `userId` / `tenantId` 定位原业务频道。
|
||
- 复用现有 WebSocket 网关事件格式推给前端，尽量不改业务前端订阅协议。
|
||
- 只负责推送与必要状态同步，不重新执行任务、不重新计算计费。
|
||
|
||
Gateway 侧配置：
|
||
|
||
```env
|
||
TASK_PROGRESS_CALLBACK_ENABLED=true
|
||
TASK_PROGRESS_CALLBACK_URL=http://easyai-server-main:3000/internal/platform/task-progress-callbacks
|
||
TASK_PROGRESS_CALLBACK_TIMEOUT_MS=5000
|
||
TASK_PROGRESS_CALLBACK_MAX_ATTEMPTS=10
|
||
```
|
||
|
||
### 1.7 结算事件
|
||
|
||
```http
|
||
POST /internal/platform/settlements
|
||
Authorization: Bearer ${SERVER_MAIN_INTERNAL_TOKEN}
|
||
Content-Type: application/json
|
||
Idempotency-Key: ${eventId}
|
||
```
|
||
|
||
结算事件中的 `billings` 由 AI Gateway 根据基准模型库、平台折扣、平台模型覆盖后的 effective pricing 计算。`server-main` 仍负责余额、资源包、账单锁和消费流水，不重新推导模型价格，只按幂等事件扣费。
|
||
|
||
## 2. server-main OpenaiService 薄门面
|
||
|
||
保留现有对内方法签名，内部新增 `AiGatewayClient`：
|
||
|
||
- `createChatCompletion`
|
||
- `generateImage`
|
||
- `editImage`
|
||
- `generateVideo`
|
||
- `createEmbedding`
|
||
- `estimateBilling`
|
||
|
||
切流开关：
|
||
|
||
```env
|
||
AI_GATEWAY_ENABLED=true
|
||
AI_GATEWAY_BASE_URL=http://easyai-ai-gateway:8088
|
||
AI_GATEWAY_INTERNAL_TOKEN=change-me
|
||
AI_GATEWAY_TASK_PROGRESS_CALLBACK_ENABLED=true
|
||
```
|
||
|
||
## 3. 迁移期双写与比对
|
||
|
||
高风险接口可短期 shadow：
|
||
|
||
1. 主路径仍走旧实现。
|
||
2. 异步把同一请求投递到 Gateway dry-run。
|
||
3. 比对候选平台、TPM/RPM/并发限流决策、预估扣费、参数预处理结果。
|
||
4. 结果稳定后切主路径。
|
||
|
||
## 4. 不迁移项
|
||
|
||
- `refresh_token` 签发和刷新。
|
||
- 用户余额查询。
|
||
- `server-main` 用户 API Key 的创建、撤销、列表。Gateway 独立模式会维护自己的本地 API Key。
|
||
- `server-main` 账单锁、扣费流水。Gateway 独立模式会维护自己的钱包账户、充值订单和钱包流水。
|
||
- OSS/COS/S3 上传配置和实际文件落库。
|
||
- 对话与绘图历史最终落库。
|