MIT License

UploadBroker

轻量级资源代理网关 —— 专为 AI 推理平台的临时文件上传、读取与生命周期管理设计。不重新发明存储，而是做现有存储（Local / S3 / R2 / OSS）的统一安全外壳。

它是临时存储界的 Redis。

AI Skill
AI / Skills 使用指南

Upload Broker 支持 AI Agent、AI Coding Assistant、Skills 等自动安装、部署和调用。

1安装指定版本：
go install github.com/doc-war/uploadbroker/cmd/uploadbroker@latest
2自动生成 uploadbroker.yaml，根据可用域名配置 base_url
3启动 Broker：
uploadbroker --config ./your-path/uploadbroker.yaml
4健康检查：GET /health
5上传资源：POST /v1/upload
6返回结果中的 url 为公网可访问地址，直接作为 AI 模型输入
去github仓库docs/skill.md查看完整指引 →
查看源码 ↗

3 个端点 · 6 项安全校验 · 0 外部运行时依赖

UPLOADBROKER
提货单 · CLAIM TICKET № 9F21C7
Issued10:42:07
Expires+24h
Key9c3f…e21a
Token4b7e…90fd
Shard9c
Backendaws-s3
BLAKE2b-256 · HMAC SIGNED
已签发ISSUED
POSITIONING

不重新发明存储，重新设计接入方式

uploadbroker 不做底层存储——它在存储的前面充当统一的安全代理层。

定位

轻量级代理网关

专为AI推理时代的临时资源url消费设计：给 Local / S3 / OSS / R2 这些现成仓库，套一层开箱即用的安全外壳——签发、校验、到期回收，一条龙。

生命周期

专为 TTL 1~24h 设计

后台秒/分级主动清理，无需 cron 脚本接管。天然契合 AI 推理（图生图、语音转文字）高频产生、短命临时文件的场景。

安全性

内容哈希寻址 + URL 签名

零信任架构。魔数检测、扩展名校验、HMAC 鉴权、Salt 轮换全套兜底。Platform 不需要知道底层存储结构，URL 不暴露真实桶路径。

体积与依赖

Go 单二进制 + SQLite

极简内聚，极易集成进 CI/CD 或作为 Sidecar 部署。存储驱动插件化，后端随意切换，上层零改动。

ARCHITECTURE

可嵌入设计，不做上层平台

定位临时存储业务核心，认证交给 Platform，剩下的事跟它没关系

Client发起上传 / 读取
⇢
Platform鉴权 / 限流
⇢
UploadBroker签发 / 读取 / 回收
→
StorageLocal · S3 · OSS · R2 · COS

Platform 决定谁可以访问（Who）；Broker 决定资源是否合法以及如何获取（What & How）。

uploadbroker 不管用户、不管权限，只认文件和签名。Platform 把 session 换成 JWT、加一层 RBAC，它没感觉；它换存储驱动或升级安全策略，Platform 也不用跟着发版。同一个实例，可以被多个产品线一起共用。

QUICKSTART

快速开始

单二进制部署，无外部运行时依赖。

1

下载二进制（或 go install github.com/doc-war/uploadbroker）

2

编写配置 uploadbroker.yaml

3

启动 Broker

4

上传文件

5

读取文件

# uploadbroker.yaml
listen: 127.0.0.1:9001
base_url: https://upload.example.com # 注入访问根，拼接提货单
# 上传 & 读取
$ curl -F "file=@photo.png" "http://127.0.0.1:9001/v1/upload"
{"code":0,"data":{"url":"https://...","mimeType":"image/png"}}
$ curl "https://upload.example.com/tmp/..."
URL ANATOMY

一张提货单，拆开看

资源 URL 由 Broker 签发，五个字段各管一件事，业务层不需要再查库判断权限。

/{prefix}/{expire}/{shard}/{key}/{token}.{ext}

{prefix}

前缀 · 配置 url_prefix，默认 tmp

{expire}

几点过期 · Unix 秒级时间戳

{shard}

存哪个格子 · key 前两位做目录分片

{key}

身份证 · BLAKE2b-256 内容哈希

{token}

防伪章 · URL 签名，防篡改

{ext}

什么类型 · 由 MIME 检测结果推导

API

三个端点，够用了

没有桶管理，没有 ACL，上传、读取、健康检查就是全部。

POST /v1/upload multipart 上传文件，可选携带 expires / sign / timestamp
GET /v1/health 健康检查
GET /{prefix}/{expire}/{shard}/{key}/{token}.{ext} 读取资源，URL 由 Broker 签发
SECURITY

默认安全，不是选装件

这些是日常开发里最容易漏掉、出事才想起来补的点，框架层面直接兜底。

✓

魔数检测

读文件头前 512 字节，确认真实格式，而非只看后缀

✓

扩展名校验

文件名后缀必须和魔数检测结果一致，防伪装上传

✓

HMAC 上传校验

配置 hmac_secret 后，上传必须携带合法签名

✓

URL 签名

BLAKE2b-256 签名，链接被改一个字符就失效

✓

自动过期回收

TTL 到期自动清理，不用自己写定时任务

✓

路径穿越防护

Local 驱动限制 .. 访问，挡掉路径穿越

STORAGE DRIVERS

存储后端，随便换

写入认 upload_driver，读取按记录里的 Backend 自动路由——换厂商不用改业务代码。

Local 文件系统 AWS S3 阿里云 OSS Cloudflare R2 腾讯 COS MinIO
FAQ

为什么不直接用主流框架？

uploadbroker 不做底层存储，而是在上层提供统一的安全代理层。以下对比帮你理解它跟主流方案的本质区别。

MinIO 已经是 S3 兼容的对象存储了，为什么还要套一层 Broker？

MinIO 定位是完整的对象存储系统，而 uploadbroker 定位是资源代理网关，它们解决的是不同层次的问题。

  • MinIO：持久化存储海量数据，面向长期存储场景，需要维护集群、配置桶策略和 Presigned URL 权限
  • uploadbroker：管理 AI 推理产生的临时文件（1~24h TTL），自动清理过期资源，统一安全层（魔数检测 + URL 签名 + 扩展名校验），存储后端对业务透明

MinIO 的 Presigned URL 暴露了桶路径和权限模型，而 Broker 的 URL 零信任——Platform 只需拿到标准 URL，不需要知道底层是 MinIO、OSS 还是本地磁盘。

一句话：MinIO 是做存储的，uploadbroker 是做安全的——始终站在存储前面，充当统一的安全代理。

SeaweedFS 支持 FUSE、S3、NoSQL，为什么不直接用？

  • SeaweedFS：Master + Volume 架构，运维成本高，无原生短 TTL 机制，过期清理需外部脚本来做
  • uploadbroker：单二进制，0 运维，内建秒级 TTL 清理，底层存储只负责读写，生命周期由 Broker 统一管理

SeaweedFS 的 FUSE 挂载功能对 AI 训练场景有价值，但对于 API 驱动的临时文件读写（推理服务的输出图片、语音、PDF），Broker 更轻量、更聚焦。

一句话：SeaweedFS 是通用分布式文件系统，uploadbroker 是专为 API 临时文件场景设计的轻量资源代理。

Ceph 是业界标准分布式存储，为什么不直接用？

  • Ceph：部署复杂（MON/MGR/OSD/MDS），运维门槛极高，适合大规模持久化存储（PB 级）
  • uploadbroker：单二进制，开箱即用，适合 AI 推理场景中高频产生、短生命周期的临时文件

Ceph 在超大规模集群中表现出色，但 AI 推理场景的临时文件管理需求是：上传 → 消费 → 过期清理，这个循环只需要小时级存在。用 Ceph 管这种临时数据是"杀鸡用牛刀"。

一句话：Ceph 是为大规模持久化设计的，uploadbroker 是为临时文件场景设计的——需求层级不同。

Garage 轻量且 S3 兼容，为什么不用？

  • Garage：轻量的底层存储节点，专注于数据持久化和复制，缺少资源生命周期管理和安全防护层
  • uploadbroker：在存储之上提供 完整的安全链——魔数检测、扩展名校验、URL 签名、HMAC 鉴权、Salt 轮换

Garage 和 uploadbroker 完美互补——你可以用 Garage 当底层，Broker 当接入层。今天用 Garage，明天切 MinIO，后天切阿里云 OSS，Platform 端零感知。

一句话：Garage 和 uploadbroker 不是替代关系，而是互补关系——Garage 管存储，Broker 管安全与生命周期。

RustFS 高性能高安全，为什么不直接用？

  • RustFS：专注于底层存储性能和一致性，适合高频读写场景，但缺少针对 AI 临时文件场景的业务抽象
  • uploadbroker：专注 AI 推理工作流——图生图输出 PNG、语音转文字输出 WAV/MP3、视频处理输出 MP4，每个文件天然小时级 TTL

性能并非 AI 临时文件管理的瓶颈——通常单机就能承载推理节点的输出流量。真正的痛点是：安全防护、过期管理和存储切换的灵活性，这正是 uploadbroker 的核心能力。

一句话：RustFS 优化的是存储性能，uploadbroker 优化的是业务安全与灵活性——不同层次的差异化价值。