邮箱密钥配置与迁移

MAIL_CREDENTIALS_KEY 是所有外部邮箱共用的凭据加密主密钥，至少需要 32 个随机 UTF-8 字节。它替代逐个配置邮箱加密 Secret 的操作；各邮箱应用密码、OAuth 令牌和第三方 API Key 仍由对应服务提供，管理员 TOTP 使用的 TOTP_ENCRYPTION_KEY 也保持独立。

支持的配置

独立密钥包括 ICLOUD_CREDENTIALS_KEY、LINUX_DO_MAIL_CREDENTIALS_KEY、 GMAIL_CREDENTIALS_KEY、MICROSOFT_CREDENTIALS_KEY、QQ_MAIL_CREDENTIALS_KEY、 NAVER_MAIL_CREDENTIALS_KEY、YANDEX_MAIL_CREDENTIALS_KEY。

旧部署不添加全局密钥也能正常升级，原有邮箱开关不变。新部署推荐仅配置全局 Secret； NAVER、Yandex 等原本要求显式启用的开关仍需按对应接入指南配置。

主管理员操作

1. 更新部署代码，先保留现有独立 Secret，并完成数据库备份。
2. 主管理员登录后打开收件箱首页。存在旧凭据或旧密钥配置时，先显示升级说明，解释统一 密钥的管理便利与兼容性，点击“开始设置”进入迁移向导；已有迁移进度时直接继续查看进度。 其他管理员及普通用户不显示此入口。可以选择“稍后处理”，之后点击首页“设置与迁移”打开。
3. 在 Cloudflare 打开当前 Worker → Settings → Variables and Secrets，新增类型为 Secret 的 MAIL_CREDENTIALS_KEY，保存并部署。不要覆盖或删除任何已有独立 Secret。 命令行也可使用交互式 npx wrangler secret put MAIL_CREDENTIALS_KEY，避免把值放进命令历史。
4. 回到页面点击“重新检查配置”。网页只读取配置是否就绪，不要求粘贴或显示密钥。
5. 点击“开始 / 继续迁移”。界面显示全部凭据总数、已统一数量和各服务剩余数量。
6. 可随时暂停或关闭。正在处理的一批可能完成，之后不会继续；再次打开时读取数据库实际 状态，点击继续即可。刷新、重复请求或多个窗口处理同一条记录不会覆盖已更新的凭据。
7. 剩余数量为零后，确认旧版本实例及在途请求均已退出，再从 Worker 删除旧独立 Secret。 历史备份依赖的旧密钥应离线保留。全局密钥必须继续保留并备份。

Cloudflare 添加 Secret 会发布 Worker 新版本；配置一次后，无需再因接入其他邮箱而新增 加密 Secret。参见 Cloudflare Secret 配置。

迁移行为与失败恢复

• 不接入 Cron、Queues 或 Workflow，不在登录、页面读取或正常解密时自动迁移历史数据。 每次点击开始后，由保持打开的页面串行请求有界批次，每批最多处理 10 个非空凭据字段。
• 迁移覆盖 7 个服务的 11 个字段，包括 Microsoft 备用密码与组合密码、iCloud Cookie、 应用密码，以及停用或长期未访问的账号。进度单位是凭据字段，不是账号数。
• 新密文使用 HKDF 按服务派生 AES-GCM 密钥，保留用户、账号、用途绑定。v2 包含非秘密 密钥标识，防止迁移页面在全局密钥变化后继续向错误配置写入。
• 更新带原密文条件，只更改密文字段，不改变账号状态、同步租约或时间戳。与改密码、 OAuth 刷新并发时跳过冲突，下一次扫描重新处理剩余数据。
• 解密失败保留原密文，继续扫描其他记录；检查对应旧密钥是否缺失、更换或配置错误后重试。 如果原密钥已经丢失或密文已经损坏，无法通过迁移恢复，需要恢复密钥或重新保存该账号凭据。
• API 仅允许主管理员 Cookie 会话；不向客户端或审计日志输出密钥、明文、密文。

备份与回滚

开始写入 v2 后不能直接回滚到不支持该格式的旧版本。滚动发布期间先确保全部流量使用 兼容代码，再配置全局 Secret、开始迁移，并避免旧实例继续写入 v1。

数据库备份包含当时的密文，不包含 Worker Secret。旧备份恢复时仍需对应旧密钥，不能因 当前进度为 100% 就销毁旧密钥备份。恢复旧数据库后，页面会重新发现待迁移凭据。

此功能用于从独立密钥收敛到一个全局密钥，不是全局密钥轮换工具。不要直接替换正在使用的 MAIL_CREDENTIALS_KEY，否则已写入的 v2 无法解密。