第 20 期 · M4 开工:设置中心
M4 是"后台、主题与运维"。第一部分是设置中心:M1–M3 的模块注册了约 50 个设置,以前只能用命令行或 API 改,现在后台有了设置页。设置的定义改为声明选项和范围,密钥变成只写不读,另外补上了 BS 的"要求验证邮箱"。
M4 怎么拆(ADR 0029)
- 设置中心(本期)。
- 外观:默认主题按主题标准重写、首页区块、后台切换主题与调整 token、首页图、favicon、版权文案、自定义 CSS(只给超级管理员)。
- 翻译覆盖与系统状态。
- CDN 刷新与备份。
- Helm、
skinloom service install,四种部署形态按文档从零验证。
设置页
后台多了"设置"(/admin/settings),按站点、注册与登录、第三方登录、邮件、积分、材质、角色与游戏接口、外置登录、开放平台分组,每组单独保存,保存后立即在所有节点和已打开的页面生效。
为了让页面知道每个设置该显示成什么,settings.Def 增加了 Enum(可选值)、Range(整数范围)和 Secret。各模块原来各写一套 oneOf、between 闭包,现在直接声明,注册时还会检查默认值是否满足自己的声明。于是:
- 有可选值的设置是下拉框,选项都有中文说明;
- 数字带上下限,填 70000 当端口时页面直接提示"请输入 1 到 65535 之间的整数",不会发出请求;
- 多语言的设置每种语言一个输入框,留空的语言不会保存成空字符串;
- 插件以后注册的设置用同一套定义,没有翻译时显示键名与英文说明。
密钥只写不读
以前设置接口把 SMTP 密码、验证码私钥和第三方登录的 clientSecret 原样发给任何一位管理员。现在:
- 密钥保存后后台只显示"已设置",不填就保持原样,点"清除"才会删掉;
- 第三方登录的提供方列表是 JSON,里面已保存的
clientSecret显示为********,原样保存就按提供方 id 沿用原来的值。
沿用旧密钥要先读出已保存的值,这又是一处"先读后写"。按 ADR 0027,读之前先锁住这一行。写测试时先去掉锁试了一下:一位管理员保存新密钥、另一位同时保存没改密钥的编辑,PostgreSQL 上 3–4 轮就把新密钥改回了旧的;加锁后连续 10 次、每次 20 轮都没有再出现。
要求验证邮箱
auth.require_email_verification 对应 BS 的 require_verification,默认关闭。开启后,没有验证邮箱的账号不能管理角色、上传或修改材质、举报、创建 OAuth 应用与个人访问令牌,也不能在启动器登录。范围和 BS 的 verified 中间件与 yggdrasil-api 插件一致,另外加上了兼容 BS 的 /api/players,否则拿个人访问令牌就能绕过。
被拒时 /api/v1 返回的 403 带 problem 类型 tag:skinloom.cn,2026:email-not-verified,前端据此提示"请先验证邮箱"。举报按钮原来把所有 403 都当成"不能举报自己的材质",有了类型才分得开。页头的验证提醒也会说明被限制了什么;没有配置邮件时改为提示联系管理员。
验证
- 新测试:设置定义的检查、Enum 与 Range、并发保存时沿用密钥(SQLite 与 PostgreSQL)、设置接口不泄露密钥、要求验证邮箱(
/api/v1四个接口、/api/players、衣柜不受影响、验证后放行)、启动器登录;前端的分组、只发改动和本地检查。 go fmt、go vet,完整的go test ./...(SQLite 与 PostgreSQL);前端类型检查、单元测试与生产构建。- 用
skinloom up --dev起了整套服务,在浏览器里走了一遍:初始化站点,保存邮件设置(密码框清空、显示"已设置"、接口响应里没有密码),填错端口,恢复默认,保存第三方登录提供方后改 clientId 再保存(密钥沿用),开启"要求验证邮箱",用普通账号创建角色被拒、看到提示,从页头重发验证邮件、打开链接验证,再创建角色成功。
在浏览器里还发现并修掉了五个问题:分组顺序(第三方登录排到了注册与登录前面);一组里只有一个填错的字段时保存按钮是灰的、也没有提示;浏览器自带的数字校验抢在页面前面;改对之后错误提示不消失;角色页把"需要先验证邮箱"显示成"操作失败"。
仍未验证
- MySQL、staticcheck、govulncheck 交给 CI。
下期计划
M4 第二部分:外观。