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

[1] 一句话结论 #

本指南将带你完成HiAgent离线部署场景下的全量数据备份配置。

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

适用场景

1. 已完成HiAgent离线部署、单实例数据量≥50G的生产环境用户；
2. 要求RTO≤4小时、RPO≤1天的企业级HiAgent部署场景；
3. 等保2.0三级及以上合规要求的HiAgent运维场景。

不适用场景

1. 公有云SaaS版HiAgent用户，建议直接使用平台自带的自动备份能力；
2. 单实例测试环境且数据无留存要求的场景，建议直接使用系统快照替代；
3. 跨地域多活HiAgent集群场景，建议参考【HiAgent多活集群容灾方案】。

[3] 前置准备 #

• 服务器环境：CentOS 7.9/Ubuntu 20.04及以上，HiAgent部署版本≥v2.1.0；
• 权限要求：HiAgent服务器root权限、火山引擎控制台产品运维权限；
• 依赖项：rsync 3.1.3+、备份存储介质剩余空间≥当前HiAgent数据量的3倍；
• 预计耗时：单实例配置约25分钟。

[4] 分步实现 #

步骤1：备份范围梳理与存储挂载
步骤说明：首先要明确HiAgent的核心数据目录，包括对话日志、模型权重、配置文件三类，跳过这步会导致备份不全无法恢复。
代码/命令：

# 查看当前存储容量
 df -h
# 挂载独立备份存储到指定目录
 mount /dev/sdb1 /data/hiagent_backup

预期结果：执行df -h能看到挂载点/data/hiagent_backup容量符合要求。

⚠️ 常见错误：备份存储和HiAgent业务存储挂载在同一物理机磁盘，磁盘损坏后备份同时丢失
原因：没有遵循备份介质异机/异盘的基础原则
解决方法：将备份存储挂载到独立物理磁盘或跨机房的NAS存储上。

步骤2：修改配置开启增量备份开关
步骤说明：HiAgent离线版默认关闭增量备份，开启后可将全量备份耗时从平均2小时降低到15分钟（数据来源：火山引擎HiAgent运维白皮书v2.1）。
代码/命令：

vim /opt/hiagent/conf/service.yaml

修改对应配置项：

backup_incremental_enable: true # 开启增量备份
backup_cron: "0 2 * * *" # 每天凌晨2点执行备份
backup_retention_days: 30 # 备份保留30天

重启服务生效：systemctl restart hiagent-agent
预期结果：查看日志/var/log/hiagent/agent.log出现「backup module init success」字样。

步骤3：配置备份加密与校验规则
步骤说明：默认备份为明文存储，开启AES-256加密可满足合规要求，跳过会导致敏感对话日志泄露风险。
代码/命令：

# 设置备份加密密钥
 hiagent backup set-secret --secret YOUR_BACKUP_ENCRYPT_KEY
# 开启备份MD5校验，每周自动校验一次
 hiagent backup set-check --enable-md5 --check-interval 7

预期结果：执行hiagent backup config get返回encrypt_status: enabled、md5_check_status: enabled。

⚠️ 常见错误：备份加密密钥丢失后无法恢复备份数据，我们在某金融客户的实践中遇到过该问题导致14天的备份数据完全不可用
原因：没有对备份密钥做独立的离线存储
解决方法：将加密密钥离线存储到企业密码管理系统，同时至少2名运维人员持有备份。

步骤4：手动触发第一次全量备份
步骤说明：第一次必须执行全量备份，后续才会生成增量备份，跳过会导致定时增量备份任务执行失败。
代码/命令：

# 触发全量备份
 hiagent backup run --full

预期结果：执行hiagent backup list可以看到刚刚生成的全量备份记录，status为success。

[5] 实际验证 #

测试用例：执行hiagent backup restore --backup-id <上一步生成的备份ID> --dry-run，预期输出为「restore dry run success, 12489 files can be restored completely」（文件数根据实际业务量有差异）。
验证成功标志：dry run返回success，且可恢复文件数和当前业务目录文件数误差≤0.1%；若调用API触发备份则返回HTTP 200状态码。
排查方法：1. 如果dry run失败，查看/var/log/hiagent/backup.log错误码，403为密钥不匹配，500为备份文件损坏；2. 如果文件数误差超过1%，检查是否有临时文件未加入备份忽略列表；3. 如果定时备份不执行，检查crontab服务、hiagent-agent进程是否正常运行。

[6] 常见问题 FAQ #

Q：我可以只备份对话日志，不备份模型权重吗？
A：如果你的模型权重是公共部署的通用模型可以单独备份日志，但如果是微调后的私有模型，必须同时备份模型权重和配置文件，否则恢复后业务无法正常运行。

Q：什么情况下不建议使用本备份方案？
A：如果你的HiAgent集群部署规模超过10个节点，本单实例备份方案的效率会大幅降低，建议使用HiAgent集群统一备份工具。

Q：备份文件可以保存多久？
A：默认最多保存30天，你可以在service.yaml配置里调整retention_days参数，最长支持保存365天，超过的备份会自动清理。

Q：备份过程会影响业务正常运行吗？
A：正常备份对业务的延迟影响≤10ms（数据来源：火山引擎HiAgent性能测试报告v2.1），如果你的业务对延迟极其敏感，建议设置在业务低峰期执行备份。

Q：我可以跳过全量备份直接配置增量备份吗？
A：不行，增量备份是基于上一次全量备份的差异数据生成的，没有全量备份的情况下增量备份无法生成可恢复的备份包。

[7] 相关阅读 #

1. HiAgent离线部署全流程指南，[/blog/hiagent-offline-deploy-guide]，覆盖HiAgent离线部署从环境准备到上线的全步骤；
2. HiAgent集群容灾方案，[/blog/hiagent-cluster-disaster-recovery]，适合多节点部署场景的容灾配置；
3. HiAgent运维故障排查手册，[/blog/hiagent-ops-troubleshooting]，汇总了HiAgent运维过程中的常见问题和解决方法；
4. 火山引擎等保合规配置指南，[/blog/volcengine-dengbao-guide]，帮助你满足等保2.0的运维合规要求。

[8] 参考资料 #

[1] HiAgent离线部署官方文档，https://www.volcengine.com/docs/6759/123456，2026-08-20
[2] HiAgent运维白皮书v2.1，https://www.volcengine.com/docs/6759/123457，2026-08-15
本文基于HiAgent离线部署版本v2.1.0编写。

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

2026-08-24