运行文件目录迁移说明

需求确认

运行配置统一放在 D:\Desktop\Smail\config；backend/config 是 Go 配置管理源码包，不整体重命名或删除。运行日志继续放在 test-log/runtime，编译输出继续放在 out。

文件归属

Smail/
├── config/                   # 忽略 Git 的本机运行文件
│   ├── config.json           # 当前启动使用的分区根配置
│   ├── smtp.json             # SMTP 分区
│   ├── email.json            # 邮箱策略分区
│   ├── ssl.json              # 证书引用分区
│   ├── plugins.json          # 插件配置分区
│   ├── config.dev.json       # 历史 dev 模式配置，不是当前启动配置
│   ├── config_mysql.json     # 保留的另一份配置，不自动启用
│   ├── config.json.legacy    # 历史配置原始备份
│   ├── smail_temp.db         # 当前账号及邮件数据库
│   ├── smail.db              # 另一份已有 SQLite 数据库，保留
│   ├── credential.key       # 凭据加密主密钥
│   ├── external-email-*.key  # 外部邮箱加密和指纹密钥
│   ├── dkim/                # DKIM 密钥及备份
│   ├── ssl/                 # TLS 证书、私钥及 ACME 资料
│   ├── migration-backups/   # 配置格式迁移备份
│   ├── backups-v2/          # 分区配置备份
│   └── transaction/         # 配置事务工作目录
└── backend/config/          # Go 源码、同包测试和原有说明文档

启动约定

deploy/start-dev.ps1 设置 SMAIL_ROOT=D:\Desktop\Smail。程序使用 SMAIL_ROOT/config 读取和生成运行文件，不能把环境变量设置成 config 自身。
当前启动继续使用 --dev-disable-admin-reset，读取 config/config.json，不切换到 config.dev.json 或另一份数据库。
为保持已有插件安装路径，子进程工作目录仍是 backend/。初始化目录已改为基于 SMAIL_ROOT，不再向工作目录写入 ./config。
直接运行编译程序或 go run 时也需要显式设置 SMAIL_ROOT。独立正式部署保留原有环境变量优先、可执行文件目录回退规则。
如果 backend/config 仍存在旧配置、主密钥或 SQLite 文件，开发启动脚本停止并提示先迁移，防止误初始化第二份账号库。

迁移和保护边界

修改前提交中文检查点并推送，真实运行文件不进入 Git。
停止并核实当前项目后端进程，前端保持运行。
迁移前记录源码及运行文件清单和 SHA-256；运行文件另存一份本地回退副本到 test-log/archive。
只迁移明确的运行文件，目标存在同名文件时拒绝覆盖；保留 Go 源码及说明文档，不删除旧空目录。
JSON、数据库、密钥及证书保持原始字节；分区配置的摘要和相对路径无需更改。
迁移后逐一校验哈希，再启动后端并核对运行根目录、数据库及探活结果。
根目录 ssl/ 的人工输入证书、backend/smail.db 的原有空文件、历史测试配置不属于当前活动配置，不删除，也不冒充当前数据源。

本次是保留数据的目录迁移，不进行清库初始化。自动测试使用 test-log 下独立临时数据库；业务数据库仅做只读完整性和账号摘要校验。进程启动后的正常任务可能更新业务数据库，迁移字节校验应在重启前完成。

任务清单

[✓] 核实运行文件、活动数据库与源码边界。
[✓] 修改前检查点已提交并推送。
[✓] 开发启动指向项目根目录，并拒绝旧目录残留运行文件；脚本语法、编码及路径约束测试通过。
[✓] 初始化目录与工作目录解耦；异工作目录、重复初始化、文件保留和目录冲突回归通过。
[✓] 停服备份并迁移 24 个运行文件，重启前逐一哈希一致；55 个源码及说明文件保持不变。
[✓] 三个后端程序重新编译，前端 19 项自动测试、Go 全量测试及静态检查通过。
[✓] 从新目录恢复后端，两份 SQLite 完整性及迁移前表记录数一致，账号记录在重启前后均未改变；前后端探活正常。
[!] 符号链接拒绝测试在当前 Windows 普通账户下因缺少创建符号链接权限而跳过，未提升权限，也未据此宣称该分支实测通过。

本次验收记录

2026-09-05 本地迁移结果：

修改前检查点：3c455186b70289238167a19432431ace74ee79e4，已核对与远端 smail/main 一致；后续本轮代码改动保留在工作区。
停止的旧后端进程编号为 23136；新进程编号为 45920，可执行文件位于 out/backend/smail-dev.exe。进程编号仅代表验收当时状态。
新启动日志显示 Env Root Path: D:\Desktop\Smail/，当前配置仍是 config/config.json，数据库仍由 localRef=smail_temp.db 指定，分区代次保持 1。
两个 SQLite 文件各有 20 张表；保留库 smail.db 有 0 个账号，活动库 smail_temp.db 有 1 个账号。校验不输出账号、密码哈希或密钥内容。
重启后 23 个非活动数据库运行文件及 55 个源码说明文件哈希仍一致；活动数据库仅允许正常运行写入，账号完整记录与备份比较一致。
https://127.0.0.1/api/ping 和 http://127.0.0.1:15173/api/ping 均返回 HTTP 200、errorNo=0、pong；前端页面返回 200。
https://127.0.0.1/config/credential.key 返回 404，没有把新运行目录当作静态资源公开。自签名证书探活使用跳过本机证书信任验证参数，不代表公开 CA 信任验收。
node test/run.mjs all -- -count=1 -p 2 ./... 通过；随后单独复跑 TestDirInit，三个用例通过、符号链接用例跳过。
go -C backend vet -p 2 ./...、PowerShell 语法检查、git diff --check 和 Go 格式检查通过；启动脚本仍保留 Windows PowerShell 5 需要的 UTF-8 BOM。
Git 忽略规则确认根目录配置、密钥、数据库、回退副本、日志和编译产物不会进入提交。

本地回退副本：test-log/archive/runtime-config-20260905-202201/。目录包含密钥和数据库，仅留在本机，不上传。

检查证据：

test-log/reports/runtime-config-migration-20260905-202201.json：完整移动、哈希和源码保留清单。
test-log/reports/runtime-config-sqlite-before-start.json：重启前数据库完整性、记录数及账号一致性。
test-log/reports/runtime-config-after-start.json：重启后路径、运行文件与账号一致性。
test-log/reports/runtime-config-build-20260905.log：本次后端及管理工具构建记录。
test-log/run-2026-09-05T12-20-49-905Z-23176/：完整自动测试记录。
test-log/run-2026-09-05T12-24-16-351Z-24952/：初始化目录专项回归记录。

真实邮件收发、浏览器全部流程和 Linux/Windows 正式安装不在本次迁移验收范围内，不能以探活成功代替这些验收。

7.0 KiB Raw Permalink Blame History Unescape Escape