Smail/docs/单数据库部署说明.md

单数据库部署说明

部署原则

• 每套部署在 SQLite、MySQL、PostgreSQL 中选择一种，只连接该数据库保存业务数据和配置历史。
• SQLite 模式默认使用 data/smail.db；MySQL 和 PostgreSQL 模式不额外创建 SQLite 文件。
• 配置历史保存在同一数据库的 config_records 表，由第 24 版数据库迁移管理。
• 首次启动仅准备运行目录和密钥，不在选择数据库前创建状态数据库。
• 所选数据库不可连接时明确报错，不回退到另一个数据库。

配置与恢复

五个生效 JSON 配置文件仍位于 config。配置提交使用 data/transaction 中的文件事务日志，跨进程锁位于 data/.config-state.lock；两者都不是数据库。这样即使远程数据库离线，也能恢复未完成的配置提交。配置历史继续保留摘要校验、原始加密内容和数量、期限限制。

数据库切换必须通过迁移流程：复制并校验所有版本化表（包含配置历史）后才切换配置。源库被迁移锁定期间，切换前配置历史写入已经复制完成的目标库，避免反向写入源库造成阻塞。旧业务数据库按原迁移安全策略保留，不会被新部署继续使用；确认切换成功后才人工清理，不擅自删除。

从双库版本升级

必须停止旧进程后升级，不能让新旧程序同时写入。启动时先恢复旧 data/smail-state.db 中未完成的事务，再校验并导入历史到所选数据库；摘要冲突或损坏会阻止升级。完成后旧文件移到 data/migration-history/smail-state.retired，仅作为不再打开的迁移原件保留，不是第二个运行数据库。核验成功且获准清理后可移除此原件；全新部署不会生成它。

不要把 smail-state.db 作为业务 SQLite 文件名，它是旧版升级识别保留名。

验证入口

node test/run.mjs backend -p 1 ./config ./db/migration ./services/dbmigration ./utils/runtimepath
node test/run.mjs all -p 1 ./...

TestSelectedDatabaseLiveIntegration 用于预先清空的专用云端数据库。通过进程环境设置 SMAIL_TEST_STATE_DATABASE（sqlite、mysql 或 postgresql），远程数据库同时提供 SMAIL_TEST_STATE_USER、SMAIL_TEST_STATE_NAME、SMAIL_TEST_STATE_PASSWORD。凭据不能写入代码、文档或提交记录。未提供连接时测试明确跳过，不能将跳过当作实机验证通过。

本次指定的域名、管理员和密码仅是测试参数，不应硬编码为部署默认值或验收条件。