HiAgent 3.0数据备份：可自定义备份周期配置指南

API 探路者

2026-9-1

[1] 一句话结论

本指南将讲解HiAgent 3.0自定义数据备份周期的配置流程、限制及注意事项。

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

适用场景

适合业务数据更新频率低，仅需每周1-3次备份的企业智能体场景，可节省存储成本。
适合业务峰值明确，需要将备份任务调度到凌晨低峰期的高并发智能体场景。
适合有等保合规要求，需要固定每周固定日期备份审计的场景。

不适用场景

如果需要备份文件保留超过7天的场景，不适用，建议搭配火山引擎对象存储TOS手动转存备份文件。
如果需要按小时级粒度设置备份周期的场景，不适用，建议自行开发定时脚本调用快照接口实现。
如果是测试环境临时实例，不需要持久化备份的场景，不建议开启自动备份，可直接手动快照节省资源。

[3] 前置准备

开发环境：无特殊要求，仅需要能访问火山引擎HiAgent控制台的浏览器，或Python 3.7+用于调用OpenAPI
账号权限：火山引擎主账号或拥有HiAgent管理员权限的子账号，已完成企业实名认证
依赖项：如果使用OpenAPI配置，需安装volcengine-python-sdk v1.0.129及以上版本
预计耗时：控制台配置约3分钟，OpenAPI配置约10分钟

[4] 分步实现

步骤1：进入HiAgent实例备份策略页面
步骤说明：首先需要登录火山引擎控制台，进入HiAgent 3.0实例列表，选择需要配置的实例，点击左侧菜单栏的「备份与恢复」->「备份策略」，这一步是配置的入口，跳过的话无法找到对应配置项。
预期结果：页面显示当前默认备份策略为每日备份，备份时段默认00:00-01:00，备份保留天数7天。

⚠️ 常见错误：子账号进入备份策略页面提示403无权限
原因：子账号没有被分配HiAgent的BackupPolicyFullAccess权限
解决方法：联系主账号在IAM控制台给对应子账号添加该权限，1分钟后刷新页面即可访问。

步骤2：自定义调整备份周期
步骤说明：点击「编辑备份策略」按钮，在备份周期选项中，勾选你需要执行备份的日期，支持多选，比如仅勾选每周一、周三、周五，我们在某电商客户的实践中发现，非每日备份可降低约40%的备份存储成本¹。
如果使用OpenAPI配置，可运行以下代码：

import volcenginesdkcore
from volcenginesdkhiagent.models.modify_backup_policy_request import ModifyBackupPolicyRequest

configuration = volcenginesdkcore.Configuration()
configuration.ak = "YOUR_AK" # 替换为你的AccessKey
configuration.sk = "YOUR_SK" # 替换为你的SecretKey
configuration.region = "cn-beijing" # 替换为实例所在区域

api_client = volcenginesdkcore.ApiClient(configuration)
api = volcenginesdkhiagent.HiAgentApi(api_client)

req = ModifyBackupPolicyRequest(
    instance_id = "YOUR_HIAGENT_INSTANCE_ID", # 替换为你的实例ID
    # 备份周期，1代表周日，2代表周一，以此类推到7代表周六
    backup_period = ["2", "4", "6"],
    # 备份开始时段，格式为HH:mm-HH:mm
    backup_time = "02:00-03:00"
)
resp = api.modify_backup_policy(req)
print(resp)

预期结果：点击保存后页面提示"备份策略修改成功"，OpenAPI调用返回HTTP 200，code为0。

步骤3：调整备份执行时段
步骤说明：在备份策略编辑页，选择你需要的备份开始时段，以1小时为粒度，建议选业务流量最低的时段，比如凌晨2点到3点，避免备份任务占用实例IO影响业务响应。

⚠️ 常见错误：设置备份时段后备份任务未按时执行
原因：设置的备份时段和实例的自动扩容窗口期冲突，系统会优先执行扩容任务
解决方法：在实例「配置调整」页面查看自动扩容窗口期，将备份时段设置为和扩容窗口期至少间隔1小时以上。

步骤4：确认策略生效
步骤说明：修改完成后回到备份策略页面，刷新后确认显示的备份周期和时段和你设置的一致，第二天可在「备份列表」中查看是否生成了对应备份文件。
预期结果：备份列表中按新的周期生成备份文件，状态为「备份成功」。

[5] 实际验证

测试用例：我们设置备份周期为每周一、周三、周五，备份时段为02:00-03:00，在对应日期的03:30查看备份列表。
预期输出：备份列表中存在创建时间为当天02:00-03:00之间的备份文件，文件大小符合实例数据量大小，状态为成功，且点击「恢复」按钮可正常发起恢复任务。
验证成功标志：HTTP 200返回，备份列表符合预期，且备份文件可正常用于恢复操作。
常见排查方法：1. 如果没有生成备份，首先检查实例状态是否为运行中，停机状态的实例不会执行备份；2. 检查是否有报错日志，在「运维中心」->「任务日志」中查看备份任务的失败原因；3. 如果是跨区域备份异常，检查跨区域备份的权限和目标区域的存储配额是否充足。

[6] 常见问题 FAQ

Q1：HiAgent 3.0的备份保留天数可以自定义吗？
A1：目前备份文件默认保留7天，暂不支持自定义调整，如果需要长期留存备份，可以手动将备份文件导出到火山引擎对象存储TOS中，TOS支持自定义生命周期规则设置长期留存。

Q2：什么情况下不建议自定义备份周期为非每日备份？
A2：如果你的智能体数据更新频率很高，比如日均新增会话数据超过10万条，或者涉及交易等核心数据，不建议降低备份频率，避免数据丢失的风险，这种场景建议保持默认每日备份。

Q3：我可以跳过控制台配置直接用OpenAPI修改备份策略吗？
A3：可以，只要你有对应的API权限，OpenAPI修改后的策略和控制台配置的是同步生效的，不过修改前建议先调用DescribeBackupPolicy接口查看当前配置，避免覆盖错误。

Q4：自定义备份周期会影响备份的恢复速度吗？
A4：不会，备份周期只影响备份生成的频率，备份的恢复速度和备份文件大小、实例规格有关，我们测试过100G的备份文件恢复时间约为20分钟²。

Q5：备份任务执行的时候会影响智能体的响应速度吗？
A5：如果是在业务高峰期执行备份，可能会导致实例的CPU和IO占用升高10%-20%，导致响应延迟增加约50ms，所以建议将备份时段设置在业务低峰期。

[7] 相关阅读

《HiAgent 3.0备份与恢复官方指南》[/docs/6293/1397596]，讲解备份恢复的全流程操作
《ModifyBackupPolicy OpenAPI参考文档》[/docs/6438/1158720]，详细说明备份策略修改接口的参数说明
《HiAgent数据安全合规最佳实践》[/blog/hiagent-security-best-practice]，介绍如何设置备份策略满足等保要求
《对象存储TOS备份数据归档教程》[/docs/6349/74819]，讲解如何将HiAgent备份转存到TOS长期留存

[8] 参考资料

[1] 火山引擎HiAgent客户实践白皮书，https://www.volcengine.com/docs/6293/162229660，2026-06
[2] 批量修改自动备份设置官方文档，https://www.volcengine.com/docs/6293/1397596?lang=zh，2026-08
本文基于HiAgent 3.0 v2.4版本编写

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0数据备份：可自定义备份周期配置指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #

[5] 实际验证 #

[6] 常见问题 FAQ #

[7] 相关阅读 #

[8] 参考资料 #

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

相关阅读