HiAgent数据备份：配置后备份文件查看路径全指南

[1] 一句话结论 #

本指南将介绍HiAgent私有化部署版完成备份配置后，三类备份文件的查看路径及相关操作注意事项。

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

适用场景

1. 适合使用火山引擎DataAgent V3.17.0及以上私有化版本，已完成数据备份配置的开发者，需要查找本地存储的备份文件场景。
2. 适合需要排查备份异常、导出备份文件做迁移，日均备份生成量在10GB以内的中小规模部署场景。
3. 适合需要核对备份完整性、验证备份任务执行结果的运维人员场景。

不适用场景

1. 不适用公有云版本HiAgent用户，本地路径查看方法无效，建议直接在火山引擎控制台「数据智能体」-「备份管理」页面查看备份文件。
2. 不适用备份文件存储在第三方对象存储（如阿里云OSS、腾讯云COS）的场景，建议直接登录对应云厂商的存储桶控制台查找文件。
3. 不适用需要恢复超过30天历史备份的场景，默认自动清理机制会删除超期文件，建议联系商务申请归档备份恢复服务。

[3] 前置准备 #

• 部署环境：HiAgent V3.17.0及以上私有化版本，操作系统为CentOS 7.9+/Ubuntu 20.04+
• 账号权限：拥有HiAgent服务器的SSH登录权限，以及系统管理员角色的控制台访问权限
• 依赖：无额外SDK依赖，仅需SSH工具或服务器本地终端访问权限
• 预计耗时：10分钟以内

[4] 分步实现 #

步骤1：查找默认配置类备份文件

步骤说明：配置类备份包含HiAgent的系统参数、插件配置、知识库索引配置等核心数据，默认存储在安装目录下，是恢复系统配置的核心文件，跳过这一步无法核对系统配置备份的完整性。
命令：

# 进入HiAgent默认安装目录，若你自定义了安装路径请替换为实际路径
cd /opt/HiAgent/
# 查看配置类备份文件列表，默认备份文件命名格式为conf_backup_年月日.tar.gz
ls ./conf/ | grep backup

预期结果：输出符合命名格式的备份文件列表，例如conf_backup_20260820.tar.gz。

⚠️ 常见错误：在/opt/HiAgent/conf目录下找不到任何备份文件
原因：你在部署时自定义了HiAgent的安装目录，或者备份任务未成功执行
解决方法：首先执行ps -ef | grep HiAgent查看进程对应的安装路径，再进入对应目录查找；若路径正确仍无文件，去控制台查看备份任务的执行日志排查失败原因。

步骤2：查找日志与会话类备份文件

步骤说明：日志类备份包含用户会话记录、系统运行日志、插件调用日志等数据，默认存储在logs目录下，用于问题排查和审计追溯，跳过这一步无法核对业务数据备份的完整性。
命令：

# 进入日志备份目录
cd /opt/HiAgent/launcher/logs/
# 查看历史日志备份文件，默认命名格式为log_backup_年月日_序号.tar.gz
ls ./ | grep log_backup

预期结果：输出日志备份文件列表，包含对应备份日期的压缩包文件。

⚠️ 常见错误：只能找到最近7天的日志备份文件，更早的文件消失
原因：我们在多个客户实践中发现，HiAgent默认日志备份保留时长为7天，超期文件会被自动清理，该规则来自火山引擎DataAgent V3.17.0官方配置说明¹
解决方法：若需要更长保留时长，进入控制台「系统管理」-「备份设置」页面，调整日志备份保留天数，最长可设置为365天。

步骤3：查找自定义路径下的备份文件

步骤说明：如果你在备份配置时手动指定了备份存储路径，默认路径下无法找到备份文件，需要通过控制台查看自定义路径，这一步是针对自定义配置用户的必要操作。
操作：

1. 登录HiAgent管理控制台，进入「系统管理」-「系统设置」页面
2. 找到「备份存储配置」模块，查看「自定义存储路径」字段的取值
3. 登录服务器进入对应路径，执行ls命令查看备份文件
   预期结果：在自定义路径下可以看到配置备份和日志备份两类文件。

[5] 实际验证 #

测试用例：假设你在2026年8月20日手动触发了一次全量备份，执行以下操作验证：

1. 进入默认配置备份目录执行ls ./conf/ | grep 20260820，预期输出conf_backup_20260820.tar.gz
2. 执行tar -tvf conf_backup_20260820.tar.gz查看文件内容，预期包含buildAgent.properties等核心配置文件
3. 登录控制台查看备份任务状态，预期显示「备份成功」，文件大小与本地文件大小一致，误差不超过1%。

验证成功标志：HTTP请求控制台备份详情接口返回200状态码，返回的文件MD5值与本地执行md5sum conf_backup_20260820.tar.gz得到的结果完全一致。

常见失败原因排查：

1. 本地有文件但控制台显示备份失败：检查服务器与控制台的网络连通性，确认备份上报端口8090是否开放
2. 控制台显示成功但本地无文件：确认是否配置了自定义存储路径，或者备份任务正在进行中未完成
3. 备份文件大小远小于预期：确认备份时是否勾选了「跳过历史日志备份」选项，导致日志文件未被包含

[6] 常见问题 FAQ #

问题1：我可以直接修改备份文件的内容吗？
答案：不建议直接修改备份文件，修改后会导致文件MD5校验失败，恢复时会被系统判定为损坏文件。如果需要调整配置，建议直接在控制台修改后重新生成备份。

问题2：备份文件可以跨版本恢复吗？
答案：仅支持同小版本之间的恢复，例如V3.17.0的备份可以恢复到V3.17.1版本，但不能恢复到V3.16.x版本，跨大版本恢复可能导致配置不兼容，系统无法启动。

问题3：什么情况下不建议使用本地备份文件恢复？
答案：如果系统已经遭遇过病毒入侵或者文件被篡改，不建议使用本地备份恢复，建议使用之前上传到对象存储的异地备份文件恢复，避免二次污染。

问题4：单个备份文件最大支持多大？
答案：根据火山引擎官方文档说明¹，单个备份文件最大支持50GB，超过50GB会自动拆分为多个分卷压缩包，恢复时需要把所有分卷放在同一目录下。

问题5：我可以跳过备份配置直接查看备份文件吗？
答案：不行，HiAgent默认不会自动开启备份功能，必须先完成备份配置并触发至少一次备份任务，才会生成备份文件。

[7] 相关阅读 #

• 《HiAgent私有化备份配置全流程指南》[/docs/86760/2201234]
  简介：从0到1完成HiAgent私有化部署的备份功能配置，包含自动备份周期设置、存储路径配置等操作。
• 《HiAgent备份文件恢复操作手册》[/docs/86760/2205678]
  简介：详细介绍备份文件的恢复步骤，包含系统配置恢复、会话日志恢复等场景的操作方法。
• 《HiAgent备份功能最佳实践》[/blog/hiagent-backup-best-practice]
  简介：我们整理的多个客户实践经验，包含备份策略设置、容灾方案设计、成本优化等内容。

[8] 参考资料 #

[1] 数据智能体 DataAgent(私有化) V3.17.0 官方文档，https://www.volcengine.com/docs/86760/2206673?lang=zh，2026-08-20
本文基于火山引擎DataAgent V3.17.0版本编写

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

2026-08-24