fix: 完善工作流公共接口上传与错误契约

- 区分 HTTP 请求标识与内部上传标识，补齐 Redis 旧记录兼容和关联日志 - 保持归一化 MIME 一致，并隔离工作流鉴权错误契约对其他公共接口的影响 - 收口 Multipart 操作日志与对象存储故障分类，归档范围：S05
2026-08-10 11:41:09 +08:00
parent bae7b18977
commit 9d2fa39a2d
16 changed files with 573 additions and 115 deletions
--- a/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiPreparedUpload.java
+++ b/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiPreparedUpload.java
@@ -7,29 +7,29 @@ import java.util.Map;
 */
 public class WorkflowApiPreparedUpload {

-    private final String requestId;
+    private final String uploadId;
    private final Map<String, Object> variables;

    /**
     * 创建文件准备结果。
     *
-     * @param requestId 临时上传请求 ID
+     * @param uploadId 内部临时上传 ID
     * @param variables 已注入文件描述的工作流变量
     */
    public WorkflowApiPreparedUpload(
-            String requestId,
+            String uploadId,
            Map<String, Object> variables) {
-        this.requestId = requestId;
+        this.uploadId = uploadId;
        this.variables = variables;
    }

    /**
-     * 获取临时上传请求 ID。
+     * 获取内部临时上传 ID。
     *
-     * @return 临时上传请求 ID
+     * @return 内部临时上传 ID
     */
-    public String getRequestId() {
-        return requestId;
+    public String getUploadId() {
+        return uploadId;
    }

    /**
--- a/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadLifecycleService.java
+++ b/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadLifecycleService.java
@@ -17,7 +17,6 @@ import tech.easyflow.common.web.exceptions.BusinessException;

 import java.net.ConnectException;
 import java.net.SocketTimeoutException;
-import java.net.UnknownHostException;
 import java.net.http.HttpTimeoutException;
 import java.time.Duration;
 import java.util.ArrayList;
@@ -89,12 +88,14 @@ public class WorkflowApiUploadLifecycleService {
    /**
     * 校验、存储 multipart 文件并注入工作流变量。
     *
+     * @param requestId HTTP 请求关联标识
     * @param workflowContent 已发布工作流内容
     * @param variables 普通运行变量
     * @param fileParts 以工作流文件参数名分组的 multipart 文件
     * @return 临时上传准备结果
     */
    public WorkflowApiPreparedUpload prepare(
+            String requestId,
            String workflowContent,
            Map<String, Object> variables,
            Map<String, List<MultipartFile>> fileParts) {
@@ -126,7 +127,10 @@ public class WorkflowApiUploadLifecycleService {

        WorkflowApiUploadRecord record = new WorkflowApiUploadRecord();
        long now = System.currentTimeMillis();
-        record.setRequestId(UUID.randomUUID().toString().replace("-", ""));
+        record.setUploadId(UUID.randomUUID().toString().replace("-", ""));
+        record.setRequestId(StringUtils.hasText(requestId)
+                ? requestId
+                : record.getUploadId());
        record.setCreatedAt(now);
        record.setCleanupAt(now + STAGED_RETENTION.toMillis());

@@ -142,7 +146,7 @@ public class WorkflowApiUploadLifecycleService {
                            workflowContent,
                            resolvedVariables);
            return new WorkflowApiPreparedUpload(
-                    record.getRequestId(),
+                    record.getUploadId(),
                    normalized);
        } catch (RuntimeException | Error error) {
            try {
@@ -157,14 +161,14 @@ public class WorkflowApiUploadLifecycleService {
    /**
     * 在工作流首个节点启动前绑定执行 ID。
     *
-     * @param requestId 临时上传请求 ID
+     * @param uploadId 内部临时上传 ID
     * @param executeId 工作流执行 ID
     */
-    public void bindExecution(String requestId, String executeId) {
-        uploadStore.bindExecution(requestId, executeId);
-        WorkflowApiUploadRecord record = uploadStore.find(requestId)
+    public void bindExecution(String uploadId, String executeId) {
+        uploadStore.bindExecution(uploadId, executeId);
+        WorkflowApiUploadRecord record = uploadStore.find(uploadId)
                .orElseThrow(() -> new IllegalStateException(
-                        "工作流临时上传记录不存在: " + requestId));
+                        "工作流临时上传记录不存在: " + uploadId));
        uploadStore.schedule(
                record,
                System.currentTimeMillis() + ACTIVE_RECHECK.toMillis());
@@ -186,10 +190,10 @@ public class WorkflowApiUploadLifecycleService {
    /**
     * 终止尚未成功启动的临时上传并立即清理。
     *
-     * @param requestId 临时上传请求 ID
+     * @param uploadId 内部临时上传 ID
     */
-    public void abort(String requestId) {
-        cleanupRequest(requestId, true);
+    public void abort(String uploadId) {
+        cleanupRequest(uploadId, true);
    }

    /**
@@ -209,15 +213,12 @@ public class WorkflowApiUploadLifecycleService {
            if (claimed.isEmpty()) {
                break;
            }
-            String requestId = claimed.get();
+            String uploadId = claimed.get();
            processed++;
            try {
-                cleanupRequest(requestId, false);
+                cleanupRequest(uploadId, false);
            } catch (RuntimeException error) {
-                LOG.error(
-                        "清理工作流 API 临时上传失败，requestId={}",
-                        requestId,
-                        error);
+                logCleanupFailure(uploadId, error);
            }
        }
        return processed;
@@ -341,7 +342,7 @@ public class WorkflowApiUploadLifecycleService {
                try {
                    writeHandle = fileStorageService.prepareRecoverableWrite(
                                STORAGE_PATH_PREFIX
-                                        + record.getRequestId(),
+                                        + record.getUploadId(),
                                buildStorageFilename(
                                        file,
                                        record.getStoredFiles().size()));
@@ -499,7 +500,6 @@ public class WorkflowApiUploadLifecycleService {
        while (current != null) {
            if (current instanceof ConnectException
                    || current instanceof SocketTimeoutException
-                    || current instanceof UnknownHostException
                    || current instanceof HttpTimeoutException
                    || current instanceof TimeoutException) {
                return true;
@@ -590,14 +590,14 @@ public class WorkflowApiUploadLifecycleService {
    /**
     * 在分布式锁下清理一条上传记录。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     * @param force 是否忽略工作流运行状态立即清理
     * @return 是否成功删除记录
     */
-    private boolean cleanupRequest(String requestId, boolean force) {
+    private boolean cleanupRequest(String uploadId, boolean force) {
        RedisLockExecutor.LockHandle handle =
                redisLockExecutor.tryAcquire(
-                        CLEANUP_LOCK_PREFIX + requestId,
+                        CLEANUP_LOCK_PREFIX + uploadId,
                        CLEANUP_LOCK_WAIT,
                        CLEANUP_LOCK_LEASE);
        if (handle == null) {
@@ -605,9 +605,9 @@ public class WorkflowApiUploadLifecycleService {
        }
        try (handle) {
            WorkflowApiUploadRecord record =
-                    uploadStore.find(requestId).orElse(null);
+                    uploadStore.find(uploadId).orElse(null);
            if (record == null) {
-                uploadStore.removeMissingIndex(requestId);
+                uploadStore.removeMissingIndex(uploadId);
                return false;
            }
            if (!force && shouldRetain(record)) {
@@ -623,6 +623,31 @@ public class WorkflowApiUploadLifecycleService {
        }
    }

+    /**
+     * 记录带 HTTP 请求关联标识的异步清理异常。
+     *
+     * @param uploadId 内部上传 ID
+     * @param error 清理异常
+     */
+    private void logCleanupFailure(
+            String uploadId,
+            RuntimeException error) {
+        WorkflowApiUploadRecord record = null;
+        try {
+            record = uploadStore.find(uploadId).orElse(null);
+        } catch (RuntimeException lookupError) {
+            if (lookupError != error) {
+                error.addSuppressed(lookupError);
+            }
+        }
+        LOG.error(
+                "清理工作流 API 临时上传失败, uploadId={}, requestId={}, executeId={}",
+                uploadId,
+                record == null ? null : record.getRequestId(),
+                record == null ? null : record.getExecuteId(),
+                error);
+    }
+
    /**
     * 判断上传记录是否仍被运行中或挂起的工作流使用。
     *
--- a/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadRecord.java
+++ b/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadRecord.java
@@ -8,6 +8,9 @@ import java.util.List;
 */
 public class WorkflowApiUploadRecord {

+    /** 服务端生成、用于 Redis 和对象存储定位的内部上传 ID。 */
+    private String uploadId;
+    /** 调用方可见、用于跨线程排障的 HTTP 请求关联标识。 */
    private String requestId;
    private String executeId;
    private List<WorkflowApiStoredFile> storedFiles = new ArrayList<>();
@@ -19,18 +22,41 @@ public class WorkflowApiUploadRecord {
    private long cleanupAt;

    /**
-     * 获取上传请求 ID。
+     * 获取内部上传 ID。
     *
-     * @return 上传请求 ID
+     * <p>兼容旧版 Redis 记录：旧记录只包含 {@code requestId}，
+     * 其值曾作为内部上传主键。</p>
+     *
+     * @return 内部上传 ID
+     */
+    public String getUploadId() {
+        return uploadId == null || uploadId.isBlank()
+                ? requestId
+                : uploadId;
+    }
+
+    /**
+     * 设置内部上传 ID。
+     *
+     * @param uploadId 内部上传 ID
+     */
+    public void setUploadId(String uploadId) {
+        this.uploadId = uploadId;
+    }
+
+    /**
+     * 获取 HTTP 请求关联标识。
+     *
+     * @return HTTP 请求关联标识
     */
    public String getRequestId() {
        return requestId;
    }

    /**
-     * 设置上传请求 ID。
+     * 设置 HTTP 请求关联标识。
     *
-     * @param requestId 上传请求 ID
+     * @param requestId HTTP 请求关联标识
     */
    public void setRequestId(String requestId) {
        this.requestId = requestId;
--- a/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadStore.java
+++ b/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadStore.java
@@ -98,50 +98,50 @@ public class WorkflowApiUploadStore {
    public void save(WorkflowApiUploadRecord record) {
        requireRecord(record);
        redisTemplate.opsForValue().set(
-                recordKey(record.getRequestId()),
+                recordKey(record.getUploadId()),
                serialize(record));
    }

    /**
     * 将上传请求绑定到工作流执行实例。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     * @param executeId 工作流执行 ID
     */
-    public void bindExecution(String requestId, String executeId) {
+    public void bindExecution(String uploadId, String executeId) {
        if (!StringUtils.hasText(executeId)) {
            throw new IllegalArgumentException("工作流执行 ID 不能为空");
        }
-        WorkflowApiUploadRecord record = find(requestId)
+        WorkflowApiUploadRecord record = find(uploadId)
                .orElseThrow(() -> new IllegalStateException(
-                        "工作流临时上传记录不存在: " + requestId));
+                        "工作流临时上传记录不存在: " + uploadId));
        String previousExecuteId = record.getExecuteId();
        record.setExecuteId(executeId);
        redisTemplate.execute(
                BIND_EXECUTION_SCRIPT,
                Arrays.asList(
-                        recordKey(requestId),
+                        recordKey(uploadId),
                        executionKey(executeId),
                        StringUtils.hasText(previousExecuteId)
                                ? executionKey(previousExecuteId)
-                                : recordKey(requestId)),
+                                : recordKey(uploadId)),
                serialize(record),
-                requestId,
+                uploadId,
                String.valueOf(EXECUTION_INDEX_TTL.toMillis()),
                StringUtils.hasText(previousExecuteId) ? "1" : "0");
    }

    /**
-     * 按上传请求 ID 查找记录。
+     * 按内部上传 ID 查找记录。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     * @return 上传记录
     */
-    public Optional<WorkflowApiUploadRecord> find(String requestId) {
-        if (!StringUtils.hasText(requestId)) {
+    public Optional<WorkflowApiUploadRecord> find(String uploadId) {
+        if (!StringUtils.hasText(uploadId)) {
            return Optional.empty();
        }
-        String value = redisTemplate.opsForValue().get(recordKey(requestId));
+        String value = redisTemplate.opsForValue().get(recordKey(uploadId));
        if (!StringUtils.hasText(value)) {
            return Optional.empty();
        }
@@ -151,7 +151,7 @@ public class WorkflowApiUploadStore {
                    WorkflowApiUploadRecord.class));
        } catch (JsonProcessingException error) {
            throw new IllegalStateException(
-                    "读取工作流临时上传记录失败: " + requestId,
+                    "读取工作流临时上传记录失败: " + uploadId,
                    error);
        }
    }
@@ -167,16 +167,16 @@ public class WorkflowApiUploadStore {
        if (!StringUtils.hasText(executeId)) {
            return Optional.empty();
        }
-        String requestId = redisTemplate.opsForValue().get(
+        String uploadId = redisTemplate.opsForValue().get(
                executionKey(executeId));
-        Optional<WorkflowApiUploadRecord> record = find(requestId);
-        if (StringUtils.hasText(requestId)
+        Optional<WorkflowApiUploadRecord> record = find(uploadId);
+        if (StringUtils.hasText(uploadId)
                && (record.isEmpty()
                || !executeId.equals(record.get().getExecuteId()))) {
            redisTemplate.execute(
                    REMOVE_EXECUTION_INDEX_SCRIPT,
                    List.of(executionKey(executeId)),
-                    requestId);
+                    uploadId);
            return Optional.empty();
        }
        return record;
@@ -199,17 +199,17 @@ public class WorkflowApiUploadStore {
     *
     * @param now 当前 Unix 毫秒时间戳
     * @param retryAt 领取后默认重试时间
-     * @return 领取到的上传请求 ID
+     * @return 领取到的内部上传 ID
     */
    public Optional<String> claimExpired(
            long now,
            long retryAt) {
-        String requestId = redisTemplate.execute(
+        String uploadId = redisTemplate.execute(
                CLAIM_EXPIRED_SCRIPT,
                List.of(CLEANUP_INDEX),
                String.valueOf(now),
                String.valueOf(retryAt));
-        return Optional.ofNullable(requestId);
+        return Optional.ofNullable(uploadId);
    }

    /**
@@ -224,23 +224,23 @@ public class WorkflowApiUploadStore {
        redisTemplate.execute(
                REMOVE_SCRIPT,
                Arrays.asList(
-                        recordKey(record.getRequestId()),
+                        recordKey(record.getUploadId()),
                        hasExecuteId
                                ? executionKey(record.getExecuteId())
-                                : recordKey(record.getRequestId()),
+                                : recordKey(record.getUploadId()),
                        CLEANUP_INDEX),
-                record.getRequestId(),
+                record.getUploadId(),
                hasExecuteId ? "1" : "0");
    }

    /**
     * 删除已经缺少详情记录的残留清理索引。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     */
-    public void removeMissingIndex(String requestId) {
-        if (StringUtils.hasText(requestId)) {
-            redisTemplate.opsForZSet().remove(CLEANUP_INDEX, requestId);
+    public void removeMissingIndex(String uploadId) {
+        if (StringUtils.hasText(uploadId)) {
+            redisTemplate.opsForZSet().remove(CLEANUP_INDEX, uploadId);
        }
    }

@@ -256,7 +256,7 @@ public class WorkflowApiUploadStore {
        } catch (JsonProcessingException error) {
            throw new IllegalStateException(
                    "写入工作流临时上传记录失败: "
-                            + record.getRequestId(),
+                            + record.getUploadId(),
                    error);
        }
    }
@@ -272,14 +272,14 @@ public class WorkflowApiUploadStore {
        redisTemplate.execute(
                SAVE_SCHEDULED_SCRIPT,
                Arrays.asList(
-                        recordKey(record.getRequestId()),
+                        recordKey(record.getUploadId()),
                        CLEANUP_INDEX,
                        hasExecuteId
                                ? executionKey(record.getExecuteId())
-                                : recordKey(record.getRequestId())),
+                                : recordKey(record.getUploadId())),
                serialize(record),
                String.valueOf(record.getCleanupAt()),
-                record.getRequestId(),
+                record.getUploadId(),
                hasExecuteId ? "1" : "0",
                String.valueOf(EXECUTION_INDEX_TTL.toMillis()));
    }
@@ -318,19 +318,19 @@ public class WorkflowApiUploadStore {
     * @param record 上传记录
     */
    private void requireRecord(WorkflowApiUploadRecord record) {
-        if (record == null || !StringUtils.hasText(record.getRequestId())) {
-            throw new IllegalArgumentException("工作流临时上传请求 ID 不能为空");
+        if (record == null || !StringUtils.hasText(record.getUploadId())) {
+            throw new IllegalArgumentException("工作流内部上传 ID 不能为空");
        }
    }

    /**
     * 构建记录 Redis Key。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     * @return Redis Key
     */
-    private String recordKey(String requestId) {
-        return RECORD_KEY_PREFIX + requestId;
+    private String recordKey(String uploadId) {
+        return RECORD_KEY_PREFIX + uploadId;
    }

    /**
--- a/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadedFileReader.java
+++ b/easyflow-modules/easyflow-module-ai/src/main/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadedFileReader.java
@@ -1,5 +1,7 @@
 package tech.easyflow.ai.easyagentsflow.upload;

+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
@@ -16,12 +18,14 @@ import java.util.regex.Pattern;
 /**
 * 读取经过 Public Workflow API 上传记录验证的临时文件。
 *
- * <p>外部文件描述只提供公开读取路径。仅当路径中的随机请求 ID、Redis 上传记录、
+ * <p>外部文件描述只提供公开读取路径。仅当路径中的随机上传 ID、Redis 上传记录、
 * 完整文件 URL 和可恢复存储句柄全部匹配时，才允许绕过公网 URL 限制并直接读取物理对象。</p>
 */
@Component
 public class WorkflowApiUploadedFileReader {

+    private static final Logger LOG = LoggerFactory.getLogger(
+            WorkflowApiUploadedFileReader.class);
    private static final String STORAGE_PATH_PREFIX = "workflow-api-upload/";
    private static final Pattern MANAGED_PATH_PATTERN = Pattern.compile(
            "(?:^|/)workflow-api-upload/([0-9a-f]{32})/([^/]+)$");
@@ -54,8 +58,11 @@ public class WorkflowApiUploadedFileReader {
        if (managedPath == null) {
            return Optional.empty();
        }
-        WorkflowApiUploadRecord record = uploadStore.find(managedPath.requestId())
+        WorkflowApiUploadRecord record = uploadStore.find(managedPath.uploadId())
                .orElseThrow(() -> new IOException("工作流上传文件已失效，请重新上传"));
+        if (!managedPath.uploadId().equals(record.getUploadId())) {
+            throw new IOException("工作流上传文件引用与上传记录不匹配");
+        }
        WorkflowApiStoredFile storedFile = record.getStoredFiles().stream()
                .filter(file -> file != null && filePath.equals(file.filePath()))
                .findFirst()
@@ -67,7 +74,7 @@ public class WorkflowApiUploadedFileReader {
        } catch (IllegalArgumentException exception) {
            throw new IOException("工作流上传文件存储定位符无效", exception);
        }
-        String expectedStoragePath = STORAGE_PATH_PREFIX + managedPath.requestId() + "/";
+        String expectedStoragePath = STORAGE_PATH_PREFIX + managedPath.uploadId() + "/";
        if (!expectedStoragePath.equals(handle.getPath())
                || !managedPath.filename().equals(handle.getFilename())) {
            throw new IOException("工作流上传文件存储定位与上传请求不匹配");
@@ -75,6 +82,12 @@ public class WorkflowApiUploadedFileReader {
        try {
            return Optional.of(fileStorageService.readRecoverable(handle));
        } catch (RuntimeException exception) {
+            LOG.error(
+                    "读取工作流 API 上传文件失败, uploadId={}, requestId={}, executeId={}",
+                    record.getUploadId(),
+                    record.getRequestId(),
+                    record.getExecuteId(),
+                    exception);
            throw new IOException("读取工作流上传文件失败", exception);
        }
    }
@@ -92,7 +105,7 @@ public class WorkflowApiUploadedFileReader {
    }

    /**
-     * 从 URL 或相对路径中解析受管请求 ID 与固定文件名。
+     * 从 URL 或相对路径中解析受管上传 ID 与固定文件名。
     *
     * @param filePath 原始文件路径
     * @return 受管路径信息
@@ -121,9 +134,9 @@ public class WorkflowApiUploadedFileReader {
    /**
     * 系统受管上传路径中的可信定位片段。
     *
-     * @param requestId 随机上传请求 ID
+     * @param uploadId 随机内部上传 ID
     * @param filename 系统生成的存储文件名
     */
-    private record ManagedPath(String requestId, String filename) {
+    private record ManagedPath(String uploadId, String filename) {
    }
 }
--- a/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadLifecycleServiceTest.java
+++ b/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadLifecycleServiceTest.java
@@ -25,6 +25,8 @@ import java.util.Set;
 */
 public class WorkflowApiUploadLifecycleServiceTest {

+    private static final String HTTP_REQUEST_ID = "http-request-1";
+
    /**
     * 验证同名文件 Part 会按顺序保存并注入文件对象数组。
     */
@@ -63,11 +65,12 @@ public class WorkflowApiUploadLifecycleServiceTest {
                        secondHandle.encodeLocator()));

        WorkflowApiPreparedUpload prepared = fixture.service.prepare(
+                HTTP_REQUEST_ID,
                "flow",
                Map.of("user_input", "解析"),
                Map.of("documents", List.of(first, second)));

-        Assert.assertNotNull(prepared.getRequestId());
+        Assert.assertNotNull(prepared.getUploadId());
        Assert.assertEquals("解析", prepared.getVariables().get("user_input"));
        @SuppressWarnings("unchecked")
        List<Map<String, Object>> documents =
@@ -85,6 +88,12 @@ public class WorkflowApiUploadLifecycleServiceTest {
                ArgumentCaptor.forClass(WorkflowApiUploadRecord.class);
        Mockito.verify(fixture.uploadStore).create(
                recordCaptor.capture());
+        Assert.assertEquals(
+                HTTP_REQUEST_ID,
+                recordCaptor.getValue().getRequestId());
+        Assert.assertNotEquals(
+                recordCaptor.getValue().getRequestId(),
+                recordCaptor.getValue().getUploadId());
        Assert.assertEquals(
                List.of("/files/first.pdf", "/files/second.docx"),
                recordCaptor.getValue().getStoredFiles().stream()
@@ -130,6 +139,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
                        handle.encodeLocator()));

        WorkflowApiPreparedUpload prepared = fixture.service.prepare(
+                HTTP_REQUEST_ID,
                "flow",
                Map.of(),
                Map.of("documents", List.of(file)));
@@ -187,6 +197,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        BusinessException exception = Assert.assertThrows(
                BusinessException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("documents", List.of(file))));
@@ -232,6 +243,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        BusinessException exception = Assert.assertThrows(
                BusinessException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("documents", List.of(file))));
@@ -245,6 +257,53 @@ public class WorkflowApiUploadLifecycleServiceTest {
                .remove(Mockito.any(WorkflowApiUploadRecord.class));
    }

+    /**
+     * 验证无法解析的存储主机按配置故障返回不可重试的 50001。
+     */
+    @Test
+    public void prepareShouldTreatUnknownStorageHostAsPermanentFailure() {
+        Fixture fixture = fixture();
+        MultipartFile file = file(
+                "report.pdf",
+                "application/pdf",
+                10L);
+        Mockito.when(fixture.parameterResolver
+                        .resolveFileParameterNames("flow"))
+                .thenReturn(Set.of("documents"));
+        Mockito.when(fixture.parameterResolver.normalizeRuntimeVariables(
+                        Mockito.eq("flow"),
+                        Mockito.anyMap()))
+                .thenAnswer(invocation -> new LinkedHashMap<>(
+                        invocation.getArgument(1)));
+        FileStorageWriteHandle handle = handle("report.pdf");
+        Mockito.when(fixture.fileStorageService.prepareRecoverableWrite(
+                        Mockito.anyString(),
+                        Mockito.anyString()))
+                .thenReturn(handle);
+        Mockito.when(fixture.fileStorageService.saveRecoverable(
+                        file,
+                        handle))
+                .thenThrow(new IllegalStateException(
+                        "storage endpoint unavailable",
+                        new java.net.UnknownHostException(
+                                "invalid-storage-host")));
+
+        BusinessException exception = Assert.assertThrows(
+                BusinessException.class,
+                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
+                        "flow",
+                        Map.of(),
+                        Map.of("documents", List.of(file))));
+
+        Assert.assertEquals(500, exception.getHttpStatus());
+        Assert.assertEquals(50001, exception.getErrorCode());
+        Assert.assertFalse(exception.getMessage().contains(
+                "invalid-storage-host"));
+        Mockito.verify(fixture.fileStorageService)
+                .deleteRecoverable(handle);
+    }
+
    /**
     * 验证未知文件 Part 在写入存储前被拒绝。
     */
@@ -258,6 +317,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        BusinessException exception = Assert.assertThrows(
                BusinessException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("unknown", List.of(file))));
@@ -284,6 +344,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        BusinessException exception = Assert.assertThrows(
                BusinessException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("documents", List.of(file))));
@@ -313,6 +374,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        BusinessException exception = Assert.assertThrows(
                BusinessException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("documents", List.of(file))));
@@ -356,6 +418,7 @@ public class WorkflowApiUploadLifecycleServiceTest {
        IllegalStateException exception = Assert.assertThrows(
                IllegalStateException.class,
                () -> fixture.service.prepare(
+                        HTTP_REQUEST_ID,
                        "flow",
                        Map.of(),
                        Map.of("documents", List.of(file))));
@@ -374,7 +437,8 @@ public class WorkflowApiUploadLifecycleServiceTest {
    public void abortShouldDeleteStoredFilesAndRecord() {
        Fixture fixture = fixture();
        WorkflowApiUploadRecord record = new WorkflowApiUploadRecord();
-        record.setRequestId("request-1");
+        record.setUploadId("upload-1");
+        record.setRequestId(HTTP_REQUEST_ID);
        FileStorageWriteHandle firstHandle = handle("a.pdf");
        FileStorageWriteHandle secondHandle = handle("b.pdf");
        record.setStoredFiles(List.of(
@@ -391,10 +455,10 @@ public class WorkflowApiUploadLifecycleServiceTest {
                        Mockito.any(),
                        Mockito.any()))
                .thenReturn(handle);
-        Mockito.when(fixture.uploadStore.find("request-1"))
+        Mockito.when(fixture.uploadStore.find("upload-1"))
                .thenReturn(Optional.of(record));

-        fixture.service.abort("request-1");
+        fixture.service.abort("upload-1");

        Mockito.verify(fixture.fileStorageService)
                .deleteRecoverable(firstHandle);
@@ -486,16 +550,17 @@ public class WorkflowApiUploadLifecycleServiceTest {
    /**
     * 创建包含单个临时文件的上传记录。
     *
-     * @param requestId 请求 ID
+     * @param uploadId 内部上传 ID
     * @param handle 文件句柄
     * @return 上传记录
     */
    private WorkflowApiUploadRecord storedRecord(
-            String requestId,
+            String uploadId,
            FileStorageWriteHandle handle) {
        WorkflowApiUploadRecord record =
                new WorkflowApiUploadRecord();
-        record.setRequestId(requestId);
+        record.setUploadId(uploadId);
+        record.setRequestId(HTTP_REQUEST_ID);
        record.setStoredFiles(List.of(
                new WorkflowApiStoredFile(
                        "/files/" + handle.getFilename(),
--- a/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadStoreTest.java
+++ b/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadStoreTest.java
@@ -116,18 +116,34 @@ public class WorkflowApiUploadStoreTest {
                        .contains("redis.call('del', KEYS[3])"));
    }

+    /**
+     * 验证旧版 Redis 记录仍可把历史 requestId 作为内部上传 ID 读取。
+     *
+     * @throws Exception JSON 反序列化失败
+     */
+    @Test
+    public void legacyRecordShouldResolveHistoricalUploadId()
+            throws Exception {
+        WorkflowApiUploadRecord record = new ObjectMapper().readValue(
+                "{\"requestId\":\"legacy-upload-1\"}",
+                WorkflowApiUploadRecord.class);
+
+        Assert.assertEquals("legacy-upload-1", record.getUploadId());
+    }
+
    /**
     * 创建测试上传记录。
     *
-     * @param requestId 上传请求 ID
+     * @param uploadId 内部上传 ID
     * @param executeId 执行 ID
     * @return 上传记录
     */
    private WorkflowApiUploadRecord record(
-            String requestId,
+            String uploadId,
            String executeId) {
        WorkflowApiUploadRecord record = new WorkflowApiUploadRecord();
-        record.setRequestId(requestId);
+        record.setUploadId(uploadId);
+        record.setRequestId("http-request-1");
        record.setExecuteId(executeId);
        record.setCleanupAt(1_000L);
        return record;
--- a/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadedFileReaderTest.java
+++ b/easyflow-modules/easyflow-module-ai/src/test/java/tech/easyflow/ai/easyagentsflow/upload/WorkflowApiUploadedFileReaderTest.java
@@ -18,13 +18,13 @@ import java.util.Optional;
 */
 public class WorkflowApiUploadedFileReaderTest {

-    private static final String REQUEST_ID =
+    private static final String UPLOAD_ID =
            "0123456789abcdef0123456789abcdef";
    private static final String FILENAME =
            "000-abcdefabcdefabcdefabcdefabcdefab.docx";
    private static final String FILE_URL =
            "http://127.0.0.1:39000/easyflow/attachment/"
-                    + "workflow-api-upload/" + REQUEST_ID + "/" + FILENAME;
+                    + "workflow-api-upload/" + UPLOAD_ID + "/" + FILENAME;

    /**
     * 验证 URL、上传记录与恢复句柄完全匹配后按固定后端读取。
@@ -40,7 +40,7 @@ public class WorkflowApiUploadedFileReaderTest {
        FileStorageWriteHandle handle = handle();
        WorkflowApiUploadRecord record = record(FILE_URL, handle);
        byte[] content = "document-content".getBytes(StandardCharsets.UTF_8);
-        Mockito.when(uploadStore.find(REQUEST_ID)).thenReturn(Optional.of(record));
+        Mockito.when(uploadStore.find(UPLOAD_ID)).thenReturn(Optional.of(record));
        Mockito.when(fileStorageService.readRecoverable(handle))
                .thenReturn(new ByteArrayInputStream(content));

@@ -81,7 +81,7 @@ public class WorkflowApiUploadedFileReaderTest {
        FileStorageService fileStorageService = Mockito.mock(FileStorageService.class);
        WorkflowApiUploadedFileReader reader =
                new WorkflowApiUploadedFileReader(uploadStore, fileStorageService);
-        Mockito.when(uploadStore.find(REQUEST_ID)).thenReturn(Optional.empty());
+        Mockito.when(uploadStore.find(UPLOAD_ID)).thenReturn(Optional.empty());

        IOException exception = Assert.assertThrows(
                IOException.class,
@@ -100,7 +100,7 @@ public class WorkflowApiUploadedFileReaderTest {
        FileStorageService fileStorageService = Mockito.mock(FileStorageService.class);
        WorkflowApiUploadedFileReader reader =
                new WorkflowApiUploadedFileReader(uploadStore, fileStorageService);
-        Mockito.when(uploadStore.find(REQUEST_ID)).thenReturn(Optional.of(
+        Mockito.when(uploadStore.find(UPLOAD_ID)).thenReturn(Optional.of(
                record(FILE_URL + "?different=true", handle())));

        IOException exception = Assert.assertThrows(
@@ -121,7 +121,7 @@ public class WorkflowApiUploadedFileReaderTest {
                "local",
                "",
                "/tmp/easyflow-test",
-                "workflow-api-upload/" + REQUEST_ID,
+                "workflow-api-upload/" + UPLOAD_ID,
                FILENAME);
    }

@@ -136,7 +136,8 @@ public class WorkflowApiUploadedFileReaderTest {
            String fileUrl,
            FileStorageWriteHandle handle) {
        WorkflowApiUploadRecord record = new WorkflowApiUploadRecord();
-        record.setRequestId(REQUEST_ID);
+        record.setUploadId(UPLOAD_ID);
+        record.setRequestId("http-request-1");
        record.setStoredFiles(List.of(new WorkflowApiStoredFile(
                fileUrl,
                handle.encodeLocator())));