# CoMi V3.0 Docker升级操作手册
北京致远互联软件股份有限公司
2026年10月
# 前言
本手册针对既有基于 Docker 安装维护的 CoMi 2.0、2.0.1、2.0.2、2.1.0、2.1.1 等老版本实例,提供原地升级到 CoMi V3.0 版本的详细操作指导。
通过本手册升级,将完整保留原有的业务数据卷(MySQL、PostgreSQL、Elasticsearch、BI 数据等)、大模型渠道与默认模型配置、三方互信凭据与平台现用有效 API Key。
本文档仅适用于既有 Docker 环境的原地升级,不适用于全新安装;全新安装请参考《CoMi V3.0 基于Docker安装部署手册》。
不同CoMi版本支持的V5、V8协同版本各不相同,升级CoMi的同时可能需要升级协同或打补丁,详细要求见下表:
| 版本 | 支持V5版本 | 支持V8版本 |
|---|---|---|
| CoMi V3.0 | 详见【CoMi和协同对应关系表 (opens new window)】 | V8所有版本均不支持 |
以下操作以默认安装路径 /data/Seeyon/Comi/comi-install 为例,实际操作时请按现场实际目录替换。
# 1. 升级包准备
# 1-1、CoMi V3.0版本安装包
CoMi Docker 一体化升级安装包请从致远官方渠道(商务营销中心产品下载库或官方源)下载,产品线对应 CoMi。仅需下载 Docker 安装包内的文件,根据服务器架构(x86_64 或 aarch64)选择对应离线包:
- x86架构离线安装包名称格式:
comi3.0.0-install-offline-x86.tar.gz - ARM架构离线安装包名称格式:
comi3.0.0-install-offline-arm64.tar.gz

安装包大小约 9.8GB,解压后镜像及文件占用约 20GB。为保证升级过程中镜像导入、临时解压及数据迁移顺利,必须确保服务器宿主机预留至少 50GB 以上的可用磁盘空间(可通过 df -h 命令查看)。
# 2. 适用范围
满足如下环境要求的客户项目,可参考本手册执行升级操作:
- 已基于 Docker 部署并运行 CoMi 2.0、2.0.1、2.0.2、2.1.0、2.1.1 等老版本;
- 协同 OA 已准备好对应 CoMi 3.0 的适配补丁(【CoMi和协同对应关系表 (opens new window)】)或已升级到支持版本;
- 本期仅升级已有服务,升级不新增智能表格、录音卡、Redis、MinIO、文档运行时等可选增量服务(新增服务可参考《CoMi V3.0 基于Docker安装部署手册》)。
# 3. CoMi新老版本服务变化
以下是 CoMi 2.x 系列至 CoMi 3.0 版本基础服务变化对照表:
| CoMi 2.0 | CoMi 2.0.2 | CoMi 2.1.0、2.1.1 | CoMi 3.0 | 备注说明 | |||
|---|---|---|---|---|---|---|---|
| AI-Manager | → | AI-Manager | → | AI-Manager | → | AI-Manager | 后台管理与调度中心 |
| AI-Engine | → | AI-Engine | → | AI-Engine | → | AI-Engine | 模型推理引擎 |
| Qdrant | → | Qdrant | → | ElasticSearch | → | ElasticSearch | 重要变更:2.1起改用ES替代Qdrant |
| 无 | → | CoMi Server | → | CoMi Server | → | CoMi Server | 业务服务与客户端支撑 |
| 无 | → | AI-DocumentParse | → | AI-DocumentParse | → | AI-DocumentParse | 协同文档与附件解析服务 |
| 无 | → | comi deno沙箱 | → | comi deno沙箱 | → | comi deno沙箱 | 智能体安全代码沙箱 |
| 无 | → | 可选按需 | → | data-pulse | → | data-pulse | 智能问数 BI(启用时保留) |
| 无 | → | 可选按需 | → | postgres | → | postgres | 协同驾驶舱数据仓库 |
| 无 | → | 可选按需 | → | nginx | → | nginx | 包内统一反向代理入口 |
重要变更特别说明:
- Qdrant 向量库废弃与迁移:CoMi 2.0.x 老版本使用的是 Qdrant 向量库,CoMi 2.1.x 及 3.0 改用更高效的 Elasticsearch 向量库。早期版本客户(2.0、2.0.1、2.0.2)升级到 3.0 时,必须在配置文件中配置迁移参数,系统会在升级时自动将历史向量数据迁移至 ES。已是 2.1.x 的环境无需该迁移。
- 原有部署范围保持:升级只针对现场已部署运行的服务进行版本升级,升级程序会自动继承旧配置,不追加未启用的新业务服务。
CoMi V3.0 服务信息:

# 4. 升级前准备
升级前请运维人员按顺序确认以下前置事项:
- 安装包准备:已将
comi3.0.0-install-offline-xxxxx.tar.gz离线包下载并上传到 CoMi 服务器; - 磁盘空间检查:在 CoMi 服务器执行
df -h,确认安装目录所在磁盘分区可用空间在 50GB 以上; - 停机窗口预留:升级过程需要停止旧容器服务并加载全新 3.0 镜像,请提前协调停机维护时间窗口。
- 确认协同版本: 提前完成协同版本的升级或打好补丁,确保协同版本满足适配要求,【CoMi和协同对应关系表 (opens new window)】。

# 5. 停止旧版本服务并备份目录
进入旧版本安装目录,停止正在运行的容器服务,然后将旧安装目录重命名为备份目录。
# 1. 进入旧版本安装目录,停止容器服务
cd /data/Seeyon/Comi/comi-install
docker compose down
# 2. 返回上级目录,将旧安装目录重命名备份
cd /data/Seeyon/Comi
mv comi-install bak-comi-install
执行完成后,旧版本程序目录变为 /data/Seeyon/Comi/bak-comi-install。
数据安全说明:
- 执行
docker compose down时,严禁添加-v参数! - 不带
-v参数只会清理容器和网络,所有的数据库数据卷(MySQL、PostgreSQL、Elasticsearch、BI 数据等 Docker Named Volumes)均安全保留在宿主机中,新版本启动时会自动复用。
# 6. 下载并解压新版本安装包
将 CoMi 3.0 离线安装包存放在 /data/Seeyon/Comi/ 目录下并解压:
# 进入安装根目录
cd /data/Seeyon/Comi
# 解压 CoMi 3.0 离线安装包(示例为X86架构)
tar -zxvf comi3.0.0-install-offline-x86.tar.gz
解压完成后,会在当前目录下生成全新的安装目录 /data/Seeyon/Comi/comi-install。
# 7. 执行升级操作
# 7.1 迁移配置文件
进入新版本安装目录,首先从模板生成新版本的 .env 配置文件:
cd /data/Seeyon/Comi/comi-install
cp .env.example .env
接下来,对照旧版本目录中的配置文件(可以通过 cat /data/Seeyon/Comi/bak-comi-install/.env 查看),使用 vi .env 将现场的自定义配置同步修改到新版本 .env 中:
vi .env
核心需要比对并填写的参数如下:
| 配置项 | 填写说明与要求 |
|---|---|
PRODUCT_LINE | 必须与老版本保持一致(如 A8) |
V5_ADDRESS | 必须与老版本保持一致,填写协同 OA 直连地址(如 192.168.94.154:80) |
V8_ADDRESS | 若为 V8 产品线,保持与老版本一致 |
NGINX_ADDRESS | 必须与老版本保持一致,填写容器内反访 OA 的基准代理地址(如 http://comi-nginx:80) |
| 各数据库密码 | MYSQL_PASSWORD、PG_PASSWORD、ES_PASSWORD 等必须与老版本保持一致 |
BI_MAC_ADDRESS | 若旧环境启用了 DataPulse BI,将旧 .env 中的 MAC 地址复制填入,确保 BI 授权不丢失 |
# 关键:Qdrant到Elasticsearch数据迁移配置说明
根据项目升级前的源版本,COMPOSE_PROFILES 配置存在重要差异,请务必核实选择:
场景一:从 CoMi 2.0、2.0.1、2.0.2 等早期版本升级至 CoMi 3.0
- 早期老版本使用 Qdrant 向量数据库,升级至 3.0 时必须执行向量数据迁移;
- 此时在
.env中修改COMPOSE_PROFILES时,必须在保留原有服务的基础上,同时追加elasticsearch,qdrant两个参数,使升级脚本同时拉起两个引擎执行无损迁移:
# 针对 2.0.x 老版本升级:同时包含 elasticsearch 与 qdrant
export COMPOSE_PROFILES="nginx,data-pulse,postgres,elasticsearch,qdrant"
配置修改示意参考:

场景二:从 CoMi 2.1.0 或 2.1.1 升级至 CoMi 3.0
- 2.1.x 版本已经切换为 Elasticsearch 向量数据库,底层不再存在 Qdrant;
- 此时直接沿用老版本的
COMPOSE_PROFILES参数即可,无需追加qdrant:
# 针对 2.1.x 版本升级:保持原有已有服务即可
export COMPOSE_PROFILES="nginx,data-pulse,postgres,elasticsearch"

# 7.2 执行升级脚本
在 .env 配置文件修改并确认无误后,进入安装目录直接执行升级脚本:
cd /data/Seeyon/Comi/comi-install
bash upgrade.sh
注意事项:
- 升级场景只执行
upgrade.sh,严禁执行install.sh(install.sh是全新安装脚本,会重新初始化数据库和配置); - 升级脚本会自动分步执行:检查环境 → 停止可能残留的服务 → 解压并加载 3.0 镜像 → 迁移数据库表结构与预置数据 → 启动全部新版本容器;
- 脚本执行过程中请保持终端连接,当控制台最终输出
CoMi 升级完成!时,表示升级脚本执行完毕。

升级完成后,会在升级可执行文件同级目录生成一个名为,里面有整个升级日志信息:

# 7.3 检查服务状态
升级完成后,通过 Docker 状态检查命令查看所有服务的运行状态:
cd /data/Seeyon/Comi/comi-install
docker compose ps
检查确认全部核心容器的 STATUS 均处于 Up 或 Up (healthy) 状态(以下列表为示例,部分客户环境可能没有部署这么多的服务,不用一定要求跟手册服务数量一致):
NAME IMAGE STATUS
comi-install-comi-builder-1 comi-builder:ai-V3.0.0-release_20260830 Up
comi-install-comi-server-1 comi-server:ai-V3.0.0-release_20260830 Up
comi-install-comi-engine-1 comi-engine:ai-V3.0.0-release_20260830 Up
comi-install-comi-security-1 comi-security:ai-V3.0.0-release_20260830 Up
comi-install-comi-dp-1 ai-document-parse:ai-V3.0.0-release_20260830 Up
comi-install-deno-sandbox-reuse comi-deno:v3.0 Up (healthy)
comi-install-mysql-1 mysql:8.0.46-all Up (healthy)
comi-install-postgres-1 postgres:16.14-all Up (healthy)
comi-install-comi-es-1 elasticsearch:7.17.29-all Up
comi-install-data-pulse-1 datapulse:ai-V3.0.0-release_20260830 Up
comi-install-nginx-1 nginx:1.30.3-all Up
运行状态截图参考(以下图片为示例,部分客户环境可能没有部署这么多的服务,不用一定要求跟手册服务数量一致):
如有个别服务未处于 Up 状态,可通过
docker logs comi-install-服务名-1查看容器启动日志排查具体原因。

# 8. 配置与核对协同三方互信
升级到 CoMi 3.0 后,容器在重新构建时内部 IP 可能产生变动。为确保协同 OA 与 CoMi 之间的安全通信正常,需要核对并完善以下三套三方互信信道。
此步必须操作!需建 3 组互信(协同问答 / 定时任务 / CoMi Server):
| 互信 | 回调地址 | 用途 |
|---|---|---|
| 协同知识问答 | http://CoMi宿主IP:8181/ai-manager/knowledge/center/third/part/callback | 问答调用 OA |
| 定时任务(V2.1.1+ 必须) | http://CoMi宿主IP:8181/ai-manager/v5Trust/callback | 定时任务令牌 |
| CoMi Server(V5 必填) | http://CoMi宿主IP:8081/comi/relation/callBack | CoMi APP 一键登录 |
绑定 IP 必须填两个:CoMi 服务器宿主 IP + 对应容器内 IP(docker inspect comi-builder | grep IPAddress、docker inspect comi-server | grep IPAddress;bridge 网络下 OA 侧实际看到的是宿主 IP,容器 IP 按 2.1 手册要求一并登记)。
# 8-1、comi-builder协同知识问答-三方互信
升级场景,此步操作主要是检查是否存在当前三方互信,如不存在则需要参考本章节新增,如存在则需要做检查、保存!
配置协同知识问答第一步: 登录协同系统管理员 → 三方互信设置 → 新建一个三方互信:
- 名称自定义,建议取一个与产品有关的名称,如
Comi协同问答互信。 升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存! - ID和密钥自动生成,无需操作
- 回调地址必填,必须是
http://ai-manager服务IP:8181/ai-manager/knowledge/center/third/part/callback其中ai-manager服务IP对应容器外IP(宿主机IP) - 必须填写绑定IP,地址需要填写容器外和容器内双IP(详见下图示例):
- 获取容器内IP:获取命令
docker inspect comi-install-comi-builder-1 | grep IPAddress - 获取容器外IP:CoMi服务器主机IP(获取命令如
ip a)
- 获取容器内IP:获取命令


配置协同知识问答第二步: 到CoMi服务器AI-Manager配置三方互信信息:
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!
# 修改CoMi服务器上ai-manager的配置文件
cd /data/Seeyon/Comi/comi-install/config/ai-manager
vim application.yaml
# 找到application.yaml中的v5CooperateThirdPartId和v5CooperateThirdPartSecret配置,将右侧的xxx改成真实值 并保存yaml文件
common: 节下:
v5CooperateThirdPartId: <协同问答互信ID>
v5CooperateThirdPartSecret: <协同问答互信密钥>
# 以上完成后重启一下AI-Manager服务(comi-builder)使配置生效:
docker restart comi-install-comi-builder-1

配置协同问答三方互信第三步: 到协同OA数据库中注册三方互信认证。
三方互信菜单下找到授权菜单,并确保“三方互信接口”下的两个接口处于勾选状态(未勾选则勾选保存),程序会自动向数据库写入SQL。
✓ POST /attachment/channel/batchDownload
✓ GET /attachment/channel/file/{fileId}

# 8-2、comi-builder定时任务-三方互信
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!
配置定时任务第一步: 登录协同系统管理员 → 三方互信设置 → 新建一个三方互信:
- 名称自定义,建议取一个与产品有关的名称,如
Comi定时任务互信。升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存! - ID和密钥自动生成,将生成的ID和密钥拷贝到AI-Manager的定时任务三方互信ID和互信密钥里
- 回调地址必填,必须是
http://ai-manager服务IP:8181/ai-manager/v5Trust/callback其中ai-manager服务IP对应容器外IP(宿主机IP) - 必须填写绑定IP,地址需要填写容器外和容器内双IP(详见下图示例):
- 获取容器内IP:获取命令
docker inspect comi-install-comi-builder-1 | grep IPAddress - 获取容器外IP:CoMi服务器主机IP(获取命令如
ip a)
- 获取容器内IP:获取命令


配置定时任务第二步: 到CoMi服务器AI-Manager配置三方互信信息:
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!
# 修改CoMi服务器上ai-manager的配置文件
cd /data/Seeyon/Comi/comi-install/config/ai-manager
vim application.yaml
# 找到application.yaml中的v5ThirdPartId和v5ThirdPartSecret配置,将右侧的xxx改成真实值 并保存yaml文件
common: 节下:
v5ThirdPartId: <定时任务互信ID>
v5ThirdPartSecret: <定时任务互信密钥>
# 以上完成后重启一下AI-Manager服务(comi-builder)使配置生效:
docker restart comi-install-comi-builder-1

配置定时任务三方互信第三步: 到协同OA数据库中注册三方互信认证。
三方互信菜单下找到授权菜单,并确保“三方互信接口”下的如下几个接口处于勾选状态(未勾选则勾选保存),程序会自动向数据库写入SQL。

# 8-3、CoMi Server安全与认证-三方互信
CoMi Server安全与认证章节的三方互信,需要到协同OA找到对应信息并配置,操作步骤如下:
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!
1、协同OA 系统管理员→信息集成配置→三方互信访问授权→找到名为“Comi一键登录”的三方互信信息,此信息随OA产品内置,不要个人新增。(如不存在,需发支持单联系研发提供补齐)。
2、修改”Comi一键登录“这条三方互信信息,主要是将里面的127.0.0.1的配置修改成CoMi Server真实的IP(容器外IP)和端口:
- 回调地址由原始值
http://127.0.0.1/comi/relation/callBack修改为http://CoMiServer服务器IP:8081/comi/relation/callBack(其中8081是CoMiServer默认运行端口,如修改了端口需自行调整) - 必须填写绑定IP,地址需要填写容器外和容器内双IP(详见下图示例):
- 获取容器内IP:获取命令
docker inspect comi-install-comi-server-1 | grep IPAddress - 获取容器外IP:CoMi服务器主机IP(获取命令如
ip a)
- 获取容器内IP:获取命令
以上几步参考如下截图示例:


3、配置 CoMi Server 三方互信信息:
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!
vim /data/Seeyon/Comi/comi-install/config/comi-server/application-prod.yaml
# 将trust节点id和secret设置成协同上面的配置
trust:
id: <CoMi一键登录互信ID>
secret: <CoMi一键登录互信密钥>
# 以上完成后重启一下CoMi Server服务使配置生效:
docker restart comi-install-comi-server-1

4、检查”Comi一键登录“是否生效:勾选”Comi一键登录“后点击授权按钮,确保系统已默认勾选三方互信接口,未勾选则执行勾选并保存:
升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!

5、到协同OA数据库执行SQL查询 SELECT * from ctp_rest_access WHERE REST_ID = 'Comi一键登录的ID'; 检查是否有数据,如有数据则说明正常:

# 9. 检查完善协同配置
1、检查协同版本与CoMi的适配性
版本不匹配需要升级,版本匹配备注补丁包则需要打补丁重启,否则后续CoMi部署会报错!
历史协同OA版本集成CoMi可能需要打补丁,具体参考【CoMi和协同对应关系表 (opens new window)】里面的说明,补丁包从CoMi安装部署云盘上面自取:

2、plugin.properties配置文件参数检查
检查协同 OA 服务器部署目录下的配置文件 协同OA地址/base/conf/plugin.properties,确保 CoMi 核心 4 条参数完整齐全。
plugin.properties配置核对方法:读取升级日志,根据升级日志中的输出信息核对配置是否齐全,一切以最新的升级日志配置为准:升级日志为位于安装程序下名为 upgrade_info_xxx.log 的文件

协同OA地址/base/conf/plugin.properties 主要配置如下:
ai.comibuilderServer=http://Nginx地址/seeyon/ai-platform/ai-manager/assistant/info/getAllRightsAssistant
ai.managerUrl=http://CoMi服务器IP:8181/ai-manager
# 注意:ai.comi.apikey 为掩码显示,完整密钥请从 /data/Seeyon/Comi/comi-install/.apikey.env 的 API_KEY 获取
ai.comi.apikey=XvJepx******krT9
comi_ai_manager_url=http://Nginx内网地址/seeyon/ai-platform
# 按需:如客户使用CoMi APP移动应用,需要配置 M3 访问地址(通常外网,不带 /seeyon 后缀),如没有使用M3则配置清空即可
comi.server.url=http(s)://M3外网访问地址
配置示例参考:

参数修改或核对完毕后,需重启协同 OA 服务使配置生效。
# 10. 检查完善Nginx配置
如Nginx使用的是当前CoMi Docker工具自动安装,即Nginx直接在当前服务器Docker中运行,则本步可以直接跳过:

如项目自己维护管理Nginx,则需要参考《CoMi Nginx安装和配置(V5产品线) (opens new window)》手册重新配置Nginx参数,哪怕上版本已经配置过NG,也需要删除comi相关配置,重新使用手册中最新的配置(最新配置有参数兼容优化)!
# 11. 协同初始化应用与大模型核对
完成上述步骤并重启协同 OA 后,进行最后的业务初始化与核对闭环:
# 11.1 核对大模型资产
- 浏览器打开并登录协同系统管理员后台 → 进入【CoMi Builder】后台;
- 点击左侧导航【资源库】→【模型管理】;
- 核对原有的 LLM 大模型、Embedding 向量模型、ReRank 重排模型配置:
- 确认原配置依然完整保留;
- 分别点击各模型的【连接测试】,确保模型测试通过;
- 确认原默认模型选择依然正确生效。
- 注意:升级后切勿随意删除或更换默认的 Embedding 向量模型,以免导致既有知识库向量索引失效。
# 11.2 全量数据初始化
在上一步相关模型配置检查完成后,再进行应用初始化操作:系统管理员 → CoMiBuilder → 系统管理 → 进入数据初始化页面操作:
CoMi V3.0 数据初始化页共 7 个页签:技能 / 专家 / 快捷指令 / 应用 / Agent / 工作流 / 工具(红点=未初始化)。要求每个页签都执行初始化操作。每页操作:勾选表头全选 → 点击右上角「初始化」→ 覆盖确认选择「是」(部分复杂应用向量化初始化耗时较长,请耐心等待)。
说明:初始化过程中若提示「依赖资源导入失败: [xxxx智能体->BI返回数据格式错误]」属于正常现象(表示未部署协同驾驶舱高级版 / 智能问数 BI 组件,不影响其余通用办公协同功能)。


再次提醒,一定要每个页签都执行初始化,确保全部执行一遍:

# 11.3 协同应用授权
上一步数据初始化完成后,切换到前端,默认系统管理员会出现小章鱼,从小章鱼进入智能门户中,点击设计 → 应用中心 → 应用市场 → 选择对应的应用进入详情 → 点击数据权限进行授权

小章鱼入口授权如下:

# 12. 日常运维
CoMi Docker升级完成后,日常运维(启停、更新、卸载、排查)参考《CoMi V3.0 Docker模式安装维护手册 (opens new window)》。
快速跳转