Kubernetes环境安装SuperMap AgentX Server

SuperMap AgentX Server支持在Kubernetes环境中快速部署。Kubernetes简称K8s，是一个开源的，用于自动化部署、扩展和管理云平台中多个主机上的容器化的应用，通过多节点集群架构实现资源的高效调度与高可用 。

注意：

本文档主要针对在线环境提供安装部署指导，如您的环境为离线环境，请联系技术支持人员提供帮助。

正式安装前，计算机需要开放30490、30080、30443、30190、30195、30090和9183端口。如果您是使用阿里云ECS服务器，您需要将以上端口添加到安全组规则中。

  • 30490端口：AgentX网关端口
  • 30080端口：Keycloak HTTP协议端口
  • 30443端口： Keycloak HTTPS协议端口 
  • 30190端口：SuperMap iPortal访问端口
  • 30195端口：SuperMap iPortal代理服务访问端口
  • 30090端口：SuperMap iServer访问端口
  • 9183端口： 许可中心端口

前置条件

Kubernetes安装

需具备版本在1.20及以上Kubernetes环境，您可以参考安装Kubernetes进行安装。

NFS Server安装

需安装好NFS存储，您可以参考安装NFS存储进行安装。如果已有 NFS 服务器，可以跳过此步。

注意：安装完成后需检查NFS挂载权限配置

 查看/etc/exports文件，参考权限配置如下：
  /home/supermap/nfs-volume *(rw,sync,no_subtree_check,no_root_squash,insecure)

安装包准备

前往技术资源中心获取下载SuperMap AgentX Server Kubernetes版本安装包。

配置文件修改

将SuperMap AgentX Server产品安装包放置到Kubernetes Master节点机器的拟安装路径下，根据实际情况修改如下配置文件：

文件名称 文件说明
values.yaml 环境变量配置文件
cfg/agentx-base-config.yaml AgentX配置文件，包含模型、本地化等通用配置

values.yaml配置文件说明

 ...

 

#存储配置
  storage:
    storageClass:
      className: "agentx-nfs-storage"
      nfs:
        server: ""
        path: ""

  ...

 

# 网络配置
network:
  bindAddress: ""

 

#管理员账户配置

account: 
  adminUsername: agentx_admin
  adminPassword: agentx@2025

 

# 数据库配置
postgres:
  username: "agentx"
  password: "agentx_2025"

 

# 认证服务配置
keycloak:
  adminUser: "admin"
  adminPassword: "agentx@2025"

 

# GIS 服务配置

iserver:
  provider: "Built-in"       #可选值： Built-in | External | None
  username: "agentx_admin"
  password: "agentx@2025"
  rootUrl: "http://agentx-iserver:8090/iserver"
  token: ""

 

# GIS 门户配置
iportal:
  provider: "Built-in"       #可选值： Built-in | External | None
  username: "agentx_admin" 
  password: "agentx@2025"
  rootUrl: "http://agentx-iportal:8190/iportal"
  token: ""

...

 

# 工作流式智能体配置（MapStudio AI制图助理、WebGPA AI建模助理、代码自定义工作流式智能体）
workflow:
  enabled: true

# 低代码搭建工作流式智能体配置
workflowStudio:
  enabled: true

# 知识问答式智能体和自主规划式智能体配置
autonomousAndChatflow:
  enabled: true

您需要根据实际情况，修改上述values.yaml文件中列出的配置项，对应的配置项说明如下：

  • storage.storageClass.className: 存储配置（使用Ceph存储或Longhorn存储时必填），支持填写Ceph存储或Longhorn存储对应的StorageClass名称。填写后，无需配置下述nfs服务器地址和路径；如果您的存储方式为NFS服务器，则无需配置此项。

  • storage.storageClass.nfs.server：存储配置（使用NFS存储时必填），配置NFS服务器地址，支持填写IP或域名。

  • storage.storageClass.nfs.path: 存储配置（使用NFS存储时必填），配置NFS服务器的挂载根路径，NFS Server提供挂载的路径默认是根路径（/），请根据您安装的NFS情况来填写，如果使用SuperMap提供的NFS离线安装包安装NFS，则此处地址填写为：/opt/nfs_data。

  • network.bindAddress: 必填，网关绑定的主机地址，即对外暴露的统一地址，公有云环境需填写弹性公网IP。

  • account.adminUsername：产品包中内置的SuperMap AgentX Server管理员初始用户名，可按需修改；

  • account.adminPassword：SuperMap AgentX Server管理员账户的初始密码，为确保系统安全，建议您在首次启动前进行修改；

  • postgres.username：产品包中内置了PostGreSQL数据库，用于结构化数据的存储。内置PostGreSQL数据库账号的初始用户名，可按需修改；

  • postgres.password：内置 PostGreSQL 数据库账号的初始密码，为确保系统安全，建议您在首次启动前进行修改，需要注意的是PostGreSQL 数据库密码禁止使用“@”符号。

  • keycloak.adminUser：内置Keycloak认证服务的管理员账户，可按需修改；

  • keycloak.adminPassword：内置Keycloak认证服务的管理员密码，可按需修改；

  • iserver.username：产品包中内置的SuperMap iServer的管理员初始用户名，可按需修改；

  • iserver.password：SuperMap iServer管理员账户的初始密码，为确保系统安全，建议您在首次启动前进行修改；

  • iportal.username：产品包中内置的SuperMap iPortal 的管理员初始用户名，可按需修改；

  • iportal.password：SuperMap iPortal 管理员账户的初始密码，为确保系统安全，建议您在首次启动前进行修改；
  • workflow.enabled：控制是否启用工作流式智能体，包括MapStudio AI制图助理、WebGPA AI建模助理以及代码自定义工作流式智能体。默认为 true，表示开启；若设置为 false，则关闭该智能体。注意：WebGPA AI 建模助理中的“问答助理”功能依赖知识问答式智能体（由 autonomousAndChatflow.enabled 控制）。若需在 WebGPA 中使用问答助理，请确保同时开启 autonomousAndChatflow.enabled 开关。
  • workflowStudio.enabled：控制是否启用低代码搭建工作流式智能体。默认为 true，表示开启；若设置为 false，则关闭该智能体。
  • autonomousAndChatflow.enabled: 控制是否启用知识问答式智能体和自主规划式智能体。默认为 true，表示开启；若设置为 false，则关闭该智能体。

SuperMap AgentX Server及相关产品的内置账户信息盘点如下，请于启动前在values.yaml配置文件中完成账户密码的修改：

产品名称 初始用户名 初始密码
SuperMap AgentX Server agentx_admin agentx@2025
SuperMap iPortal agentx_admin agentx@2025
SuperMap iServer agentx_admin agentx@2025
PostGreSQL 数据库 agentx agentx_2025
Keycloak 认证服务 admin agentx@2025

cfg/agentx-base-config.yaml配置文件说明

#大模型(llm)配置，允许多个模型

llm:

  BASIC_MODEL:

    base_url: https://ark.cn-beijing.volces.com/api/v3

    model: "doubao-1-5-pro-32k-250115"

    api_key: xxx

 

   REASONING_MODEL:

    base_url: https://dashscope.aliyuncs.com/compatible-mode

    model: "qwen3-32b"

    api_key: xxx

 

  EMBEDDING_MODEL:

    base_url: https://ark.cn-beijing.volces.com/api/v3

    model: "Doubao-embedding"

    api_key: xxx

    max_tokens: 8192
       
  RERANK_MODEL:

    base_url: http://172.16.168.199:8008/v1

    model: "BAAI/bge-reranker-v2-m3"

    api_key: EMPTY

 

#使用阿里云在线的重排序模型时，需额外配置llm_factory参数，配置示例如下：
   # RERANK_MODEL:
   # base_url: https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank
   # model: "qwen3-rerank"
   # llm_factory: "Tongyi-Qianwen"
   # api_key: sk-*******

 

...

 


您需要根据实际情况，修改上述agentx-base-config.yaml文件中列出的配置项，对应配置项说明如下：

模型参数 模型类别 适用的智能体 是否必选
BASIC_MODEL     大语言模型   知识问答式智能体 是。注意：WebGPA AI建模助理需配置带Function Call功能的大语言模型
自主规划式智能体
MapStudio AI制图助理
WebGPA AI建模助理
代码自定义工作流式智能体
EMBEDDING_MODEL  词嵌入模型     知识问答式智能体 是
WebGPA AI建模助理
REASONING_MODEL     大语言模型（带推理功能）     自主规划式智能体 否，如需开启深度思考功能，可配置该类模型
RERANK_MODEL   重排序模型    知识问答式智能体 否，如需进一步提升答案精准度，可配置该类模型
  • BASIC_MODEL：大语言模型的配置信息
    • base_url：大语言模型服务的地址，如使用本地部署的模型服务，需填写的模型服务地址示例格式为： http://<ip地址>:port/v1；如使用在线大模型云服务，模型服务的地址格式请参考对应厂商的官方文档说明；
    • model：大语言模型服务的名称，如使用本地部署的模型服务，可前往http://<ip地址>:port/v1/models查询模型名称的标准写法：
    • api_key：大语言模型服务的密钥；
  • EMBEDDING_MODEL：词嵌入模型的配置信息，词嵌入模型在知识问答式智能体中用于知识库向量化构建、知识检索与匹配：
    • base_url：词嵌入模型服务的地址，地址填写说明同上；
    • model：词嵌入模型服务的名称，名称填写说明同上；
    • api_key：词嵌入模型服务的密钥；
    • max_tokens：模型允许的最大token数，默认值为8192，可按需设置。当实际的token数超过模型允许的最大值时会导致模型解析失败。
  • REASONING_MODEL：带推理功能的大语言模型的配置信息，在自主规划式智能体中可用于深度思考，可与BASIC_MODEL使用同一个模型：
    • base_url：推理模型服务的地址，地址填写说明同上；
    • model：推理模型服务的名称，名称填写说明同上；
    • api_key：推理模型服务的密钥；
  • RERANK_MODEL：重排序模型的配置信息，在知识问答式智能体中，重排序模型可以根据查询与文档之间的相关性程度对候选结果进行重新排列，将最具相关性的资源优先呈现给用户：
    • base_url：重排序模型服务的地址，地址填写说明同上；
    • model：重排序模型服务的名称，名称填写说明同上；
    • api_key：重排序模型服务的密钥。
    • llm_factory：阿里云开源的大语言模型微调框架，使用阿里云在线的重排序模型 qwen3-rerank 和 gte-rerank-v2 时，需增加该参数，并配置为Tongyi-Qianwen。阿里云在线重排序模型的详细介绍请参考：https://help.aliyun.com/zh/model-studio/text-rerank-api

产品启动

启动SuperMap AgentX Server

完成文件配置后，在values.yaml文件所在路径下执行以下命令，启动SuperMap AgentX Server服务：

chmod +x startup.sh && ./startup.sh

配置许可

安装完成之后，还需要导入许可才能使用，具体请参见：许可配置说明

访问SuperMap AgentX Server

SuperMap AgentX Server服务启动后，直接访问 http://<ip地址>:30490，即可进入AgentX产品首页，该页面整合了三种智能体、各类MCP服务以及管理服务的访问地址，可按需访问：

图：SuperMap AgentX Server产品首页

产品卸载

如果您要卸载SuperMap AgentX Server服务，只需前往values.yaml文件所在路径，按需执行以下命令即可：

  • 卸载但保留数据 

./shutdown.sh 

  • 完全卸载

./shutdown.sh -v 

产品升级

如果您需要进行产品升级，替换旧的产品包，请按照如下操作进行：

  1. 获取最新的AgentX安装包，放置于合适的目录并解压；
  2. 将旧包中做过修改的配置文件(如values.yaml、agentx-base-config.yaml等)手动同步到新包中；
    注意：旧包的values.yaml文件中必须同步到新包的配置项如下，其余配置根据实际情况修改即可：

    storage.storageClass.className
    storage.storageClass.nfs.server
    storage.storageClass.nfs.path
    network.bindAddress

  3. 若您处于联网环境，可直接跳过此步。若您处于无网络环境，需参照镜像准备中的步骤更新镜像；
  4. 在新产品包的 values.yaml 文件所在路径下执行以下命令，即可自动拉取相关镜像，启动服务：
     ./startup.sh
注意：Helm 默认升级机制仅会重启配置项发生变更的服务，若存在镜像更新或 ConfigMap 内容更新的场景，引用该 ConfigMap 的 Pod 不会自动重启，需执行下列操作使更新生效：
检查 values.yaml 文件中 global.imagePullPolicy 配置项的值是否为 Always：
  • 若该值不为 Always，需修改为 Always 后，重新启动服务；
  • 若该值已为 Always，执行对应命令重启 Pod：
      重启指定命名空间下所有 Deployment 对应的 Pod：

      kubectl rollout restart deployment -n <namespace>

      仅重启指定 Deployment 对应的 Pod（将 <name> 替换为目标 Deployment 名称：

      kubectl rollout restart deployment/<name> -n <namespace>