跳到主要内容

备份、恢复与 CDN

备份​

skinloom backup # 写到 data/backups/skinloom-<时间>.tar.gz
skinloom backup --keep 7 # 只保留最新 7 份
skinloom backup --out /mnt/backup --no-textures

备份文件包含:

内容说明
数据库仅 SQLite:用 VACUUM INTO 复制,站点不用停
config.toml静态配置
secrets/管理员令牌等密钥
plugins/、themes/、plugins-data/已解压的插件、本地主题、插件私有文件,以及 Tier 2 原生插件在 SQLite 下的隔离数据库(plugins-data/<id>/plugin.db,同样通过 VACUUM INTO 在线安全复制)
材质文件与 .slp 包通过存储读取,本地目录与 S3 都可以;用 --no-textures 跳过材质文件(例如材质在 S3、桶本身有备份时)

MySQL / PostgreSQL 的数据库不在备份里,请用各自的工具导出,例如:

pg_dump -Fc -d skinloom > skinloom.dump
mysqldump --single-transaction skinloom > skinloom.sql

备份文件含有密钥和全部账号数据(SQLite 时),权限是 0600,请和数据目录一样妥善保管。在 Windows 上,data/backups、data/secrets、备份文件和日志文件只允许运行 SkinLoom 的账户、SYSTEM 和 Administrators 访问,不继承上级目录的权限。

定时备份​

用系统自带的定时任务调用即可。Linux(cron,每天 4 点):

# crontab -u skinloom -e:以服务用户运行,备份文件和 data/backups 都归它
0 4 * * * /opt/skinloom/skinloom backup --data /opt/skinloom/data --keep 14

systemd timer、macOS launchd、Windows 计划任务同理:运行 skinloom backup --data <数据目录> --keep N。

恢复​

可通过两种方式恢复 SkinLoom 备份:

  1. 安装向导在线恢复(全新部署 / 灾难重建推荐):在首次安装向导选择 从 SkinLoom 备份恢复,完成第 2 步目标数据库(支持恢复时从 SQLite 切换到 MySQL/PostgreSQL 或从本地切换到 S3)配置后,通过浏览器分片上传 <= 1 GiB 备份归档(或指定服务器本地备份文件路径),系统会在预览归档清单后安全写入并立即热切换上线。
  2. 命令行离线恢复(适合 > 1 GiB 大文件或原地覆盖恢复):先停止站点,再恢复到数据目录。运行中的站点占用着数据目录(data/skinloom.lock),这时恢复会直接拒绝,加 --force 也一样:
skinloom restore data/backups/skinloom-20261031-040000.tar.gz --data /opt/skinloom/data

以系统服务运行时(Linux),用服务用户恢复,恢复出的文件才归它:sudo -u skinloom ./skinloom restore …;已经用 root 恢复了,就再执行 sudo chown -R skinloom: data。

  • 目标目录已经有站点(有 config.toml、密钥或数据库)时会拒绝,确认要覆盖时加 --force。所有检查都在写入任何文件之前完成,被拒绝的恢复不会改动目标目录。
  • 材质写入恢复后配置的存储,所以可以把本地备份恢复到 S3,反过来也行:先恢复,再改 config.toml 的 [storage],或者在恢复前准备好目标配置。
  • 恢复后照常启动,较新版本的迁移会自动执行。
  • MySQL / PostgreSQL 先用 pg_restore / mysql 导入数据库,再运行 skinloom restore 恢复其余部分。

CDN 刷新​

站点放在 CDN 后面时,角色资料(/{角色名}.json 等)和头像可以被缓存 delivery.profile_cache_seconds 秒。为了让玩家换皮肤后马上生效,在后台 设置 → CDN 刷新 选择服务商:

服务商需要
Cloudflare区域 ID、带"缓存清除"权限的 API 令牌
阿里云 CDN授权了 cdn:RefreshObjectCaches 的 RAM 用户的 AccessKey
腾讯云 CDN授权了 cdn:PurgeUrlsCache 的子账号的 SecretId / SecretKey
Webhook一个接收 POST 的地址,可以对接其它 CDN

之后角色创建、改名、换装或被删除,以及它的主人被封禁、解封、注销、恢复或删除时,SkinLoom 会刷新这个角色的 6 个地址(CustomSkinLoader、UniSkinMod、旧版 PNG 与头像)。刷新失败会自动重试。材质文件按内容命名,永远不需要刷新。

"CDN 上的站点地址"留空时使用站点地址 site.url。

Webhook 收到的请求:

{"urls": ["https://skin.example.com/Steve.json", "…"], "event": "player.updated"}

设置了签名密钥时,请求带 X-SkinLoom-Signature: sha256=<请求正文的 HMAC-SHA256>。

手动刷新某些角色(也可以用来检查凭据是否正确):

curl -X POST -H "Authorization: Bearer $(skinloom admin token)" -H "Content-Type: application/json" \
-d '{"players": ["Steve"]}' http://127.0.0.1:17546/api/v1/admin/cdn/purge