openJiuwen Studio 升级指导

升级说明

请在升级前仔细阅读本指导文档，按照步骤完成升级操作。

一、本地安装升级

1. 切换到新版本分支

1. 进入项目根目录
2. 拉取最新代码：

   git pull
   

3. 切换到指定版本分支（如：v0.1.2 ）：

   git checkout v0.1.2
   

2. 前端升级

1. 进入前端项目目录：

   cd frontend
   

2. 重新执行依赖安装命令：

   npm install
   

3. 启动开发服务器以应用更新：

   npm run dev
   

3. 后端升级

1. 进入后端项目目录：

   cd backend
   

2. 重新执行依赖同步命令：

   uv sync
   

3. 数据库升级： 请参考 DATABASE_MIGRATION_DEVELOPMENT_GUIDE.md 的 [2. 版本升级说明] 章节进行后端数据库升级。

4. 激活虚拟环境并启动后端服务：

   source .venv/bin/activate
   python main.py
   

二、Docker安装升级

前置准备：旧版本配置文件

将旧版本实例的配置文件，复制至新版本部署工具的 pre_upgrade_envs 目录下。不同版本旧实例的配置文件如下：

• 旧版本 0.1.1：.env.<实例ID>
• 旧版本 0.1.2：.envs/env.<实例ID>
• 旧版本 0.1.3：.envs/env.deploy.<实例ID> 与 .envs/env.runtime.<实例ID>
• 旧版本 0.1.4：.envs/env.deploy.<实例ID> 与 .envs/env.runtime.<实例ID>

关于如何查看本实例的实例ID，请参考这里。

升级约束说明和配置要求

1. 本升级流程仅支持从低版本向高版本升级，或者同版本的数据迁移，不支持版本回退或降级操作。支持的版本迁移路径如下（以v0.1.5版本为例）：

源版本	目标版本	支持状态
0.1.1	0.1.5	支持
0.1.2	0.1.5	支持
0.1.3	0.1.5	支持
0.1.4	0.1.5	支持
0.1.5	0.1.5	支持（同版本数据迁移）

2. 本升级流程仅支持同类型数据库组件的平滑迁移，需确保新旧版本实例的数据库组件类型完全一致：

• 若旧版本实例使用 MySQL 组件，新版本实例需继续使用 MySQL 组件；
• 若旧版本实例使用 Milvus 组件，新版本实例需继续使用 Milvus 组件。

3. 若升级涉及 MySQL 或 Milvus 组件，请确保旧版本实例配置文件中，已正确配置实例运行所在机器的 IP 地址变量，保障升级组件和旧版本实例的宿主机的网络连通性。

IP=<实例组件所在服务器的IP地址>

4. 若升级涉及 SQLITE 组件，请确保新旧版本实例在同一台物理机上。

5. 不支持外挂 MySQL 组件或者外挂 Milvus 组件的数据迁移和升级。

6. 升级过程中需对旧实例的 MySQL 与 Milvus 组件数据进行拷贝，并迁移至新实例。请在升级前核查旧实例上述组件的数据总量，确保磁盘剩余空间不低于该总量的两倍，以满足升级所需空间条件。

执行升级命令

升级前请注意：请保持旧版本实例正常运行，切勿执行 shutdown 操作，确保旧版本容器处于正常工作状态（升级过程需要连接旧版本容器读取业务数据）。

在新版本部署工具的根目录下，执行以下一键升级命令，启动新版本实例并完成旧数据迁移：

$ ./service.sh up -n --upgrade

命令执行完成后，新启动的新版本实例将自动继承旧版本实例的大部分业务数据，实现无感知升级与数据平滑迁移。

注意，部分数据，如记忆数据和知识库原文件，暂不支持迁移，将在未来版本中支持。

三、验证升级

完成上述步骤后，请通过以下方式验证升级是否成功：

1. 前端页面能够正常访问
2. 后端服务能够正常响应API请求

如果在升级过程中遇到任何问题，请查看项目日志、安装指导的FAQ或联系项目管理人员。