升级指南

本文档介绍 Snail AI 的版本升级流程，包括升级准备、数据库迁移、配置变更和回滚方案。

升级原则

逐版本升级 -- 请按版本顺序依次升级，不要跨多个大版本直接升级
先备份再升级 -- 升级前务必完成数据库和文件的完整备份
先测试再生产 -- 建议在测试环境验证通过后再升级生产环境
阅读变更日志 -- 升级前阅读目标版本的更新日志，了解 Breaking Changes

升级前准备

1. 数据备份

重要

升级前请务必完成以下备份，以便在升级失败时回滚。

关系型数据库备份

MySQL:

bash

mysqldump -u root -p --single-transaction --routines --triggers snail_ai > snail_ai_backup_$(date +%Y%m%d_%H%M%S).sql

PostgreSQL:

bash

pg_dump -U postgres -Fc snail_ai > snail_ai_backup_$(date +%Y%m%d_%H%M%S).dump

SQL Server:

sql

BACKUP DATABASE snail_ai TO DISK = '/backup/snail_ai_backup.bak' WITH FORMAT, INIT;

达梦 (DM):

sql

BACKUP DATABASE BACKUPSET '/backup/snail_ai_backup';

向量数据库备份

PgVector（随 PostgreSQL 一起备份）:

bash

pg_dump -U postgres -Fc snail_ai_vector > snail_ai_vector_backup_$(date +%Y%m%d_%H%M%S).dump

Milvus:

bash

# 使用 Milvus Backup 工具
milvus-backup create -n snail_ai_backup

文件存储备份

bash

# 本地存储
tar -czf snail_ai_storage_$(date +%Y%m%d_%H%M%S).tar.gz /data/snail-ai/storage/

# MinIO（使用 mc 客户端）
mc mirror minio/snail-ai /backup/snail-ai-storage/

2. 检查当前版本

bash

# 查看当前运行版本
curl http://localhost:8080/actuator/info

# 或查看 JAR 包版本
java -jar snail-ai-starter.jar --version

3. 阅读版本变更说明

前往更新日志页面，仔细阅读从当前版本到目标版本之间所有版本的变更内容，特别注意标记为 Breaking Change 的条目。

升级步骤

Docker 部署升级

bash

# 1. 进入部署目录
cd /path/to/snail-ai/deploy/docker

# 2. 拉取最新镜像
docker compose pull

# 3. 停止当前服务
docker compose down

# 4. 启动新版本（数据库迁移会自动执行）
docker compose up -d

# 5. 查看启动日志，确认无报错
docker compose logs -f snail-ai-server

JAR 包部署升级

bash

# 1. 停止当前服务
systemctl stop snail-ai-server
# 或
kill -SIGTERM $(cat /opt/snail-ai/snail-ai.pid)

# 2. 备份旧版 JAR 包
cp /opt/snail-ai/snail-ai-starter.jar /opt/snail-ai/snail-ai-starter.jar.bak

# 3. 替换为新版 JAR 包
cp /path/to/new/snail-ai-starter.jar /opt/snail-ai/snail-ai-starter.jar

# 4. 执行数据库迁移脚本（如果版本要求手动执行）
# 具体脚本路径参见各版本的升级说明
mysql -u root -p snail_ai < docs/sql/migration/v0.x.x_to_v0.y.y.sql

# 5. 启动新版服务
systemctl start snail-ai-server

# 6. 查看日志确认启动正常
journalctl -u snail-ai-server -f

前端升级

bash

# Docker 部署 -- 前端随 Nginx 镜像一起更新
docker compose pull nginx
docker compose up -d nginx

# 手动部署 -- 替换前端构建产物
cd /path/to/snail-ai-admin
git pull
pnpm install
pnpm build
# 将 dist/ 目录内容复制到 Nginx 静态资源目录
cp -r dist/* /var/www/snail-ai-admin/dist/
nginx -s reload

Agent Client 升级

版本兼容性

Agent Client 的版本应与 Server 版本保持一致。升级 Server 后请同步升级所有 Client 节点。

xml

<!-- Maven 依赖更新 -->
<dependency>
    <groupId>com.opensnail</groupId>
    <artifactId>snail-ai-agent-sdk</artifactId>
    <version>新版本号</version>
</dependency>

升级步骤：

更新 Maven 依赖版本号
重新编译打包
逐个节点滚动升级（先下线一个节点，升级后重新上线，再升级下一个）

数据库 Schema 迁移

每个版本升级可能包含数据库 Schema 变更。迁移脚本位于后端仓库的 docs/sql/migration/ 目录。

迁移脚本命名规则

v{源版本}_to_v{目标版本}_{数据库类型}.sql

例如：

v0.0.1_to_v0.1.0_mysql.sql
v0.0.1_to_v0.1.0_postgresql.sql
v0.0.1_to_v0.1.0_dm.sql

执行迁移

bash

# MySQL
mysql -u root -p snail_ai < docs/sql/migration/v0.0.1_to_v0.1.0_mysql.sql

# PostgreSQL
psql -U postgres -d snail_ai -f docs/sql/migration/v0.0.1_to_v0.1.0_postgresql.sql

# SQL Server
sqlcmd -S localhost -U sa -P your_password -d snail_ai -i docs/sql/migration/v0.0.1_to_v0.1.0_sqlserver.sql

# 达梦
disql SYSDBA/your_password@localhost:5236 \`/path/to/v0.0.1_to_v0.1.0_dm.sql

自动迁移

部分版本支持启动时自动执行数据库迁移（基于 Flyway / 自研迁移框架）。请查阅具体版本的 Release Notes 确认是否支持自动迁移。

Breaking Changes 处理

以下是各版本升级中可能遇到的 Breaking Changes 及处理方法。

配置项变更

当配置项名称或结构发生变化时，需要更新 application.yml：

版本	变更内容	处理方式
--	后续版本将在此处记录	--

API 变更

当 REST API 路径或参数发生变化时，如果有外部系统通过 OpenAPI 集成，需要同步更新。

数据格式变更

当数据库中的数据格式发生变化时，迁移脚本会自动处理数据转换。但请务必在执行迁移前完成数据库备份。

回滚方案

如果升级后出现问题，可按以下步骤回滚。

Docker 部署回滚

bash

# 停止新版服务
docker compose down

# 恢复旧版镜像
docker compose pull --policy=never  # 使用本地缓存的旧版镜像
# 或指定旧版本标签
# 在 docker-compose.yml 中将镜像版本改回旧版

# 恢复数据库
mysql -u root -p snail_ai < /backup/snail_ai_backup_YYYYMMDD_HHMMSS.sql

# 启动旧版服务
docker compose up -d

JAR 包部署回滚

bash

# 停止服务
systemctl stop snail-ai-server

# 恢复旧版 JAR 包
cp /opt/snail-ai/snail-ai-starter.jar.bak /opt/snail-ai/snail-ai-starter.jar

# 恢复数据库
mysql -u root -p snail_ai < /backup/snail_ai_backup_YYYYMMDD_HHMMSS.sql

# 启动服务
systemctl start snail-ai-server

升级检查清单

每次升级前请逐项确认：

[ ] 已阅读目标版本的更新日志和 Breaking Changes
[ ] 已完成关系型数据库的完整备份
[ ] 已完成向量数据库的备份
[ ] 已完成文件存储的备份
[ ] 已在测试环境验证升级流程
[ ] 已准备好回滚方案
[ ] 已通知相关用户可能的服务中断时间
[ ] 已准备好对应数据库类型的迁移脚本
[ ] Agent Client 版本与 Server 版本匹配
[ ] 升级完成后已验证核心功能正常

版本升级历史

升级路径	数据库迁移	配置变更	注意事项
初始安装 → v0.0.1	执行初始化脚本	无	首次安装

持续更新

本表格将随版本发布持续更新。请关注更新日志获取最新版本信息。

下一步

更新日志 -- 查看各版本详细变更
配置参考 -- 了解配置项变化
故障排除 -- 升级后遇到问题的排查方法

升级指南 ​

升级原则 ​

升级前准备 ​

1. 数据备份 ​

关系型数据库备份 ​

向量数据库备份 ​

文件存储备份 ​

2. 检查当前版本 ​

3. 阅读版本变更说明 ​

升级步骤 ​

Docker 部署升级 ​

JAR 包部署升级 ​

前端升级 ​

Agent Client 升级 ​

数据库 Schema 迁移 ​

迁移脚本命名规则 ​

执行迁移 ​

Breaking Changes 处理 ​

配置项变更 ​

API 变更 ​

数据格式变更 ​

回滚方案 ​

Docker 部署回滚 ​

JAR 包部署回滚 ​

升级检查清单 ​

版本升级历史 ​

下一步 ​

升级指南

升级原则

升级前准备

1. 数据备份

关系型数据库备份

向量数据库备份

文件存储备份

2. 检查当前版本

3. 阅读版本变更说明

升级步骤

Docker 部署升级

JAR 包部署升级

前端升级

Agent Client 升级

数据库 Schema 迁移

迁移脚本命名规则

执行迁移

Breaking Changes 处理

配置项变更

API 变更

数据格式变更

回滚方案

Docker 部署回滚

JAR 包部署回滚

升级检查清单

版本升级历史

下一步