从 Blessing Skin 迁移
你可以通过两种方式将现有 Blessing Skin(BS)站点平滑迁移到 SkinLoom:
- 图形化向导(推荐):直接启动全新 SkinLoom 打开
/setup?token=...,在安装向导中选择 从 Blessing Skin 迁移,支持上传.env、在线测试连通性、浏览模拟试跑报告(Dry-Run)、上传<= 1 GiB材质压缩包或“仅迁移数据库稍后补传”,以及配合独立的blessing-skin-export-bridge插件跨服务器通过 HTTPS 直接拉取数据与材质。 - 命令行工具:
skinloom import bs适合自动化脚本、超大型归档或纯终端环境。
两种方式底层共用同一套迁移引擎,对 BS 数据库严格只读不写,随时可以切回。
方式 A:通过交互式安装向导与桥接插件迁移(推荐)
- 全新启动 SkinLoom:无需手动修改
config.toml或先建数据库,打开安装链接后选择 从 Blessing Skin 迁移 并在第 2 步完成目标数据库和存储(本地 / S3)的测试。 - 选择来源方式:
- 同机 / 私网直连数据库:上传或填写 BS
.env(密钥仅在内存中读取不回显,容器部署下若使用127.0.0.1会自动警告),选择本地storage/textures目录、浏览器分片上传材质包(<= 1 GiB),或选 仅迁移数据库。 - 跨服务器迁移(免开数据库端口):从独立的 blessing-skin-export-bridge 仓库获取最新版插件压缩包,安装到 BS 的
plugins/blessing-skin-export-bridge/启用并由超级管理员签发短时效 256-bit 令牌(推荐同时开启插件内置的“写入冻结”与 IP 白名单),将连接串 JSON 或站点地址与令牌填入向导 通过迁移桥接插件远程拉取(公网域名强制 HTTPS)即可并发校验并拉取数据与材质。
- 同机 / 私网直连数据库:上传或填写 BS
- 试跑检查与执行:在页面点击 运行模拟试跑(Dry-Run),分类核对
BLOCKING/LEFT IN BLESSING SKIN/WARNING/FIXED/DROPPED报告,也可下载完整.txt报告;确认无阻断项后点击 开始正式迁移,完成后进程自动热切换至新站点。 - “仅迁移数据库”的补扫校验:若迁移时未提供材质文件,后续将 BS 材质复制到目标目录/S3 后,只需进入 管理后台 → 系统状态 点击 校准补扫缺失材质(或执行
skinloom textures rescan),即可自动校验 SHA-256 与 PNG 尺寸并补齐材质大小信息。迁移完成后记得在 BS 删除blessing-skin-export-bridge插件。
方式 B:命令行 skinloom import bs
skinloom import bs 把一个 Blessing Skin(BS)站点导入全新的 SkinLoom。BS 的数据库只读不写,随时可以切回去。
会带过来什么
| 内容 | 说明 |
|---|---|
| 账号 | 邮箱、昵称、积分、权限(封禁、管理员、超级管理员)、邮箱是否已验证、注册 IP 和时间 |
| 密码 | 原来的密码照常能登录。BS 的全部算法(BCRYPT、ARGON2I、MD5、SHA256、SHA512 及加盐的版本)都认得,启用了 password-algorithm-transition 插件的站点按 PASSWORD_METHODS 和对应的盐逐个识别。首次登录后自动升级为 argon2id |
| 角色 | 名字、皮肤、披风,以及 Yggdrasil 插件分配的 UUID:进服后背包、领地等按 UUID 存的数据都还在 |
| 材质 | ID、名字、类型、公开或私有、上传者、上传时间,以及文件本身。文件名就是 hash,链接不变;只有上传后被改过内容的文件按新内容的 hash 保存,它的皮肤地址会变 |
| 衣柜 | 收藏的材质和自己起的名字;收藏数按衣柜重新计算 |
| 举报、通知 | 全部举报;只有未读的通知 |
| 站点设置 | 站点名称、简介、公告、地址、版权文字、注册与验证、验证码(reCAPTCHA)、角色名规则、积分与签到、材质大小与命名规则、自定义 CSS 与 JavaScript、关键词、Yggdrasil 的令牌与 UUID 设置。中文和英文的版本分别带过来 |
| 邮件 | BS 的邮件设置在 .env 里,用 --env 时一起导入:SMTP 服务器、端口、账号、密码、发件人 |
| 改过的称呼 | 在 BS 的"翻译"里改过的常用词:首页、皮肤库、用户中心、登录、衣柜、管理面板、积分、皮肤、披风。比如把"积分"改成了"金币",SkinLoom 里所有只显示这个词的地方也是"金币" |
| OAuth 应用 | 用户创建的第三方应用,ID、密钥、回调地址都不变,应用不用改配置 |
| Yggdrasil 签名密钥 | 公钥不变,游戏服务器不用重启 |
不会带过来:网页登录状态、启动器令牌、第三方应用的授权,所有人重新登录一次即可。
报告会列出每一项没带过来的设置和文字,并说明在 SkinLoom 里怎么做,主要是这些:
- 改过的其它文字:SkinLoom 的界面文字是重新写的,与 BS 的对不上,导入后到后台的"翻译"页重新改。包含"积分"等词的长句也保留默认写法,需要的话在那里一并改。
<head>里的额外 HTML、首页背景图、导航栏颜色等布局选项:SkinLoom 的主题和首页编辑器有自己的设置。- 自定义 JavaScript 会导入,但运行方式不同:SkinLoom 在站内切换页面时不重新加载,脚本只在打开网站时运行一次,而不是每个页面一次。修改页面内容的脚本要自己监听页面切换,报告里会提醒。
- 自己写的角色名或材质名正则用了 SkinLoom 不支持的写法(反向引用、环视等)时,保留默认规则。
- 签名密钥读不出来时会生成新的,此时用 authlib-injector 的游戏服务器要在切换后重启一次,报告里会写明。
- 插件和其它表:BS 启用的每个插件在报告里各占一行,写明 SkinLoom 用什么代替,或者它的表和设置没有导入。数据库里导入器不读、又有数据的表也逐个列出行数,包括插件的表和共用这个数据库的其它程序的表。材质描述、正版验证、邀请码、Yggdrasil Connect 的 OAuth 登录(Janus)目前没有对应功能;不认识的插件和表(包括自己写的)一律提醒手动处理。这些条目单独放在报告开头的"LEFT IN BLESSING SKIN"一节,控制台总是完整显示。
- 邮件:导入后在后台发一封测试邮件。BS 在服务器不支持加密时会退回明文发送,SkinLoom 不会;发不出去时把加密方式改成"不加密"。
材质、角色、用户的 ID 都与 BS 相同,所以 /skinlib/show/123 这类链接和游戏里的皮肤地址都不用改。
步骤
-
准备一个全新的 SkinLoom,按 部署 装好,但先不要打开安装页面:导入会带来 BS 的超级管理员。已经启动过也没关系,只要还没创建账号,导入前先停掉即可。
-
BS 开启维护模式,或者至少停止注册和上传。导入在一个一致的快照里读数据,BS 不停也能导,但之后的改动不会跟过来。
-
试运行。下面的路径换成 BS 网站的目录:
skinloom import bs --env /var/www/blessing-skin/.env --dry-run导入器从
.env读出数据库连接、表前缀、密码算法和盐。材质默认从 BS 的storage/textures读。-
用了 OSS、COS、七牛等存储插件的站点,先把材质下载到一个目录,再加上
--textures 目录。 -
BS 在别的服务器上时,直接指定连接,并把
storage/textures复制过来。连接串里有密码,放在环境变量SKINLOOM_BS_DSN里,不要写在命令行上(会留在 shell 历史和进程列表里);盐同理用SKINLOOM_BS_SALT:export SKINLOOM_BS_DSN='用户:密码@tcp(主机:3306)/数据库'skinloom import bs --driver mysql --textures ./textures --dry-run -
建议给导入用一个只读的数据库账号。
-
-
看报告。控制台显示报告的前 40 行;紧跟在汇总后面的"LEFT IN BLESSING SKIN"(留在 BS、没有导入的插件数据和表,切换前要逐条确认)不论多长都完整显示,它的条目不计入这 40 行。完整报告写在
data/import/下。其余条目分四类:类别 含义 要做什么 BLOCKING(阻止) 需要人来决定的冲突,比如两个账号的邮箱只差大小写 在 BS 后台改掉,再试运行 WARNING(警告) 导入了,但有东西和以前不一样,比如材质文件缺失、密码格式不认识 能补的补上(比如把文件放回材质目录);认不出密码的用户要用邮件重设 FIXED(已修正) 按默认规则改过,比如重名的角色加了 _2、指向已删除材质的皮肤被清空看一遍即可 DROPPED(已丢弃) 没有导入,比如主人已不存在的角色、衣柜里重复的条目 看一遍即可 试运行和正式导入做的是完全相同的事情,只是最后撤销,所以报告也一样。
-
正式导入:去掉
--dry-run再执行一次。全部写入在一个事务里,中途出错不会留下半个站点;失败时报告照样写出,开头写明原因,修好后重新执行即可。 -
启动 SkinLoom,用 BS 的超级管理员账号登录。抽查几个账号、皮肤库,再用启动器实际进一次服。
-
对比两个站:让 SkinLoom 和 BS 回答同样的问题,挑几个有皮肤、有披风、被封禁、不存在的角色:
skinloom import compare --bs https://skins.example.com --skinloom http://127.0.0.1:17546 Steve Alex Notch它按启动器和游戏服务器的方式请求 CustomSkinLoader、UniSkinMod、旧版皮肤地址、材质文件和 Yggdrasil 的角色查询,两边的签名各用自己的公钥验证;第一行比较两边的签名公钥,不同说明密钥没有导入,用 authlib-injector 的游戏服务器切换后要重启。每一行都应该是
same;DIFFERS的会列出两边的回答。错误提示的措辞和缓存时间本来就不同,不参与比较;导入之后在 BS 里改过的角色当然也会不同。 -
切换反向代理或域名到 SkinLoom。所有地址都兼容,玩家和游戏服务器不用改配置。
-
回滚:BS 的数据库从未被写入,切回 BS 即可。材质目录与 BS 共用时见下文。
默认的处理规则
| 情况 | 处理 |
|---|---|
| 两个账号的邮箱只差大小写,或账号没有邮箱 | 阻止导入:SkinLoom 的邮箱不区分大小写 |
| 角色名重复(不区分大小写)或超过 32 个字符 | 最早的保留,其余改为 名字_2、名字_3……,并给主人发一条站内通知 |
| 同一用户把同一个文件上传了两次 | 合并到最早的那个,衣柜和角色都改指过去 |
| 皮肤或披风指向已删除的材质,或皮肤放在了披风的位置 | 清空 |
| 材质的上传者已注销 | 保留材质,显示为已注销用户 |
| 材质文件和文件名(hash)对不上 | 按文件内容的 hash 保存 |
| 材质文件缺失 | 材质照样导入,与 BS 一样:文件和预览图返回 404,头像显示默认头像。找回文件后,按报告里写的名字放进 SkinLoom 的材质目录即可,不用重新导入 |
| 衣柜里重复的条目 | 只留一条 |
| 衣柜里指向不存在的材质或用户的条目 | 丢弃 |
| 同一人对同一材质的重复举报 | 只留最早的一条 |
| 文字里有无效的 UTF-8 或 NUL 字符 | 去掉 NUL,无效的字节换成 � |
| 设置的值超出 SkinLoom 的范围(比如材质宽度 4096) | 改为最接近的允许值 |
| 设置的值不合格 | 保留 SkinLoom 的默认值 |
| BS 安装时自带的简介、公告、版权文字 | 不导入,用 SkinLoom 的默认值 |
| OAuth 应用的某个回调地址不合格(比如不是完整的网址) | 去掉这个地址;一个都不剩的应用不导入 |
| BS 只存了哈希的 OAuth 密钥 | 换成随机值,应用的主人到用户中心重新生成 |
材质文件放在哪
导入会把文件复制进 SkinLoom 的材质目录(默认 data/textures)或 S3,需要同样多的磁盘空间。推荐这样做:BS 的目录保持原样,随时可以切回去。
空间实在不够时,可以在导入前把 BS 的目录挂到 data/textures 上(Linux:mount --bind /var/www/blessing-skin/storage/textures data/textures),导入发现是同一个目录,就只复制内容被改过的文件。用挂载而不是符号链接:系统服务只允许写 data/ 之下的路径,符号链接指向的目录写不进去。
共用目录之后,SkinLoom 把这个目录当成自己的:
- 定期清理会删掉没有材质用到的文件,包括 BS 里那些没有导入的材质(比如类型未知)的文件,以及被改过内容的文件的原文件。
- 在 SkinLoom 里删除材质会删掉它的文件,BS 那边的同一个材质随之失效。
所以共用之前先备份 BS 的材质目录,回滚时用备份。
常见问题
- "the SkinLoom database already has users or textures":只能导入到没有账号的新站点。如果已经在安装页面建了管理员,删掉
data/重新开始;用 MySQL、PostgreSQL 的,换一个空库。 - BS 改过时区:BS 按
config/app.php的时区记录时间,默认Asia/Shanghai。改过的话加上--timezone 时区名。 - 导入成功后还想重来:换一个空库(SQLite 就是删掉
data/skinloom.db)再导入。导入不会和已有的数据合并。