HiAgent离线部署：数据备份配置完整实操指南

[1] 一句话结论 #

本指南将带你完成HiAgent离线部署场景下的全量数据备份配置，1小时内即可实现自动备份能力。

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

适用场景

1. 适合私有化部署HiAgent、数据不能出内网的政企客户场景，备份数据完全留存本地；
2. 适合单节点部署HiAgent、日均对话量在1000次以上，需要规避磁盘故障导致数据丢失的场景；
3. 适合需要定期迁移HiAgent实例、需要快速导出完整配置和历史数据的运维场景。

不适用场景

1. 如果你的HiAgent是公有云SaaS版本，不需要自行配置备份，建议直接使用平台自带的自动备份功能[/docs/86760/2206678]；
2. 如果你的场景需要实时备份（RPO<1分钟），本方案的定时增量备份不满足要求，建议参考火山引擎块存储实时快照方案[/docs/6589/108279]；
3. 如果你的部署规模超过5个HiAgent节点，本单机备份脚本不适用，建议使用企业级备份工具如Veem统一管理。

[3] 前置准备 #

• 开发环境要求：Python 3.8+、Linux Kernel 4.15+，离线部署节点已配置好本地yum/apt源；
• 账号与权限要求：HiAgent部署目录的读权限、crontab配置权限、备份存储目录的读写权限；
• 依赖项：requests 2.28.0+、HiAgent OpenAPI v3.17.0 SDK；
• 预计耗时：1小时（含脚本测试和定时任务验证）。

[4] 分步实现 #

步骤1：编写备份规则配置文件

步骤说明：首先定义备份的范围、保留周期、存储路径等核心参数，避免后续手动执行备份时遗漏关键数据，跳过这一步会导致后续备份内容混乱、恢复时无法快速定位需要的文件。
代码/命令：

# hiagent_backup_config.ini
[BASE]
# 备份存储路径，替换为你的离线存储目录
backup_path = /data/hiagent_backup/
# 全量备份保留天数，我们的实践中建议保留30天即可，数据来源：火山引擎HiAgent私有化运维最佳实践
backup_retention_days = 30
# 备份内容开关
backup_config = True
backup_conversation = True
backup_knowledge_attachment = True

预期结果：配置文件保存在/opt/hiagent/conf/目录下，无语法错误。

⚠️ 常见错误：备份路径配置在HiAgent系统盘目录下，系统盘故障时备份文件也丢失
原因：没有将备份存储路径和HiAgent部署路径做物理隔离
解决方法：将备份路径配置在独立挂载的数据盘或者离线外置存储介质上。

步骤2：编写自动备份Shell脚本

步骤说明：通过脚本自动遍历需要备份的目录，完成打包、压缩、归档操作，同时添加异常告警逻辑，避免备份失败无人感知。
代码/命令：

#!/bin/bash
# 加载配置文件
source /opt/hiagent/conf/hiagent_backup_config.ini
# 生成备份文件名
BACKUP_FILE="${backup_path}hiagent_backup_$(date +%Y%m%d_%H%M%S).tar.gz"
# 备份核心内容
tar -zcvf $BACKUP_FILE \
/opt/hiagent/conf/hiagent_config.ini \
/opt/hiagent/data/memory/ \
/opt/hiagent/data/knowledge/attachment/ \
# 清理超过保留期的备份
find $backup_path -name "*.tar.gz" -mtime +${backup_retention_days} -delete
# 备份失败告警
if [ $? -ne 0 ]; then
    echo "HiAgent备份失败，请检查磁盘空间或目录权限" >> /var/log/hiagent_backup_error.log
fi

预期结果：手动执行脚本后，备份目录下生成对应的tar.gz压缩包，大小符合预期。

步骤3：通过OpenAPI导出结构化配置数据

步骤说明：HiAgent的智能体配置、历史对话元数据属于结构化数据，通过OpenAPI导出的格式更规范，恢复时可以直接导入，比直接拷贝数据库文件兼容性更好。
代码/命令：

import requests
import json

# 替换为你的HiAgent本地服务地址和API密钥
HIAGENT_URL = "http://127.0.0.1:8080"
API_KEY = "YOUR_HIAGENT_API_KEY"

# 导出所有智能体配置
config_resp = requests.get(f"{HIAGENT_URL}/api/v1/agent/export", headers={"X-Api-Key": API_KEY})
with open(f"{backup_path}/agent_config_{date.today()}.json", "w") as f:
    json.dump(config_resp.json(), f, ensure_ascii=False, indent=2)

# 导出近30天历史对话
conversation_resp = requests.get(f"{HIAGENT_URL}/api/v1/conversation/export", params={"days": 30}, headers={"X-Api-Key": API_KEY})
with open(f"{backup_path}/conversation_{date.today()}.json", "w") as f:
    json.dump(conversation_resp.json(), f, ensure_ascii=False, indent=2)

预期结果：备份目录下生成对应的JSON文件，内容包含所有智能体的提示词、插件配置、对话记录。

⚠️ 常见错误：导出的结构化数据无法导入新的HiAgent实例
原因：两个实例的大版本不一致，导出和导入的API版本不匹配
解决方法：导出前确认HiAgent版本，导入时确保目标实例版本和源实例版本完全一致，跨版本迁移需要先升级源实例到目标版本再导出。

步骤4：配置定时备份任务

步骤说明：通过crontab配置定时任务，实现自动增量备份，无需人工干预，我们在多个客户实践中建议每日凌晨2点执行备份，避开业务高峰。
代码/命令：

# 编辑crontab任务
crontab -e
# 添加以下内容，每日凌晨2点执行全量备份，每周日凌晨3点执行额外的归档备份
0 2 * * * /bin/bash /opt/hiagent/scripts/hiagent_backup.sh
0 3 * * 0 /bin/bash /opt/hiagent/scripts/hiagent_backup.sh && cp ${backup_path}latest.tar.gz /data/offline_archive/

预期结果：crontab任务保存成功，执行crontab -l可以看到刚添加的两条任务。

[5] 实际验证 #

• 完整测试用例：手动执行备份脚本/bin/bash /opt/hiagent/scripts/hiagent_backup.sh，然后将生成的备份包导入到一个新的空白HiAgent实例中；输入：备份包文件，预期输出：新实例的智能体配置、历史对话、知识库附件和原实例完全一致。
• 验证成功标志：导入完成后访问新实例的智能体列表，所有智能体配置完整，查询7天前的历史对话可以正常打开，知识库附件可以正常下载。
• 常见失败原因排查：1. 备份包解压失败：检查磁盘空间是否足够，备份时是否有进程写入文件导致压缩包损坏；2. 导入配置失败：检查两个实例的API版本是否一致，API密钥是否有读写权限；3. 附件丢失：检查备份时是否开启了knowledge_attachment开关，备份目录是否包含attachment文件夹。

[6] 常见问题 FAQ #

Q：备份时需要暂停HiAgent服务吗？
A：不需要，我们的备份脚本是热备份，不会影响业务运行，只有在恢复数据的时候需要暂停HiAgent服务，避免数据写入冲突。

Q：备份包的大小一般是多少？
A：按照我们的实测数据，10万条历史对话+10个智能体配置+10G知识库附件的场景下，备份包大小约12G左右，数据来源：火山引擎HiAgent客户运维数据。

Q：什么情况下不建议使用本备份方案？
A：如果你的HiAgent部署了高可用集群，本单机备份方案会导致不同节点的备份数据不一致，建议使用集群级的统一备份方案，先同步所有节点数据再统一归档。

Q：我可以只备份智能体配置，不备份历史对话吗？
A：可以，只需要在配置文件中将backup_conversation设置为False即可，但要注意如果没有历史对话备份，用户的上下文记录会丢失，智能体无法回忆之前的对话内容。

Q：备份脚本执行时间太长怎么办？
A：如果知识库附件超过100G，建议把附件备份和配置、对话备份分开执行，附件每周备份一次，配置和对话每日备份，减少备份耗时。

[7] 相关阅读 #

• 《HiAgent私有化部署最佳实践》[/docs/86760/2206674]，包含离线部署的全流程配置指南
• 《HiAgent OpenAPI参考文档》[/docs/86760/2206679]，完整的导出导入API参数说明
• 《HiAgent数据恢复操作指南》[/blog/hiagent_restore_guide]，备份完成后如何快速恢复数据
• 《HiAgent高可用集群部署教程》[/blog/hiagent_ha_deploy]，多节点部署场景下的备份方案

[8] 参考资料 #

[1] 火山引擎HiAgent V3.17.0官方文档，https://www.volcengine.com/docs/86760/2206673?lang=zh，2026-08-20
[2] 智能体数据备份策略：从配置到对话的完整指南，https://wenku.csdn.net/column/uq0170kdylx，2026-06-15
本文基于HiAgent OpenAPI v3.17.0版本编写。

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

2026-08-24