# 项目导出与导入

由系统管理员导出项目配置与元数据，并通过管理接口创建项目副本。

项目导出将数据源配置、连接信息、库表字段元数据和训练数据保存为 JSON。系统管理员可以把这份文件导入同版本环境，创建新的项目副本。

**这不是完整项目备份。** 数据库中的业务数据、Workbook 数据与专用元数据、上传的原始文件、对话、智能体、画卷、看板、成员、权限配置及 AI 搜索值索引都不包含在内。完整环境的备份与恢复见[版本升级与迁移](https://docs.asktable.com/deploy/migration)。

**Warning**

导出文件包含数据源连接账号和**解密后的数据库密码**，应按凭证文件保管。限制访问人员，使用受控渠道传输，不要上传到公开仓库、工单或聊天群。导入后密码会重新加密存储，但导出的 JSON 文件仍包含明文密码。

## 权限与准备

- **界面导出**：需要系统管理员身份（`SYS_ADMIN`），同时在当前项目具有 Owner 或 Admin 权限，才能进入项目设置并看到导出入口。普通项目管理员身份不足以使用系统导出功能。
- **接口导入**：需要系统 API Key，或系统管理员登录后取得的访问令牌。项目 API Key 不能用于该接口。
- **版本一致**：源环境与目标环境应使用相同的 AskTable 版本和数据库迁移版本。导出文件没有完整的数据结构版本标记，也不提供跨版本格式转换；不要把历史 JSON 当作跨版本迁移包。
- **目标组织**：导入会在目标组织中创建新项目，仍受组织只读状态和项目容量限制。准备目标组织 ID，并通过 `X-Org-Id` 明确指定。

## 从界面导出

1. 使用具备上述权限的账号进入目标项目，打开**项目设置**。
2. 在**系统管理**区域点击**导出项目**，阅读连接信息和密码提示后确认。
3. 浏览器下载 `export_<项目ID>_<时间戳>.json`。保管好原文件，导入时使用完整内容，不手工重建 JSON 结构。

导出的主要内容如下：

| 内容     | 范围                                 |
| ------ | ---------------------------------- |
| 项目基本信息 | 项目名称与来源项目 ID                       |
| 数据源与连接 | 数据源配置、连接地址、账号及密码等连接信息              |
| 元数据    | 普通数据源的库、表、字段结构与描述；不含 Workbook 专用结构 |
| 训练数据   | 项目中的训练问答数据                         |

字段与训练数据的向量不随文件导出，导入时根据描述和问题重新生成。来源数据库和外部服务仍需由目标环境自行连接；上传文件、Workbook 和值索引需要另行迁移或重建，不能仅靠这份 JSON 恢复。

## 通过管理员接口导入

目前没有项目导入界面。管理员通过 `POST /api/v1/sys/projects/import` 提交完整导出文件，请求体是文件中的 JSON 对象，不是文件上传表单，也不需要额外包一层字段。

以下示例以标准 Docker 部署的访问地址为基础。将占位值替换为目标实例地址、管理员凭证和目标组织 ID，并让 `project-export.json` 指向实际导出文件；使用子路径部署时，在 `/api` 前补上部署子路径。

```bash
curl --request POST 'https://<目标实例地址>/api/v1/sys/projects/import' \
  --header 'Authorization: Bearer <系统APIKey或系统管理员访问令牌>' \
  --header 'X-Org-Id: <目标组织ID>' \
  --header 'Content-Type: application/json' \
  --data-binary '@project-export.json'
```

成功响应返回新项目的 `project_id`。导入会生成新的资源 ID，不覆盖原项目；名称冲突时会添加副本后缀。新项目使用私有访问策略，不复制来源项目成员与权限。使用系统管理员访问令牌且该管理员属于目标组织时，管理员成为新项目 Owner；否则由目标组织 Owner 担任。

导入过程中会重新生成字段与训练数据的向量，目标环境应具备可用的向量模型配置。若失败，先根据接口错误检查凭证、目标组织状态、容量、版本和模型配置，再处理；不要把含密码的完整请求体附在排查记录里。

## 导入后检查

1. 在目标组织找到响应返回的新项目，检查名称、数据源和元数据。
2. 核对数据源连接仍指向哪些数据库，确认目标环境能访问，且权限符合预期。导入不会复制外部数据库，也不会自动把连接切换成其他地址。
3. 为需要的成员重新配置访问权限，并单独处理未导出的文件、Workbook、智能体等资源。
4. 通过实际提问检查连接、字段理解和训练数据是否可用，再交给团队使用。