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不会让步骤失败,改为显式判断。
- Helm 拒绝
影响
- 新设置字段
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 刷新。
- 服务器端的翻译覆盖校验仍只检查花括号。