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

如下图红框是CoMi基础服务部署包,红框中的每个文件夹中的程序都需要下载,选择合适的架构安装包:
如项目部署了智能问数还需要下载DataPulse升级,ComiBuilder-Security同理

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

# 工具升级与 CoMi 版本升级操作
# 1、升级前数据与环境备份(必做)
升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!
升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!
升级前备份CoMi数据库数据(ai_manager和comi_server两个库)!
升级涉及SQL更新,如存在异常,无法还原数据!

# 2、升级智能部署工具至 V3.0
- 停止老版本部署工具:
进入老版本部署工具目录并执行停止脚本,释放
9526端口:
cd /data/comi-deployer-tools/Deployer-Tools-v2.1.1-linux-x86_64
sh shutdown.sh
- 解压 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
- 迁移老版本历史数据:
将 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/
- 迁移管理员登录凭据: 将老版本登录密码数据导入新工具,保留原管理员密码:
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/
- 启动新版 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、停用运行中服务并进入更新环境
- 打开浏览器访问新版部署工作台:
http://CoMi宿主IP:9526,输入管理员账号密码登录。 - 进入当前纳管的部署环境页面,查看「核心服务状态」列表。
- 依次停用运行中的老版本服务:为确保升级过程平稳无冲突,在升级前需将列表中的运行中服务逐个点击操作列的「停用」(包括 AI-Manager、CoMi Server、AI-Security、协同驾驶舱、Elasticsearch 等)。
- 确认待升级服务均已停用后,点击页面右上角「修改并更新环境」按钮,进入服务升级向导。

如果是CoMi 2.0版本升级,项目上还有Qdrant服务,则必须保持此服务处于启动状态!
再次提醒:确保Qdrant处于启动状态,其余服务全部停止,升级程序才会将Qdrant数据向ElasticSearch迁移。

# 4、指定服务器部署包路径并执行解析
- 准备新版本的部署包,提前参考 【升级程序包准备】 章节获取。
- 客户端本地对升级包进行打包并上传,升级前将全部包统一上传至 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.zipAI-Engine_centos8-x86_64.zipai-engine-sandbox-x86.zip(全新容器化沙箱包,包含 comi-deno 与 ai-engine-sandbox 镜像)AI-Security_centos8-x86_64.zipComi-Server-linux-x86_64.zipAI-DocumentParse_centos8-x86_64.zipelasticsearch-7-linux-x86_64.zipseeyon-datapulse-linux-x86_64.zip(可选,智能问数)
3、上传后,回到CoMi管理控制台,录入新版本部署包路径,自动解析直至新版包信息渲染出来

# 5、逐个重新配置确认与一键配置校验
解析成功后,系统将在下方「第二步:服务环境规划表」呈现各服务的目标版本(如 CoMi Server 3.0.0、AI-Manager 3.0.0、AI-Engine 3.0.0、代码执行沙箱 1.0 等),各服务初始状态显示为「未配置」。
请严格按照以下三步操作:
- 第一步(红标 1):逐个重新配置确认:
- 依次点击每个服务操作列的「配置」链接,打开弹窗核对配置项并点击「确定」保存。
- 第二步(红标 2):配置完成后全选:
- 所有服务配置保存后,点击服务列表表头左上角的复选框进行全选。
- 第三步(红标 3):全选后点击一键配置校验:
- 点击左下角的「一键配置校验」按钮,系统自动触发网络连通性、端口占用及配置合规性前置体检。

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

# 6、重点服务配置项核对
依次配置CoMi核心服务,大部分核心服务只需要重新确定保存一遍:
# AI-Security、AI-Engine、代码执行沙箱
AI-Security、AI-Engine、代码执行沙箱这几个基础服务升级无相关变化,无需调整参数,重新配置确定即可。
如升级前没有相关服务(如代码执行沙箱),本期需要进行全新配置场景,请参考另一份智能部署工具部署维护手册做相关配置。
# CoMi Server服务配置升级
新版本需要配置产品线,其余配置无变化。
如升级前没有CoMi Server服务,本期需要进行全新配置场景,请参考另一份智能部署工具部署维护手册做相关配置。

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三方互信密钥上
以上几步参考如下截图示例:

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

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

# 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配置需要使用

# AI-Manager服务配置ES
AI-Manager需要新增ES配置:
- ES地址:对应上一步ElasticSearch向量库配置的地址和http端口(默认9200)
- ES认证用户名:对应上一步ElasticSearch向量库配置的Elastic用户名
- ES认证密码:对应上一步ElasticSearch向量库配置的Elastic密码

# 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

AI-Manager配置协同问答三方互信第二步: 到协同OA数据库中注册三方互信认证。
三方互信菜单下找到授权菜单,并确保“三方互信接口”下的两个接口处于勾选状态(未勾选则勾选保存),程序会自动向数据库写入SQL。
升级场景需要勾选如图所示的参数,如没有该参数,需要针对协同打补丁再试:
✓ POST /attachment/channel/batchDownload
✓ GET /attachment/channel/file/{fileId}

AI-Manager配置定时任务三方互信第一步: 登录协同系统管理员-三方互信设置-新建一个三方互信(如上版本已经配置,本版本需要做人工复核):
- 名称自定义,建议取一个与产品有关的名称,如
Comi定时任务互信 - ID和密钥自动生成,将生成的ID和密钥拷贝到AI-Manager的定时任务三方互信ID和互信密钥里
- 回调地址必填,必须是
http://ai-manager服务IP:8181/ai-manager/v5Trust/callback - 必须设置绑定IP,绑定IP对应:AI-Manager服务器IP

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

# document文档解析服务配置升级
ai-document-parse 文档解析服务升级涉及两个参数配置:
- 迁移数据:需要勾选“开启”
- Qdrant URL地址:指向老版本Qdrant服务地址,http协议,默认端口6333。

如果是CoMi 2版本,项目上还有Qdrant服务,则必须保持此服务处于启动状态!
再次提醒:确保Qdrant处于启动状态,其余服务全部停止,升级程序才会将Qdrant数据向ElasticSearch迁移。

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

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

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

# 升级后协同集成与业务初始化
# 1、导出生成报告与检查协同配置
- 服务全部升级为运行中后,点击页面右上角「生成报告(含后续指引)」。
- 打开报告,核实协同 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密钥
- 检查协同 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)》 进行部署配置!

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

# 4、CoMiBuilder 数据初始化(必做)
CoMi V3.0 包含随版本新增的系统官方 Agent、工具集与内置应用,升级后必须在后台重新批量执行数据更新初始化:
- 使用协同管理员账号(如
admin1)登录协同系统管理后台。 - 依次进入:CoMiBuilder → 系统管理 → 数据初始化 ,然后挨个页签进行全量重新初始化。

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

小章鱼入口授权如下:

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