准备明确候选版本
记录当前源码提交、镜像或二进制标识及数据库备份。从有权访问的源码构建候选版本，并检查配置和结构变更。应用发行号为 0.1.0，上游 0.30/0.31 升级指南不是本分支的版本历史。不要把数据库记录的结构版本强行改成应用版本。
测试完整路径
用可丢弃的数据库和附件副本演练启动与结构升级，再检查登录、笔记读写、附件访问、集成与可见性。安排生产变更，干净停止旧写入者，并监控新进程。不要在生产上运行结构变更或破坏性存储测试。
回退也涉及数据
旧二进制文件可能无法理解新结构。安全回退可能需要恢复对应的升级前数据库与文件，而不只是换回旧容器标签。先隔离恢复并验证。在新版本验收前，保留升级记录和已知可用备份。
在 SQLite 副本上演练迁移
先完成一致备份，复制解压到新的 upgrade-check 目录；下面的 memos_prod.db 必须是副本，不能是正在使用的数据库。按构建指南生成候选二进制。inspect 为只读；migrate-copy 会写入指定数据库，必须明确确认它是测试副本。这些 SQLite 诊断命令不能用于 PostgreSQL/MySQL DSN。
./build/memos inspect --database ./upgrade-check/memos_prod.db
./build/memos migrate-copy \
--database ./upgrade-check/memos_prod.db \
--confirm-test-copy
./build/memos inspect --database ./upgrade-check/memos_prod.db使用隔离副本启动候选镜像
在已审核的应用源码目录构建独立候选镜像。upgrade-check 目录只能包含可丢弃的恢复 SQLite 与本地附件副本。下面启动完整应用，但不连接外部网络、不发布端口，再从容器内部探测。不要把挂载路径指向生产数据。如果容器名已存在，应检查上次测试，不要盲目删除。健康响应只验证启动；生产切换前还要完成下文的笔记、认证及文件检查。
docker build -f scripts/Dockerfile -t memos:candidate .
docker run -d --name memos-upgrade-check --network none \
-e MEMOS_DRIVER=sqlite -e MEMOS_PORT=5230 \
--mount type=bind,src="$PWD/upgrade-check",dst=/var/opt/memos \
memos:candidate
docker logs --tail 100 memos-upgrade-check
docker exec memos-upgrade-check wget -qO- http://127.0.0.1:5230/healthz
docker stop --time 60 memos-upgrade-check切换前记录验收结果
迁移前后的 inspect 都应报告 quickCheck 为 "ok"。比较 schemaVersion 并保留迁移报告；应用版本不需要与 schemaVersion 相同。现有部署若使用实例 URL，migrate-copy 应传入同样的预期 --instance-url，并在之后复核访问策略。迁移失败时停止演练，保留日志和原始备份，不要直接修改版本号。候选版本通过隔离功能验证后，停止旧写入者，完成最后一次一致备份，启动候选版本，再次检查健康、登录、笔记及文件。
回退应用与匹配数据
变更生产前记录回退组合：旧镜像或二进制、升级前数据库、附件快照及配置。需要回退时先停候选进程，避免恢复旧数据的同时继续写入。恢复到新目标位置，用旧构建验证数据后再切换流量。备份之后产生的笔记不在该恢复点内，因此丢弃候选数据前必须决定如何保留或补录。