oss —— 对象存储统一抽象(本地磁盘 / 阿里云 OSS)
文件存哪、key 怎么拼、直链怎么给 —— 一套接口罩住本地磁盘和阿里云 OSS。 本仓的模型是一个桶 / 一棵树 / key 恒 5 段,文件没有 public 状态。
功能
Provider 接口(8 个方法)
| 方法 | 干什么 |
|---|---|
Name() |
实现名(local / oss / mock),排障和选型断言的抓手 |
SignUploadToken(key, ttl, maxSize) |
签发上传凭证 |
Put(key, r, contentType) |
服务端直写(必须是原子的) |
SignDownloadURL(key, ttl) |
签出下载 URL |
Stat(key) |
取单个对象元信息 |
Delete(keys...) |
删对象(key 不存在不算错) |
DeletePrefix(prefix) |
删前缀下全部对象,返回删掉的字节数 |
List(opt) |
列举前缀下的对象 + 虚拟目录 |
三个实现:local(本地磁盘)、aliyun(阿里云 OSS)、MockProvider(内存桩)。
key 恒 5 段
<root>/<userID>/<biz>/<folderID>/<objectName>
例:rapid-admin/1001/order/5001/1756000000-a1b2c3d4-报告扫描件.pdf
root—— 路径根词,默认rapid-admin,可配(file.path_root)userID/biz/folderID—— 全部由服务端决定,客户端只能提交文件名objectName——{unix秒}-{rand8}-{清洗后原名},扩展名一定留在末尾
文件没有 public 状态
存储侧只有一个桶(阿里云)或一棵树(本地磁盘),所有文件都能按 URL 直接取到。 "私密"只意味着外部用户猜不到这个 key(uid 是雪花 id、对象名带随机后缀), 而不是"存在另一个别人访问不到的目录"。
所以 key 里不许有 public 段,也不许有"公开/私有"两套形态 —— 两套形态意味着两套路径规则、两套前缀清单、两处删除前缀逻辑,而它们迟早会分叉。
每个文件都有一个不带签名的稳定直链
前端把这个 URL 直接塞进 <img src>。签名 URL 一过期,页面上的图就裂 ——
而文件列表页可能开一整天。直链稳定是刻意的,代价是桶必须是公共读。
可选接口(高级特性)
MultipartProvider(分片 + 断点续传)、ScanProvider(病毒扫描)、
ThumbnailProvider(缩略图)、HotlinkProvider(防盗链)、QuotaProvider(配额)、
CDNProvider(CDN 刷新/预热)、ContentProvider(服务端中转读)、
MetaReader(读小元数据对象)。
mp, sp, tp, hp, qp, cp := oss.Advanced(provider) // 不支持的一律返 nil
它不解决什么
- 不做业务编排(什么时候上传、配额怎么算、归属怎么校验)—— 那是 service 层
- 不做分片阈值的策略决策(该用多大分片)——
CheckPartSize只管硬限制 - 不做"公开/私有"两套布局(本仓没有这个概念)
配置
yaml 侧(file: 块 —— 决定"文件放在哪、怎么放")
file:
provider: local # local | aliyun。**空 = local**
root: data/files # local 时的磁盘根(相对 server/,加载时转绝对)
path_root: rapid-admin # 路径根词 = key 的第一段 = 静态挂载点
allowed_biz: [] # 业务段白名单。**留空 = 不限**
max_file_size_mb: 100 # 单文件上限,0 = 不限
multipart_threshold_mb: 100 # 超过这个大小建议走分片
multipart_part_size_mb: 8 # 分片大小(下限对齐 OSS 的 100KB)
session_ttl: 24h # 上传会话有效期
download_url_ttl: 15m # 下载 URL 默认有效期
max_download_ttl: 24h # 下载 URL 有效期上限
yaml 侧(oss: 块 —— 决定"怎么连阿里云")
oss:
endpoint: oss-cn-hangzhou.aliyuncs.com
endpoint_private: oss-cn-hangzhou-internal.aliyuncs.com
access_key: ${OSS_ACCESS_KEY}
access_secret: ${OSS_ACCESS_SECRET}
bucket: rapid-admin
cdn_domain: https://cdn.rapid-admin.local
upload_token_ttl: 3600
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
file.provider |
string | local |
local / aliyun。空 = local |
file.root |
string | data/files |
local 的磁盘根 |
file.path_root |
string | rapid-admin |
key 第一段 + 静态挂载点 |
file.allowed_biz |
[]string | 空(不限) | 业务段白名单,填了就当白名单用 |
file.max_file_size_mb |
int | 100 |
单文件上限,0 = 不限 |
file.multipart_threshold_mb |
int | 100 |
建议分片的阈值 |
file.multipart_part_size_mb |
int | 8 |
分片大小 |
file.session_ttl |
duration | 24h |
上传会话有效期 |
file.download_url_ttl |
duration | 15m |
下载 URL 默认有效期 |
file.max_download_ttl |
duration | 24h |
下载 URL 有效期上限 |
oss.endpoint |
string | — | 外网 endpoint,只用来拼直链 |
oss.endpoint_private |
string | — | 内网 endpoint,只给 SDK 客户端 |
oss.access_key / oss.access_secret |
string | — | 阿里云 AK/SK |
oss.bucket |
string | — | 只有一个桶,必须是公共读 |
oss.cdn_domain |
string | 空 | 可选 CDN 域名,配了就用它拼直链 |
oss.upload_token_ttl |
int(秒) | 3600 |
直传凭证有效期。⚠️ 当前没有接线(见下) |
⚠️ oss: 整块在 file.provider: local 时不生效;file: 块在 aliyun 模式下
照样生效(路径形态和配额闸跟后端无关)。两块正交,别合并。
代码侧
local.New(local.Config{Root: ..., URLBase: ...}) // 本地磁盘
aliyun.New(aliyun.Config{Endpoint: ..., Bucket: ..., ...}) // 阿里云 OSS
oss.NewMockProvider() // 内存桩
local.Config.URLBase 是静态挂载点(如 /rapid-admin),
必须等于静态挂载点 —— 而挂载点由 path_root 推导,两边从同一个值算出来,
就不可能对不齐(以前它们各配各的,对不齐的症状是"URL 永远 404")。
使用方法
完整示例:examples/oss/main.go。
一、对象名清洗
name, err := oss.NewObjectName("报告 扫描件.pdf") // 1756000000-a1b2c3d4-报告 扫描件.pdf
ext := oss.ObjectExt(name) // ".pdf"
二、构造 key
spec := oss.PathSpec{
Root: oss.DefaultRoot, // "rapid-admin"
UserID: 1001,
Biz: "order",
FolderID: 5001,
ObjectName: name,
}
key, err := oss.BuildKey(spec) // rapid-admin/1001/order/5001/<name>
三、反解 key
parts, err := oss.ParseKey(oss.DefaultRoot, key)
// parts.Root / parts.UserID / parts.Biz / parts.FolderID / parts.ObjectName
四、MockProvider(不依赖外部存储)
p := oss.NewMockProvider()
meta, err := p.Put(ctx, key, bytes.NewReader([]byte("hello")), "application/pdf")
got, err := p.Get(ctx, key)
_, err = p.Stat(ctx, "不存在的key")
oss.IsNotFound(err) // true
五、列举
res, err := p.List(ctx, oss.ListOption{Prefix: oss.DefaultRoot + "/1001/"})
六、删前缀(返回字节数)
n, err := p.DeletePrefix(ctx, oss.DefaultRoot+"/1001/")
// 用户存储配额靠这个值回退
七、直链
url, err := p.SignDownloadURL(ctx, key, time.Hour)
注意事项
⚠️ key 恒 5 段,段数是死的:
root/uid/biz/folder/name。ParseKey不许"尽力而为"解析出一半 —— 归属校验宁可失败也不能猜。 多一段少一段都是非法 key。⚠️
ParseKey是 key 的唯一反解入口。全仓只能问这一份实现 —— 不许在 service / handler / 前端各写一遍strings.Split(key, "/")再按下标取: 那种写法在"biz 段数变了"、"root 可配"时会错位,而错位之后取到的 uid 是别人的, 归属校验会静默失效。⚠️ 文件没有 public 状态。私密靠"key 不可猜"(uid 是雪花 id、对象名带随机后缀), 不是靠 ACL 挡。key 里不许有 public 段。
⚠️ 直链是不带签名、不带过期时间的稳定 URL ⇒ 桶必须是公共读(public-read)。 私有桶上它会 403,症状是"传上去了、列表里点得开、打开是裂图"。
SignDownloadURL的ttl参数在这里不用(没有过期时间的东西不需要 ttl), 签名它只是为了满足 Provider 接口的统一形状。⚠️ CDN 必须真的回源到这个桶,否则直链全是 404 —— 症状同样是"上传成功、 列表里点得开、打开是裂图"。
⚠️ 直链永远用外网 endpoint。
oss.endpoint_private只给 SDK 客户端用 —— 直链是给公网上的浏览器看的,给它内网地址它访问不到。 而且endpoint_private在构造时会探一次TCP 连通性(不只是 DNS: 阿里云-internal域名在公网上也能解析,指向 VPC 内部的 100.64.0.0/10, 路由不通),连不上就自动回落外网 endpoint。⚠️ provider 名有常量,别写字面量:
oss.ProviderNameLocal/oss.ProviderNameOSS/oss.ProviderNameMock。service 层要按这个名字判断"文件实际躺在哪" (model.FileStorage)。早先 service 层比的是手写字符串"aliyun",而 aliyun provider 的Name()返回"oss"—— 永远不相等,于是无论真配了 OSS 还是本地磁盘, 每一行文件都被记成"本地磁盘",逐行记 storage 的意义整个废掉。⚠️
oss.provider这个 yaml 键不存在(已删)。真正决定"文件存哪"的是file.provider。留着它的害处比删掉大:配置里写什么都零症状(viper 不认的键直接丢掉), 于是"这个键到底管什么"永远查不出来。⚠️
SignUploadToken的参数是完整 key,不是目录前缀。旧的 PostObject 形态只签starts-with $key =<dir>,客户端能在那个前缀下任意写 key —— 拿到凭证就能把文件 塞进同 bucket 的任意目录。改成eq $key =<key>之后,凭证的作用域就是那一个对象。⚠️
Stat找不到对象时必须让oss.IsNotFound(err) == true—— service 层靠它 把 404 和 500 分开。上游用errors.Is(err, os.ErrNotExist)是判不出来的 (ErrNotFound实现了Is方法,errors.Is/errors.As都能用)。⚠️
DeletePrefix返回字节数:用户存储配额(sys_user.storage_used_bytes)靠它回退, 没有返回值就只能整表重算。而Delete里 key 不存在不算错(幂等),否则重试会永远失败。⚠️
SafeKey允许 Unicode(中文文件名在本平台是常态),但拒..、\、控制字符、 空段、单段超长。空段最容易漏:只查HasPrefix/HasSuffix的话a//b会漏过去, 而它在filepath.Join之后会静默塌成a/b。 ⚠️SafeKey不等于安全 —— 它只管字符,不管这个 key 属不属于当前用户, 归属校验在 service 层,别拿SafeKey当授权用。⚠️ 对象名带 unix 秒 + rand8 前缀,不是原名直用。Windows/macOS 的磁盘大小写不敏感:
A.pdf和a.pdf在 DB 里是两行,在磁盘上是同一个文件,第二行会静默覆盖第一行。⚠️
oss.DefaultRoot从res改成rapid-admin是一次数据迁移,不是改个常量就完了: key 的第一段同时是静态挂载点,改了之后存储上的对象和库里的 key 必须一起搬, 否则每个历史文件 404(而且直链不经后端,日志里可能一次请求都没有)。 它必须跟file.path_root的默认值一致 —— 两者一旦漂移,"用兜底值的路径"和 "用配置值的路径"会长成两棵树。⚠️ local 的
Put是原子的:同目录临时文件 → fsync → rename 覆盖。 临时文件必须在同目录 —— 跨文件系统的 rename 会失败(EXDEV),而/tmp和数据盘 几乎总是两个文件系统。Windows 上 rename 覆盖一个"正被读"的文件会 EPERM, 实现里带退避重试(6 次)。⚠️ local 的路径解析有三层防御:
SafeKey→filepath.Rel边界检查 → 符号链接检查。边界检查不能用strings.Contains(target, root)—— root=/data/res 时/data/res2/x也 Contains 成立。符号链接检查的求值对象是 最近的已存在祖先目录,不是目标本身(对还不存在的目标文件调EvalSymlinks会拿到 ENOENT,把正常上传全拒掉)。⚠️ 直链要逐段 percent-encode:整条编码一次会把
/也变成%2F, 那条路径在 OSS 上根本不存在。不编码的话中文直链在"复制到聊天工具/邮件"这类场景里 会被截断,空格会让 URL 解析提前结束。⚠️ MockProvider 是内存桩,不是磁盘桩 —— 进程一重启数据全没。 它的
SignDownloadURL返回的 URL 访问不到任何东西:测试里断言 "拿到 URL 就当能下载"会假绿,要测下载得换 local 或真 OSS。⚠️
MetaReader.Get有 8MB 上限(各实现),只用于读小元数据对象(当前唯一用途 是info.json)。拿它读大文件就是应用服务器 OOM —— 大文件走ContentProvider或直链。⚠️
oss.upload_token_ttl配了不生效。yaml 里的这个值被读进config.OSSConfig.UploadTokenTTL,但没有任何地方把它接到service.FileOptions.UploadTokenTTL—— service 那边始终用默认值 (30 分钟)。凭证有效期想改,得走 service 层的选项,不是改 yaml。⚠️ 分片大小不要依赖默认值。默认
DefaultPartSize是 10MB,对 100GB 文件会 正好卡满 10000 片上限;1GB 文件用 100MB 分片只要 10 片。WithPartSize/WithTotalSize是InitMultipartUpload的选项,CheckPartSize/CheckPartNumber只管硬限制(下限 100KB、上限 10000 片)。