#从 ChatBI 1.0 迁移到 DataAgent

本教程介绍如何将 ChatBI 1.0 系统中的业务建模数据迁移到 DataAgent。

#概述

DataAgent 是 ChatBI 的全面升级版本，业务建模数据格式完全兼容。迁移过程分为两个步骤：

1. 在 ChatBI 1.0 中导出业务建模数据
2. 在 DataAgent 中导入数据

#迁移内容

迁移的数据包括：

• 数据源配置
• Schema 定义
• 语义层配置
• 业务逻辑配置
• 自定义词表与词汇

#前置条件

• ChatBI 1.0 系统正常运行
• DataAgent 已完成部署和初始化
• 拥有 ChatBI 1.0 容器的命令行访问权限
• 拥有 DataAgent 系统的管理员权限

#迁移步骤

#步骤一：从 ChatBI 1.0 导出数据

1. 登录到 ChatBI 1.0 所在的服务器

2. 进入 ChatBI 容器的命令行：

   docker exec -it <chatbi-container-name> /bin/sh

3. 在容器中执行导出命令：

   npm run project-dump:json

   如需导出指定空间的数据，可使用：

   npm run project-dump:json --space=<空间名>

4. 命令执行完成后，会生成一个 zip 压缩包，包含所有业务建模数据

5. 将压缩包从容器中复制到宿主机：

   # 在宿主机执行
   docker cp <chatbi-container-name>:/app/<export-file>.zip ./

#导出文件说明

#压缩包命名规则

• 指定空间导出：dump_<空间名>_<时间戳>.zip
• 未指定空间导出：dump_all_spaces_<时间戳>.zip

#压缩包内 JSON 文件

#JSON 文件结构

每个 JSON 文件包含以下数据结构：

{
  "from": "1.0",
  "data": {
    "yiask_datasource": [...],
    "yiask_schema": [...],
    "yiask_property": [...],
    "yiask_schema_hierarchy": [...],
    "yiask_custom_metric": [...],
    "yiask_alisa_custom_node": [...],
    "yiask_synonyms": [...],
    "yiask_prompt": [...],
    "yiask_function_overwrite": [...]
  }
}

#字段说明

#步骤二：在 DataAgent 中导入数据

1. 登录 DataAgent 系统

2. 进入【系统搭建】→【全局设置】→【导入导出】

3. 在「导入建模数据」区域，点击「选择文件」按钮

4. 选择从 ChatBI 1.0 导出的文件（支持 JSON 和 ZIP 格式）

5. 点击「导入」按钮，等待导入完成

#DataAgent 支持导入的数据类型

#步骤三：验证迁移结果

导入完成后，请验证以下内容：

1. 数据源：检查所有数据源连接是否正常
2. 业务建模：检查表结构、字段定义和层级关系
3. 指标：检查自定义指标和函数覆盖配置
4. 自定义配置：检查业务术语和同义词是否正确导入
5. 用户指引：检查快捷指令配置

#常见问题

#导入失败怎么办？

1. 检查 zip 文件是否完整
2. 确认 DataAgent 版本是否支持该数据格式
3. 查看系统日志获取详细错误信息

#数据源连接失败？

导入的数据源配置保留了原 ChatBI 1.0 的连接信息。如果数据库地址、端口或凭据有变化，需要手动更新数据源配置。

#可以选择性导入部分数据吗？

目前不支持选择性导入。如需部分迁移，建议先完整导入，然后删除不需要的配置。

#地理位置表Schema变更

如果 ChatBI 1.0 中使用了地理位置表，升级到 DataAgent 后需要手动更新表结构，新增 syno 字段。

变更说明：

不同数据库的DDL语句：

-- ClickHouse / StarRocks
ALTER TABLE location_table ADD COLUMN syno Array(String);

-- Doris
ALTER TABLE location_table ADD COLUMN syno ARRAY<VARCHAR>;

-- MySQL
ALTER TABLE location_table ADD COLUMN syno JSON;

-- PostgreSQL
ALTER TABLE location_table ADD COLUMN syno text[];

#后续操作

迁移完成后，建议：

1. 测试关键的问答场景
2. 验证数据权限配置
3. 对新的建模数据进行备份