diff --git a/control-plane/.env.example b/control-plane/.env.example index f50e675..43d0fec 100644 --- a/control-plane/.env.example +++ b/control-plane/.env.example @@ -9,3 +9,7 @@ AUTH_PASSWORD_PEPPER=replace-with-a-long-random-secret ADMIN_ACCOUNT=adimin ADMIN_PASSWORD=replace-with-a-strong-initial-password ADMIN_DISPLAY_NAME=平台管理员 + +# Tripo 3D Provider(仅服务端读取,禁止提交真实值) +TRIPO_API_KEY= +TRIPO_BASE_URL=https://openapi.tripo3d.com/v3 diff --git a/control-plane/.env.memory.example b/control-plane/.env.memory.example index acd97ad..dd10b6f 100644 --- a/control-plane/.env.memory.example +++ b/control-plane/.env.memory.example @@ -9,3 +9,7 @@ AUTH_PASSWORD_PEPPER=replace-with-a-long-random-secret ADMIN_ACCOUNT=adimin ADMIN_PASSWORD=replace-with-a-strong-initial-password ADMIN_DISPLAY_NAME=平台管理员 + +# Tripo 3D Provider(仅服务端读取,禁止提交真实值) +TRIPO_API_KEY= +TRIPO_BASE_URL=https://openapi.tripo3d.com/v3 diff --git a/control-plane/README.md b/control-plane/README.md index 529d430..d5edb43 100644 --- a/control-plane/README.md +++ b/control-plane/README.md @@ -61,3 +61,5 @@ pnpm dev - D4 的 Mock Key、项目和模型目录暂存于内存仓库;PostgreSQL 迁移已准备 `model_providers`、`model_catalog`、`model_projects` 和 `platform_api_keys` 表,接真实持久化时复用同一接口。 - 额度界面统一按人民币 `¥` 展示;内测额度由管理员手动发放,真实计量、扣费和账单在后续节点实现。 - 上游供应商密钥不进入模型目录或用户响应,后续由 Provider Adapter 通过环境变量/密钥管理服务读取。 +- Tripo 3D 适配器读取 `TRIPO_API_KEY` 和可选的 `TRIPO_BASE_URL`;真实值只放本地 `.env` 或服务器密钥管理,不得写入 Git。 +- 当前 Tripo 任务归属映射仍随 Control Plane 进程保存在内存中,服务重启后会清空;D6 接入持久化任务表与队列后解决。 diff --git a/control-plane/src/catalog.ts b/control-plane/src/catalog.ts index 5dd4eb8..47c493c 100644 --- a/control-plane/src/catalog.ts +++ b/control-plane/src/catalog.ts @@ -114,7 +114,7 @@ export class MemoryCatalogRepository implements CatalogRepository { code: 'vast', name: 'VAST / Tripo', protocol: 'http', - description: '预留 3D 生成供应商适配位,D4 先登记目录。', + description: 'Tripo v3 文生 3D 供应商适配器;未配置服务端密钥时自动使用 Mock。', status: 'active', createdAt: now, updatedAt: now, @@ -139,11 +139,11 @@ export class MemoryCatalogRepository implements CatalogRepository { this.models.set('model-mock-3d', { id: 'model-mock-3d', providerId: vastProvider.id, - publicName: 'VAST 3D Generator (Mock)', - upstreamModel: 'tripo-mock-3d-v1', + publicName: 'Tripo 3D Generator', + upstreamModel: 'v3.1-20260211', type: '3d', mode: 'async', - description: '异步 3D 生成模型,预留任务创建、轮询和回调字段。', + description: 'Tripo v3.1 异步 3D 生成模型,支持任务创建、进度轮询和 GLB 结果。', inputTypes: ['text', 'image'], outputTypes: ['model', 'thumbnail'], capabilities: { taskPolling: true, webhook: true, formats: ['glb', 'obj', 'fbx'] }, diff --git a/control-plane/src/providers/tripo.ts b/control-plane/src/providers/tripo.ts new file mode 100644 index 0000000..921cfd0 --- /dev/null +++ b/control-plane/src/providers/tripo.ts @@ -0,0 +1,174 @@ +export type TripoTaskStatus = 'queued' | 'running' | 'success' | 'failed' | 'cancelled' + +export interface TripoTaskOutput { + model_url?: string + rendered_image_url?: string + [key: string]: unknown +} + +export interface TripoTask { + task_id: string + type: string + status: TripoTaskStatus + progress: number + output?: TripoTaskOutput + error_code?: number + error_message?: string + credits_consumed?: number + created_at?: string + completed_at?: string +} + +export interface TripoApiResponse { + code: number + message?: string + data?: T +} + +export interface TripoTextToModelInput { + prompt: string + model?: string + negative_prompt?: string + model_seed?: number + image_seed?: number + face_limit?: number + texture?: boolean + pbr?: boolean + texture_quality?: 'standard' | 'detailed' | 'extreme' + geometry_quality?: 'standard' | 'detailed' + auto_size?: boolean + quad?: boolean + smart_low_poly?: boolean + generate_parts?: boolean + compress?: 'geometry' + export_uv?: boolean +} + +export interface MoyiTaskView { + id: string + provider: 'tripo' + status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' + progress: number + model?: string + output?: { modelUrl?: string; previewUrl?: string } + creditsConsumed?: number + error?: { code?: number; message?: string } + createdAt?: string + completedAt?: string +} + +export interface TripoProviderOptions { + apiKey: string + baseUrl?: string + timeoutMs?: number + fetcher?: typeof fetch +} + +export class TripoProviderError extends Error { + constructor( + message: string, + readonly statusCode?: number, + readonly providerCode?: number, + ) { + super(message) + } +} + +export class TripoProvider { + private readonly baseUrl: string + private readonly timeoutMs: number + private readonly fetcher: typeof fetch + + constructor(private readonly options: TripoProviderOptions) { + if (!options.apiKey.trim()) throw new TripoProviderError('TRIPO_API_KEY 未配置') + this.baseUrl = (options.baseUrl || 'https://openapi.tripo3d.com/v3').replace(/\/$/, '') + this.timeoutMs = options.timeoutMs ?? 30_000 + this.fetcher = options.fetcher || fetch + } + + async createTextToModel(input: TripoTextToModelInput) { + const prompt = input.prompt.trim() + if (!prompt) throw new TripoProviderError('Tripo prompt 不能为空') + if (prompt.length > 1024) throw new TripoProviderError('Tripo prompt 不能超过 1024 个字符') + const response = await this.request('/generation/text-to-model', { + method: 'POST', + body: JSON.stringify({ + model: input.model || 'v3.1-20260211', + texture: true, + pbr: true, + ...input, + prompt, + }), + }) + if (!response.data?.task_id) throw new TripoProviderError(response.message || 'Tripo 未返回任务 ID', undefined, response.code) + return response.data.task_id + } + + async getTask(taskId: string): Promise { + if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{7,127}$/.test(taskId)) throw new TripoProviderError('Tripo task_id 格式无效') + const response = await this.request(`/tasks/${encodeURIComponent(taskId)}`) + if (!response.data) throw new TripoProviderError(response.message || 'Tripo 未返回任务数据', undefined, response.code) + return mapTripoTask(response.data) + } + + async waitForTask(taskId: string, options: { intervalMs?: number; timeoutMs?: number } = {}) { + const intervalMs = options.intervalMs ?? 3_000 + const timeoutMs = options.timeoutMs ?? 10 * 60_000 + const deadline = Date.now() + timeoutMs + while (Date.now() <= deadline) { + const task = await this.getTask(taskId) + if (task.status === 'succeeded' || task.status === 'failed' || task.status === 'cancelled') return task + await new Promise((resolve) => setTimeout(resolve, intervalMs)) + } + throw new TripoProviderError(`Tripo 任务轮询超时:${taskId}`) + } + + private async request(path: string, init: { method?: string; body?: string } = {}): Promise> { + const controller = new AbortController() + const timer = setTimeout(() => controller.abort(), this.timeoutMs) + try { + const response = await this.fetcher(`${this.baseUrl}${path}`, { + method: init.method || 'GET', + headers: { + Accept: 'application/json', + Authorization: `Bearer ${this.options.apiKey}`, + ...(init.body ? { 'Content-Type': 'application/json' } : {}), + }, + ...(init.body ? { body: init.body } : {}), + signal: controller.signal, + }) + const payload = await response.json().catch(() => ({})) as TripoApiResponse + if (!response.ok || payload.code !== 0) { + throw new TripoProviderError(payload.message || `Tripo 请求失败(HTTP ${response.status})`, response.status, payload.code) + } + return payload + } catch (error) { + if (error instanceof TripoProviderError) throw error + if (error instanceof Error && error.name === 'AbortError') throw new TripoProviderError('Tripo 请求超时') + throw new TripoProviderError(error instanceof Error ? error.message : 'Tripo 请求失败') + } finally { + clearTimeout(timer) + } + } +} + +export function mapTripoTask(task: TripoTask): MoyiTaskView { + const status = task.status === 'success' ? 'succeeded' : task.status + return { + id: task.task_id, + provider: 'tripo', + status, + progress: Math.max(0, Math.min(100, Number(task.progress) || 0)), + ...(task.output ? { output: { + ...(task.output.model_url ? { modelUrl: task.output.model_url } : {}), + ...(task.output.rendered_image_url ? { previewUrl: task.output.rendered_image_url } : {}), + } } : {}), + ...(task.credits_consumed !== undefined ? { creditsConsumed: task.credits_consumed } : {}), + ...(task.error_code || task.error_message ? { error: { + ...(task.error_code !== undefined ? { code: task.error_code } : {}), + ...(task.error_message ? { message: task.error_message } : {}), + } } : {}), + ...(task.created_at ? { createdAt: task.created_at } : {}), + ...(task.completed_at ? { completedAt: task.completed_at } : {}), + } +} diff --git a/control-plane/src/server.ts b/control-plane/src/server.ts index ac1def4..2818a78 100644 --- a/control-plane/src/server.ts +++ b/control-plane/src/server.ts @@ -3,6 +3,7 @@ import { createServer, type IncomingMessage, type ServerResponse } from 'node:ht import { parse as parseUrl } from 'node:url' import { AuthError, AuthService, MemoryAuthRepository, type AuthRepository } from './auth.js' import { CatalogService, MemoryCatalogRepository, type CallMode, type ModelType, type ProviderProtocol } from './catalog.js' +import { TripoProvider, TripoProviderError } from './providers/tripo.js' const config = { host: process.env.CONTROL_PLANE_HOST || '127.0.0.1', @@ -12,6 +13,8 @@ const config = { passwordPepper: process.env.AUTH_PASSWORD_PEPPER || 'development-only-pepper', databaseUrl: process.env.DATABASE_URL, nodeEnv: process.env.NODE_ENV || 'development', + tripoApiKey: process.env.TRIPO_API_KEY, + tripoBaseUrl: process.env.TRIPO_BASE_URL, } let repository: AuthRepository = new MemoryAuthRepository() @@ -34,6 +37,11 @@ type MockTask = { result?: { format: string; url: string } } const mockTasks = new Map() +const tripo = config.tripoApiKey ? new TripoProvider({ + apiKey: config.tripoApiKey, + ...(config.tripoBaseUrl ? { baseUrl: config.tripoBaseUrl } : {}), +}) : undefined +const tripoTaskOwners = new Map() if (config.nodeEnv === 'production' && (!process.env.AUTH_PASSWORD_PEPPER || process.env.AUTH_PASSWORD_PEPPER.length < 32)) { throw new Error('AUTH_PASSWORD_PEPPER must contain at least 32 characters in production') @@ -57,7 +65,7 @@ const server = createServer(async (request, response) => { response.setHeader('Vary', 'Origin') } if (request.method === 'OPTIONS') { - response.setHeader('Access-Control-Allow-Headers', 'Content-Type') + response.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization') response.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS') response.writeHead(204) response.end() @@ -74,6 +82,7 @@ const server = createServer(async (request, response) => { server.listen(config.port, config.host, () => { console.log(`MOYI Control Plane listening on http://${config.host}:${config.port}`) console.log(config.databaseUrl ? 'Persistence: PostgreSQL' : 'Persistence: in-memory development store') + console.log(tripo ? 'Tripo 3D Provider: enabled' : 'Tripo 3D Provider: mock mode') }) async function route(request: IncomingMessage, response: ServerResponse) { @@ -128,6 +137,23 @@ async function route(request: IncomingMessage, response: ServerResponse) { const model = await catalogModel(modelId) if (model.type !== '3d' || model.mode !== 'async') throw new AuthError('NOT_ASYNC_3D_MODEL', '该模型不是异步 3D 模型', 400) if (!catalog.canInvoke(keyRecord, model.id)) throw new AuthError('MODEL_FORBIDDEN', '当前 Key 无权调用该模型', 403) + if (tripo) { + const prompt = stringValue(body.prompt).trim() + if (!prompt) throw new AuthError('PROMPT_REQUIRED', '3D 生成提示词不能为空') + const taskId = await tripo.createTextToModel({ + prompt, + model: stringValue(body.providerModel) || 'v3.1-20260211', + ...(body.negativePrompt ? { negative_prompt: stringValue(body.negativePrompt) } : {}), + ...(body.faceLimit !== undefined ? { face_limit: numberValue(body.faceLimit, 'faceLimit') } : {}), + ...(body.texture !== undefined ? { texture: booleanValue(body.texture, 'texture') } : {}), + ...(body.pbr !== undefined ? { pbr: booleanValue(body.pbr, 'pbr') } : {}), + ...(body.smartLowPoly !== undefined ? { smart_low_poly: booleanValue(body.smartLowPoly, 'smartLowPoly') } : {}), + }) + tripoTaskOwners.set(taskId, { userId: keyRecord.userId, model: model.id }) + const task = await tripo.getTask(taskId) + send(response, 202, { task: { ...task, model: model.id } }) + return + } const now = new Date().toISOString() const task: MockTask = { id: `task_${randomToken(14)}`, userId: keyRecord.userId, model: model.id, status: 'queued', createdAt: now, updatedAt: now } mockTasks.set(task.id, task) @@ -145,6 +171,12 @@ async function route(request: IncomingMessage, response: ServerResponse) { const taskId = taskMatch?.[1] if (method === 'GET' && taskId) { const keyRecord = await authenticatePlatformKey(request) + const tripoOwner = tripoTaskOwners.get(taskId) + if (tripo && tripoOwner) { + if (tripoOwner.userId !== keyRecord.userId) throw new AuthError('TASK_NOT_FOUND', '任务不存在', 404) + send(response, 200, { task: { ...await tripo.getTask(taskId), model: tripoOwner.model } }) + return + } const task = mockTasks.get(taskId) if (!task || task.userId !== keyRecord.userId) throw new AuthError('TASK_NOT_FOUND', '任务不存在', 404) send(response, 200, { task: publicTask(task) }) @@ -352,6 +384,16 @@ function stringValue(value: unknown) { return typeof value === 'string' ? value : '' } +function numberValue(value: unknown, field: string) { + if (typeof value !== 'number' || !Number.isFinite(value)) throw new AuthError('INVALID_NUMBER', `${field} 必须是有效数字`) + return value +} + +function booleanValue(value: unknown, field: string) { + if (typeof value !== 'boolean') throw new AuthError('INVALID_BOOLEAN', `${field} 必须是布尔值`) + return value +} + async function authenticatePlatformKey(request: IncomingMessage) { const authorization = request.headers.authorization || '' const match = authorization.match(/^Bearer\s+(.+)$/i) @@ -450,6 +492,11 @@ function handleError(response: ServerResponse, error: unknown) { send(response, error.statusCode, { error: { code: error.code, message: error.message } }) return } + if (error instanceof TripoProviderError) { + console.error(`Tripo provider error: ${error.message}`) + send(response, 502, { error: { code: 'TRIPO_PROVIDER_ERROR', message: '3D 模型供应商请求失败,请稍后重试' } }) + return + } console.error(error) send(response, 500, { error: { code: 'INTERNAL_ERROR', message: '服务暂时不可用' } }) } diff --git a/control-plane/tests/tripo.test.ts b/control-plane/tests/tripo.test.ts new file mode 100644 index 0000000..f950d67 --- /dev/null +++ b/control-plane/tests/tripo.test.ts @@ -0,0 +1,65 @@ +import assert from 'node:assert/strict' +import test from 'node:test' +import { TripoProvider, TripoProviderError, mapTripoTask } from '../src/providers/tripo.js' + +function response(body: unknown, status = 200) { + return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } }) +} + +test('Tripo adapter creates a text-to-model task with official endpoint shape', async () => { + const requests: Array<{ url: string; init?: RequestInit }> = [] + const provider = new TripoProvider({ + apiKey: 'test-tripo-key', + fetcher: async (url, init) => { + requests.push({ url: String(url), ...(init ? { init } : {}) }) + return response({ code: 0, data: { task_id: 'task_abc123' } }) + }, + }) + const taskId = await provider.createTextToModel({ prompt: 'a low-poly wooden stool' }) + + assert.equal(taskId, 'task_abc123') + assert.equal(requests[0]?.url, 'https://openapi.tripo3d.com/v3/generation/text-to-model') + assert.equal(requests[0]?.init?.headers && new Headers(requests[0].init.headers).get('Authorization'), 'Bearer test-tripo-key') + assert.deepEqual(JSON.parse(String(requests[0]?.init?.body)), { model: 'v3.1-20260211', texture: true, pbr: true, prompt: 'a low-poly wooden stool' }) +}) + +test('Tripo task response maps to MOYI task view', () => { + const mapped = mapTripoTask({ + task_id: 'task_abc123', + type: 'text_to_model', + status: 'success', + progress: 100, + output: { model_url: 'https://cdn.example/model.glb', rendered_image_url: 'https://cdn.example/preview.png' }, + credits_consumed: 48, + }) + + assert.equal(mapped.status, 'succeeded') + assert.equal(mapped.output?.modelUrl, 'https://cdn.example/model.glb') + assert.equal(mapped.creditsConsumed, 48) +}) + +test('Tripo adapter accepts the UUID task identifiers returned by the live v3 API', async () => { + const provider = new TripoProvider({ + apiKey: 'test-tripo-key', + fetcher: async () => response({ + code: 0, + data: { task_id: '950caa18-7003-4435-880d-cbb9e10ec8b6', type: 'text_to_model', status: 'running', progress: 42 }, + }), + }) + + const task = await provider.getTask('950caa18-7003-4435-880d-cbb9e10ec8b6') + assert.equal(task.status, 'running') + assert.equal(task.progress, 42) +}) + +test('Tripo adapter rejects provider failures without leaking credentials', async () => { + const provider = new TripoProvider({ + apiKey: 'test-tripo-key', + fetcher: async () => response({ code: 1001, message: 'invalid api key' }, 401), + }) + + await assert.rejects( + provider.createTextToModel({ prompt: 'test' }), + (error: unknown) => error instanceof TripoProviderError && error.statusCode === 401 && !error.message.includes('test-tripo-key'), + ) +}) diff --git a/docs/04-open-source-baseline-and-development-nodes.md b/docs/04-open-source-baseline-and-development-nodes.md index 3849b7a..bc4ac03 100644 --- a/docs/04-open-source-baseline-and-development-nodes.md +++ b/docs/04-open-source-baseline-and-development-nodes.md @@ -140,4 +140,4 @@ POST /v1/tasks ## 六、当前结论 -当前 D3 已完成认证与权限基线。D4 输入已确认:先使用 Mock 建立 Key/模型目录闭环,真实接入方向包含国内文本/多模态模型和 VAST 相关 3D 模型,测试环境使用现有服务器,首轮规模按 4—5 人、3—4 个项目估算。D4 Mock 已提供平台 Key 生命周期、统一模型目录、标准同步调用和异步 3D 任务接口;目录使用内存仓库,PostgreSQL 表结构已准备,下一步进入真实 Provider Adapter 与用量计量。详见 [D4 密钥与模型目录实施计划](06-d4-integration-plan.md)。 +当前 D3 已完成认证与权限基线。D4 已提供平台 Key 生命周期、统一模型目录、标准同步调用和异步 3D 任务接口,并完成首个 Tripo 真实 Provider Adapter 与文生 3D 验收。目录和真实任务归属当前仍使用内存仓库,PostgreSQL 表结构已准备;下一步进入 D5 调用计量,并在 D6 持久化异步任务、队列和结果文件。详见 [D4 密钥与模型目录实施计划](06-d4-integration-plan.md)。 diff --git a/docs/06-d4-integration-plan.md b/docs/06-d4-integration-plan.md index c5ba9b7..7c5e5be 100644 --- a/docs/06-d4-integration-plan.md +++ b/docs/06-d4-integration-plan.md @@ -95,3 +95,7 @@ SDK 不直接暴露给 MOYI 用户。后续如果上游从 HTTP API 切换为 SD - `GET|POST /api/admin/models`:管理员查看或登记统一模型目录。 Mock 目录使用内存仓库,重启会重置,适合原型与接口联调;`migrations/002_catalog_keys.sql` 已准备 PostgreSQL 表结构,后续接持久化仓库时保持 API 不变。 + +Tripo Provider Adapter 已按官方 v3 文档实现:服务端从 `TRIPO_API_KEY` 读取密钥,调用 `POST /generation/text-to-model` 创建异步任务,再通过 `GET /tasks/{task_id}` 查询状态、进度、消耗额度和模型下载地址。适配器不会把上游密钥返回给用户端。 + +2026-08-25 已完成首次真实文生 3D 验收:使用 `v3.1-20260211` 和 standard 质量生成低面数木质凳子,任务状态为 `success`、进度 100%,Tripo 记录消耗 20.0 积分,并返回 GLB 模型与 WebP 预览地址。验收记录不保存 API Key 和带签名的临时下载 URL。