# CoMi V3.0 智能部署工具升级手册

北京致远互联软件股份有限公司

2026年10月

# 前言

本手册就 CoMi V2.x(重点覆盖 CoMi 2.1.0、CoMi 2.1.1 版本)向 CoMi V3.0 版本平滑升级提供标准化实操指引。

致远 CoMi 智能部署工具(Deployer-Tools)采用 B/S 架构,支持向导式完成各基础服务的部署、升级、配置管理与运维监控。通过将旧版部署工具的元数据无损迁移至 V3.0 部署工具,管理员可直接在 Web 工作台中读取原有主机拓扑与环境配置,快速完成 CoMi V3.0 基础服务升级。

不同CoMi版本支持的V5、V8协同版本各不相同,升级CoMi的同时可能需要升级协同或打补丁,详细要求见下表:

版本 支持V5版本 支持V8版本
CoMi V3.0 详见【CoMi和协同对应关系表 (opens new window)】 V8所有版本均不支持

# 环境准备与服务变化

# CoMi各版本必备服务变化清单

以下是CoMi不同版本部署的服务变化列表,CoMi2.1.0最重大的变更为:Qdrant向量库废弃,改用更高效的ElasticSearch向量库,到CoMi 3.0基础服务无变化。

从CoMi 2.0.x升级到CoMi 3.0版本,您需要做如下事情:

  • 提前下载CoMi 3.0必须的所有程序,参照本手册进行程序的升级或安装
  • CoMi2.0版本客户还需要参照本手册将Qdrant向量库数据迁移到ElasticSearch向量库
  • 如由CoMi 2.1.0升级到CoMi3.0或更高版本则不用再做Qdrant向量库替换
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
AI-Security → AI-Security → AI-Security → AI-Security
Qdrant → Qdrant → ElasticSearch → ElasticSearch V2.1开始ES替代Qdrant
无 → CoMi Server → CoMi Server → CoMi Server
无 → AI-DocumentParse → AI-DocumentParse → AI-DocumentParse
无 → comi deno沙箱 → comi deno沙箱 → ai-engine-sandbox V3.0沙箱更名
data-pulse → data-pulse → data-pulse 3.4 → data-pulse 3.5 智能问数

# 升级程序包准备

CoMi部署升级工具从商务公布的安装程序地址下载(文档中心-文档库-营销中心-营销体系销售管理知识库-产品下载地址-提交给区域产品下载地址xxx.xls),产品线对应CoMi V3.0。

注意:CoMi部署工具部署包 和 CoMi基础服务部署包 是不同文件夹存放,项目上需要根据自身环境情况下载文件夹的部署包。

CoMi部署工具部署包:找到部署工具文件夹,下载与服务器相合适的架构安装包(arm架构信创系统下载linux-arm_64.zip):

1791445224452.png

如下图红框是CoMi基础服务部署包,红框中的每个文件夹中的程序都需要下载,选择合适的架构安装包:

如项目部署了智能问数还需要下载DataPulse升级,ComiBuilder-Security同理

1791445340405.png

部分服务按照CPU架构和操作系统拆分成多个包,如果X86架构操作系统无匹配的安装包则默认取centos7尝试,如果ARM架构操作系统无匹配的安装包则默认取kylinv10(麒麟V10)尝试:

1791446654069.png

# 工具升级与 CoMi 版本升级操作

# 1、升级前数据与环境备份(必做)

升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!

升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!

升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!

升级涉及SQL更新,如存在异常,无法还原数据!

1766132457416.png

# 2、升级智能部署工具至 V3.0

  1. 停止老版本部署工具: 进入老版本部署工具目录并执行停止脚本,释放 9526 端口:
cd /data/comi-deployer-tools/Deployer-Tools-v2.1.1-linux-x86_64
sh shutdown.sh
  1. 解压 V3.0 部署工具: 参考【升级程序包准备】 提前下载 Deployer-Tools-v3.0.0-xxx.zip 部署工具,将 Deployer-Tools-v3.0.0-linux-x86_64.zip 上传至服务器,然后解压到指定目录:
# 在新版部署包目录下运行解压(示例为X86架构)
unzip Deployer-Tools-v3.0.0-linux-x86_64.zip -d /data/comi-deployer-tools
  1. 迁移老版本历史数据: 将 V2.1.1 工具中的部署配置数据库 install.db 导入新版本程序目录,实现无损继承已纳管的主机拓扑、部署空间与服务配置:
cp -a /data/comi-deployer-tools/Deployer-Tools-v2.1.1-linux-x86_64/install.db /data/comi-deployer-tools/Deployer-Tools-v3.0.0-linux-x86_64/
  1. 迁移管理员登录凭据: 将老版本登录密码数据导入新工具,保留原管理员密码:
mkdir -p /data/comi-deployer-tools/Deployer-Tools-v3.0.0-linux-x86_64/file/auth
cp -a /data/comi-deployer-tools/Deployer-Tools-v2.1.1-linux-x86_64/file/auth/auth.json /data/comi-deployer-tools/Deployer-Tools-v3.0.0-linux-x86_64/file/auth/
  1. 启动新版 V3.0 部署工具:
cd /data/comi-deployer-tools/Deployer-Tools-v3.0.0-linux-x86_64
bash startup.sh

# 验证启动结果:
# 查看启动日志,确认数据库表结构自动完成 DDL 迁移,服务在 `9526` 端口成功监听:
tail -f logs/output.log
netstat -tlpn | grep 9526

# 3、停用运行中服务并进入更新环境

  1. 打开浏览器访问新版部署工作台:http://CoMi宿主IP:9526,输入管理员账号密码登录。
  2. 进入当前纳管的部署环境页面,查看「核心服务状态」列表。
  3. 依次停用运行中的老版本服务:为确保升级过程平稳无冲突,在升级前需将列表中的运行中服务逐个点击操作列的「停用」(包括 AI-Manager、CoMi Server、AI-Security、协同驾驶舱、Elasticsearch 等)。
  4. 确认待升级服务均已停用后,点击页面右上角「修改并更新环境」按钮,进入服务升级向导。

1791997297973.png

如果是CoMi 2.0版本升级,项目上还有Qdrant服务,则必须保持此服务处于启动状态!

再次提醒:确保Qdrant处于启动状态,其余服务全部停止,升级程序才会将Qdrant数据向ElasticSearch迁移。

1778430615995.png

# 4、指定服务器部署包路径并执行解析

  1. 准备新版本的部署包,提前参考 【升级程序包准备】 章节获取。
  2. 客户端本地对升级包进行打包并上传,升级前将全部包统一上传至 CoMi 宿主机的指定目录(统一推荐路径:/data/comi-v3.0.0-packages/)
cd /data
mkdir comi-v3.0.0-packages
# 服务器找到zip压缩文件,解压到指定文件夹下
unzip comi-v3.0.0-packages.zip -d comi-v3.0.0-packages
# 部署工具前端录入/data/comi-v3.0.0-packages解析
cd /data/comi-v3.0.0-packages

新版本部署升级包主要包含如下内容(以下以X86平台为例,ARM架构自行选择合适的包):

新版本部署包还有comi-table等包,都不是必须安装的服务,无需在升级场景添加

  • AI-Manager-linux-x86_64.zip
  • AI-Engine_centos8-x86_64.zip
  • ai-engine-sandbox-x86.zip(全新容器化沙箱包,包含 comi-deno 与 ai-engine-sandbox 镜像)
  • AI-Security_centos8-x86_64.zip
  • Comi-Server-linux-x86_64.zip
  • AI-DocumentParse_centos8-x86_64.zip
  • elasticsearch-7-linux-x86_64.zip
  • seeyon-datapulse-linux-x86_64.zip(可选,智能问数)

3、上传后,回到CoMi管理控制台,录入新版本部署包路径,自动解析直至新版包信息渲染出来

1791448073927.png

# 5、逐个重新配置确认与一键配置校验

解析成功后,系统将在下方「第二步:服务环境规划表」呈现各服务的目标版本(如 CoMi Server 3.0.0、AI-Manager 3.0.0、AI-Engine 3.0.0、代码执行沙箱 1.0 等),各服务初始状态显示为「未配置」。

请严格按照以下三步操作:

  1. 第一步(红标 1):逐个重新配置确认:
    • 依次点击每个服务操作列的「配置」链接,打开弹窗核对配置项并点击「确定」保存。
  2. 第二步(红标 2):配置完成后全选:
    • 所有服务配置保存后,点击服务列表表头左上角的复选框进行全选。
  3. 第三步(红标 3):全选后点击一键配置校验:
    • 点击左下角的「一键配置校验」按钮,系统自动触发网络连通性、端口占用及配置合规性前置体检。

1791997527336.png

校验通过后,建议外部依赖与集成配置开启“自动注入配置”(开启后工具会自动注入最新的comi配置到nginx),然后下一步:

1792150078409.png

# 6、重点服务配置项核对

依次配置CoMi核心服务,大部分核心服务只需要重新确定保存一遍:

# AI-Security、AI-Engine、代码执行沙箱

AI-Security、AI-Engine、代码执行沙箱这几个基础服务升级无相关变化,无需调整参数,重新配置确定即可。

如升级前没有相关服务(如代码执行沙箱),本期需要进行全新配置场景,请参考另一份智能部署工具部署维护手册做相关配置。

# CoMi Server服务配置升级

新版本需要配置产品线,其余配置无变化。

如升级前没有CoMi Server服务,本期需要进行全新配置场景,请参考另一份智能部署工具部署维护手册做相关配置。

1778428589593.png

CoMi Server安全与认证-三方互信

CoMi Server安全与认证章节的三方互信,需要到协同OA找到对应信息并配置,如上版本已经配置,本版本需要做复核:

1、协同OA 系统管理员→信息集成配置→三方互信访问授权→找到名为“Comi一键登录”的三方互信信息,此信息随OA产品内置,不要个人新增。(如不存在,需发支持单联系研发提供补齐)。

2、修改”Comi一键登录“这条三方互信信息,主要是将里面的127.0.0.1的配置修改成CoMi Server真实的IP和端口:

  • 回调地址由原始值http://127.0.1/comi/relation/callBack 修改为 http://CoMiServer服务器IP:8081/comi/relation/callBack (其中8081是CoMiServer默认运行端口,如修改了端口需自行调整)
  • 绑定IP由原始值 127.0.1 修改为 CoMiServer服务器IP (配置示例见下方截图)

3、将”Comi一键登录“里面的ID完整复制到CoMi Server三方互信ID上,将密钥完整复制到CoMi Server三方互信密钥上

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

1791536228870.png

4、建议升级场景都重新进行一次授权保存:勾选”Comi一键登录“后点击授权按钮,确保系统已默认勾选三方互信接口,未勾选则执行勾选并保存:

1791540190689.png

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

1791540539095.png

# ElasticSearch向量库配置

自CoMi V2.1.0版本开始,CoMi使用ElasticSearch作为向量数据存储,替代老版本Qdrant向量库引擎。

  • 部署模式: 默认安装,即自动安装一个独立的ES向量库,注意不可复用协同全文检索(缺插件)。
  • 目标主机: 特指ElasticSearch远程部署到哪台服务器,建议资源充足的前提下与CoMi基础服务放置在一起。
  • HTTP运行端口: 默认9200,此端口在AI-Manager配置需要使用
  • Transport运行端口: 默认9300
  • 集群名称、节点名称: 如无特殊要求建议保持默认
  • 运行用户: ElasticSearch默认内置elastic作为管理用户,如无特殊要求建议保持默认
  • 部署路径、数据存储路径、日志存储路径: 可保持默认,需要确保路径磁盘空间充足,后续数据存储都在相关目录下
  • 堆内存大小: 根据实际情况设置,如4、8,设置后ES会占用对应大小的内存,POC可设置1~2,生产大并发需根据情况调大,新版本都是数字,不带单位g
  • 启用X-Pack安全认证: 建议启用,如禁用则无需用户名密码就能连接ES,安全要求较高的环境不允许此行为
  • Elastic用户名: 建议保持默认,启用X-Pack安全认证后,认证连接的用户名,在AI-Manager配置需要使用
  • Elastic密码: 自定义一个12位以上的密码,启用X-Pack安全认证后,认证连接的密码,在AI-Manager配置需要使用

1778132170812.png

# AI-Manager服务配置ES

AI-Manager需要新增ES配置:

  • ES地址:对应上一步ElasticSearch向量库配置的地址和http端口(默认9200)
  • ES认证用户名:对应上一步ElasticSearch向量库配置的Elastic用户名
  • ES认证密码:对应上一步ElasticSearch向量库配置的Elastic密码

1778429625455.png

# AI-Manager配置协同问答三方互信

CoMi V2.1.0 版本开始,需要单独为 协同知识问答 到系统后台配置一套三方互信,否则协同知识问答无法使用,详细配置方法如下:

AI-Manager配置协同问答三方互信第一步: 登录协同系统管理员-三方互信设置-新建一个三方互信(如上版本已经配置,本版本需要做人工复核):

  • 名称自定义,建议取一个与产品有关的名称,如 Comi协同问答互信
  • ID和密钥自动生成,将生成的ID和密钥拷贝到AI-Manager的协同问答三方互信ID和互信密钥里
  • 回调地址必填,必须是 http://ai-manager服务IP:8181/ai-manager/knowledge/center/third/part/callback
  • 必须设置绑定IP,绑定IP对应:AI-Manager服务器IP

1791455668699.png

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

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

升级场景需要勾选如图所示的参数,如没有该参数,需要针对协同打补丁再试:

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

1794738448140.png

AI-Manager配置定时任务三方互信第一步: 登录协同系统管理员-三方互信设置-新建一个三方互信(如上版本已经配置,本版本需要做人工复核):

  • 名称自定义,建议取一个与产品有关的名称,如 Comi定时任务互信
  • ID和密钥自动生成,将生成的ID和密钥拷贝到AI-Manager的定时任务三方互信ID和互信密钥里
  • 回调地址必填,必须是 http://ai-manager服务IP:8181/ai-manager/v5Trust/callback
  • 必须设置绑定IP,绑定IP对应:AI-Manager服务器IP

1791455864587.png

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

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

1794740469894.png

# document文档解析服务配置升级

ai-document-parse 文档解析服务升级涉及两个参数配置:

  • 迁移数据:需要勾选“开启”
  • Qdrant URL地址:指向老版本Qdrant服务地址,http协议,默认端口6333。

1778430043966.png

如果是CoMi 2版本,项目上还有Qdrant服务,则必须保持此服务处于启动状态!

再次提醒:确保Qdrant处于启动状态,其余服务全部停止,升级程序才会将Qdrant数据向ElasticSearch迁移。

1778430615995.png

# 7、检查 Nginx 外部依赖配置并进入部署

  1. 点击「一键配置校验」后,等待列表内所有 8 个服务状态均变为绿色的「已校验」。
  2. 向下滚动页面至「外部依赖与集成配置」区块(配置 Nginx 作为所有服务的统一反向代理入口):
    • 确保开启「自动注入配置」开关。
    • Nginx 服务器主机:下拉选择纳管的 Nginx 服务器。
    • Nginx 主配置文件路径:填写宿主机上真实的 Nginx 主配置路径(示例:/apps/nginx/conf/nginx.conf)。
    • 协同服务监听端口:填写协同 OA 通过 Nginx 代理对外暴露的监听端口(示例:80)。
  3. 仔细检查 Nginx 配置的准确性,确认各服务主机别名及 IP 映射无误。
  4. 确认全部正确后,点击页面右下角的「下一步 →」按钮。

1791997726290.png

# 8、确认数据库备份并正式执行升级

  1. 点击「下一步」后,系统弹出前置保护确认弹窗:「请确认已完成数据库备份」。
  2. 弹窗提示:检测到本次选择的服务可能会初始化或修改数据库。为避免误操作、脚本异常或重复执行导致数据丢失,请在继续前手动完成相关数据库备份。
  3. 提示清单重点核对三项:协同驾驶舱、CoMi Server、AI-Manager 数据库。
  4. 确认此前已完成上述数据库转储备份后,勾选复选框:「我已完成上述数据库备份,并了解继续执行可能会修改数据库。」。
  5. 点击蓝底按钮「我已备份,继续部署」。

1791997743898.png

# 9、升级执行与沙箱镜像加载注意事项

  1. 系统进入控制台实时日志界面,自动按依赖顺序停用旧程序、解压升级包并启动新服务。
  2. 沙箱镜像加载特别提醒(避坑要点):
    • 日志执行到 [deno-docker-setup] 任务时,将首先加载 comi-deno:v3.0 镜像,随后清理旧容器;
    • 紧接着输出:[deno-docker-setup] 开始加载 ai-engine-sandbox 镜像...;
    • 关键事项:因 ai-engine-sandbox 为全功能容器化沙箱,随包镜像文件体积较大(接近 4GB),通过 docker load 解压导入需要耗费一定 I/O 资源,需要等待若干分钟;
    • 此阶段控制台可能会静默等待数分钟,属正常解压加载过程,切勿强制刷新页面或终止部署。
  3. 等待所有服务升级就绪且右下角按钮变为「完成部署 →」,点击完成,返回核心服务状态列表,确认所有服务均处于「运行中」。

1791998168141.png

# 升级后协同集成与业务初始化

# 1、导出生成报告与检查协同配置

  1. 服务全部升级为运行中后,点击页面右上角「生成报告(含后续指引)」。
  2. 打开报告,核实协同 OA 端 plugin.properties 的三项基准参数是否与报告一致:
# CoMi 服务访问入口(经 Nginx 统一代理入口)
ai.comi.server.url=http://Nginx代理IP:端口/seeyon/ai/comi
# CoMi 后端通信基准网关
ai.comi.base.url=http://Nginx代理IP:端口
# 平台接入密钥(与报告中 COMI_API_KEY 一致)
ai.comi.api.key=从生成报告中获取的API密钥
  1. 检查协同 OA 服务器上 ApacheJetspeed/webapps/seeyon/WEB-INF/cfgHome/plugin.properties,若参数有变动需补齐并重启协同 OA 生效。

# 2、Nginx更新CoMi配置

如使用CoMi部署工具升级时开启了外部依赖与集成配置,并且设置了正确的Nginx服务器,则CoMi工具会自动向Nginx写入配置。如参考本章节操作发现Nginx配置内容已经写入,则可以跳过本章节。

如发现近期Nginx配置文件夹生成了comi相关的conf配置,则说明CoMi部署工具已经自动写入,如没有生成则必须参考手册 《CoMi Nginx安装和配置(V5产品线) (opens new window)》 进行部署配置!

1791974228227.png

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

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

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

1791544305034.png

# 4、CoMiBuilder 数据初始化(必做)

CoMi V3.0 包含随版本新增的系统官方 Agent、工具集与内置应用,升级后必须在后台重新批量执行数据更新初始化:

  1. 使用协同管理员账号(如 admin1)登录协同系统管理后台。
  2. 依次进入:CoMiBuilder → 系统管理 → 数据初始化 ,然后挨个页签进行全量重新初始化。

1792081257506.png

# 5、检查与确认应用授权(闭环)

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

1791798114690.png

小章鱼入口授权如下:

1791798314817.png

# 其它升级运维事项

CoMi智能部署工具的维护(启停、打包、卸载、取日志、部署新服务)均参考 《CoMi V3.0部署工具安装维护手册 (opens new window)》

编撰人:het