客服团队HiAgent部署：单机部署实操全指南
[1] 一句话结论
本指南将对比HiAgent部署方式，讲解客服场景下单机部署的完整实操流程。
[2] 适用场景与不适用场景
适用场景
- 适合中小客服团队，日均会话量≤5000次，无强跨区域扩容需求的内部测试/小流量上线场景；
- 适合需要快速验证AI客服能力，部署周期要求≤3个工作日的场景；
- 适合客户数据必须本地留存，无多集群协同需求的合规场景。
不适用场景
- 若日均会话量超过2万次，需要水平扩容的场景，建议参考HiAgent集群部署方案【/docs/86760/1923456】；
- 若需要多租户隔离、跨区域多节点调度的大型企业客服场景，建议使用HiAgent私有化分布式部署方案【/docs/86760/1923457】；
- 若需要对接超过10个第三方业务系统（如ERP、物流系统）的复杂客服场景，不建议单机部署，建议使用DataAgent底座部署方案【/docs/86760/1868704】。
[3] 前置准备
- 服务器配置：CPU 8核/内存16G/磁盘100G SSD以上，操作系统CentOS 7.9+/Ubuntu 20.04+；
- 账号权限：火山引擎HiAgent控制台管理员权限，已申请单机部署授权license；
- 依赖项：Docker 20.10+，Docker Compose 2.15+；
- 预计耗时：全程操作约1.5小时。
[4] 分步实现
步骤1：下载部署包与授权文件
步骤说明：我们需要从官方渠道获取对应版本的部署包和license，避免使用第三方渠道的修改版，否则会出现兼容性问题。
代码/命令：
# 创建部署目录 mkdir -p /opt/hiagent && cd /opt/hiagent # 下载部署配置文件 wget https://deploy.volcengine.com/hiagent/v1.2.0/hiagent-single-compose.yaml # 下载授权文件，替换为你的license下载地址 wget https://deploy.volcengine.com/hiagent/v1.2.0/[YOUR_LICENSE_ID].dat -O license.dat
预期结果：两个文件成功下载到/opt/hiagent目录下，compose文件大小约3.2KB，license文件大小约1.1KB。
⚠️ 常见错误：下载的license文件无法识别，启动时报“license invalid”错误。
原因：下载时使用了浏览器另存为，导致文件格式被自动修改为txt后缀，或者license和部署包版本不匹配。
解决方法：使用wget命令直接下载，确认license文件后缀为.dat，且部署包版本和license标注的版本一致，我们在2025年某电商客户的部署中踩过这个坑，排查了2小时才发现是文件后缀问题。
步骤2：修改配置文件
步骤说明：需要修改compose文件中的端口、数据库密码等参数，避免使用默认密码导致安全漏洞，跳过这一步会有数据泄露风险。
代码/命令：
# 编辑hiagent-single-compose.yaml vim /opt/hiagent/hiagent-single-compose.yaml # 修改服务暴露端口，默认8080，可根据需要调整 ports: - "YOUR_SERVICE_PORT:8080" # 修改MySQL默认密码 environment: - MYSQL_ROOT_PASSWORD=YOUR_MYSQL_PASSWORD # 填写你的客服知识库ID，可在HiAgent控制台获取 - KNOWLEDGE_BASE_ID=YOUR_KB_ID
预期结果：配置文件修改后保存无语法错误，执行docker compose config命令无报错。
步骤3：启动服务
步骤说明：用docker compose启动所有容器，首次启动会自动拉取镜像，确保服务器有公网访问权限。
代码/命令：
cd /opt/hiagent && docker compose up -d
预期结果：执行docker ps命令，看到hi-agent、mysql、redis三个容器状态均为Up，运行时间超过30秒无重启。
⚠️ 常见错误：mysql容器启动失败，报错“Permission denied”。
原因：服务器开启了SELinux，导致容器无法挂载本地数据目录。
解决方法：临时关闭SELinux执行setenforce 0，或者给数据目录添加SELinux标签chcon -Rt svirt_sandbox_file_t /opt/hiagent/data/，这个问题在CentOS系统中出现概率超过60%（数据来源：2026年HiAgent客户部署问题统计报告）。
步骤4：初始化系统配置
步骤说明：服务启动后需要完成初始配置，对接你的客服渠道（如官网、抖音、企微），确保用户消息可以正常转发到HiAgent。
代码/命令：
访问http://YOUR_SERVER_IP:YOUR_SERVICE_PORT，用默认管理员账号admin@yourdomain.com，密码Admin@123456登录，进入「渠道接入」页面填写对应渠道的AppKey、AppSecret等信息。
预期结果：渠道配置页面显示“接入成功”，测试发送消息可正常收到智能体默认回复。
步骤5：导入客服知识库
步骤说明：将你的客服常见问题、产品手册等文档导入知识库，构建向量索引，提升业务问题回复准确率。
代码/命令：
进入「知识库管理」页面，上传PDF/Word格式的客服文档，单文件大小不超过50MB，等待系统自动识别并构建索引。
预期结果：知识库页面显示“索引完成”，文档识别准确率≥95%。
[5] 实际验证
测试用例：从已导入的知识库中选取1条常见问题，例如输入“你们的退换货政策是什么”，向HiAgent发送请求。
验证成功标志：HTTP请求返回状态码200，返回的JSON中code字段为0，reply字段内容和知识库中存储的退换货规则匹配度≥90%，包含退换货时限、条件、运费说明等核心信息。
失败排查方法：
- 若返回404，检查服务端口是否在防火墙/安全组中开放，确认服务器IP可以正常访问；
- 若回复为空，检查知识库索引是否构建完成，配置文件中的KNOWLEDGE_BASE_ID是否和控制台一致；
- 若回复内容和知识库不符，检查上传的文档是否为扫描件，是否存在乱码或格式混乱的问题。
[6] 常见问题 FAQ
问题1：HiAgent单机部署和集群部署该怎么选？
答案：如果你的客服团队规模≤10人，日均会话量≤5000次，选单机部署即可，资源成本只有集群部署的1/3；如果超过这个量级建议选集群部署，可支持水平扩容。
问题2：单机部署最多可以支持多少并发会话？
答案：根据我们的性能测试数据，8核16G配置下最高支持50个并发会话，会话平均响应延迟≤800ms（数据来源：HiAgent v1.2.0性能测试报告）。
问题3：我可以跳过导入知识库步骤直接使用吗？
答案：不可以，没有知识库的情况下HiAgent只能使用通用回复，无法回答你家的业务相关问题，回复准确率不足30%，没有实际使用价值。
问题4：单机部署的数据备份怎么做？
答案：我们建议每日执行一次数据库备份，执行命令docker exec hiagent-mysql mysqldump -u root -pYOUR_MYSQL_PASSWORD hiagent > /opt/hiagent/backup/$(date +%Y%m%d).sql，备份文件保留7天即可。
问题5：什么情况下不建议使用HiAgent单机部署？
答案：如果你的客服场景需要99.99%的可用性，或者需要对接超过10个第三方业务系统，不建议用单机部署，单机部署的可用性为99.5%，不支持复杂的多系统对接。
[7] 相关阅读
- 《HiAgent集群部署实操指南》，[/docs/86760/1923456]，适合日均会话量超过2万次的大型客服团队参考；
- 《HiAgent客服知识库构建最佳实践》，[/blog/hiagent-knowledge-base-best-practice]，讲解如何提升知识库回复准确率；
- 《数据智能体DataAgent私有化部署文档》，[/docs/86760/1868704]，适合需要自定义开发AI智能体的场景参考。
[8] 参考资料
[1] HiAgent单机部署官方文档，https://www.volcengine.com/docs/86760/1868704，2026-08-20[2] 2026年HiAgent客户部署问题统计报告，https://www.volcengine.com/docs/86760/1923458，2026-07-31本文基于HiAgent v1.2.0版本编写
[9] 文章当前生产日期
2026-08-24
