升级流程——拉代码、重启、Flyway 自动迁移

Docker 栈升级

Docker 用户升级最省心——三步：

1. 拉新版本代码
2. 备份 PostgreSQL 数据（强烈建议）
3. docker compose up -d

Flyway 会在 MateClaw 启动时自动检测新版本的 migration 脚本并执行。旧版本到新版本的表结构变更全由 Flyway 管——你不需要手动改数据库。

升级前备份 PostgreSQL：docker compose exec postgres pg_dump mateclaw > backup.sql。

桌面端升级

桌面端直接下载新版安装器覆盖安装。Electron 不会覆盖用户数据（H2 数据库在 Application Support/MateClaw/data/ 下）——升级后启动自动跑 Flyway migration。

JAR 升级

下载新版 JAR（或重新构建），停掉旧进程，启动新 JAR。Flyway 在启动时自动执行 migration。

如果数据库里有未应用的 migration（旧版本停在中间版本），Flyway 会报错并停止启动——这时候要先排查为什么旧版本没跑完，手动补 migration 或者恢复数据库备份。

升级后检查

• 启动成功，控制台能打开
• 登录正常（admin/admin123 或你的密码）
• 之前的知识库、Agent、渠道配置都还在
• 随便跑一个 Agent 看看工具调用正不正常

如果有异常，看日志最后 50 行——大概率是某个 migration 脚本没跑完或者数据库连接问题。

回滚

MateClaw 没有官方的「降级」路径——Flyway 只管前进不管后退。如果升级后出问题，用升级前的数据库备份恢复，然后用旧版本 JAR/镜像启动。这也是为什么升级前一定要备份。