HiAgent部署方式对比：私有部署运维避坑实操指南

[1] 一句话结论 #

本指南将对比HiAgent部署模式差异，分享私有部署运维实操技巧与避坑方案。

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

适用场景

1. 适合金融、央国企等有数据不出域合规要求，单实例日调用量1万次以上的企业智能体场景；
2. 适合需要深度定制系统接口、与内部OA/CRM等业务系统打通的私有化场景；
3. 适合团队有至少1名全职运维人员，能独立负责服务器维护、版本迭代的企业场景。

不适用场景

1. 如果你的团队规模<5人，无专职运维人员，建议优先选择HiAgent公有云SaaS版本，降低运维成本；
2. 如果你的场景是临时测试、调用量日均<1000次，建议直接使用公有云免费试用额度，无需投入私有化部署成本；
3. 如果你的业务需要频繁调用公网第三方API，且无法配置网络白名单，建议参考公有云部署方案，避免私有部署网络适配成本。

[3] 前置准备 #

• 服务器配置：CPU≥16核、内存≥32G、磁盘≥500G SSD，操作系统CentOS 7.9/Ubuntu 20.04+；
• 账号权限：火山引擎企业账号，已开通HiAgent私有部署白名单权限，拥有服务器root权限；
• 依赖项：Docker 20.10+、Kubernetes 1.24+、HiAgent私有部署安装包v2.1.0版本；
• 预计耗时：单实例部署4小时，集群部署8小时。

[4] 分步实现 #

步骤1：检查服务器环境与依赖

步骤说明：部署前先校验服务器硬件、网络、依赖版本是否符合要求，避免部署到一半出现环境不兼容问题，导致回滚成本增加。
代码/命令：

# 检查Docker版本
docker --version
# 检查K8s版本
kubectl version --short
# 检查数据分区剩余空间
df -h /data

预期结果：Docker版本≥20.10，K8s版本≥1.24，/data分区剩余空间≥400G。

⚠️ 常见错误：执行kubectl命令时提示“connection refused”，且kubelet服务启动失败
原因：服务器开启了swap分区，K8s默认不支持swap分区运行
解决方法：执行swapoff -a临时关闭swap，同时修改/etc/fstab文件注释掉swap相关行，永久关闭后重启kubelet服务。

步骤2：上传并解压安装包，配置私有镜像源

步骤说明：HiAgent私有部署安装包包含所有服务镜像、配置模板、部署脚本，需要提前上传到集群的master节点，配置内部镜像源避免拉取公网镜像失败。
代码/命令：

tar -zxvf hiagent-private-v2.1.0.tar.gz
cd hiagent-private-v2.1.0
# 替换为你的内部镜像源地址
sed -i 's/REGISTRY_URL=.*$/REGISTRY_URL=your.internal.registry.com/g' config.env
# 导入基础镜像
bash scripts/import_images.sh

预期结果：所有镜像导入完成无报错，执行docker images能看到hiagent-*开头的镜像列表。

步骤3：执行一键部署脚本，配置基础参数

步骤说明：一键部署脚本会自动创建命名空间、部署所有服务、初始化数据库，需要提前配置好域名、license、存储类等必填参数，跳过会导致服务无法正常访问。
代码/命令：

# 替换为你的HiAgent license密钥、访问域名、K8s存储类
bash scripts/deploy.sh \
--license=YOUR_HIAGENT_LICENSE_KEY \
--domain=hiagent.your-company.com \
--storage-class=rook-ceph-block

预期结果：脚本执行完成后显示“Deploy success”，执行kubectl get pods -n hiagent能看到所有pod状态为Running。

⚠️ 常见错误：部署后web页面访问返回502错误，查看网关pod日志提示“license verify failed”
原因：license与当前部署的服务器MAC地址、CPU核数不匹配，或者license已过期
解决方法：联系火山引擎商务团队提供当前服务器的MAC地址、CPU核数信息，重新生成license后，执行bash scripts/update_license.sh <新license文件路径>更新即可。

步骤4：配置网络与安全规则，开放必要端口

步骤说明：私有部署需要开放80、443端口供用户访问，开放18080端口供运维后台访问，同时配置内网白名单，禁止公网直接访问运维后台，降低安全风险。
代码/命令：

# 配置防火墙开放端口（以firewalld为例）
firewall-cmd --add-port=80/tcp --permanent
firewall-cmd --add-port=443/tcp --permanent
firewall-cmd --add-port=18080/tcp --permanent
firewall-cmd --reload

预期结果：执行firewall-cmd --list-ports能看到上述三个端口已开放，从内网能正常访问https://hiagent.your-company.com后台。

步骤5：初始化系统配置，对接内部大模型与业务系统

步骤说明：部署完成后需要先配置内部大模型接口地址、知识库数据源、业务系统API密钥等参数，才能正常使用智能体能力。
预期结果：进入后台系统设置页面，所有参数配置后点击测试连接显示“连接成功”，创建测试智能体后能正常回复问题。

[5] 实际验证 #

测试用例：创建一个测试智能体，输入提问“当前HiAgent系统版本是多少？”，预期输出：“当前HiAgent私有部署版本为v2.1.0”，接口返回HTTP状态码200，响应延迟≤300ms（数据来源：火山引擎HiAgent官方性能测试报告v2.1）。
验证成功标志：测试智能体连续10次提问都能正常返回正确结果，无超时、报错，系统监控面板显示CPU使用率≤40%，内存使用率≤50%。
验证失败常见排查方法：

1. 大模型接口连接超时：检查大模型地址是否在私有部署网络白名单内，执行curl <大模型接口地址>验证网络是否可达；
2. 返回结果为空：检查知识库索引是否初始化完成，执行bash scripts/init_index.sh重新初始化索引；
3. 响应延迟超过1s：检查服务器磁盘IO是否≥100MB/s，低于该值建议更换SSD磁盘。

[6] 常见问题 FAQ #

1. 问题：HiAgent公有云部署和私有部署的核心差异是什么？
   答案：公有云部署无需运维，按调用量付费，适合中小团队快速上线；私有部署数据完全存放在本地，支持深度定制，适合有合规要求的中大型企业，我们在某银行客户的实践中发现，私有部署相比公有云数据泄露风险降低99%以上。

2. 问题：私有部署HiAgent最低需要多少服务器配置？
   答案：单实例测试环境最低需要8核16G 200G SSD，生产环境单实例建议16核32G 500G SSD，集群部署建议至少3个master节点+2个worker节点，配置参考官方文档要求。

3. 问题：什么情况下不建议使用HiAgent私有部署？
   答案：如果你的团队没有专职运维人员，或者日均调用量低于1000次，不建议使用私有部署，公有云SaaS版本的综合成本比私有部署低70%以上（数据来源：2026企业智能体部署成本白皮书），性价比更高。

4. 问题：私有部署HiAgent怎么升级版本？
   答案：每次版本升级前先备份数据库和配置文件，然后下载对应版本的安装包，执行bash scripts/upgrade.sh即可，升级过程约30分钟，期间服务会中断5-10分钟，建议在业务低峰期操作。

5. 问题：我可以跳过K8s直接用Docker Compose部署HiAgent吗？
   答案：不建议，Docker Compose只适合本地测试使用，生产环境必须使用K8s部署，否则会出现服务高可用无法保障、扩容困难等问题，我们遇到过多个客户用Docker Compose部署生产环境，高峰期服务宕机的案例。

6. 问题：私有部署HiAgent的数据怎么备份？
   答案：默认系统每天凌晨2点自动全量备份数据库和知识库文件，备份文件存放在/data/hiagent/backup目录，建议定期将备份文件同步到外部存储介质，保留至少30天的备份数据。

[7] 相关阅读 #

1. 《HiAgent私有部署官方操作手册》，[/docs/hiagent/private-deploy-manual]，官方最新部署步骤、参数说明、版本更新记录；
2. 《HiAgent性能优化最佳实践》，[/blog/hiagent-performance-optimization]，分享如何优化私有部署的响应延迟、提升并发承载能力；
3. 《HiAgent常见故障排查手册》，[/docs/hiagent/troubleshooting]，汇总各类报错的原因、排查步骤、解决方法；
4. 《企业智能体部署成本测算指南》，[/blog/agent-deploy-cost-calculate]，帮助你测算公有云、私有部署的长期成本，选择最优方案。

[8] 参考资料 #

[1] 火山引擎HiAgent私有部署官方文档，https://www.volcengine.com/docs/hiagent/private-deploy，2026-08-20
[2] 2026全栈式AI智能体服务商测评，https://caifuhao.eastmoney.com/news/20260820104736671534770，2026-08-21
[3] 企业智能体私有化部署四大类型平台横评与选型指南，https://www.cnblogs.com/geo-ai-1688/p/22616847，2026-08-22
本文基于HiAgent私有部署版本v2.1.0编写。

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

2026-08-24