feat(queue): 增加非文本模型分布式准入队列

使用 PostgreSQL 统一同步与异步非文本任务的并发准入、持久化等待和 Worker 容量分配，并将生产 API 与独立 Worker 角色拆分。补充策略管理、共享契约、OpenAPI、Kubernetes 双节点 Worker 清单及跨节点验收脚本；未默认启用任何生产 queue_size 策略。已在原基线完成 Go、前端、迁移、Shell、Kustomize 与长任务容量验收；合入最新主干后将重新执行发布门禁。
2026-07-29 16:15:43 +08:00
parent 2e5a90731b
commit 9e4fc7362d
55 changed files with 4565 additions and 237 deletions
@@ -6255,7 +6255,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。",
+                "description": "默认同步返回 OpenAI-compatible Images 响应；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时异步创建任务并返回 202。",
                "consumes": [
                    "application/json"
                ],
@@ -6319,6 +6319,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.OpenAIErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.OpenAIErrorEnvelope"
+                        }
                    }
                }
            }
@@ -6330,7 +6336,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。",
+                "description": "默认同步返回 OpenAI-compatible Images 响应；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时异步创建任务并返回 202。",
                "consumes": [
                    "application/json"
                ],
@@ -6394,6 +6400,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.OpenAIErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.OpenAIErrorEnvelope"
+                        }
                    }
                }
            }
@@ -7059,7 +7071,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
+                "description": "默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
                "consumes": [
                    "application/json"
                ],
@@ -7147,6 +7159,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
+                        }
                    }
                }
            }
@@ -7921,7 +7939,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
+                "description": "默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
                "consumes": [
                    "application/json"
                ],
@@ -8009,6 +8027,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
+                        }
                    }
                }
            }
@@ -8020,7 +8044,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
+                "description": "默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
                "consumes": [
                    "application/json"
                ],
@@ -8108,6 +8132,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
+                        }
                    }
                }
            }
@@ -8462,7 +8492,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
+                "description": "默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
                "consumes": [
                    "application/json"
                ],
@@ -8550,6 +8580,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
+                        }
                    }
                }
            }
@@ -8781,7 +8817,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
+                "description": "默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504 queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。",
                "consumes": [
                    "application/json"
                ],
@@ -8869,6 +8905,12 @@
                        "schema": {
                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
                        }
+                    },
+                    "504": {
+                        "description": "Gateway Timeout",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.ErrorEnvelope"
+                        }
                    }
                }
            }
@@ -14325,6 +14367,9 @@
                        "type": "string"
                    }
                },
+                "oldestQueueWaitSeconds": {
+                    "type": "number"
+                },
                "platformCooldownUntil": {
                    "type": "string"
                },
@@ -14358,6 +14403,9 @@
                "providerModelName": {
                    "type": "string"
                },
+                "queueLimit": {
+                    "type": "integer"
+                },
                "queuedTasks": {
                    "type": "number"
                },
@@ -14376,6 +14424,12 @@
                },
                "tpm": {
                    "$ref": "#/definitions/store.RateLimitMetricStatus"
+                },
+                "waitingAsyncTasks": {
+                    "type": "integer"
+                },
+                "waitingSyncTasks": {
+                    "type": "integer"
                }
            }
        },
@@ -3174,6 +3174,8 @@ definitions:
        items:
          type: string
        type: array
+      oldestQueueWaitSeconds:
+        type: number
      platformCooldownUntil:
        type: string
      platformDisabledReason:
@@ -3196,6 +3198,8 @@ definitions:
        type: string
      providerModelName:
        type: string
+      queueLimit:
+        type: integer
      queuedTasks:
        type: number
      rateLimitPolicy:
@@ -3209,6 +3213,10 @@ definitions:
        $ref: '#/definitions/store.RateLimitMetricStatus'
      tpm:
        $ref: '#/definitions/store.RateLimitMetricStatus'
+      waitingAsyncTasks:
+        type: integer
+      waitingSyncTasks:
+        type: integer
    type: object
  store.Platform:
    properties:
@@ -8008,7 +8016,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。
+      description: 默认同步返回 OpenAI-compatible Images 响应；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回
+        504 queue_timeout；设置 X-Async=true 时异步创建任务并返回 202。
      parameters:
      - description: OpenAI Images 请求
        in: body
@@ -8047,6 +8056,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建或编辑 OpenAI Images
@@ -8056,7 +8069,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。
+      description: 默认同步返回 OpenAI-compatible Images 响应；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回
+        504 queue_timeout；设置 X-Async=true 时异步创建任务并返回 202。
      parameters:
      - description: OpenAI Images 请求
        in: body
@@ -8095,6 +8109,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.OpenAIErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建或编辑 OpenAI Images
@@ -8527,8 +8545,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway
-        与 server-main EasyAIClient 的异步提交结构。
+      description: 默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504
+        queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -8583,6 +8601,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建 EasyAI 媒体任务
@@ -9088,8 +9110,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway
-        与 server-main EasyAIClient 的异步提交结构。
+      description: 默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504
+        queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -9144,6 +9166,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建 EasyAI 媒体任务
@@ -9153,8 +9179,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway
-        与 server-main EasyAIClient 的异步提交结构。
+      description: 默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504
+        queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -9209,6 +9235,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建 EasyAI 媒体任务
@@ -9437,8 +9467,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway
-        与 server-main EasyAIClient 的异步提交结构。
+      description: 默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504
+        queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -9493,6 +9523,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建 EasyAI 媒体任务
@@ -9645,8 +9679,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 默认同步返回 EasyAI GeneratedResponse；设置 X-Async=true 时返回同时兼容 Gateway
-        与 server-main EasyAIClient 的异步提交结构。
+      description: 默认同步返回 EasyAI GeneratedResponse；非文本模型并发饱和且配置队列时等待准入，超过最长等待返回 504
+        queue_timeout；设置 X-Async=true 时返回同时兼容 Gateway 与 server-main EasyAIClient 的异步提交结构。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -9701,6 +9735,10 @@ paths:
          description: Bad Gateway
          schema:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "504":
+          description: Gateway Timeout
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
      summary: 创建 EasyAI 媒体任务