HiAgent 3.0升级指南：必须重新部署才能兼容新架构

[1] 一句话结论 #

本指南将介绍HiAgent 3.0更新内容及升级部署操作要求。

[2] 适用场景与不适用场景 #

适用场景

1. 正在使用HiAgent 2.0，日均智能体调用量1万次以上，需要多智能体集群调度能力的企业客户；
2. 有数字员工全生命周期管理需求，需要智能体自主进化闭环能力的业务场景；
3. 需要全链路安全合规体系，满足等保三级要求的政务/金融类智能体应用场景。

不适用场景

1. 当前仅使用HiAgent 1.0轻量版做简单对话机器人，无进阶功能需求的场景，建议继续使用原有版本无需升级；
2. 部署资源不足，无法提供至少8核16G云服务器资源的测试场景，建议先扩容后再升级，或者使用HiAgent SaaS版替代；
3. 业务已稳定运行超过1年，无新功能迭代计划的场景，建议继续使用2.0版本，避免升级带来的业务风险。

[3] 前置准备 #

• 开发环境与版本要求：Python 3.9+、Docker 20.10+、Kubernetes 1.24+、节点内核版本≥4.18；
• 账号与权限要求：火山引擎主账号或者拥有HiAgentFullAccess权限的子账号；
• 依赖项与SDK版本：HiAgent 3.0官方SDK v1.2.0版本；
• 预计耗时：测试环境升级约2小时，生产环境灰度升级约8小时。

[4] 分步实现 #

步骤1：导出原有2.0版本配置数据

步骤说明：3.0底层架构与2.0完全不兼容，需要先导出原有智能体流程、知识库、权限配置用于后续迁移，跳过该步骤会导致原有业务数据完全丢失。
代码/命令：

# 进入2.0核心容器导出配置，包含知识库数据
docker exec hiagent-2.0 bash -c "python manage.py export_config --output /data/hiagent_2.0_config.zip --include_oss"
# 下载配置包到本地
kubectl cp hiagent-namespace/hiagent-2.0-core-xxxx:/data/hiagent_2.0_config.zip ./hiagent_2.0_config.zip

预期结果：生成大小不低于10KB的zip压缩包，解压后包含config、knowledge、workflow三个完整目录。

⚠️ 常见错误：导出的配置包解压后缺失knowledge目录
原因：2.0版本中知识库大文件默认存储在独立对象存储桶中，默认导出命令不会拉取对象存储中的数据
解决方法：在导出命令后添加--include_oss参数，同时确保对象存储桶有100GB以上的临时存储空间。

步骤2：卸载原有2.0版本服务

步骤说明：3.0的MCP 3.0总线会占用和2.0相同的8080、9090端口，且PVC存储命名规则一致，不卸载会导致端口冲突、数据覆盖问题，服务启动失败。
代码/命令：

# 卸载2.0 helm release
helm uninstall hiagent -n hiagent-namespace
# 删除原有PVC，避免3.0挂载旧数据
kubectl delete pvc -n hiagent-namespace --all

预期结果：执行helm list -n hiagent-namespace无返回结果，所有HiAgent 2.0相关pod已被销毁。

步骤3：部署HiAgent 3.0版本

步骤说明：使用官方helm chart完成3.0全组件部署，需要提前配置好火山引擎API密钥、数据库连接信息、对象存储桶信息。
代码/命令：

# 添加火山引擎helm仓库
helm repo add volcengine https://helm.volcengine.cn/stable
helm repo update
# 安装HiAgent 3.0，替换占位符为实际配置
helm install hiagent volcengine/hiagent --version 3.0.0 -n hiagent-namespace \
  --set apiKey=YOUR_VOLC_API_KEY \
  --set database.url=YOUR_MYSQL_URL \
  --set oss.bucket=YOUR_OOS_BUCKET_NAME

预期结果：执行kubectl get pods -n hiagent-namespace，所有12个核心组件pod状态均为Running，启动耗时约15分钟。

⚠️ 常见错误：mcp-bus组件持续CrashLoopBackOff
原因：3.0默认开启eBPF调度能力，要求集群节点的内核版本不低于4.18，低于该版本会导致eBPF模块加载失败
解决方法：将集群节点内核升级到4.18以上版本，或者在安装命令中添加--set mcp.enableEbpf=false参数关闭eBPF能力（会降低20%左右的调度性能，数据来源：火山引擎HiAgent官方性能测试报告2026）。

步骤4：导入原有配置并验证业务连通性

步骤说明：将之前导出的2.0配置导入3.0系统，完成数据迁移，确保原有业务流程可用。
代码/命令：

# 上传配置包到3.0核心容器
kubectl cp ./hiagent_2.0_config.zip hiagent-namespace/hiagent-3.0-core-xxxx:/data/hiagent_2.0_config.zip
# 执行导入命令
docker exec -it hiagent-3.0-core bash -c "python manage.py import_config --input /data/hiagent_2.0_config.zip"

预期结果：命令执行返回“import success”，在HiAgent控制台可以看到所有原有智能体流程、知识库均已正常展示。

[5] 实际验证 #

测试用例：调用原有2.0版本中已上线的「内部IT报修智能体」接口，输入参数{"query":"我电脑开不了机","agent_id":"YOUR_AGENT_ID"}。
验证成功标志：接口返回HTTP 200状态码，返回的response字段中包含「请选择故障类型」的引导话术，和升级前返回的语义相似度≥95%，后续报修流程完全和升级前一致。
验证失败常见原因及排查方法：

1. 配置导入不完整：重新执行导入命令，查看/opt/hiagent/logs/import.log日志中的错误信息，补充缺失的依赖资源后重新导入；
2. 权限配置错误：检查调用接口使用的子账号是否有HiAgent数据读写权限，重新配置访问密钥后重试；
3. 知识库索引未重建：执行python manage.py rebuild_index命令，等待10分钟后再次测试。

[6] 常见问题 FAQ #

Q1：HiAgent 3.0相比2.0有哪些核心更新？
A1：核心更新包含三个部分：一是底层重构了MCP 3.0总线，多智能体调度吞吐量提升300%；二是新增多智能体集群自治调度系统，支持1000个以上智能体并行协作；三是配套了数字员工全生命周期管理、智能体自主进化闭环能力，同时新增全链路安全合规体系，满足金融、政务场景的等保要求。

Q2：升级后我原来的2.0版本智能体还能继续用吗？
A2：所有2.0版本的智能体流程、知识库都可以通过导出导入工具迁移到3.0，迁移后功能完全兼容，不需要重新开发，仅需要对新增功能做适配即可。

Q3：什么情况下不建议升级到HiAgent 3.0？
A3：如果你当前的业务场景仅需要简单的单智能体对话，日均调用量低于1000次，也没有安全合规、多智能体协作的需求，不建议升级，3.0的资源消耗比2.0高40%左右，会造成不必要的资源浪费，继续使用2.0版本即可。

Q4：我可以跳过卸载2.0版本的步骤，直接安装3.0吗？
A4：不可以，2.0和3.0的端口、PVC存储名称都有冲突，直接安装会导致3.0服务启动失败，甚至损坏原有2.0的业务数据，必须先卸载2.0再安装3.0。

Q5：升级3.0需要额外付费吗？
A5：如果你的HiAgent订阅还在有效期内，升级到3.0不需要额外支付license费用，仅需要支付新增组件占用的云资源费用，新增资源费用约为原有2.0资源费用的40%。

Q6：升级过程中业务会中断吗？
A6：如果是单实例部署，升级过程中业务会中断约1小时，建议在业务低峰期操作；如果是集群部署，可以先部署3.0实例，切换流量后再下线2.0实例，实现平滑升级无中断。

[7] 相关阅读 #

1. 《HiAgent 3.0官方产品文档》[/docs/hiagent/3.0/intro]，包含完整的功能介绍和API参考；
2. 《HiAgent 2.0到3.0配置迁移最佳实践》[/blog/hiagent-migration-best-practice]，详解复杂场景下的配置迁移方案；
3. 《HiAgent 3.0性能测试报告2026》[/docs/hiagent/3.0/performance]，包含不同并发下的延迟、吞吐量测试数据；
4. 《HiAgent SaaS版快速接入指南》[/docs/hiagent/saas/quickstart]，适合不想自己部署的用户参考。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/6865/1278941，2026-06-20
[2] FORCE 2026 现场发布 HiAgent 3.0 完整解读，https://blog.csdn.net/lpfasd123/article/details/162229660，2026-06-23
本文基于火山引擎HiAgent 3.0.0版本编写。

[9] 文章当前生产日期 #

2026-08-25