升级与数据迁移
升级要同时保护业务数据、密钥、配置和可回退能力。当前版本迁移序列为 001–065，后端启动时自动执行未完成项。
升级前
- 固定并审查准备部署的 Git 提交，不在生产机自动拉取未知变更。
- 记录当前提交、镜像摘要、容器状态、迁移版本和关键数据计数。
- 备份 PostgreSQL、邮件存储、上传目录、
.env、KEK 和 TLS 配置。 - 验证备份可以读取，并在隔离数据库恢复一次。
- 在恢复副本执行全部迁移、后端测试和核心业务写操作。
- 安排维护窗口，暂停会造成数据持续变化的入口。
数据库示例中的服务名、用户和库名按部署修改：
bash
docker compose exec -T db pg_dump -U <db-user> -Fc <db-name> > database.dump
pg_restore --list database.dump >/dev/null只有成功做过恢复演练的文件才算可用备份。
050–065 迁移内容
| 迁移 | 作用 |
|---|---|
| 050 | 保证同一 OAuth 提供方身份只能创建一个独立用户 |
| 051 | 在用户表持久化令牌撤销边界，避免 Redis 丢失后旧会话复活 |
| 052 | 为出站通道小时/每日额度增加幂等预留 |
| 053 | 删除没有运行时约束的旧“已验证邮箱数量”设置 |
| 054 | 按收件人数原子记录用户每日发信用量和能量预留 |
| 055 | 扩大个人图床加密密钥字段，容纳完整密文 |
| 056 | 为个人与组织存储额度增加短期预留 |
| 057 | 删除用户时保留必要审计日志 |
| 058 | 强制订单、订阅只能有一个明确的计费所有者 |
| 059 | 为短窗口 SMTP 重试增加入站邮件指纹去重 |
| 060 | 把邮箱共享约束为只读权限 |
| 061 | 每个全局或邮箱范围只允许一个默认签名 |
| 062 | 规范化 OAuth 身份键，并阻止大小写、空白或跨表归属冲突 |
| 063 | 规范化已验证找回邮箱，并保证一个地址只归一个用户 |
| 064 | 把拦截记录升级为保存完整原文、认证结果、指纹和处理状态的持久隔离区 |
| 065 | 建立组织每日收件人数用量与预留账本，把企业邮箱历史当日用量从成员个人账本迁出 |
050、058、062 和 063 遇到歧义数据会主动停止，不会猜测归属。升级前应在副本检查重复 OAuth 身份、双所有者订单/订阅、空身份键、跨表冲突和重复已验证找回邮箱。
064 不会为升级前的拦截记录虚构正文；这些行会标记为不可放行的历史记录。065 会迁移仍存在的企业发信预留，并根据 054 的应用时间重建当日早期企业发送用量，再从成员个人账本扣除同一批企业流量。升级副本中应核对组织总数、当日企业收件人数、个人用量变化和预留状态，不能只确认表已创建。
执行升级
在审查过的工作树中：
bash
git fetch --all --prune
git checkout <reviewed-commit>
docker compose config --quiet
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=300 backend nginx部署脚本只使用当前工作树，不自动执行 git pull。先构建镜像，再在维护窗口让单个后端实例执行迁移；确认后端健康和迁移版本后再恢复全部入口。
数据核对
升级前后至少比较：
- 用户、邮箱、邮件、附件和组织数量。
- OAuth 绑定唯一性及 NodeLoc 等级字段。
- 邮箱和邮件是否存在孤立外键。
- IMAP UID 是否在邮箱内唯一。
- 订单与订阅是否只有一个所有者。
- 邮箱共享是否全部为只读。
- 默认签名是否在每个范围唯一。
- 迁移记录是否完整到
065。 - 隔离原文大小是否计入个人或组织存储，升级前历史记录是否保持“不可放行”。
- 当日企业发信是否只计组织账本，成员个人账本是否已移除同一企业流量。
数据量会因维护窗口内合法业务变化而不同。比较时记录时间边界，不只追求数字完全相等。
功能验证
- 官网、
/app/、登录、注册和管理员入口。 - 已有账号不进入重复引导；管理员直接进入后台。
- 普通账号、NodeLoc 账号、NodeLoc 真实等级和系统配额徽章正确。
- 注册验证码、找回密码、找回邮箱绑定、Turnstile 与 OAuth。
- 邮箱创建、收信、业务发信、草稿、搜索、附件、导入导出和邮箱级转发。
- 高风险隔离、净化预览、放行到收件箱、永久删除与清理统计。
- 共享只读、转让并发、清理取消、个人邮箱永久清理，以及个人清理不能处理企业邮箱。
- 组织、域名、成员、仅对处于生效或宽限状态的组织与企业套餐开放的已验证域名品牌、企业邮箱、套餐和全组织共享每日发信额度。
- 支付回调幂等、订单、钱包、兑换码和订阅。
- SMTP、IMAPS、POP3S、Redis、rspamd、Nginx 与 DNS/TLS。
真实付款、外部批量发信和永久删除优先在隔离环境完成。生产只用明确标记的测试对象，并立即清理。
回退
先判断已经执行的新迁移是否与旧代码兼容。若不兼容，停止所有写入，从升级前备份整体恢复数据库、邮件数据、配置和对应代码。不要只回退镜像却保留旧程序无法理解的新约束。
回退后重新核对数据、协议端口、证书和外部回调，并记录失败原因。修复后重新走副本迁移和完整验证。