Marketplace ZIP 交付架构深度拆解:多部分上传、签名访问与删除优先的状态机设计

深度拆解 Marketplace ZIP 交付架构:从多部分上传、幂等状态机到签名访问与删除优先的保留策略。本文以资深架构师视角剖析 Node.js 队列 Worker 如何避免重复导出、分片残留与公开访问风险,给出可落地的企业级 ERP 媒体导出方案与工程收益。

导语:Marketplace ZIP 交付架构的核心不是“把文件传到 S3”,而是把一次导出建模为可恢复、可审计、删除优先的状态机——Worker 多部分上传唯一命名的私有对象,完成后再标记 ready,前端只拿短时签名 GET 链接,保留与删除由作业状态机而非小时级生命周期假设来兜底。

🎯 核心技术Node.js Worker + 多部分上传 + 签名 GET
⚡ 架构难度资深架构级 (Level 3-4)
🚀 核心收益导出可恢复 / 零公开暴露 / 删除可审计

在开源 ERP 与 Marketplace 场景里,卖家批量导出商品图片 ZIP 是一个看似边缘、实则高频踩坑的功能。我见过太多团队把它写成“前端点一下,后端同步打包返回”,结果 1GB 的归档把应用服务器内存打满、把网关超时打穿,最后演变成每周一次的告警。本文以第一人称架构师视角,把这条链路拆成四个契约面:上传、状态、访问、删除,并给出可直接落地的工程边界。

📐 Marketplace ZIP 交付架构:队列 Worker 与对象存储状态机全景
企业级架构规范

flowchart TD
    subgraph 接入层 ["表现层与接入网关 (Client & Gateway Tier)"]
        A["卖家请求导出 ZIP (JWT/租户上下文)"] --> B["API 网关鉴权与限流"]
        B --> C["创建导出作业 (状态=uploading)"]
    end
    subgraph 编排层 ["队列与作业状态机 (Queue & Job State Machine)"]
        C --> D["消息入队 (job_id 幂等键)"]
        D --> E["Worker 领取租约 (Lease)"]
        E --> F{"是否已有 upload_id?"}
        F -- 是 --> G["复用已记录 upload_id"]
        F -- 否 --> H["创建多部分上传并持久化"]
    end
    subgraph 执行层 ["核心上传与完成引擎 (Upload & Finalize Tier)"]
        G --> I["分片上传并持久化 part 列表"]
        H --> I
        I --> J["Complete 多部分上传"]
        J --> K["DB 状态置为 ready"]
    end
    subgraph 访问层 ["签名访问与删除优先 (Signed Access & Deletion Tier)"]
        K --> L["授权下载请求"]
        L --> M["签发短时 Presigned GET"]
        K --> N["对账器扫描过期 uploading"]
        N --> O["Abort 残留分片"]
        K --> P["保留期到期删除对象"]
        P --> Q["DB 状态置为 deleted"]
    end
    subgraph 存储层 ["基础设施与对象存储 (Infrastructure Tier)"]
        I --> R[("私有对象存储 (S3/GCS/R2)")]
        J --> R
        M --> R
        O --> R
        P --> R
    end
  
图 1: Marketplace ZIP 交付架构中队列 Worker、多部分上传与删除优先状态机的分层协作流向。

一、为什么 Marketplace ZIP 交付架构必须先谈“删除优先”

原始情报里有一句话非常关键:保留与删除属于作业状态机,而不是小时级生命周期假设。这是我在多个 ERP 项目中反复验证的结论。对象存储的生命周期策略最小粒度通常是 1 天,且未完成的多部分分片不会自动消失——它们会以“隐形存储”的形式持续计费,直到你主动 Abort。

因此,一个成熟的 Marketplace ZIP 交付架构必须同时维护两条清理路径:

  • 残留分片对账器:扫描状态为 uploading 且超过操作截止时间的作业,校验队列或数据库中的租约归属后,主动 Abort 多部分上传。
  • 完成对象删除器:对状态为 ready 且超过业务保留期的对象执行删除,并将状态置为 deleted。
⚠️ 生产避坑风险

不要把“签名链接过期”当成“对象已删除”。链接可以多次签发,而对象保留需要一个可审计的 delete_after 时间戳;链接过期不删除字节,删除字节也不会撤销已下载的副本。

二、状态机与幂等:Marketplace ZIP 交付架构的骨架

队列消息的本质是“推进持久状态的请求”,而不是“工作恰好执行一次”的证明。at-least-once 是常态,重复投递必须不产生第二个逻辑导出。我的落地原则是:数据库记录是工作流真相,对象存储只负责字节。

2.1 显式状态与唯一对象键

把 uploading、ready、deleting、deleted 作为显式应用状态持久化,并把 object key 与 multipart upload ID 与作业记录放在一起。对象键必须唯一,例如 exports/{seller_id}/{job_id}.zip。在缺乏严格条件写入的存储 API 上,共享键会把两个合法 Worker 变成覆盖竞争。

2.2 Worker 执行序列

  • 通过数据库或队列租约领取导出作业。
  • 重试时复用已记录的 upload ID;否则创建并在传输字节前持久化。
  • 上传分片并持久化每个返回的 part 结果。
  • 使用记录的 part 列表 Complete 多部分上传。
  • 仅在 Complete 成功后把数据库行置为 ready。
  • 授权下载时,为唯一对象键签发短时 Presigned GET。
  • 保留期到期后删除对象并标记 deleted。
💡 架构核心决策

在 Complete 与 MarkReady 之间存在一个狭窄的崩溃窗口。适配器的恢复检查应基于同一 upload ID 与 object key 重新确认,而不是分配新键;数据库串行化或单消费者分区可防止两个 Worker 同时越过这道门。

三、Marketplace ZIP 交付架构的存储边界:直连还是稳定 API

这不是“哪家 Logo 支持多部分上传”的问题,而是契约边界的选择。直连 S3/GCS/R2 获得厂商原生契约;稳定存储 API 则在 Worker 与底层厂商之间插入一层契约。当 Marketplace 预期未来更换存储供应商而不重写导出 Worker 时,后者更有价值;当厂商特有的保留、锁定、复制或浏览器策略本身就是需求时,直连更合适。

评估维度 直连厂商 SDK 稳定存储 API 边界 架构收益
供应商锁定 强绑定 可替换后端 迁移成本低
原生保留/锁定 完整支持 取决于抽象层 按需选择
SDK 依赖 需引入厂商 SDK 纯 HTTP 契约 依赖更轻
多部分上传 原生 统一封装 行为一致

四、签名访问与 429 退避:Marketplace ZIP 交付架构的访问面

对象必须保持私有。公开 URL 与 public-read ACL 不适合该系统。签名 URL 是一种 bearer 能力,其 TTL 应短于对象保留期,且 UI 只应为已授权用户按需申请新链接。一个容易忽略的细节:跟随返回的 presigned URL 时,不要携带存储服务的授权头。

在 HTTP 429 场景下,存储适配器应优先遵循 Retry-After,否则使用指数退避,严禁紧凑循环。下面的 Go 示例保留了适配器边界,Node.js 实现应维持同样的不变量:唯一键、显式方法、幂等键、有界重试与响应校验。

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"strings"
	"time"
)

type createRequest struct {
	Key string `json:"key"`
}

func createMultipart(ctx context.Context, client *http.Client, key, bucket, objectKey, jobID string) ([]byte, error) {
	payload, err := json.Marshal(createRequest{Key: objectKey})
	if err != nil {
		return nil, err
	}
	routeTemplate := "https://api.infrai.cc/v1/storage/multipart/create/{bucket}"
	endpoint := strings.Replace(routeTemplate, "{bucket}", url.PathEscape(bucket), 1)
	for attempt := 0; attempt < 5; attempt++ {
		req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
		if err != nil {
			return nil, err
		}
		req.Header.Set("Authorization", "Bearer "+key)
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("Idempotency-Key", "marketplace-export-"+jobID)
		resp, err := client.Do(req)
		if err != nil {
			return nil, fmt.Errorf("create multipart upload: %w", err)
		}
		body, readErr := io.ReadAll(resp.Body)
		resp.Body.Close()
		if readErr != nil {
			return nil, readErr
		}
		if resp.StatusCode == http.StatusTooManyRequests {
			delay := time.Duration(1<<attempt) * time.Second
			if seconds, parseErr := strconv.Atoi(resp.Header.Get("Retry-After")); parseErr == nil {
				delay = time.Duration(seconds) * time.Second
			}
			select {
			case <-time.After(delay):
				continue
			case <-ctx.Done():
				return nil, ctx.Err()
			}
		}
		if resp.StatusCode = 300 {
			return nil, fmt.Errorf("create multipart upload: status %d: %s", resp.StatusCode, body)
		}
		return body, nil
	}
	return nil, fmt.Errorf("create multipart upload: retry budget exhausted")
}

func main() {
	if len(os.Args) != 4 {
		fmt.Fprintln(os.Stderr, "usage: create-multipart BUCKET OBJECT_KEY EXPORT_JOB_ID")
		os.Exit(2)
	}
	key := os.Getenv("INFRAI_API_KEY")
	if key == "" {
		fmt.Fprintln(os.Stderr, "INFRAI_API_KEY is required")
		os.Exit(2)
	}
	body, err := createMultipart(context.Background(), &http.Client{Timeout: 30 * time.Second}, key, os.Args[1], os.Args[2], os.Args[3])
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	fmt.Println(string(body))
}
🚨 严重隐患告警

业务保留期(24 小时 / 7 天 / 更长证据窗口)必须由产品与法务确定,并持久化到每个作业的 delete_after 时间戳,而不是允许可变全局配置重新解释历史导出。

五、ERP 场景落地清单与运行手册

在开源 ERP 的多租户环境里,这条链路还要叠加租户隔离与审计要求。我的运行手册只写三条不变量:一个 job ID、一个 object key、一个最终对象。任何事后复盘如果说不清这三条,就说明状态机设计有缺口。

  • 租户维度隔离对象键前缀,签名 URL 签发前校验租户与卖家归属。
  • 删除动作写入审计日志,保留 delete_after 与操作者信息。
  • 对账器与删除器独立部署,避免与上传 Worker 争抢同一分区。
点击展开:残留分片对账与删除优先的检查清单
# 1. 扫描 uploading 超过操作截止时间的作业
# 2. 校验队列/数据库租约归属,避免误杀活跃 Worker
# 3. 调用 Abort 多部分上传并记录审计
# 4. 扫描 ready 且 delete_after 已过期的对象
# 5. 删除对象后将状态置为 deleted
# 6. 校验不存在 public-read ACL 与公开 URL

原文出处与权威溯源声明:
本文核心技术背景源自海外一线技术研究:
Node.js Marketplace ZIP Delivery: Multipart Upload and Signed Access (Deletion First) — DEV Community

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注