第 9 期 · M2 起步:上传、皮肤库与衣柜
· 阅读需 7 分钟
M2(材质与角色)开工。第一部分把"材质"这条主线打通:上传、存储、皮肤库、材质页、衣柜,以及之后所有积分变动都要经过的积分流水。
M2 的拆分
| 部分 | 内容 |
|---|---|
| 一(本期) | 文件存储、上传管线、blob 引用计数、积分流水、皮肤库、材质页、衣柜列表、材质文件与原图下载 |
| 二 | 角色、UUID、换肤(类型校验),CustomSkinLoader / UniSkinMod / Legacy 接口 |
| 三 | 收藏与取消收藏、材质编辑与删除(引用计数删文件、孤儿清理)、签到、仪表盘 |
| 四 | 头像与预览渲染器、举报、站内通知与公告、后台概览;S3 兼容存储 |
本期完成
- 文件存储(
internal/storage):内容寻址(文件名即 SHA-256),先写临时文件再改名,重复写入为空操作。 - 上传管线(
internal/texture):先读 PNG 头校验尺寸再解码(防解压炸弹),按类型校验宽高比,重新编码去掉元数据;同一张图已在库里(公开或自己的)就直接返回,不扣分;别人私有的同一张图共用文件、引用计数加一。 - 积分(
internal/score):唯一入口Apply,一条带条件的原子UPDATE加一行流水;注册赠送与管理员改分也改走这里。 - 皮肤库:只列公开材质(私有材质在上传者的衣柜里);类型筛选、名称搜索、最新 / 最受欢迎两种排序(白名单),游标分页,每一页都是一段有序的索引范围。
- 文件接口:
/textures/{hash}不查库,永久缓存、ETag、断点续传;/raw/{tid}遵守可见性与下载开关。 - 前端:皮肤库(首屏服务端渲染,筛选是普通链接)、材质页(skinview3d 3D 预览)、上传页(自动识别经典 / 纤细 / 披风,2D 预览,费用预估)、衣柜。
- 设计记录:ADR 0017 材质、文件存储与积分流水。
本地实测(skinloom up --dev)
用程序生成了四张测试材质:经典皮肤、纤细皮肤(手臂 3 像素)、旧版 64×32 皮肤、披风。
- 通过接口上传纤细皮肤(公开)、旧版皮肤(私有)、披风:公开每 KB 1 分、私有每 KB 10 分;再传一次披风 → 返回原来的材质,
duplicate = true,积分不变。 - 在上传页选择经典皮肤:名称自动取文件名,类型自动识别为"经典皮肤",2D 预览正确,显示预计消耗 1 积分;上传后跳到材质页,3D 模型旋转、走动。
- 皮肤库显示 4 个材质:旧版皮肤被正确转换成新布局(左手左脚镜像),纤细皮肤手臂更窄,私有材质带"私有"标记;按"纤细"筛选只剩 1 个,搜索
red只剩披风,地址分别是?category=alex、?q=red。 - 衣柜:皮肤栏 3 个、披风栏 1 个。披风的材质页单独展示披风。
- 退出登录:皮肤库只剩 3 个公开材质;打开私有材质页显示"这是一个私有材质";
/raw/2返回 403,/raw/1.png返回图片;未登录访问上传页、衣柜跳转登录页,不存在的材质 404。
实测中发现并修复:上传接口返回的材质缺少上传者信息(新建的行没有加载关联);生成的 TypeScript 上传函数会把文字字段当文件发送,改为手写的上传函数。
发布前审查
提交前又完整审查了一遍,改了这些地方(都有回归测试):
- 皮肤库原来对已登录用户列出"公开 + 自己的私有",这个
OR让数据库无法沿索引顺序读取,大库下每页都要扫描、排序全部公开材质;"全部类型"的默认视图也缺少对应的索引。现在皮肤库只列公开材质(私有材质在上传者的衣柜里),并补上(visibility, id)、(visibility, likes, id)两个索引,每一页都是一段有序的索引范围。 - 同一用户并发上传同一张图(双击、重放)会通过去重检查、生成两个材质并扣两次分;新增唯一索引
(uploader_id, hash),冲突时返回已有材质。 - 上传接口沿用了 Huma 默认 5 秒的请求体读取超时,慢速网络传不完几 MB 的图片;改为 2 分钟。上传没有频率限制,重复上传虽不扣分但同样要解码,一个用户就能占满解码槽;改为每人 10 分钟 30 次。
- 系统不认识扩展名时,浏览器以
application/octet-stream发送文件,会在校验内容前被拒绝;现在以内容判断。 [storage] path写绝对路径时会被拼到数据目录下;零积分的变化会写一行空流水;Windows 上并发写入同一文件可能失败;文件地址不支持HEAD;衣柜快速切换分栏时旧请求可能覆盖新结果。均已修复。
测试
- 存储:读写、重复写、删除、非法键(含路径穿越)。
- 积分:扣减、透支被拒、管理员改分记录操作人、15 个并发请求从只够 10 次的余额里扣分(恰好成功 10 次、余额 0、流水 10 行)。SQLite 与 PostgreSQL。
- 图片:各类型的合法 / 非法尺寸、非 PNG、只有头部却声称 65536×32768 的"炸弹"在解码前被拒、文字块被去掉。
- 上传:费用与流水、自动入衣柜、重复上传、共用文件的引用计数、积分不足时不写文件、大小与名称规则。
- 皮肤库与衣柜:可见范围、筛选、搜索、两种排序的逐页遍历、非法排序与游标、私有材质对访客 / 他人 / 本人 / 管理员。
- HTTP:上传(未登录、非 PNG、积分不足 402)、列表、详情、私有状态码 403 / 404、衣柜、三个文件前缀、
If-None-Match返回 304、原图下载与开关。 - 前端:2D 正面图的部件布局、披风识别、费用计算、筛选参数解析;类型检查、生产构建。
- 全量回归:
go test ./...(含 PostgreSQL 18)、vet、staticcheck、govulncheck;生成代码无差异、迁移无漂移。MySQL 迁移为手写,由 CI 的 MySQL 漂移检查验证。
问题与风险
- 上传会先写文件再写数据库;事务失败(例如并发下积分刚好不够)会留下没有引用的文件,孤儿清理任务在第三部分。
- 材质卡片的 2D 图在浏览器里绘制,列表很长时会有一些绘制开销;第四部分有了服务端预览图后再评估替换。
- 皮肤库的名称搜索是
LIKE '%关键字%',大站需要全文索引(设计文档里的搜索 provider),留待性能验证时处理。
下期计划
M2 第二部分:角色(建角色扣分、改名、删除)、UUID、给角色穿上衣柜里的皮肤和披风(校验类型,修 C07),以及游戏客户端拉取皮肤的 CustomSkinLoader、UniSkinMod、Legacy 接口。