48 lines
4.0 KiB
Markdown
48 lines
4.0 KiB
Markdown
# 运行目录迁移说明
|
||
|
||
`SMAIL_ROOT` 始终指向服务根目录，不能指向 `config`、`data` 或编译输出目录。
|
||
|
||
```text
|
||
服务根目录/
|
||
├── config/ # 仅五个当前配置文件
|
||
│ ├── config.json
|
||
│ ├── smtp.json
|
||
│ ├── email.json
|
||
│ ├── ssl.json
|
||
│ └── plugins.json
|
||
└── data/ # 必须与配置一起备份，不得上传 Git
|
||
├── *.db # SQLite 数据库及其附属文件
|
||
├── *.key # 原加密密钥，不可重新生成或替换
|
||
├── ssl/ # 证书、私钥、签发账号、受管版本
|
||
├── dkim/ # 邮件签名密钥
|
||
├── backups-v2/ # 分区配置历史备份
|
||
├── transaction/ # 配置事务与故障恢复
|
||
├── migration-backups/ # 旧配置迁移备份
|
||
├── config-audit-v2.jsonl
|
||
└── legacy-config/ # 待验收后人工清理的废弃配置
|
||
```
|
||
|
||
## 升级旧部署
|
||
|
||
1. 停止后端及自动重启服务，确认没有其他进程读写数据库；关闭前端开发服务器。
|
||
2. 将整个旧 `config` 目录备份到受保护位置，包括数据库的 WAL、SHM 和日志文件。不要使用历史配置备份替换当前配置。
|
||
3. 编译配置工具：在 `backend` 中运行 `go build -o ../out/backend/smail-config.exe ./cmd/smail-config`。Linux 去掉 `.exe`。
|
||
4. 只读检查：`smail-config --root 服务根目录 --runtime-data`。
|
||
5. 确认已停服后执行：`smail-config --root 服务根目录 --runtime-data --apply`。
|
||
6. 核对迁移清单及文件哈希，启动新版后端，然后启动前端。Windows 开发入口为 `deploy/start-dev.ps1`，后端仍是 5201，前端仍是 80/443。
|
||
7. 验证登录、证书、配置保存、备份及审计。通过后才能清理 `data/legacy-config` 中明确废弃的文件；数据库、密钥和证书不能删除。
|
||
|
||
工具不会覆盖目标文件。未知项目、符号链接或目标冲突会阻止迁移。操作失败时逆序回滚已移动项目；回滚失败时保留现场和原始备份，禁止启动旧后端或新建数据库。迁移独占锁为 `data/.runtime-migration.lock`；进程崩溃或回滚失败后会保留锁并阻止启动，管理员必须先确认没有运行进程、核对源和目标文件与备份一致，再移除残留锁并重新检查。已移动项目不会重复覆盖。嵌套 SQLite 目录须根据 `database.localRef` 人工核对，未知目录不会被自动处理。
|
||
|
||
若升级前只有旧格式 `config.json`，先执行运行目录迁移，再执行 `smail-config --root 服务根目录 --apply` 转换为五个分区配置。不要先生成新密钥，也不要用旧格式配置覆盖现有分区配置。迁移工具不自动备份整个数据库目录，也不自动停止服务；停服和完整备份是执行前提。
|
||
|
||
迁移只移动运行文件，不改写五个配置的字节、代次和摘要。旧 `config/ssl` 相对引用先通过原摘要校验，再在运行态解析到 `data/ssl`；下一次正常保存会写入新引用。历史备份不改写摘要，恢复时沿用同一兼容规则。
|
||
|
||
## 权限与回退
|
||
|
||
- Linux：`config`、`data` 由专用服务账号拥有，目录 0700、敏感文件 0600；不要给普通账号开放读取权限。
|
||
- Windows：正式服务由安装脚本设置服务账户和受保护 ACL；开发模式仍明确停用管理员恢复通道，不提升普通邮件业务权限。
|
||
- 加密密钥必须与数据库及配置一同迁移，不能只复制 JSON。已初始化部署缺少数据库或关键密钥时，新后端拒绝启动，不会默默生成空库。
|
||
- 需要回退时先停服，使用迁移前的完整备份与对应旧二进制成套恢复；若迁移后已经收信或修改账号，先备份最新数据并制定数据回迁方案，不能直接覆盖。
|
||
- 前端开发证书默认读取 `data/ssl/xuans.com.crt` 与 `data/ssl/xuans.com.key`；自定义环境变量指向旧位置时需要同步修改。
|