feat: 主密钥诊断与迁移命令;空/占位主密钥启动警告

渠道上游 key 用 OT_MASTER_KEY 经 AES-GCM 加密落库,主密钥一旦变化,全部渠道在运行时
报 "failed to decrypt channel key"。最常见的成因是历史实例先用了空主密钥(退化为
sha256("")),后来才补上 OT_MASTER_KEY——旧密文从此解不开,看起来像渠道全挂了。

- 新增 `check-channels`:打印主密钥派生路径与指纹(SHA-256 前 4 字节,不泄露密钥)
  + 逐渠道解密结果,区分「全部失败=主密钥不对」与「个别失败=该渠道密文异常」;
  存在失败时退出码为 1,便于脚本告警
- 新增 `rotate-master-key`:旧密钥解密、新密钥重新加密,全部渠道单事务更新,
  任一渠道解不开就整体回滚(--force 可跳过),避免库里新旧密钥混杂;
  写入前对新密文做回读校验;--dry-run 只验证不改库。空主密钥作为默认 --old,
  正是「先空后补」的历史路径;配套迁移无需重新录入任何渠道 key
- crypto 新增 KeyFingerprint / KeyMode:指纹用于比对两个实例是否同一把密钥,
  KeyMode 显式暴露「16/24/32 字节用原始字节、其他长度走 SHA-256 派生」这条
  容易踩的长度陷阱(改长度等于换密钥)
- 启动警告:开发环境不拦空/占位主密钥,但明确提示它等于公开密钥,并给出
  rotate-master-key 指引;生产环境仍由 config.validate 直接拒绝启动
- README 补主密钥与渠道密钥运维小节
- 测试:换密钥必解密失败、长度切换 32↔33 字节必失败、指纹一致性

验证:go vet、go test ./... 全绿;端到端复现「空主密钥建渠道 → 配新主密钥全部解密失败
→ rotate-master-key 迁移 → check-channels 全部正常」,明文长度与前后缀保持一致。
This commit is contained in:
Sakurasan committed 2026-11-08 23:12:17 +08:00
1 parent 531a03c836
commit 5d6e5bdb04
8 files changed
+417 -4

No files matched your search

+13
View File
@@ -302,3 +302,16 @@ func knownSecret(s string) bool {
}
return false
}
// InsecureMasterKey 返回主密钥不可用的原因,安全时返回空串。
// 生产环境由 validate 直接拒绝启动;开发环境不拦,但启动时要打警告——
// 空主密钥会退化成 sha256(""),任何能读到数据库的人都能解出全部上游 key。
func (c *Config) InsecureMasterKey() string {
if c.Master == "" {
return `未设置,渠道密钥用公开可还原的 sha256("") 加密`
}
if knownSecret(c.Master) {
return "仍是仓库示例文件里的占位值,等同于公开密钥"
}
return ""
}