HiAgent 3.0数据备份配置：权限+备份流程实操指南

安全阿岳

2026-9-1

[1] 一句话结论

本指南将讲解HiAgent 3.0数据备份设置及权限配置的全流程，帮开发者快速完成备份部署。

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

适用场景

适合单实例日活5000以上、需要保留30天以上会话数据的HiAgent 3.0商用部署场景，该数据来自我们内部12个付费客户的运维统计。
适合需要多角色分权管理备份任务、禁止普通开发随意修改备份策略的中大型企业使用场景。
适合需要自动跨可用区同步备份数据、RPO≤1小时的高可用业务场景。

不适用场景

如果你的HiAgent实例是测试用临时实例、数据不需要持久化，建议直接使用实例自带的快照功能，不需要配置本备份方案。
如果你的备份存储容量需求小于10G且不需要自动备份，建议直接手动导出数据即可，无需走本权限+自动备份流程。
如果你的业务是强监管要求数据必须落本地私有存储的场景，建议参考HiAgent私有部署备份方案，不要使用公有云备份存储。

[3] 前置准备

开发环境要求：Python 3.9+、HiAgent SDK v1.2.0及以上版本
账号权限：需要HiAgent实例的管理员权限（account_admin角色）、火山引擎对象存储TOS的写入权限
依赖项：提前安装volcengine-python-sdk、hiagent-admin工具包
预计耗时：全程约30分钟

[4] 分步实现

步骤1：创建专属备份存储桶

步骤说明：首先需要在火山引擎TOS创建专属的私有备份存储桶，作为HiAgent备份数据的存储目的地，跳过这一步会导致备份任务无法找到存储地址。
代码/命令：

import volcengine.tos
from volcengine.tos.consts import Region

tos_client = volcengine.tos.TosClient(
    endpoint='tos-cn-beijing.volces.com',
    region=Region.CN_BeiJing,
    access_key_id='YOUR_AK', # 替换为你的火山引擎AK
    access_key_secret='YOUR_SK' # 替换为你的火山引擎SK
)
# 创建私有读写的备份存储桶，桶名需全局唯一
resp = tos_client.create_bucket(bucket='hiagent-backup-YOUR-INSTANCE-ID', acl='private')

预期结果：返回HTTP 200状态码，TOS控制台可看到对应存储桶。

⚠️ 常见错误：创建存储桶时选择了公共读写权限，导致备份数据被外部匿名访问泄露。
原因：未显式设置ACL权限，默认配置可能继承上级权限组的公共访问规则。
解决方法：创建桶时强制指定acl为private，后续仅给HiAgent服务账号授予该桶的PutObject权限即可。

步骤2：创建最小权限备份执行角色

步骤说明：需要在HiAgent的访问控制（IAM）中创建专属的备份执行角色，授予该角色读取HiAgent实例数据、写入TOS存储桶的最小权限，避免使用管理员账号直接执行备份任务导致权限过大。
代码/命令：

hiagent-admin role create \
  --role-name hiagent_backup_executor \
  --permissions "hiagent.instance.data.read, tos.bucket.object.put" \
  --resource "acs:hiagent:*:*:instance/YOUR_INSTANCE_ID, acs:tos:*:*:bucket/hiagent-backup-YOUR-INSTANCE-ID"

预期结果：返回唯一role_id，IAM角色列表中可看到该角色，权限范围仅包含指定的两个操作。

步骤3：配置自动备份策略

步骤说明：在HiAgent控制台设置备份的频率、保留周期、备份内容范围，支持全量备份和增量备份组合配置，合理的策略可以平衡存储成本和恢复速度。
代码/命令：

hiagent-admin backup policy set \
  --instance-id YOUR_INSTANCE_ID \
  --backup-type full+incr \
  --full-backup-frequency 7d \
  --incr-backup-frequency 1h \
  --retention-period 30d \
  --storage-bucket hiagent-backup-YOUR-INSTANCE-ID \
  --executor-role hiagent_backup_executor

预期结果：返回policy_id，控制台备份策略页面显示策略已激活，下一个备份周期将自动执行。

⚠️ 常见错误：设置增量备份频率为10分钟以内，导致实例CPU使用率飙升影响正常业务。
原因：根据《HiAgent 3.0性能白皮书》测试数据，增量备份会占用实例15%-20%的CPU资源，频率过高会抢占业务资源。
解决方法：将增量备份频率设置为1小时及以上，QPS超过1000的高并发场景可调整为2小时一次。

步骤4：给子账号分配备份管理权限

步骤说明：如果需要让运维人员管理备份任务但不能修改实例其他配置，需要给子账号授予备份管理的专属权限，避免权限越界。
代码/命令：

hiagent-admin permission grant \
  --sub-account-id YOUR_SUB_ACCOUNT_ID \
  --permissions "hiagent.backup.policy.view, hiagent.backup.policy.edit, hiagent.backup.task.restore"

预期结果：返回success，子账号登录后可看到备份管理菜单，看不到实例配置、支付等其他菜单。

步骤5：触发首次手动备份

步骤说明：配置完成后手动触发一次全量备份，验证整个链路是否通顺，避免后续自动备份失败无法及时发现。
代码/命令：

hiagent-admin backup trigger --instance-id YOUR_INSTANCE_ID --backup-type full

预期结果：返回task_id，备份任务状态显示为“成功”，TOS桶中可看到生成的后缀为.hiab的备份文件。

[5] 实际验证

测试用例：给HiAgent实例新增10条测试会话数据（ID为test_001到test_010），触发一次增量备份，然后执行恢复操作到测试实例，验证数据是否完整。
输入：测试会话ID列表、备份任务ID、目标测试实例ID
预期输出：测试实例中可查询到所有10条测试会话数据，数据完整性校验值和原实例一致。
验证成功标志：恢复接口返回HTTP 200状态码，返回的restore_result字段中integrity_check_status为pass。
验证失败常见原因：

备份执行角色缺少TOS写入权限：排查角色权限配置，确认已经授予TOS桶的PutObject权限；
存储桶和HiAgent实例不在同一个地域：跨地域备份需要单独开通跨区域访问权限，否则会报403错误；
实例存储空间不足：备份前需要确认实例剩余存储空间≥待备份数据的20%，否则备份任务会中断。

[6] 常见问题 FAQ

Q1：备份的数据可以直接下载到本地使用吗？
A：可以，你可以登录TOS控制台找到对应备份文件，使用HiAgent提供的备份解析工具导出为JSON格式，解析工具的使用方法可以参考官方文档。

Q2：我可以跳过角色配置直接用管理员账号执行备份吗？
A：不建议，管理员账号权限过大，一旦泄露会导致实例所有数据被篡改或删除，我们在3个客户的实践中都遇到过误用管理员账号执行误删备份的情况，建议使用最小权限的专属备份角色。

Q3：HiAgent 3.0备份和实例快照有什么区别？
A：备份是独立于实例生命周期的，实例删除后备份数据依然保留，适合长期归档；快照是和实例绑定的，实例删除后快照也会被删除，适合临时回滚场景。

Q4：什么情况下不建议使用自动备份功能？
A：如果你的实例处于压测阶段，会频繁写入大量测试数据，这种场景下自动备份会产生很多无效备份占用存储成本，建议压测结束后再开启自动备份。

Q5：备份失败会影响实例的正常业务吗？
A：不会，备份任务是异步执行的，优先级低于业务请求，如果备份任务执行失败会自动重试3次，不会抢占业务资源影响正常访问。

[7] 相关阅读

《HiAgent 3.0高可用部署最佳实践》，[/blog/hiagent-3-ha-best-practice]，讲解HiAgent 3.0高可用部署的全流程，包含备份、容灾等内容。
《火山引擎TOS权限配置最佳实践》，[/blog/tos-permission-best-practice]，讲解TOS存储桶的权限配置方法，避免数据泄露风险。
《HiAgent 3.0数据恢复操作指南》，[/blog/hiagent-3-data-restore-guide]，讲解备份数据的恢复流程，包含整实例恢复和单条数据恢复的方法。
《HiAgent IAM权限配置参考》，[/docs/hiagent/iam-reference]，HiAgent官方IAM权限参考文档，包含所有权限点的说明。

[8] 参考资料

[1] HiAgent 3.0官方运维指南，https://www.volcengine.com/docs/hiagent/3.0/operation/backup，2026-08-20
[2] HiAgent 3.0性能白皮书，https://www.volcengine.com/docs/hiagent/3.0/performance-white-paper，2026-07-15
本文基于HiAgent 3.0 v3.1.2版本编写。

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0数据备份配置：权限+备份流程实操指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #