跳到主要内容

0034 M4 全量审查的修正

  • 状态:已接受(2026-10-31)
  • 相关:ADR 0026、0027、0029–0033

背景​

M4 五个部分完成后,对暂存区的全部改动(157 个文件)分五个方向做了一次审查:设置中心与邮箱验证、外观与系统状态、CDN/备份/系统服务、前端、部署文件。每个疑似问题先写出失败的测试再修。下面是改变了设计的决定,其余是普通的缺陷修复,见 CHANGELOG。

决策​

  • 恢复在写入任何文件之前完成全部检查。 归档里配置和密钥排在数据库之前,以前遇到数据库条目才检查"目标已有站点",被拒绝时配置和密钥已经被覆盖了。现在配置和密钥先留在内存里(各 1 MB 上限),到数据库或第一个材质时,用归档里的配置算出数据库路径,检查配置、密钥、数据库任何一个已存在就拒绝,然后才写。另外:
    • 密钥条目名不能是 .、..。
    • 材质超过 64 MB 直接拒绝,不再截断;内容必须与名字(SHA-256)一致,因为材质地址被当作永久不变来缓存。
    • 备份先复制数据库、再列出材质,归档里不会出现数据库引用、文件却不在的材质。
  • 保存设置先锁配置版本行。 设置保存的第一条写入改为递增 system_state.config_version,保存因此一个接一个地执行。两次保存的行锁不会交叉;某个键第一次保存时,带密钥的设置在 MySQL 上不会留下间隙锁而互相死锁。设置保存很少,串行化的代价可以忽略。这补充了 ADR 0026/0027 的加锁顺序:设置事务是"配置版本行 → 设置行(按键名)→ 审计"。
  • 保留的密钥跟着它的去处。
    • settings.Def.SentTo 列出决定密钥发往哪里的设置(SMTP 密码对应主机、端口、加密方式)。保存时改了其中任何一个、却没有重新填写密钥,就拒绝,提示重新填写。
    • 社交登录提供商的密钥只在 type、issuer、tenant 都没变时才还原。
    • 否则管理员可以把已保存的密钥发到自己指定的服务器。
  • "需要验证邮箱"也管启动器令牌。 Yggdrasil 的 refresh、上传材质、重置材质都检查。以前未验证账号的启动器令牌可以一直刷新、永不过期。
  • 主题变量值必须完整地留在自己那条声明里。 引号和括号必须成对,不能以反斜杠结尾,不能换行,否则一个值会吞掉后面所有变量和整个暗色规则。服务器(safeTokenValue)与前端(safeTokenValue、safeToken)用同一规则。值的长度按字符计。
  • 翻译覆盖用 ICU 解析器校验。 前端改用 @formatjs/icu-messageformat-parser(next-intl 本来就依赖它),比较占位符和标签。以前只数花括号,格式错误的文字会让页面显示键名,合法的复数写法反而被拒。英文没有的键(设置说明的英文由服务器提供)不再提供英文输入框。
  • CDN 只在配置完整时监听玩家事件。 配置不完整时监听,只会让发件箱里塞满注定失败、反复重试的事件。几个 worker 同时收到设置变更时,同步改为逐个执行。事件送达时 CDN 已被关闭,就直接跳过,不再报错。Webhook 不跟随重定向,失败时不回显响应内容:设置 URL 的管理员不应借此读取内网接口的响应。
  • 日志文件只由提供服务的进程写入。 Paths.Serve 由 Run 设置。在站点旁边执行的 CLI 命令只写控制台:它们以前也会打开并轮换服务器正在写的文件,在 Windows 上失败,在 Linux 上会丢掉服务器的日志。
  • 系统服务:
    • 路径或用户名含控制字符,或用户名不合法,一律拒绝(换行会往 root 运行的单元里注入指令)。
    • ReadWritePaths= 只转义 %,不再把 $ 写成 $$。
    • 程序目录或数据目录在 /home、/root、/run/user 下时,ProtectHome=read-only。
    • Windows 给 LOCAL SERVICE 程序目录的读取权限。
    • 服务自己退出时,把原因也写进系统日志(事件查看器、syslog)。
    • 停止等待时间改为 50 秒,TimeoutStopSec=60。
  • 首页区块不再随每个页面发给浏览器。 布局传给客户端的 bootstrap 去掉 theme.home,只有首页使用它。服务器按(配置版本、语言)缓存渲染好的区块和翻译覆盖。系统状态改用不加锁的迁移版本查询(goose 的 Status 会拿迁移锁,另一个节点迁移时状态页会卡住),整个查询限时 10 秒。首页统计改为 singleflight:只计数一次,等待的请求在自己的请求结束时放弃等待。
  • 约束冲突按错误码识别,不按错误文字。 验证时发现(M4 之前就有):ent 的 IsConstraintError 靠匹配英文错误信息("violates unique constraint")识别冲突。PostgreSQL 用服务器的语言写错误信息(lc_messages;装在中文系统上就是中文),这时邮箱已被使用、角色名已被占用之类都会变成 500。新增 db.IsConstraint:先用 ent 的判断,再看 PostgreSQL 的 SQLSTATE(23505、23503、23514)。所有调用方都改用它,并有测试禁止再直接用 ent.IsConstraintError。MySQL 的错误文字总带错误号(ent 匹配的正是它),SQLite 的错误信息不翻译,不受影响。
  • 积分比率有上限(每项 0 到 1 000 000,举报积分 ±1 000 000,初始积分最多 10 亿)。以前比率乘以上传的 KB 数会溢出 int64,"花费"变成了大笔进账。
  • 部署:
    • Helm 拒绝 persistence.enabled=false 配 SQLite,或配本地材质存储;也拒绝开启 Ingress 却没有域名。
    • split 模式的后端挂载可写的 /tmp:只读根文件系统下,上传超过几 KB 时 multipart 的临时文件会写失败。Kustomize 的 split 清单同样修正。
    • 所有 Pod 关闭 enableServiceLinks。
    • 单副本时不创建 PDB,避免挡住节点排空。
    • 发行包的 tar.gz 里文件属主为 root。
    • 冒烟脚本不再用 curl | grep -q(pipefail 下 grep 提前退出会让 curl 失败)。
    • CI 里 ! cmd 不会让步骤失败,改为显式判断。

影响​

  • 新设置字段 settings.Def.SentTo;新函数 migrate.Versions、db.IsSQLite、db.IsConstraint;Paths.Serve。
  • yggdrasil.Service.UploadTexture 与 ResetTexture 多了 Policy 参数。
  • 前端新增直接依赖 @formatjs/icu-messageformat-parser(lockfile 里原本就有);翻译问题类型 braces 改名为 syntax。
  • 审查时写下的失败测试都保留为回归测试。
  • 仍未解决、已记录(均已在 ADR 0039 解决):
    • 恢复时不检查站点是否已停止。
    • Windows 上备份文件与日志的权限继承父目录。
    • 封禁或删除用户不会触发 CDN 刷新。
    • 服务器端的翻译覆盖校验仍只检查花括号。