补充运行目录迁移验收与配置保存说明

README.md

@@ -1,5 +1,7 @@
 # Smail
 
+当前版本的运行配置仅保存在根目录 `config` 的五个 JSON 文件中，数据库、密钥、证书和配置历史保存在根目录 `data`。升级已有部署前请先阅读 [运行目录迁移说明](docs/运行目录迁移说明.md)，停服并完整备份；不能只复制配置文件，也不能沿用下文历史容器示例中仅挂载 `config` 的方式。
+
 > 一台服务器、一个域名、一行代码、一分钟时间，你就能够搭建出一个自己的域名邮箱。
 
 Smail是一个追求极简部署流程、极致资源占用的个人域名邮箱服务器。单文件运行，包含完整的收发邮件服务和Web端邮件管理功能。只需一台服务器、一个域名、一行代码、一分钟部署时间，你就能够搭建出一个自己的域名邮箱。
@@ -80,6 +82,8 @@ Smail是一个追求极简部署流程、极致资源占用的个人域名邮箱
 
 # 配置文件说明
 
+以下是旧版单文件配置示例，仅供迁移时识别字段，不能覆盖当前五分区配置。当前文件为 `config/config.json`、`config/smtp.json`、`config/email.json`、`config/ssl.json` 和 `config/plugins.json`；建议通过管理页面修改，系统会同步维护代次与摘要。
+
 ```jsonc
 {
   "logLevel": "info", //日志输出级别

README_CN.md

@@ -1,5 +1,7 @@
 # Smail
 
+当前版本的运行配置仅保存在根目录 `config` 的五个 JSON 文件中，数据库、密钥、证书和配置历史保存在根目录 `data`。升级已有部署前请先阅读 [运行目录迁移说明](docs/运行目录迁移说明.md)，停服并完整备份；不能只复制配置文件，也不能沿用下文历史容器示例中仅挂载 `config` 的方式。
+
 > 一台服务器、一个域名、一行代码、一分钟时间，你就能够搭建出一个自己的域名邮箱。
 
 Smail是一个追求极简部署流程、极致资源占用的个人域名邮箱服务器。单文件运行，包含完整的收发邮件服务和Web端邮件管理功能。只需一台服务器、一个域名、一行代码、一分钟部署时间，你就能够搭建出一个自己的域名邮箱。
@@ -80,6 +82,8 @@ Smail是一个追求极简部署流程、极致资源占用的个人域名邮箱
 
 # 配置文件说明
 
+以下是旧版单文件配置示例，仅供迁移时识别字段，不能覆盖当前五分区配置。当前文件为 `config/config.json`、`config/smtp.json`、`config/email.json`、`config/ssl.json` 和 `config/plugins.json`；建议通过管理页面修改，系统会同步维护代次与摘要。
+
 ```jsonc
 {
   "logLevel": "info", //日志输出级别

docs/运行目录迁移说明.md

@@ -18,6 +18,7 @@
     ├── backups-v2/         # 分区配置历史备份
     ├── transaction/        # 配置事务与故障恢复
     ├── migration-backups/  # 旧配置迁移备份
+    ├── runtime-migration-backups/ # 本次人工保存的完整迁移前备份，不由工具自动生成
     ├── config-audit-v2.jsonl
     └── legacy-config/      # 待验收后人工清理的废弃配置
 ```
@@ -45,3 +46,18 @@
 - 加密密钥必须与数据库及配置一同迁移，不能只复制 JSON。已初始化部署缺少数据库或关键密钥时，新后端拒绝启动，不会默默生成空库。
 - 需要回退时先停服，使用迁移前的完整备份与对应旧二进制成套恢复；若迁移后已经收信或修改账号，先备份最新数据并制定数据回迁方案，不能直接覆盖。
 - 前端开发证书默认读取 `data/ssl/xuans.com.crt` 与 `data/ssl/xuans.com.key`；自定义环境变量指向旧位置时需要同步修改。
+
+## 配置保存与证书路径
+
+- 管理页面保存成功后，系统通过事务写入五个当前配置文件，更新代次与摘要；历史备份中的同名文件不参与日常配置加载。
+- 自定义证书填写的是后端服务器上的证书、私钥文件路径。校验成功后会复制到 `data/ssl/managed/upload/version-...`，页面回读受管副本的引用，而不是保留输入的任意外部路径。
+- 旧配置中的 `config/ssl` 引用可兼容读取；下一次正常保存写入 `data/ssl`。不要手工批量替换 JSON 中的路径，否则会破坏分区摘要。
+- 保存后需要重启的服务以页面返回结果为准。启动新版后端后，应确认当前代次不变、待重启标记清空，并核对邮件监听实际使用的证书。
+
+## 无损验收
+
+`test/runtime_data_check.py` 必须在停服状态下执行，只读核对文件 SHA256、SQLite 完整性及各表内容摘要，不输出账号数据或密钥。迁移前使用 `--layout old`，完整备份也使用 `--layout old`，迁移后使用 `--layout new`，通过 `--baseline` 比较三者。`--output` 必须是尚不存在的文件，测试记录放在 `test-log`。
+
+正常运行后，配置保存、会话活动、审计和新邮件都会产生合法变化，不能继续要求整个运行目录与迁移前完全一致。应保留停服阶段的原始验收记录，并单独记录保存、刷新、重启及协议验收。
+
+本机 Windows 迁移已核对 51 个原始文件及两份 SQLite 数据库；证书保存、刷新和后端重启后仍使用新目录，SMTP、IMAP、POP3 隐式 TLS 监听返回的证书与当前配置一致。Linux 正式部署、真实外部收发信及完整首次初始化流程不属于本次本机迁移验收结果。