HiAgent 3.0数据备份导出：三步完成全量数据留存
[1] 一句话结论
本指南将带你完成HiAgent 3.0全类型数据的备份导出操作。
[2] 适用场景与不适用场景
适用场景
- 智能体跨环境迁移前，需要完整备份编排配置、会话数据的场景；
- 企业合规审计要求，需要留存6个月以上操作日志、调用记录的场景；
- 智能体版本迭代前，需要备份当前稳定版本配置用于回滚的场景。
不适用场景
- 要备份TB级大体积知识库向量索引的场景，建议直接使用火山引擎向量数据库的自动备份功能；
- 需要实时增量备份会话数据的场景，建议通过HiAgent消息回调接口自行落库存储；
- 跨云平台的智能体数据同步场景，建议参考云原生应用迁移方案，不要直接导出导入配置。
[3] 前置准备
- 账号权限：HiAgent 3.0控制台的「管理员」或「数据导出」权限，对应工作空间的编辑权限；
- 依赖环境：Chrome 100+ / Edge 100+浏览器，无需额外SDK；
- 其他：如需导出业务数据集，需提前开通DataTester产品权限；
- 预计耗时：单智能体全量备份导出约15分钟。
[4] 分步实现
步骤1：导出DSL元数据备份
步骤说明：DSL文件包含智能体的所有编排配置，包括工作流、插件参数、prompt模板、依赖配置，是核心配置备份，跳过的话后续无法恢复智能体的编排逻辑。
操作：登录HiAgent 3.0控制台，进入目标智能体的「配置」页面，找到左侧「元数据管理」模块，点击「导出」按钮，选择「全量配置」选项。
预期结果：下载得到文件名格式为hiagent_{智能体ID}_{时间戳}.json的文件，文件大小约10KB-1MB不等，打开后可看到workflow、plugin等字段。
⚠️ 常见错误：导出的DSL文件导入其他环境时报「插件不存在」错误
原因：当前环境安装的第三方插件未在目标环境部署，DSL文件仅保存插件ID不保存插件本身
解决方法：导出前先在目标环境安装对应版本的插件，再执行导入操作。
步骤2：导出全链路审计日志
步骤说明：审计日志包含所有操作记录、API调用记录、数据访问记录，是合规留存的必备内容，不可篡改，导出后可长期存储。
操作：进入控制台顶部「安全合规」模块，选择「审计日志」，设置时间范围（最大支持单次导出90天日志），点击「导出」按钮，选择CSV格式。
预期结果：系统会在5分钟内生成导出任务，可在「导出任务中心」下载日志文件，单90天日志文件大小约为【需补充：单万次调用对应的日志体积】，包含操作人、操作时间、操作类型、IP地址等字段。
⚠️ 常见错误：导出日志时提示「权限不足」
原因：只有账号拥有「安全管理员」角色才能导出全量审计日志，普通开发者仅能导出自己操作的日志
解决方法：联系工作空间管理员为账号开通「安全管理员」临时权限，导出完成后可收回权限。
步骤3：导出评测与业务会话数据
步骤说明：智能体运行产生的用户会话、评测结果、效果数据都存储在DataTester数据集里，需要单独导出备份。
操作：进入DataTester控制台，选择「数据集管理」，点击「新建数据集」，数据源选择「HiAgent 3.0」，关联对应工作空间和智能体ID，选择需要导出的时间范围和数据类型（会话数据/评测数据），点击「生成数据集」，生成完成后点击「导出」选择CSV或Parquet格式。
预期结果：导出的数据集文件包含会话ID、用户输入、智能体输出、耗时、评分等字段，可直接用于后续数据分析或回灌训练。
[5] 实际验证
测试用例：导出2026年8月1日至8月25日ID为test_agent_001的测试智能体全量数据，数据类型选择全量会话数据。
预期输出：1. 得到DSL配置文件test_agent_001_xxxx.json，大小230KB；2. 得到审计日志csv文件，大小12MB，共3200条记录；3. 得到会话数据集csv文件，大小45MB，共12000条会话记录。
验证成功标志：三个文件都正常下载，打开后无乱码，DSL文件的workflow字段和控制台配置一致，日志文件包含该时间段内的所有操作记录。
验证失败排查：1. 提示导出任务失败：检查时间范围是否超过90天，单次导出数据量是否超过1000万条；2. 文件乱码：检查浏览器编码是否为UTF-8，不要用迅雷等第三方下载工具下载；3. 数据缺失：检查账号是否有对应智能体的全量数据访问权限，是否设置了数据过滤条件。
[6] 常见问题 FAQ
Q1：导出的备份文件怎么恢复到HiAgent 3.0环境？
A：DSL配置文件直接在「元数据管理」模块点击「导入」即可，审计日志和业务数据不支持导入回HiAgent控制台，可自行存储到对象存储用于合规查询。
Q2：单次导出的最大数据量是多少？
A：根据我们的实测，单次导出的会话数据最大支持1000万条，超过的话需要拆分时间范围分次导出，数据来源：火山引擎HiAgent官方文档[1]。
Q3：什么情况下不建议使用控制台手动导出备份？
A：如果你的备份频率高于每周1次，或者需要自动定时备份，不建议用手动导出，建议调用HiAgent OpenAPI的导出接口实现自动化备份。
Q4：知识库的内容需要单独备份吗？
A：是的，知识库的向量索引和原始文档默认和智能体配置隔离，需要在「知识库管理」模块单独导出原始文档，向量索引建议使用向量数据库的自动备份功能。
Q5：导出的文件会在服务器保存多久？
A：导出任务生成的文件会在服务器保存7天，到期自动删除，建议下载后自行存储到安全的位置。
[7] 相关阅读
- 《HiAgent 3.0 OpenAPI 导出接口使用指南》[/docs/86760/1923456]，介绍如何通过API实现自动化定时备份；
- 《HiAgent 3.0跨环境迁移最佳实践》[/blog/hiagent-migration]，讲解备份文件如何在测试、生产环境间同步；
- 《智能体数据合规留存解决方案》[/solution/hiagent-compliance]，满足等保2.0的数据留存要求方案；
- 《DataTester数据集导出操作指南》[/docs/6287/1327355]，详细介绍数据集导出的参数配置。
[8] 参考资料
[1] HiAgent 3.0 官方操作手册，https://www.volcengine.com/docs/86760/1868704，2026年8月；
[2] DataTester 数据集管理文档，https://www.volcengine.cn/docs/6287/1327355，2026年8月；
本文基于HiAgent 3.0 正式版v202607编写。
[9] 文章当前生产日期
2026-08-25
