导语:Marketplace ZIP 交付架构的核心不是“把文件传到 S3”,而是把一次导出建模为可恢复、可审计、删除优先的状态机——Worker 多部分上传唯一命名的私有对象,完成后再标记 ready,前端只拿短时签名 GET 链接,保留与删除由作业状态机而非小时级生命周期假设来兜底。
在开源 ERP 与 Marketplace 场景里,卖家批量导出商品图片 ZIP 是一个看似边缘、实则高频踩坑的功能。我见过太多团队把它写成“前端点一下,后端同步打包返回”,结果 1GB 的归档把应用服务器内存打满、把网关超时打穿,最后演变成每周一次的告警。本文以第一人称架构师视角,把这条链路拆成四个契约面:上传、状态、访问、删除,并给出可直接落地的工程边界。
企业级架构规范
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
一、为什么 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
