0035 M5 的拆分;BS 导入器(核心数据)
- 状态:已接受(2026-11-04)
- 相关:设计文档 02 §5、§6;04 §10、§13(M5);ADR 0017、0018、0022、0027
背景
- 04 §13 的 M5 是"迁移与发布":BS 导入器、契约测试全量、k6 压测、安全自查、真实站点 beta,验收是真实站点稳定运行 2 周后发布 v1.0。
- 02 §5 列了 BS 每张表的转换规则,并要求导入器只读源库、可 dry-run、幂等可重跑、输出报告,支持 MySQL/PG/SQLite 源与表前缀。04 §10 是迁移步骤:dry-run → 处理报告 → 正式导入 → 抽查 → 切换 → 回滚只需切回 BS。
- 用户侧的承诺(04 §10):密码、角色、UUID、皮肤链接、衣柜、积分不变;会话、启动器令牌不迁移,大家重新登录一次。
决策
-
M5 分五部分,每部分一期开发日志:
- BS 导入器:账号、角色与 UUID、材质与文件、衣柜、举报、未读通知(本 ADR)。
- BS 导入器:站点设置(02 §4 的 options 映射)、翻译覆盖(
language_lines,ADR 0031)、OAuth 应用(02 §2.6)、Yggdrasil 签名密钥;迁移回归库(02 §6 第 4 条)与密码兼容向量(第 3 条)。 - 契约测试全量:黄金文件、authlib-injector 端到端、渲染快照(02 §6 第 1、2、5 条)。
- k6 压测,验证 04 §5.4 的性能目标。
- 安全自查:CSP(与自定义 JS 一起,ADR 0030)以及 ADR 0034 记下的遗留问题。
之后用真实站点 beta(04 §12 D6,需要一个真实的 BS 站),稳定两周发布 v1.0。
-
命令
skinloom import bs:- 从 BS 的
.env(--env)读出数据库、表前缀、PWD_METHOD、SALT、材质目录(TEXTURES_DIR,默认storage/textures)。命令行参数可以逐项覆盖;连接串和盐也可以放在SKINLOOM_BS_DSN、SKINLOOM_BS_SALT里,不出现在命令行上。 .env按 Laravel 的规则读:不带引号的值在第一个#处截断,null、(null)、empty、(empty)都是空。FS_DRIVER指向对象存储时,材质要先下载到一个目录,再用--textures指定。- 报告写到
<data>/import/bs-<时间>.txt,权限 0600(里面有邮箱;--report指向已有文件时也改成 0600)。控制台只显示前 40 行。复制文件或写库失败时,报告照样写出,开头写明原因。
- 从 BS 的
-
只导入到全新的站点,整个导入是一个事务。
- 目标库已有用户或材质就拒绝。
- 事务先插入一行
system_state(import.bs.running),提交前删掉:同时启动的第二个导入在这一行的唯一键上等待,等到的是一个已经有数据的站点,于是拒绝。这是这个事务唯一的锁,最先获取(ADR 0026)。 - 导入带来 BS 的超级管理员,并写入"安装已完成"标记,不需要也不应该先走安装向导。
- dry-run 就是同一个事务最后回滚:报告与正式导入完全一样,连约束冲突都能提前发现。
- 失败的导入不留任何数据,修好后直接重跑。
- 与 02 §5 的"幂等可重跑"的差别:导入成功后不支持再导一次。那时站点可能已经有了新数据,合并两边没有安全的默认做法;要重来,就换一个空库。
-
保留 BS 的 ID(uid、tid、pid、举报 id):
/skinlib/show/{tid}等所有链接不变。PostgreSQL 的自增序列在同一个事务里、提交之前移到最大 ID 之后(事务用sql.Tx再包一层 ent 客户端,因为 ent 的 Tx 不能执行原始 SQL),所以不会出现"已提交但序列没移";MySQL 与 SQLite 会自己前移。 -
源库只读:
- SQLite 以
mode=ro与query_only打开,测试会比较导入前后的文件。 - MySQL 与 PostgreSQL 在一个只读的可重复读事务里读,BS 没停写也能读到一致的快照。文档仍建议先开维护模式,并给导入一个只读账号。
- SQLite 以
-
时间:BS 按
config/app.php的时区(默认Asia/Shanghai)存不带时区的时间,用--timezone换算。0000-00-00视为空。 -
材质文件:
- 每个文件都读一遍,算 SHA-256,读 PNG 头得到宽高。
- 内容与文件名不符(上传后被改过)时,按内容的 hash 存,材质跟着用新 hash。存储按内容寻址,恢复备份时也检查这一点(ADR 0034)。
- 文件缺失或不是 PNG:材质照样导入(角色不丢、URL 与 BS 一样返回 404),blob 宽高记 0,大小用 BS 记录的 KB 数;报告里提示把找回的文件按这个名字放进 SkinLoom 的材质目录,不用重新导入。
- 文件先复制、后写数据库(同 ADR 0017),复制时再校验一次 SHA-256。失败留下的文件由孤儿清理回收。
- SkinLoom 的本地材质目录就是 BS 的目录时(挂载或指过去),只复制内容与文件名不符的文件(存到内容的 hash 下)。此后孤儿清理会删掉目录里没有 blob 的 BS 文件,所以文档推荐复制,共用前先备份。
-
密码:
password_hash()的结果看前缀:$2y$、$argon2i$、$argon2id$。- 十六进制摘要按长度分 MD5、SHA256、SHA512,是否加盐看
PWD_METHOD。加盐的存为<摘要>:<SALT>,与 M1 的校验格式一致。 - password-algorithm-transition 插件启用时(
plugins_enabled里有它),按它的PASSWORD_METHODS(新的在前)与按,\s*拆开的SALT一一配对识别。有几种方法都可能生成同一种摘要时取第一种,并写进报告;没有方法对得上时按不加盐处理,也写进报告。 - 认不出的记为
unknown,这些用户要用邮件重设密码。 - 首次登录成功后,统一升级为 argon2id。
-
脏数据的默认处理(02 §5),每一条都写进报告:
情况 处理 两个账号邮箱只差大小写,或没有邮箱 阻止导入:在 BS 里改掉再导 未知的 permission普通用户(警告) 昵称为空 用邮箱 @ 前的部分 角色名重复(不区分大小写),或超过 32 个字符 最早的保留,其余加 _2、_3……,并给主人发一条站内通知角色的主人已不存在 丢弃 uuid表角色名去掉首尾空白后匹配。先给所有角色做精确匹配,再给剩下的做不区分大小写的匹配,最后才生成,所以前面的角色不会抢走后面角色精确匹配的 UUID;同一名字取最早的一行。没有对应 UUID 时,按 ygg_uuid_algorithm生成(v3 由名字算出,v4 随机;没有这个选项但有uuid表时按 v4)。无效或已被占用的 UUID 换新的。没有角色的行丢弃皮肤或披风指向已删除的材质,或放错了槽位 置空 同一用户上传了两次同一个文件 合并到最早的一个,引用全部改指过去;其中有公开的,合并后就是公开的 材质的上传者已不存在 保留,显示为"已注销用户" 未知类型、hash 不是 SHA-256 丢弃 衣柜重复或悬空的行 丢弃;空名字用材质名 同一人对同一材质的重复举报 只留最早的 通知 只导入未读的 文字里有 NUL 或无效的 UTF-8 去掉 NUL,无效字节换成 U+FFFD(已修正):PostgreSQL 不接受它们 收藏数按导入后的衣柜重新计算,blob 的引用数按材质计算。
-
这一部分不导入:站点设置、翻译覆盖、OAuth 应用、Yggdrasil 密钥(第 2 部分,见 ADR 0036),以及其它插件的表。会话、记住登录、启动器令牌、OAuth 令牌永远不导入。
-
读源库的错误:可选的表(衣柜、举报、通知、
uuid)只有在数据库明确回答"表或列不存在"时才当作没有(PostgreSQL 42P01/42703、MySQL 1146/1054、SQLite "no such"),其它错误(权限、断线)让导入停下,不会悄悄少导一张表。 -
一次读入内存:每行几百字节,十万用户、几十万材质的站点只需要几百 MB。流式读取等真实站点证明需要时再做。
备选方案
- 允许导入到已有数据的站点,按 ID 合并:BS 的 ID 会与 SkinLoom 自己的冲突,改 ID 又破坏链接,得不偿失。
- 邮箱只差大小写时自动给一个改名:被改的人就用原来的邮箱登录不了,而且没有办法通知他;这必须由站长决定。
- 重新编码导入的材质:同一张图的 hash 会变,游戏客户端与外链缓存的 URL 全部失效。
- 每张表一个事务:中途失败会留下一半的站点,dry-run 也无法等同于正式导入。
影响
- 新包
internal/importer/bs,新命令skinloom import bs,app.ImportBS。 - 新文档"从 Blessing Skin 迁移"(部署一节)。
- 第 2 部分之前,Yggdrasil 签名密钥是新生成的。切换后,用 authlib-injector 的游戏服务器要重启一次,才会取到新的公钥。第 2 部分(ADR 0036)起,BS 的密钥随导入带过来。