升级与回退¶

升级与恢复均需确保代码、配置和数据库版本相互匹配。 数据库迁移是单向的，自动备份提供升级前快照，不是降级程序。 使用新版本启动前，应保留可用于恢复的完整副本。

升级前保留什么¶

退出桌宠与后端；systemd 部署先停止服务，避免备份时仍有写入。 保存当前代码版本或发布包，同时备份这些本机内容：

使用自定义目录时备份实际路径，而不是根目录下同名空目录。 备份含明文密钥和会话数据，应保存于受控存储位置。 升级时不应使用模板覆盖已有配置，以免丢失已保存的参数。

更新代码后，在项目根同步依赖；使用向量功能时保留对应 extra：

uv sync

用面板或桌宠时执行 npm ci、npm run build，或者部署同版本的面板产物。 再运行 uv run bot.py，阅读配置对账、迁移和启动自检输出。

配置升级如何发生¶

Python 启动会检查已有配置段：新增字段补入当前默认值，退休字段移除。 尽量保留原有注释和排版；出现实际改动才打印一次汇总。 写入前会把整个主体配置目录复制到 data/backups/config/<时间戳>/。 这一备份不包含项目其他位置的插件连接配置。

自动对账不会向模型、厂商列表添加首装条目，也不会补充整段缺失的可选功能配置。 因此，升级会保留已有模型目录，不会将其替换为当前首装预设。 需要新功能时，对照配置模板说明自行补齐。

配置版本号和字段对账是两回事。 Python 要求主体四份文件的 [inner].version 与当前模板一致，对账不会改版本号。 无头运行遇到跨版本配置时会报错；先备份，再按新模板迁移旧值和引用关系。 确认新增、改名、退休字段都处理完，才写入对应版本号；单改版本号不算升级。

桌面外壳读取旧版本配置时可按当前格式重写四份主体文件。 外壳读取路径不执行上述 Python 整目录备份，启动外壳前仍需手动备份。 Python 因版本不匹配退出时，不会自动启动外壳执行配置升级。 已装桌面依赖时可单独运行 npm run dev 让外壳读取配置，再检查文件并重启 Python。 外壳只负责读写和连接，不会因配置迁移完成就自动启动后端。

项目根存在旧单文件 config.toml 时，外壳只在目标配置目录不存在时迁移它。 迁移后保留原文件；已有拆分目录不会再用该旧文件覆盖。 完整机制见开发手册：配置体系。

数据库自动备份落点¶

已有数据库需要向前迁移时，在数据库同目录的 backups/ 创建 SQLite 一致性快照。 默认路径形如 data/backups/memory.v<旧版本>.<日期>.db。 文件名含 v5 表示备份时数据库版本为 5，并非所有安装都应恢复到 5。 备份包含当时 WAL 中尚未合入主文件的数据；不能用运行中直接复制主库替代。

同一数据库、同一旧版本、同一天已有同名备份时，会复用该文件，不再覆盖。 全新空库直接初始化；没有迁移的启动也不会每次创建这类备份。 它不是定期备份，更不保证保存升级后的新消息。 迁移失败会暴露错误，当前迁移事务回滚；先前已完成的迁移可能已经提交。 应保留失败现场后再确定恢复方案，避免反复修改版本号尝试启动。

恢复升级前状态¶

完全退出所有会写入数据的进程，暂停自动重启服务。 把当前配置与整个数据目录另存一份，保留升级后的消息和排查现场。 切回与备份对应的旧代码和依赖，并恢复那一版主体配置与插件配置。

优先恢复停机时保存的整个数据目录，保证数据库记录与关联文件匹配。 若只能恢复自动数据库快照，把当前数据库及同名 -wal、-shm 一并移出活动位置保存， 随后将选定快照复制为实际使用的 memory.db，避免新库旁文件与旧快照混用。 自动快照本身已带版本元信息，不需要再执行 PRAGMA user_version = 5。

恢复后先确认启动读取的是预期目录，再检查历史会话、人物与素材是否对应。 自检命令见 scripts/check/self_check.py：

uv run python scripts/check/self_check.py

不能直接回退的情形¶

没有升级前备份时，不能靠删除新列或降低版本号恢复旧结构与旧数据。 多人事实归属、关系拆分以及删除表的迁移，没有自动反向路径。 旧代码能够打开新库不代表版本兼容；当前迁移入口不提供降级安全性校验。 要求保留升级后的全部写入时，旧快照无法满足，需先做专门的数据迁移评估。 只有主库快照、关联素材已被淘汰时，也不能宣称恢复了完整运行状态。 结构细节见开发手册：数据库。