# 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

CoMi V3.0安装包下载目录

安装包大小约 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 服务信息:

官方 V3.0 Docker 部署示意图

# 4. 升级前准备

升级前请运维人员按顺序确认以下前置事项:

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

1791544305034.png

# 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"

配置修改示意参考:

1792381510174.png

场景二:从 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"

1792381207459.png

# 7.2 执行升级脚本

在 .env 配置文件修改并确认无误后,进入安装目录直接执行升级脚本:

cd /data/Seeyon/Comi/comi-install
bash upgrade.sh

注意事项:

  • 升级场景只执行 upgrade.sh,严禁执行 install.sh(install.sh 是全新安装脚本,会重新初始化数据库和配置);
  • 升级脚本会自动分步执行:检查环境 → 停止可能残留的服务 → 解压并加载 3.0 镜像 → 迁移数据库表结构与预置数据 → 启动全部新版本容器;
  • 脚本执行过程中请保持终端连接,当控制台最终输出 CoMi 升级完成! 时,表示升级脚本执行完毕。

upgrade.sh执行完成示例

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

1792397673431.png

# 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 查看容器启动日志排查具体原因。

1792382018885.png

# 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)

1791784985134.png

1791785826792.png

配置协同知识问答第二步: 到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

1791785285893.png

配置协同问答三方互信第三步: 到协同OA数据库中注册三方互信认证。

三方互信菜单下找到授权菜单,并确保“三方互信接口”下的两个接口处于勾选状态(未勾选则勾选保存),程序会自动向数据库写入SQL。

✓ POST /attachment/channel/batchDownload
✓ GET /attachment/channel/file/{fileId}

1794738448140.png

# 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)

1791784985134.png

1791787502166.png

配置定时任务第二步: 到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

1791787764090.png

配置定时任务三方互信第三步: 到协同OA数据库中注册三方互信认证。

三方互信菜单下找到授权菜单,并确保“三方互信接口”下的如下几个接口处于勾选状态(未勾选则勾选保存),程序会自动向数据库写入SQL。

1794740469894.png

# 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)

以上几步参考如下截图示例:

1791788087459.png

1791788284374.png

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

1791788631126.png

4、检查”Comi一键登录“是否生效:勾选”Comi一键登录“后点击授权按钮,确保系统已默认勾选三方互信接口,未勾选则执行勾选并保存:

升级场景如不存在则需要参考本章节新增,如存在则需要做检查、保存!

1791540190689.png

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

1791540539095.png

# 9. 检查完善协同配置

1、检查协同版本与CoMi的适配性

版本不匹配需要升级,版本匹配备注补丁包则需要打补丁重启,否则后续CoMi部署会报错!

历史协同OA版本集成CoMi可能需要打补丁,具体参考【CoMi和协同对应关系表 (opens new window)】里面的说明,补丁包从CoMi安装部署云盘上面自取:

1791544305034.png

2、plugin.properties配置文件参数检查

检查协同 OA 服务器部署目录下的配置文件 协同OA地址/base/conf/plugin.properties,确保 CoMi 核心 4 条参数完整齐全。

plugin.properties配置核对方法:读取升级日志,根据升级日志中的输出信息核对配置是否齐全,一切以最新的升级日志配置为准:升级日志为位于安装程序下名为 upgrade_info_xxx.log 的文件

1792398519805.png

协同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外网访问地址

配置示例参考:

1792398699333.png

参数修改或核对完毕后,需重启协同 OA 服务使配置生效。

# 10. 检查完善Nginx配置

如Nginx使用的是当前CoMi Docker工具自动安装,即Nginx直接在当前服务器Docker中运行,则本步可以直接跳过:

1792399823338.png

如项目自己维护管理Nginx,则需要参考《CoMi Nginx安装和配置(V5产品线) (opens new window)》手册重新配置Nginx参数,哪怕上版本已经配置过NG,也需要删除comi相关配置,重新使用手册中最新的配置(最新配置有参数兼容优化)!

# 11. 协同初始化应用与大模型核对

完成上述步骤并重启协同 OA 后,进行最后的业务初始化与核对闭环:

# 11.1 核对大模型资产

  1. 浏览器打开并登录协同系统管理员后台 → 进入【CoMi Builder】后台;
  2. 点击左侧导航【资源库】→【模型管理】;
  3. 核对原有的 LLM 大模型、Embedding 向量模型、ReRank 重排模型配置:
    • 确认原配置依然完整保留;
    • 分别点击各模型的【连接测试】,确保模型测试通过;
    • 确认原默认模型选择依然正确生效。
    • 注意:升级后切勿随意删除或更换默认的 Embedding 向量模型,以免导致既有知识库向量索引失效。

# 11.2 全量数据初始化

在上一步相关模型配置检查完成后,再进行应用初始化操作:系统管理员 → CoMiBuilder → 系统管理 → 进入数据初始化页面操作:

CoMi V3.0 数据初始化页共 7 个页签:技能 / 专家 / 快捷指令 / 应用 / Agent / 工作流 / 工具(红点=未初始化)。要求每个页签都执行初始化操作。每页操作:勾选表头全选 → 点击右上角「初始化」→ 覆盖确认选择「是」(部分复杂应用向量化初始化耗时较长,请耐心等待)。

说明:初始化过程中若提示「依赖资源导入失败: [xxxx智能体->BI返回数据格式错误]」属于正常现象(表示未部署协同驾驶舱高级版 / 智能问数 BI 组件,不影响其余通用办公协同功能)。

1791545656955.png

1770023415678.png

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

1791545724551.png

# 11.3 协同应用授权

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

1791798114690.png

小章鱼入口授权如下:

1791798314817.png

# 12. 日常运维

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

编撰人:het