# 协同McpGateway网关部署维护手册

适用系统:Linux x86_64 / Windows 64 位 推荐版本:协同V11.0.2 北京致远互联软件股份有限公司 2026 年 11 月

# 前言

本手册说明如何使用安装包中的 SeeyonMcpGatewayInstall.sh(Linux)和 SeeyonMcpGatewayInstall.bat(Windows)完成 MCP 网关的安装。按「安装前提 → 执行安装 → 启动服务 → 验证安装」的顺序操作即可;安装过程的配置项全部由安装脚本自动写入,无需手工编辑配置文件。

# 一、安装前提

安装前请确认服务器满足下表条件;不满足的项需先处理,否则安装过程中会中断。

项目 要求
操作系统 Linux x86_64(CentOS 7 及以上、麒麟等主流发行版)或 Windows 64 位
执行权限 Linux 使用 root 或对安装目录有写权限的账号;Windows 使用管理员账号
Java 无需预装。安装包自带 JDK 1.8.0_372,安装时会自动复制到 <安装路径>/McpGateway/jdk
磁盘空间 安装包解压后约 2.3 GB,安装目录约 0.4 GB(含内置 JDK),建议预留 10 GB 以上
内存 4 GB 以上(服务默认 JVM 堆为 2 GB,服务还会占用部分堆外内存,故建议4GB以上)
服务端口 默认 18080,需未被占用,并在防火墙放行
安装路径 绝对路径,且不能含中文、空格和特殊字符,也不能直接使用根目录
  • 安装包内同时存放了其它产品线的程序包(文件服务、全文检索等),本次安装只会部署 MCP 网关,其余文件无需处理,也不要删除。
  • 安装路径建议统一采用纯英文,例如 Linux 用 /data/Seeyon,Windows 用 D:\Seeyon。

安装包获取方式:从商务公布的对应版本安装程序下载地址下载名为“1.IndependentService.zip”的文件:

1794021024576.png

确保安装包包含名为SeeyonMcpGatewayInstall的可执行文件:

1794021081616.png

网络拓扑图: 1794536628968.png

Nginx参考配置(配置后MCP网关后台访问地址: http|https://{nginx地址}:{nginx端口}/mcp-gateway/admin/index.html)

    location /mcp-gateway/ {
      add_header 'Access-Control-Allow-Origin' '*';
      add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
      add_header 'Access-Control-Allow-Headers' 'Origin, Content-Type, Accept, Authorization';
      if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Headers' 'Origin, Content-Type, Accept, Authorization';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Origin' '*';
        return 204;
      }
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_cache_bypass $nocache $cookie_nocache $arg_nocache $arg_comment;
      # 静态页面:/mcp-gateway/admin/* → /admin/*(剥掉 /mcp-gateway 前缀)
      rewrite ^/mcp-gateway/admin/index\.html$ /admin/index.html break;
      proxy_pass http://{MCP网关部署服务器IP}:{MCP网关启动端口};   # ← 必须不带尾斜杠
    }

# 二、Linux 环境安装

以下四个步骤在服务器上以 root 账号执行,全部命令可直接复制粘贴。

# 步骤 1 上传并解压安装包

将 1.IndependentService.zip 上传到服务器上空间充足的目录(下例为 /data),然后解压:

cd /data
unzip -q 1.IndependentService.zip

预期结果:/data 下出现 1.IndependentService 目录,且安装包与解压目录处于同一级。

解压耗时数分钟,请等待命令返回后再执行下一步;服务器若没有 unzip,可先执行 yum install -y unzip 或 apt-get install -y unzip。建议保留 1.IndependentService.zip,不要解压后删除。

# 步骤 2 执行安装脚本

进入解压目录并运行安装入口脚本:

cd /data/1.IndependentService
bash SeeyonMcpGatewayInstall.sh

脚本会依次询问安装路径与服务端口,并按顺序自动完成:写入安装配置(产品线固定为 McpGateway)→ 解压静默安装工具 → 部署程序 → 按需调整端口。

交互提示 输入示例 说明
请输入安装路径(必填,绝对路径,如 /data/Seeyon) /data/Seeyon 必填,以 / 开头;不要含中文、空格、特殊字符
请输入服务端口(直接回车使用默认 18080) 直接回车 回车即使用 18080;也可输入 1–65535 之间的端口
确认以上配置? [Y/n] Y 输入 n 则取消安装

预期结果:脚本输出 [OK] install.sh 执行完成 与「安装完成!」横幅,并列出安装路径、服务端口、启动与停止命令。入口脚本确认后,静默安装器还会提示“是否继续安装?输入 y 继续”,输入 y。

安装程序落在 <安装路径>/McpGateway,例如 /data/Seeyon/McpGateway。端口若使用默认值 18080,脚本不会改动配置文件;填写了其它端口,脚本会自动修改 <安装路径>/McpGateway/config/application.yml。全过程包含解压与复制 JDK,中途会停留数分钟,属正常现象。

1794020432997.png

# 步骤 3 启动服务

安装完成后服务不会自动启动,需手工执行启动脚本:

cd /data/Seeyon/McpGateway
bash startup.sh

预期结果:输出使用的 JDK、外部配置文件路径与 应用已在后台启动,PID=xxxx,随后窗口持续滚动日志。

服务以后台方式启动,日志写入 logs_sy/console.log 与 logs_sy/gateway.log,进程号写入 logs_sy/app.pid。当前窗口会持续显示日志,按 Ctrl+C 只退出日志显示,服务仍在后台运行。安装过程不会把服务注册为系统服务,服务器重启后需重新执行本节命令。

# 步骤 4 验证安装

依次执行以下三条命令确认安装结果:

ps -ef | grep mcp-gateway | grep -v grep
ss -lntp | grep 18080
tail -n 50 /data/Seeyon/McpGateway/logs_sy/gateway.log

预期结果:能查到 java 进程;18080 端口处于 LISTEN;日志中无报错信息。浏览器访问 http://<服务器IP>:18080/admin/index.html 可打开网关管理端,用于安装后的业务配置。

# 停止服务

cd /data/Seeyon/McpGateway
bash shutdown.sh

# 三、Windows 环境安装

Windows 下的安装步骤与 Linux 一致,区别是安装入口为批处理脚本,启动方式为前台窗口运行。

# 步骤 1 解压安装包

把 1.IndependentService.zip 复制到磁盘空间充足的目录(下例为 D:\),使用 7-Zip 解压,得到 D:\1.IndependentService\。

建议使用 7-Zip 解压:安装包接近 2 GB 且目录层级较深,Windows 自带解压工具容易中途失败或提示路径过长。

# 步骤 2 运行安装脚本

右键 D:\1.IndependentService\SeeyonMcpGatewayInstall.bat,选择「以管理员身份运行」。脚本会先解压静默安装工具,再依次询问安装路径与服务端口。

交互提示 输入示例 说明
请输入安装路径: D:\Seeyon 必填,带盘符的绝对路径;不要含中文、空格、特殊字符
请输入服务端口(默认 18080): 直接回车 回车即使用 18080
确认以上配置? [Y/n] Y 输入 n 取消安装

预期结果:屏幕输出「安装完成!」,并列出安装路径、服务端口和启动、停止命令,按任意键关闭窗口。入口脚本确认后,静默安装器还会提示“是否继续安装?输入 y 继续”,输入 y。

安装程序落在 D:\Seeyon\McpGateway。填写了非默认端口时,脚本会自动修改 D:\Seeyon\McpGateway\config\application.yml 中的端口。

1794020485292.png

# 步骤 3 启动与停止服务

启动:双击 D:\Seeyon\McpGateway\startup.bat,该窗口需保持打开,关闭窗口即停止服务。

停止:双击 D:\Seeyon\McpGateway\shutdown.bat,或在启动窗口按 Ctrl+C。

启动脚本会先检查配置端口是否被占用,被占用时提示先执行 shutdown.bat 再启动。与 Linux 相同,安装过程不会把服务注册为 Windows 服务,重启服务器后需重新执行启动脚本。

启动时,控制台会输出MCP相关服务信息,参考信息做后续的连接部署配置和测试:

1794791243604.png

# 步骤 4 验证安装

在命令提示符中执行:

netstat -ano | findstr :18080

预期结果:能查到 18080 端口的 LISTENING 记录。日志文件位于 D:\Seeyon\McpGateway\logs_sy\gateway.log。浏览器访问 http://<服务器IP>:18080/admin/index.html 可打开网关管理端。

# 四、安装后目录说明与常用操作

安装完成后,程序目录(下表以 Linux 路径为例)内的关键文件如下,排障和日常操作都会用到。

路径 说明
McpGateway/mcp-gateway.jar 网关主程序
McpGateway/config/application.yml 外部配置文件,可改服务端口、二次确认有效期、链路数据上报,改动后重启生效;文件缺失时服务无法启动
McpGateway/startup.sh、startup.bat 启动脚本
McpGateway/shutdown.sh、shutdown.bat 停止脚本
McpGateway/jdk/ 安装时从安装包复制的内置 JDK,服务默认使用它启动
McpGateway/logs_sy/ 运行日志:gateway.log、console.log、app.pid
McpGateway/Uninstall.sh Linux 卸载脚本
1.IndependentService/SilentInstallerTool/SilentInstaller/logs/ 安装过程日志:install.log、error.log

修改服务端口:编辑 McpGateway/config/application.yml 中的 server.port,然后执行停止脚本、启动脚本各一次。

卸载:先停止服务,再删除整个 McpGateway 目录;Linux 也可执行安装目录下的 Uninstall.sh。

# 五、常见问题处理

安装或启动过程中遇到下表现象时,按对应的处理方法操作。

现象 处理方法
提示「找不到 …/1.IndependentService.zip,请先上传安装包」 安装包与 1.IndependentService 目录不在同一级。把 zip 放回同级目录后重新执行脚本
提示「解压后仍找不到 …/SilentInstallerTool/SilentInstaller,请检查安装包结构」 安装包解压不完整(Windows 常见)。删除已解压目录,用 7-Zip 重新完整解压后再执行
提示安装路径不合法(含中文、空格、特殊字符,或指向根目录) 改用纯英文路径,如 /data/Seeyon、D:\Seeyon
启动报「未找到外部配置文件 …/config/application.yml」 安装目录内配置文件缺失,说明安装包不完整,需重新安装
启动提示端口被占用 先停止占用端口的进程,或改 config/application.yml 的 server.port 后重启;也可重新运行安装脚本并填写新端口
Linux 提示 startup.sh: Permission denied 执行 chmod +x startup.sh shutdown.sh 后再启动
安装中途失败,需要重试 直接重新运行安装脚本即可,检测到已有 McpGateway 目录时安装器会按覆盖方式重新部署;故障详情看 SilentInstaller/logs/install.log 与 error.log
Windows 执行 shutdown.bat 提示未找到运行中的进程,但服务确实在运行 新版 Windows 已移除脚本依赖的 wmic 命令,在任务管理器中结束对应的 java.exe 进程即可
内网其它机器无法访问管理端 确认服务器防火墙已放行服务端口,如 Linux 执行 firewall-cmd --add-port=18080/tcp --permanent && firewall-cmd --reload

# 六、协同 OA 对接MCP与配置验证

部署服务后,需要在MCP侧配置OA地址才能使用,如何配置和使用MCP服务详见《MCP网关操作手册 (opens new window)》。

McpGateway 安装并启动后,还需完成网关管理端登录、OA 后台配置、网关回填授权和调用验证四个步骤。下文以默认端口 18080、默认应用 ID seeyon(应用类型编码 1001)为例;如果安装时使用了其他端口,将地址中的 18080 替换为实际端口即可。

前置要求:协同 OA 需为 V11.0.2 及以上版本(9.0SP1\10.0SP1\11.0版本最新的BuildID号打补丁),OA 服务器与 MCP 网关服务器之间网络互通。

# 6.1 登录 MCP 网关管理端并记录回调地址

  1. 登录安装 McpGateway 的服务器,查看首次启动时自动生成的平台登录密钥(accessKey):
cat /data/Seeyon/McpGateway/.mcp-gateway/global.json
  1. 在浏览器打开网关管理端:http://网关服务器IP:18080/admin/index.html。
  2. 在「平台登录」页签填入查到的平台密钥,点击「登录」。
  3. 在应用列表找到默认应用 seeyon(致远OA),点击右侧「选择工具并启用」(或「配置」),在「接入地址」区域记下两个地址,下一步在 OA 后台会用到:
    • 三方互信回调地址:http://网关服务器IP:18080/mcp-gateway/v5/trust/callback
    • MCP Endpoint:http://网关服务器IP:18080/mcp-gateway/1001/apps/seeyon/message

# 6.2 在 OA 后台配置三方互信与网关连接

使用系统管理员账号(admin1)登录协同 OA 管理后台,在「信息集成配置」下完成两项配置。

# 1. 配置三方互信访问授权

  1. 进入「信息集成配置 → 三方互信访问授权」,点击「新建」。
  2. 按实际环境填写表单:
    • 名称:填写便于识别的名称,例如 mcpgateway。
    • 回调地址:填入上一步记录的 http://网关服务器IP:18080/mcp-gateway/v5/trust/callback。
    • IP 校验:勾选开启,添加 MCP 网关服务器的 IP 地址。
    • 状态:选择「启用」。
  3. 记录页面生成的「ID」(三方互信 ID)和「密钥」(三方互信密钥),点击「确定」保存。
  4. 回到三方互信列表,勾选新建的 mcpgateway 记录,点击工具栏「授权」,勾选需要开放的资源组和三方互信接口(可直接点击「全选」),点击「确定」保存。

注意:必须完成「授权」并勾选资源后,网关侧才能从 OA 拉取工具清单。

# 2. 配置 MCP 网关连接

  1. 进入「信息集成配置 → MCP网关连接」。
  2. 填写以下两项后点击「保存」:
    • 网关地址:http://网关服务器IP:18080
    • endpoint地址:/mcp-gateway/1001/apps/seeyon/message(与网关侧 MCP Endpoint 的路径部分保持一致)

# 6.3 回填网关配置并授权启用工具

切回 MCP 网关管理端的 seeyon 应用「配置」页面:

  1. 在「基础信息」区域填写 OA 信息:
    • 应用版本:填写当前 OA 版本号,例如 11.0.2。
    • 应用域名:填写协同 OA 访问地址,必须包含 /seeyon 上下文路径,例如 http://OA访问地址/seeyon。
  2. 在「安全与认证」区域填入 OA 侧记录的「三方互信 ID」和「三方互信密钥」,点击「保存配置」。
  3. 在上方「工具授权」卡片点击「选择工具」(或「调整授权」),在抽屉右上角点击「强制刷新工具缓存」,等待网关向 OA 拉取工具清单(耗时数秒至数十秒)。
  4. 清单加载完成后勾选需要开放的工具(初次对接可先点「仅加入低危工具」),点击「保存变更」。
  5. 在基础配置页面打开「启用状态」开关并保存配置。返回应用列表,确认该应用状态显示为「运行中」。

# 6.4 验证配置是否生效

  1. 在 MCP 网关管理端核对:
    • 应用列表中 seeyon 状态为「运行中」,工具授权数大于 0。
    • 如刷新工具缓存时提示「工具清单加载失败」,可到网关服务器查看 logs_sy/gateway-error.log,重点排查回调地址、网关 IP 绑定以及 OA 三方互信资源授权是否已勾选保存。
  2. 在 OA 个人中心测试调用:
    • 使用普通业务账号登录协同 OA,进入「个人设置 → 任务令牌」,新建并授权一个任务令牌。
    • 在下方「MCP 授权码」区域新建一条授权码,绑定该任务令牌、设置有效期并启用。
    • 使用该页面上的「模拟三方调用」(或第三方 MCP 客户端),将地址设为 http://网关服务器IP:18080/mcp-gateway/1001/apps/seeyon/message,并在请求头 Authorization 中携带生成的授权码。能够正常列出并调用已授权工具,即说明配置完成。

# 七、日常维护

# 日常启停服务

1、Windows系统直接到MCP程序目录下启停: 运行startup.bat启动,运行shutdown.bat停止

1794020250974.png

2、Linux系统启停命令参考:

# 默认程序路径  : /data/Seeyon/McpGateway

# 启动命令  :
cd /data/Seeyon/McpGateway && bash startup.sh
# 停止命令  :
cd /data/Seeyon/McpGateway && bash shutdown.sh

# 修改端口

默认端口18080,如需修改,则到MCP程序路径修改配置文件: McpGateway\config\application.yml,修改后重启MCP服务生效。

1794020316172.png

# JVM配置

启动脚本startup.sh设置了JVM内存配置信息,默认最大堆内存2048m(2G),考虑非堆内存等开销,请确保服务器给MCP服务提供至少4G空闲内存。

1794020763844.png

编撰人:het