perf(storage): 拦截任务二进制并本地暂存结果

原因：任务标准结果中的 Base64、Data URI 和 Buffer 会进入 PostgreSQL JSON，导致 TOAST 与备份体积快速增长。

影响：新增统一 JSON 持久化关口；upload_none 将二进制原子写入本地结果目录，数据库仅保存带 SHA-256 的有界占位符；任务详情、同步响应、异步查询和兼容协议按需校验恢复。补充 24 小时清理、容量上限、历史小批量治理命令及管理端说明。

风险：本地结果超过 TTL、丢失或损坏时分别返回明确的 410/500；空间不足时返回 503 且不重试上游。未自动执行历史治理。

验证：三种真实图片模型同步/异步与幂等重放通过；Go vet/全量测试、前端 111 测试、lint/typecheck/build、OpenAPI、迁移安全、govulncheck、依赖审计、手工发布测试及 Linux amd64 构建通过。

apps/api/internal/httpapi/binary_results.go

@@ -0,0 +1,30 @@
+package httpapi
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/easyai/easyai-ai-gateway/apps/api/internal/clients"
+	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
+)
+
+func (s *Server) hydrateTaskResult(ctx context.Context, task store.GatewayTask) (store.GatewayTask, error) {
+	if task.Status != "succeeded" || len(task.Result) == 0 {
+		return task, nil
+	}
+	result, err := s.runner.HydrateTaskResult(ctx, task.ID, task.Result)
+	if err != nil {
+		return store.GatewayTask{}, err
+	}
+	task.Result = result
+	return task, nil
+}
+
+func writeStoredBinaryResultError(w http.ResponseWriter, err error) {
+	status := statusFromRunError(err)
+	code := clients.ErrorCode(err)
+	if code == "" {
+		code = "binary_result_corrupted"
+	}
+	writeError(w, status, err.Error(), code)
+}

apps/api/internal/httpapi/gemini_compat.go

@@ -170,6 +170,10 @@ func (s *Server) geminiGenerateContent(w http.ResponseWriter, r *http.Request) {
 			writeGeminiTaskError(http.StatusConflict, "Idempotency-Key was reused for a different request", nil, "idempotency_key_reused")
 			return
 		}
+		if errors.Is(err, store.ErrTaskRequestBinaryNotMaterialized) {
+			writeGeminiTaskError(http.StatusBadRequest, err.Error(), nil, clients.ErrorCode(err))
+			return
+		}
 		s.logger.Error("create gemini task failed", "kind", mapping.Kind, "error_category", "task_create_failed")
 		writeGeminiTaskError(http.StatusInternalServerError, "create task failed", nil, "task_create_failed")
 		return
@@ -184,6 +188,11 @@ func (s *Server) geminiGenerateContent(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		if task.Status == "succeeded" {
+			task, err = s.hydrateTaskResult(r.Context(), task)
+			if err != nil {
+				writeGeminiTaskError(statusFromRunError(err), err.Error(), nil, clients.ErrorCode(err))
+				return
+			}
 			if _, native := task.Result["candidates"]; native {
 				writeJSON(w, http.StatusOK, task.Result)
 				return

apps/api/internal/httpapi/handlers.go

@@ -1134,6 +1134,10 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 				writeTaskError(http.StatusConflict, "Idempotency-Key was reused for a different request", nil, "idempotency_key_reused")
 				return
 			}
+			if errors.Is(err, store.ErrTaskRequestBinaryNotMaterialized) {
+				writeTaskError(http.StatusBadRequest, err.Error(), nil, clients.ErrorCode(err))
+				return
+			}
 			s.logger.Error("create task failed", "kind", kind, "error_category", "task_create_failed")
 			writeTaskError(http.StatusInternalServerError, "create task failed", nil, "task_create_failed")
 			return
@@ -1150,6 +1154,17 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 				writeTaskError(http.StatusConflict, "streaming idempotent replay is not supported", nil, "idempotency_stream_replay_unsupported")
 				return
 			}
+			if task.Status == "succeeded" && !responsePlan.asyncMode && (targetProtocol != "" || responsePlan.compatibleMode) {
+				task, err = s.hydrateTaskResult(r.Context(), task)
+				if err != nil {
+					if targetProtocol != "" {
+						writeProtocolError(w, targetProtocol, statusFromRunError(err), err.Error(), nil, clients.ErrorCode(err))
+					} else {
+						writeStoredBinaryResultError(w, err)
+					}
+					return
+				}
+			}
 			if targetProtocol != "" && !responsePlan.asyncMode {
 				if task.Status == "succeeded" {
 					writeJSON(w, http.StatusOK, task.Result)
@@ -1597,6 +1612,12 @@ func scopeForTaskKind(kind string) string {
 
 func statusFromRunError(err error) int {
 	switch {
+	case clients.ErrorCode(err) == "binary_result_expired":
+		return http.StatusGone
+	case clients.ErrorCode(err) == "binary_result_corrupted" || clients.ErrorCode(err) == "result_binary_not_materialized":
+		return http.StatusInternalServerError
+	case clients.ErrorCode(err) == "local_result_storage_unavailable":
+		return http.StatusServiceUnavailable
 	case clients.ErrorCode(err) == "billing_hold":
 		return http.StatusServiceUnavailable
 	case runner.IsPricingUnavailable(err):
@@ -1901,6 +1922,7 @@ func boolValue(body map[string]any, key string) bool {
 // @Success 200 {object} store.GatewayTask
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 404 {object} ErrorEnvelope
+// @Failure 410 {object} ErrorEnvelope
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks/{taskID} [get]
 // @Router /api/v1/tasks/{taskID} [get]
@@ -1920,6 +1942,11 @@ func (s *Server) getTask(w http.ResponseWriter, r *http.Request) {
 		task.Cancellable = &cancelState.Cancellable
 		task.Submitted = &cancelState.Submitted
 		task.Message = cancelState.Message
+		task, err = s.hydrateTaskResult(r.Context(), task)
+		if err != nil {
+			writeStoredBinaryResultError(w, err)
+			return
+		}
 		writeJSON(w, http.StatusOK, task)
 		return
 	}

apps/api/internal/httpapi/keling_compat_handlers.go

@@ -177,6 +177,10 @@ func (s *Server) createKelingOmniVideo(w http.ResponseWriter, r *http.Request) {
 			writeKelingCompatError(w, requestID, kelingCompatGatewayError(staged.Err))
 			return
 		}
+		if errors.Is(createErr, store.ErrTaskRequestBinaryNotMaterialized) {
+			writeKelingCompatError(w, requestID, newKelingCompatError(http.StatusBadRequest, 1201, clients.ErrorCode(createErr)))
+			return
+		}
 		s.logger.Error("create Kling-compatible task failed", "error", createErr)
 		writeKelingCompatError(w, requestID, newKelingCompatError(http.StatusInternalServerError, 5000, "create task failed"))
 		return
@@ -221,6 +225,7 @@ func (s *Server) createKelingOmniVideo(w http.ResponseWriter, r *http.Request) {
 // @Failure 401 {object} KelingCompatibleEnvelope
 // @Failure 403 {object} KelingCompatibleEnvelope
 // @Failure 404 {object} KelingCompatibleEnvelope
+// @Failure 410 {object} KelingCompatibleEnvelope
 // @Failure 500 {object} KelingCompatibleEnvelope
 // @Router /api/v1/videos/omni-video/{taskID} [get]
 func (s *Server) getKelingOmniVideo(w http.ResponseWriter, r *http.Request) {
@@ -247,6 +252,11 @@ func (s *Server) getKelingOmniVideo(w http.ResponseWriter, r *http.Request) {
 		writeKelingCompatError(w, requestID, newKelingCompatError(http.StatusNotFound, 1203, "task not found"))
 		return
 	}
+	task, err = s.hydrateTaskResult(r.Context(), task)
+	if err != nil {
+		writeKelingCompatError(w, requestID, newKelingCompatError(statusFromRunError(err), 5000, clients.ErrorCode(err)))
+		return
+	}
 	writeJSON(w, http.StatusOK, KelingCompatibleEnvelope{
 		Code:      0,
 		Message:   "SUCCEED",

apps/api/internal/httpapi/kling_compat.go

@@ -144,6 +144,8 @@ func (s *Server) createKlingCompatTask(w http.ResponseWriter, r *http.Request, v
 			writeKlingCompatError(w, http.StatusConflict, err.Error(), "idempotency_key_reused")
 		case errors.Is(err, store.ErrExternalTaskIDReused):
 			writeKlingCompatError(w, http.StatusConflict, err.Error(), "external_task_id_reused")
+		case errors.Is(err, store.ErrTaskRequestBinaryNotMaterialized):
+			writeKlingCompatError(w, http.StatusBadRequest, err.Error(), clients.ErrorCode(err))
 		default:
 			s.logger.Error("create Kling compatibility task failed", "version", version, "model", model, "error", err)
 			writeKlingCompatError(w, http.StatusInternalServerError, "create task failed", "task_create_failed")
@@ -464,6 +466,7 @@ func validateKlingCompatBody(model string, body map[string]any) error {
 // @Param taskID path string true "任务 ID"
 // @Success 200 {object} map[string]interface{}
 // @Failure 404 {object} map[string]interface{}
+// @Failure 410 {object} map[string]interface{}
 // @Router /api/v1/kling/v1/videos/omni-video/{taskID} [get]
 func (s *Server) klingV1GetOmniVideo(w http.ResponseWriter, r *http.Request) {
 	user, _ := auth.UserFromContext(r.Context())
@@ -476,6 +479,11 @@ func (s *Server) klingV1GetOmniVideo(w http.ResponseWriter, r *http.Request) {
 		writeKlingCompatError(w, http.StatusInternalServerError, "get task failed", "task_query_failed")
 		return
 	}
+	task, err = s.hydrateTaskResult(r.Context(), task)
+	if err != nil {
+		writeKlingCompatError(w, statusFromRunError(err), err.Error(), clients.ErrorCode(err))
+		return
+	}
 	writeJSON(w, http.StatusOK, klingV1Envelope(task))
 }
 
@@ -520,6 +528,7 @@ func (s *Server) klingV1ListOmniVideos(w http.ResponseWriter, r *http.Request) {
 // @Param task_ids query string false "逗号分隔的任务 ID"
 // @Param external_task_ids query string false "逗号分隔的外部任务 ID"
 // @Success 200 {object} map[string]interface{}
+// @Failure 410 {object} map[string]interface{}
 // @Router /api/v1/kling/v2/tasks [get]
 func (s *Server) klingV2GetTasks(w http.ResponseWriter, r *http.Request) {
 	user, _ := auth.UserFromContext(r.Context())
@@ -543,6 +552,11 @@ func (s *Server) klingV2GetTasks(w http.ResponseWriter, r *http.Request) {
 			writeKlingCompatError(w, http.StatusInternalServerError, "get task failed", "task_query_failed")
 			return
 		}
+		task, err = s.hydrateTaskResult(r.Context(), task)
+		if err != nil {
+			writeKlingCompatError(w, statusFromRunError(err), err.Error(), clients.ErrorCode(err))
+			return
+		}
 		data = append(data, klingV2TaskData(task))
 	}
 	writeJSON(w, http.StatusOK, map[string]any{"code": 0, "message": "success", "request_id": klingRequestIDFromAny(data), "data": data})

apps/api/internal/httpapi/local_temp_assets.go

@@ -45,6 +45,58 @@ func (s *Server) cleanupExpiredLocalTempAssets(ctx context.Context, now time.Tim
 	for _, target := range targets {
 		deleted += s.cleanupExpiredLocalTempAssetsInDir(ctx, now, target)
 	}
+	deleted += s.cleanupExpiredLocalBinaryResults(now)
+	return deleted
+}
+
+func (s *Server) cleanupExpiredLocalBinaryResults(now time.Time) int {
+	storageDir := strings.TrimSpace(s.cfg.LocalGeneratedStorageDir)
+	if storageDir == "" {
+		storageDir = config.DefaultLocalGeneratedStorageDir
+	}
+	root := filepath.Join(storageDir, "results")
+	ttlHours := s.cfg.LocalResultTTLHours
+	if ttlHours <= 0 {
+		ttlHours = 24
+	}
+	expiredBefore := now.Add(-time.Duration(ttlHours) * time.Hour)
+	deleted := 0
+	var directories []string
+	err := filepath.WalkDir(root, func(path string, entry os.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			if !errors.Is(walkErr, os.ErrNotExist) && s.logger != nil {
+				s.logger.Warn("walk local binary result failed", "path", path, "error", walkErr)
+			}
+			return nil
+		}
+		if entry.IsDir() {
+			if path != root {
+				directories = append(directories, path)
+			}
+			return nil
+		}
+		if entry.Type()&os.ModeSymlink != 0 {
+			return nil
+		}
+		info, infoErr := entry.Info()
+		if infoErr != nil || info.ModTime().After(expiredBefore) {
+			return nil
+		}
+		if removeErr := os.Remove(path); removeErr != nil && !errors.Is(removeErr, os.ErrNotExist) {
+			if s.logger != nil {
+				s.logger.Warn("remove local binary result failed", "path", path, "error", removeErr)
+			}
+			return nil
+		}
+		deleted++
+		return nil
+	})
+	if err != nil && !errors.Is(err, os.ErrNotExist) && s.logger != nil {
+		s.logger.Warn("scan local binary result root failed", "dir", root, "error", err)
+	}
+	for index := len(directories) - 1; index >= 0; index-- {
+		_ = os.Remove(directories[index])
+	}
 	return deleted
 }
 

apps/api/internal/httpapi/request_preparation_test.go

@@ -11,6 +11,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -235,6 +236,47 @@ func TestCleanupExpiredLocalTempAssetsDeletesExpiredStaticFiles(t *testing.T) {
 	}
 }
 
+func TestCleanupExpiredLocalTempAssetsDeletesNestedBinaryResultsWithIndependentTTL(t *testing.T) {
+	generatedDir := t.TempDir()
+	taskDir := filepath.Join(generatedDir, "results", "task-123")
+	if err := os.MkdirAll(taskDir, 0o750); err != nil {
+		t.Fatalf("create local result fixture dir: %v", err)
+	}
+	oldResult := filepath.Join(taskDir, strings.Repeat("a", 64)+".bin")
+	freshResult := filepath.Join(taskDir, strings.Repeat("b", 64)+".bin")
+	for _, path := range []string{oldResult, freshResult} {
+		if err := os.WriteFile(path, []byte("asset"), 0o640); err != nil {
+			t.Fatalf("write fixture %s: %v", path, err)
+		}
+	}
+	now := time.Now()
+	if err := os.Chtimes(oldResult, now.Add(-25*time.Hour), now.Add(-25*time.Hour)); err != nil {
+		t.Fatalf("age old binary result: %v", err)
+	}
+	if err := os.Chtimes(freshResult, now.Add(-23*time.Hour), now.Add(-23*time.Hour)); err != nil {
+		t.Fatalf("age fresh binary result: %v", err)
+	}
+	server := &Server{
+		cfg: config.Config{
+			LocalGeneratedStorageDir: generatedDir,
+			LocalResultTTLHours:      24,
+		},
+		logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
+	}
+
+	deleted := server.cleanupExpiredLocalTempAssets(context.Background(), now)
+
+	if deleted != 1 {
+		t.Fatalf("expected one expired binary result delete, got %d", deleted)
+	}
+	if _, err := os.Stat(oldResult); !os.IsNotExist(err) {
+		t.Fatalf("old binary result should be deleted, stat err=%v", err)
+	}
+	if _, err := os.Stat(freshResult); err != nil {
+		t.Fatalf("fresh binary result should remain: %v", err)
+	}
+}
+
 func TestRequestConversationKeyPriority(t *testing.T) {
 	request := httptest.NewRequest(http.MethodPost, "/api/v1/chat/completions", nil)
 	request.Header.Set("X-EasyAI-Conversation-ID", "from-header")

apps/api/internal/httpapi/volces_compat_handlers.go

@@ -56,12 +56,19 @@ func (s *Server) createVolcesContentsGenerationTask(w http.ResponseWriter, r *ht
 // @Param taskID path string true "任务 ID"
 // @Success 200 {object} VolcesContentsGenerationTaskResponse
 // @Failure 404 {object} VolcesErrorEnvelope
+// @Failure 410 {object} VolcesErrorEnvelope
 // @Router /api/v1/contents/generations/tasks/{taskID} [get]
 func (s *Server) getVolcesContentsGenerationTask(w http.ResponseWriter, r *http.Request) {
 	task, ok := s.volcesCompatibleTaskForUser(w, r)
 	if !ok {
 		return
 	}
+	var err error
+	task, err = s.hydrateTaskResult(r.Context(), task)
+	if err != nil {
+		writeVolcesError(w, statusFromRunError(err), err.Error(), clients.ErrorCode(err))
+		return
+	}
 	writeJSON(w, http.StatusOK, volcesCompatibleTask(task))
 }
 
@@ -178,6 +185,7 @@ func (s *Server) createLegacyVolcesVideoGeneration(w http.ResponseWriter, r *htt
 // @Param taskID path string true "任务 ID"
 // @Success 200 {object} EasyAIGeneratedResponse
 // @Failure 404 {object} EasyAIGeneratedResponse
+// @Failure 410 {object} EasyAIGeneratedResponse
 // @Router /api/v1/ai/result/{taskID} [get]
 func (s *Server) getEasyAITaskResult(w http.ResponseWriter, r *http.Request) {
 	user, ok := auth.UserFromContext(r.Context())
@@ -199,6 +207,11 @@ func (s *Server) getEasyAITaskResult(w http.ResponseWriter, r *http.Request) {
 		writeEasyAIAsyncError(w, http.StatusNotFound, "task not found", nil, "not_found")
 		return
 	}
+	task, err = s.hydrateTaskResult(r.Context(), task)
+	if err != nil {
+		writeEasyAIAsyncError(w, statusFromRunError(err), err.Error(), nil, clients.ErrorCode(err))
+		return
+	}
 	writeJSON(w, http.StatusOK, easyAITaskResultResponse(task))
 }
 
@@ -408,6 +421,8 @@ func writeVolcesCompatibleTaskError(w http.ResponseWriter, err error) {
 		status = clientErr.StatusCode
 	} else if errors.As(err, &clientErr) {
 		status = http.StatusBadRequest
+	} else if errors.Is(err, store.ErrTaskRequestBinaryNotMaterialized) {
+		status = http.StatusBadRequest
 	}
 	if wire := clients.ErrorWireResponse(err); wireResponseMatches(wire, clients.ProtocolVolcesContents) {
 		writeWireResponse(w, wire)