存储、迁移、备份与恢复

实际持久化内容

当前 schema 2 只保存：

表	内容
sa_schema_version	唯一 schema 版本与更新时间。
sa_health_checkpoint	玩家生命、管理状态、修订与更新时间。
sa_persistent_source	PERMANENT/EXPIRES_AT 来源的 provider、source、schema 1 payload、修订、到期、删除墓碑。
sa_resource_state	玩家各已注册资源的当前值、初始化状态、修订。

不保存：运行时装备来源、普通实体完整快照、Base Profile、战斗 trace、PRD 连败、GUI、配置副本或离线恢复累计时间。重启后运行时装备由当前物品/owner 重建。

写入模型

• 战斗、治疗和资源操作先同步提交内存，不在热路径等待 SQL；
• 玩家生命与资源按 health-checkpoint.interval-seconds、退出和停服保存；相同事实不会重复标脏；
• 同一玩家写入串行，revision 防止旧任务覆盖新状态；
• 队列满时持久操作明确失败，健康/资源保持 dirty 供后续机会，不创建无界队列；
• 数据库中断后已 READY 玩家可继续内存战斗，新登录与新持久写 fail closed；
• /sa database status 查看 availability、pending、lane 与成功/失败/拒绝计数。

升级前标准流程

1. 通知维护窗口，停止新业务写入；
2. /sa database flush，确认命令完成；
3. 正常停服，确认 storage stopped: drained=true；
4. 保存当前主 JAR、SHA-256、八份 YAML、扩展 JAR 列表、Java/服务端/软依赖版本；
5. 备份数据库并在隔离环境实际恢复；
6. 在隔离服替换新 JAR，启动迁移；
7. 登录验证 READY、生命、永久来源、资源、装备、战斗和停服排空；
8. 再进入生产窗口。

SQLite 备份与恢复

可靠手工备份必须在服务器停止后复制数据库；运行时只复制主文件可能漏 WAL。

Copy-Item -LiteralPath .\plugins\SealAttributes\storage\sealattributes.db `
  -Destination .\backups\sealattributes-before-upgrade.db
Get-FileHash .\backups\sealattributes-before-upgrade.db -Algorithm SHA256

已有 SQLite 需要向前迁移时，插件会先执行 WAL checkpoint，用 VACUUM INTO 创建 sealattributes.db.backup-<UTC时间>，然后对备份执行 PRAGMA integrity_check。这是迁移保险，不替代你的异机备份和恢复演练。

恢复：停服并保留故障副本，把同一时间点的数据库与八份配置恢复到原位置，使用与 schema 匹配的 JAR 启动。用 /sa database status、测试玩家登录和正常停服验收。

MySQL 备份与恢复

插件只创建/更新当前数据库中的 sa_* 表，不创建 database。使用最小权限账户。升级已有 schema 前，先由管理员完成物理备份，或：

mysqldump --single-transaction --routines=false --triggers=false `
  --host=db.internal.example --user=backup_user sealattributes_prod `
  --result-file=sealattributes-before-upgrade.sql

不要把密码写进命令历史；使用客户端受保护的凭据机制。备份必须在隔离库实际导入和查询，文件存在不等于可恢复。

只有备份已确认且版本说明要求迁移时，临时设置：

migration:
  mysql-backup-confirmed: true

完整启动迁移成功后改回 false。若没有确认，已有 MySQL schema 向前迁移会拒绝启动。每个版本迁移在事务中执行；未来 schema 高于当前代码时拒绝启动。

回滚

1. 停止新版本，保留日志、JAR SHA 和数据库故障副本；
2. 若未执行 schema/语义变更，可恢复旧 JAR和旧配置；
3. 若 schema 已变，必须同时恢复升级前数据库，不能只删新表或手改版本号；
4. 用备份对应的 Java、服务端和依赖在隔离服验证；
5. READY、来源、生命、资源、战斗、保存、drained=true 全部通过后再开放。

不支持的操作

• 没有 SQLite↔MySQL 自动迁移；改 type 只是换连接目标；
• 没有 /sa database backup|restore|export；
• 没有多个服务器同时权威写同一在线玩家；
• 没有 Redis/Velocity 协调；
• 没有通过手改 sa_schema_version 跳过迁移的安全路径。