NewSzxcn-Email/docs/BACKUP_RESTORE.md

NewSzxcn 完整备份与灾难恢复

后台创建并推送到 Telegram

1. 使用系统管理员登录 NewSzxcn 后台。
2. 在“系统设置 -> 通知”绑定 Telegram Bot Token 和私聊 Chat ID，并发送测试通知。
3. 打开“备份与恢复”。
4. 在“定时备份与 Telegram 推送”中选择每 3、5、7、30 天，或填写 1 至 365 天的自定义周期。
5. 备份 Chat ID 留空时沿用邮件通知私聊；也可以填写一个仅管理员可见的私有群组 Chat ID，将邮件通知与备份文件分开。Bot 必须已经加入该群组。
6. 填写服务器公网 IP。备份密码可以自己输入，也可以点击“生成 24 位”；必须另外保存到 1Password 等密码管理器。
7. 开启“自动创建并推送”，保存设置。
8. 首次配置建议点击“创建备份”，勾选“完成后发送到 Telegram”，确认机器人能收到说明消息和 .tar.zst.enc 加密附件。

Telegram 消息包含邮局域名、服务器 IP、系统版本、已有域名、管理员账号、普通用户账号、邮箱账号、文件大小、SHA-256 和恢复步骤。已有域名只列域名，不附加账号身份。

消息不会包含管理员密码、用户密码或备份密码。数据库只保存登录密码哈希，不能反向读取明文；恢复后账号继续使用原登录密码。备份密码与加密附件也不应保存在同一个 Telegram 会话中。

原服务器失联后的恢复

准备一台新的 Debian 或 Ubuntu 服务器。先把 Telegram 中的加密附件原样上传到新服务器的 /root/ 目录，请不要解压、修改或固定填写某个示例文件名。备份日期和版本号每次可能不同。

确认文件已经上传后，首次执行官方脚本：

curl -fsSL https://gitea.xzys.me/szx/NewSzxcn-Email/raw/branch/main/install.sh | sudo bash

脚本显示“尚未安装”管理菜单后，输入 2，选择“备份恢复”。在恢复完成后，以后需要管理系统时才使用 ns 打开管理菜单。

在“尚未安装”菜单选择：

==================================================
          NewSzxcn Email 管理面板
==================================================
状态：尚未安装
--------------------------------------------------
1. 一键安装 NewSzxcn Email
2. 备份恢复
3. 退出
==================================================

进入备份恢复菜单后，输入 1 选择“本地上传”。脚本会自动扫描 /root/newszxcn-backup-*：只有一份时直接选中；多份时按日期从新到旧显示为 1、2、3 等序号，输入对应序号，例如输入 1 恢复第 1 份。没有找到时才要求手动输入完整路径。选定后输入备份密码，脚本会检查压缩包路径、SQLite 完整性和必要目录，再启动服务。

恢复完成后：

1. 如果新服务器 IP 改变，更新邮件主机的 A/AAAA、邮件域名的 MX/SPF，以及服务商处的 PTR 记录。
2. 检查 DKIM 和 DMARC；DKIM 私钥已随备份恢复，但 DNS 仍应核对。
3. 检查 TLS 证书是否适用于当前主机名，必要时重新签发。
4. 登录网页并测试收信、发信、IMAP、POP3 和 SMTP Submission。
5. 打开“备份与恢复”，重新测试 Telegram 推送。

备份内容

完整备份包括 SQLite 数据库、附件、Maildir 原始邮件、DKIM 私钥、TLS 证书、.env、Compose 配置、版本清单和 SHA-256 校验文件。备份使用 Zstandard 压缩，并以 AES-256-CBC、PBKDF2 200000 次迭代和 SHA-256 加密。

Telegram 适合保存体积较小的应急副本，不应作为唯一备份位置。超过 Telegram 发送上限的文件请从后台下载，并保存到 Google 云端硬盘、另一台服务器、对象存储或离线磁盘。

Google 云端硬盘

后台“备份与恢复”支持将同一份加密备份保存到 Google 云端硬盘。系统只申请 drive.file 权限，只能管理由 NewSzxcn 创建的文件，不会读取云端硬盘中的其他文件。

1. 在 Google Cloud Console 创建项目并启用 Google Drive API。
2. 配置 OAuth 同意屏幕，再创建“Web 应用”类型的 OAuth 客户端。
3. 授权重定向 URI 填写 https://你的邮局域名/api/admin/backups/google-drive/callback，必须与后台系统设置中的公开访问地址一致。
4. 在后台填写 OAuth 客户端 ID、客户端密钥和云端文件夹名称，先保存或直接点击“连接 Google”。
5. 在 Google 授权页面确认后会自动返回“备份与恢复”，状态显示“已连接”。
6. 可开启“用于定时备份”，也可在创建备份或已有备份菜单中单独上传。

OAuth 客户端密钥和刷新令牌会使用服务器内部密钥加密保存。Google 云端硬盘中只保存 .tar.zst.enc 加密备份，备份密码仍应单独保管。