# 命令行导入工具

觅思文档提供了一些命令行导入工具，用于在运行觅思文档的设备上直接进行导入操作。

通过 Docker、Docker-Compose 等方式部署的觅思文档需要在 python 命令前加上 `docker exec -it <容器ID或名称>`，例如 `docker exec -it mrdoc python manage.py ……`。

## 一、命令总览

| 命令 | 导入内容 | 数据来源 | 可否重复执行 |
| --- | --- | --- | --- |
| `import_oo_docs` | 本地 Office / PDF 文件 | 服务器本地目录 | 否，重复执行会重复创建文档 |
| `import_confluence` | Confluence 空间页面 | 在线 API / 离线 HTML 导出包 | 是，按状态文件增量补齐 |
| `import_yuque` | 语雀知识库 | 在线 API | 是，按状态文件增量补齐 |
| `import_notion` | Notion 页面树 | 在线 API | 是，按状态文件增量补齐 |
| `import_feishu` | 飞书 / Lark 知识空间 | 在线 API | 是，按状态文件增量补齐 |
| `import_dingtalk` | 钉钉知识库 | 在线 API | 是，按状态文件增量补齐 |

除 `import_oo_docs` 外，其余命令共用同一套参数与执行流程：来源平台专属参数 + 通用参数。

## 二、通用参数（在线来源导入命令）

适用于 `import_confluence`、`import_yuque`、`import_notion`、`import_feishu`、`import_dingtalk`。

### 使用语法

```shell
python manage.py import_<平台> [平台专属参数] --user <用户名> [通用参数]
```

### 通用参数说明

| 参数名 | 是否必填 | 说明 |
| --- | --- | --- |
| `--user` | ✅ 必填 | 导入内容归属的站点用户名，必须是已存在的用户 |
| `--project` | ⛔ 可选 | 导入到指定文集 ID；不指定则每次执行新建一个文集 |
| `--project-name` | ⛔ 可选 | 新建文集时的名称，默认取来源空间名称 |
| `--project-role` | ⛔ 可选 | 新建文集权限：0 公开、1 私密、2 指定用户、3 访问码，默认 1 私密 |
| `--space` | ⛔ 可选 | 要导入的空间 / 知识库标识，多个用英文逗号分隔；与 `--all-spaces` 二选一 |
| `--all-spaces` | ⛔ 可选 | 导入当前凭据可访问的全部空间 |
| `--editor-mode` | ⛔ 可选 | 文档编辑器模式：1 Editormd、2 Vditor、3 富文本，默认 1 |
| `--doc-status` | ⛔ 可选 | 文档状态：1 发布、0 草稿，默认 1 |
| `--mode` | ⛔ 可选 | 重复导入策略：`skip-existing`、`update`、`create`，默认 `skip-existing` |
| `--no-images` | ⛔ 可选 | 不导入正文内嵌图片 |
| `--no-attachments` | ⛔ 可选 | 不导入附件 |
| `--state-file` | ⛔ 可选 | 状态文件路径，默认 `config/<平台>_import_state.json` |
| `--limit` | ⛔ 可选 | 每个空间最多导入的页面数，0 表示不限制 |
| `--delay` | ⛔ 可选 | 每次请求前的间隔秒数，用于给源站降速 |
| `--dry-run` | ⛔ 可选 | 只盘点与试转换，不写数据库、不写状态文件 |
| `--keep-search-index` | ⛔ 可选 | 导入期间保留实时搜索索引（默认关闭以提升批量导入速度） |
| `--ai-index` | ⛔ 可选 | 导入完成后为文集入队 AI 向量索引重建任务 |

`--mode` 语义：

| 取值 | 行为 |
| --- | --- |
| `skip-existing`（默认） | 状态文件中已同步且来源版本未变化 → 跳过 |
| `update` | 命中状态文件也重新读取并同步正文，内容无变化则不写库 |
| `create` | 忽略状态文件，一律新建文档（会产生重复，仅用于一次性迁移） |

> `--project` 与 `--mode create` 不能同时使用，否则会报错，改用 `update`。

### 执行机制

- **不指定 `--project`**：每执行一次就新建一个文集，适合先试跑、多版本对比。
- **指定 `--project`**：导入到已有文集，配合状态文件可反复执行，只补齐新增与变更的内容。
- **状态文件**：记录已导入页面（来源版本号、文档 ID）与已下载的图片、附件，默认位于 `config/<平台>_import_state.json`。删除该文件可强制全量重跑，但已存在的文档不会自动删除。
- **搜索索引**：批量导入期间默认暂停实时搜索索引；导入结束后如需检索，执行 `python manage.py rebuild_index`。
- **AI 索引**：启用 AI 问答的站点，正式导入时可追加 `--ai-index`，为新建文集入队向量索引重建任务。

### 各平台能力对照

| 命令 | 空间标识 | 文档层级 | 正文图片 | 附件 | 仅导入的文档类型 |
| --- | --- | --- | --- | --- | --- |
| `import_confluence` | 空间 key，如 `DOC` | ✅ | ✅ | ✅ | 页面 |
| `import_yuque` | 知识库 namespace，如 `login/repo` | ✅ | ✅ | ❌ | 已发布的普通文档 |
| `import_notion` | 页面 ID（32 位） | ✅ | ✅ | ✅ | 页面（不支持数据库） |
| `import_feishu` | 知识空间 ID | ✅ | ✅ | ✅ | docx 文档 |
| `import_dingtalk` | 知识库 workspaceId | ✅ | ✅ | ❌ | 钉钉文档（.adoc） |

## 三、导入本地 Office/PDF 文档

命令：`import_oo_docs`

用于将指定目录中的 Office 文件批量导入为觅思文档中的 Office 文档，并关联到指定文集和父文档下。

### 使用语法

```shell
python manage.py import_oo_docs --path <目录路径> --user <用户名> --project <项目ID> [--parent_doc <父文档ID>]
```

### 参数说明

| 参数名 | 是否必填 | 说明 |
| --- | --- | --- |
| `--path` | ✅ 必填 | 本地文件所在目录路径。例如：`D:/office-files/` 或 `/home/user/docs/` |
| `--user` | ✅ 必填 | 创建文档的用户名（系统中已存在的用户） |
| `--project` | ✅ 必填 | 所属项目（文集）ID，必须为有效的 `Project.id` |
| `--parent_doc` | ⛔ 可选 | 指定导入文档的父文档 ID，默认为 `0`（即直接挂在项目根下） |

### 使用示例

```shell
python manage.py import_oo_docs --path /www/wwwroot/office --user mrdoc --project 3
```

上面的命令表示将 `/www/wwwroot/office` 目录下的 Office 文件导入到 ID 为 `3` 的文集中，使用的用户名是 `mrdoc`。

Docker 部署：

```shell
docker exec -it mrdoc python manage.py import_oo_docs --path /app/MrDoc/office --user mrdoc --project 3
```

### 支持的文件格式

`.docx`、`.xlsx`、`.pptx`、`.doc`、`.xls`、`.ppt`、`.pdf`（扩展名不区分大小写）。

### 处理规则

- 只处理 `--path` 目录**第一层**的文件，子目录和目录中的其它类型文件会跳过。
- 文件会拷贝到 `media/onlyoffice/<年>/<月>/` 下，目标文件名重复时自动追加 `-1`、`-2` 等序号，不覆盖已有文件。
- 每份文件创建为一篇 OnlyOffice 文档（`editor_mode=7`），文档标题取文件名（不含扩展名）。
- 会尝试提取文件文本内容，用于站内搜索与内容预览；提取失败不影响文档创建。
- 该命令没有状态文件、`--dry-run` 与增量同步；重复执行会重复创建文档，导入前请确认目录内容。

## 四、从 Confluence 导入

命令：`import_confluence`

把 Confluence 的内容迁移为觅思文档的文集与文档，保留页面父子层级与顺序，并把正文内嵌图片、附件、页面互链一并转换到本地。

支持两种数据来源：

| 来源 | `--source` | 说明 |
| --- | --- | --- |
| 在线接口 | `api` | 通过 Confluence REST API 抓取，支持 Cloud 与 Server/DC |
| 离线导出包 | `export` | 解析 Confluence 空间「HTML 导出包」（zip），无需网络 |

快速示例：

```shell
# 在线导入，每次新建文集
python manage.py import_confluence --source api --base-url https://xxx.atlassian.net/wiki \
    --email me@corp.com --api-token xxx --space DOC --user admin

# 离线导出包导入到指定文集
python manage.py import_confluence --source export --archive D:/DOC-export.zip \
    --project 3 --user admin
```

平台专属参数：

| 参数 | 说明 |
| --- | --- |
| `--source {api,export}` | 必填，数据来源 |
| `--base-url` | 在线导入必填，Confluence 站点地址 |
| `--deployment {auto,cloud,server}` | 部署类型，默认 `auto` 按域名自动判断 |
| `--email` / `--api-token` | Cloud 账号邮箱与 API Token；Token 未提供时读取环境变量 `CONFLUENCE_API_TOKEN` |
| `--token` | Server/DC 个人访问令牌；未提供时读取环境变量 `CONFLUENCE_TOKEN` |
| `--username` / `--password` | Server/DC 账号密码鉴权 |
| `--archive` | 离线导入必填，空间 HTML 导出包（zip）路径 |
| `--insecure` | 跳过 HTTPS 证书校验（自签证书的内网站点） |

完整参数、输出说明、重跑与排错参见 [Confluence 迁移导入操作手册](command_import_confluence.md)。

## 五、从语雀导入

命令：`import_yuque`

把语雀个人或团队知识库整体搬进本站。每个知识库对应一个文集，知识库目录构成文档树。

### 使用语法

```shell
python manage.py import_yuque --token <语雀Token> --space <namespace> --user <用户名> [通用参数]
```

### 平台专属参数

| 参数 | 说明 |
| --- | --- |
| `--token` | 语雀个人 Token；未提供时读取环境变量 `YUQUE_TOKEN` |
| `--api-root` | 语雀 API 地址，默认 `https://www.yuque.com/api/v2`；企业版为 `https://<企业>.yuque.com/api/v2` |
| `--insecure` | 跳过 HTTPS 证书校验 |

### 使用示例

```shell
# 导入指定知识库（新建文集）
python manage.py import_yuque --token xxx --space mylogin/mybook --user admin

# 导入到已有文集（可重复执行，补齐新增/变更）
python manage.py import_yuque --token xxx --space mylogin/mybook --project 3 --user admin

# 导入当前账号可见的全部知识库
python manage.py import_yuque --token xxx --all-spaces --user admin

# 只盘点不写库
python manage.py import_yuque --token xxx --space mylogin/mybook --user admin --dry-run
```

### 说明

- `--space` 使用知识库的 namespace，格式为 `登录名/知识库路径`。
- 只导入已发布的普通文档；画板、表格、资源等其它类型及未发布草稿会跳过。
- 支持正文图片；语雀接口未提供附件下载能力，附件不会导入。
- 目录中的分组节点在本站没有对应实体，其下文档会上挂到最近的文档祖先。
- 文档详情接口有频率限制，命令已内置详情请求节流；如仍触发限流，可继续加大 `--delay`。

## 六、从 Notion 导入

命令：`import_notion`

把 Notion 页面树整体搬进本站。每个可访问的顶层页面视为一个文集，其下的子页面构成文档树。

### 使用语法

```shell
python manage.py import_notion --token <Notion Token> --space <页面ID> --user <用户名> [通用参数]
```

### 平台专属参数

| 参数 | 说明 |
| --- | --- |
| `--token` | Notion Internal Integration Token；未提供时读取环境变量 `NOTION_TOKEN` |
| `--base-url` | Notion API 地址，默认 `https://api.notion.com` |
| `--api-version` | `Notion-Version` 请求头，默认 `2022-06-28` |
| `--insecure` | 跳过 HTTPS 证书校验 |

### 使用示例

```shell
# 导入指定顶层页面（新建文集）
python manage.py import_notion --token ntn_xxx --space <页面ID> --user admin

# 导入到已有文集（可重复执行，补齐新增/变更）
python manage.py import_notion --token ntn_xxx --space <页面ID> --project 3 --user admin

# 导入集成可访问的全部顶层页面
python manage.py import_notion --token ntn_xxx --all-spaces --user admin

# 只盘点不写库
python manage.py import_notion --token ntn_xxx --all-spaces --user admin --dry-run
```

### 说明

- `--space` 使用 Notion 页面 ID（页面链接中 32 位十六进制字符串）。
- 需先把目标页面「共享」给该集成，否则接口会返回 404。
- 支持正文图片与附件。Notion 文件是限时签名直链，导入时需立即下载，请保持网络畅通。
- **数据库（database）暂不支持迁移**，遇到时会跳过并告警；数据库内的子页面也不会导入。
- 单个页面最多抓取 2000 个块，超出部分会截断并告警。

## 七、从飞书 / Lark 导入

命令：`import_feishu`

把飞书知识空间（wiki）整体搬进本站。每个知识空间对应一个文集，空间下的节点构成文档树。飞书与 Lark 接口一致，仅域名不同。

### 使用语法

```shell
python manage.py import_feishu --app-id <AppID> --app-secret <AppSecret> --space <知识空间ID> --user <用户名> [通用参数]
```

### 平台专属参数

| 参数 | 说明 |
| --- | --- |
| `--app-id` | 飞书应用 App ID；未提供时读取环境变量 `FEISHU_APP_ID` |
| `--app-secret` | 飞书应用 App Secret；未提供时读取环境变量 `FEISHU_APP_SECRET` |
| `--base-url` | 开放平台域名，国内默认 `https://open.feishu.cn`；国际版 Lark 传 `https://open.larksuite.com` |
| `--web-base-url` | 用户侧站点域名（用于生成来源链接），默认按 `--base-url` 推导 |
| `--insecure` | 跳过 HTTPS 证书校验 |

### 使用示例

```shell
# 导入指定知识空间（新建文集）
python manage.py import_feishu --app-id cli_xxx --app-secret yyy --space <知识空间ID> --user admin

# 导入国际版 Lark
python manage.py import_feishu --app-id cli_xxx --app-secret yyy \
    --base-url https://open.larksuite.com --space <知识空间ID> --user admin

# 导入到已有文集（可重复执行，补齐新增/变更）
python manage.py import_feishu --app-id cli_xxx --app-secret yyy \
    --space <知识空间ID> --project 3 --user admin

# 只盘点不写库
python manage.py import_feishu --app-id cli_xxx --app-secret yyy \
    --space <知识空间ID> --user admin --dry-run
```

### 说明

- 需为该应用开通 wiki 与 docx 的读取权限，并把应用添加为目标知识空间的成员，否则接口会返回无权限错误。
- 当前只支持 `docx` 文档；飞书电子表格、多维表格、思维笔记、幻灯片、旧版文档等类型会跳过并告警。
- 支持正文图片与附件；部分嵌入对象会在正文中标注为暂不支持。

## 八、从钉钉文档导入

命令：`import_dingtalk`

把钉钉知识库整体搬进本站。每个知识库对应一个文集，知识库内的节点构成文档树。

### 使用语法

```shell
python manage.py import_dingtalk --app-key <AppKey> --app-secret <AppSecret> \
    --operator-id <操作者unionId> --space <知识库ID> --user <用户名> [通用参数]
```

### 平台专属参数

| 参数 | 说明 |
| --- | --- |
| `--app-key` | 钉钉应用 AppKey；未提供时读取环境变量 `DINGTALK_APP_KEY` |
| `--app-secret` | 钉钉应用 AppSecret；未提供时读取环境变量 `DINGTALK_APP_SECRET` |
| `--operator-id` | 操作者 unionId；未提供时读取环境变量 `DINGTALK_OPERATOR_ID` |
| `--base-url` | 钉钉开放平台地址，默认 `https://api.dingtalk.com` |
| `--insecure` | 跳过 HTTPS 证书校验 |

### 使用示例

```shell
# 导入指定知识库（新建文集）
python manage.py import_dingtalk --app-key dingxxx --app-secret yyy \
    --operator-id <操作用户unionId> --space <知识库ID> --user admin

# 导入到已有文集（可重复执行，补齐新增/变更）
python manage.py import_dingtalk --app-key dingxxx --app-secret yyy \
    --operator-id <操作用户unionId> --space <知识库ID> --project 3 --user admin

# 只盘点不写库
python manage.py import_dingtalk --app-key dingxxx --app-secret yyy \
    --operator-id <操作用户unionId> --space <知识库ID> --user admin --dry-run
```

### 说明

以下限制均来自钉钉接口本身：

1. 接口要求以某个成员身份操作，必须提供 `--operator-id`（该成员的 unionId），且该成员需对目标知识库有访问权限；
2. 只迁移「钉钉文档」（`.adoc`），知识库里的其它文件（xlsx、pdf 等）钉钉未提供下载地址，会跳过；
3. 钉钉块接口只返回第一层块，容器（标注、分栏）里的嵌套正文可能取不到；
4. 文档内的附件只有不透明标识，无法下载，只在正文中保留文件名。

## 九、迁移执行建议

1. **备份数据库**：正式导入前先完成一次数据库备份。
2. **先试运行**：在线来源命令先加 `--dry-run`，核对空间、页面数、图片/附件数量是否符合预期。
3. **选择落地方式**：首次试跑可不指定 `--project` 新建文集；确认无误后再指定 `--project` 做正式迁移。
4. **低峰期执行**：导入会占用源站接口与本地 IO，建议在业务低峰期执行，并保持进程不中断。
5. **增量重跑**：中断或漏导时直接重复执行同一命令（带 `--project`），已导入且未变化的内容会跳过。
6. **重建索引**：导入完成后执行 `python manage.py rebuild_index`；启用 AI 问答的站点追加 `--ai-index` 或另行重建 AI 索引。
7. **验收**：检查文档树层级与顺序、图片与附件、页面互链跳转，以及站内搜索能否命中新内容。

## 十、常见错误与处理

| 提示信息 | 处理方式 |
| --- | --- |
| `用户不存在` | `--user` 指定的用户名在站点中不存在，先创建用户或核对拼写 |
| `文集不存在` / `文集ID不存在` | `--project` 指定的文集 ID 不存在，先在个人中心确认文集 ID |
| `project参数未设置` | `import_oo_docs` 未传 `--project`，补上文集 ID |
| `源文件目录不存在` | `--path` 路径填写错误，或目录未挂载到容器内 |
| `请用 --space 指定空间，或使用 --all-spaces` | 未指定导入范围 |
| `未找到任何空间` | `--space` 标识写错，或当前凭据没有对应空间的访问权限 |
| `--project 与 --mode create 同时使用会产生重复文档` | 参数冲突，改用 `--mode update` |
| `使用 --source export 时必须提供 --archive` | Confluence 离线导入缺少导出包路径 |
| `导出包不存在` | 路径填写错误或文件未上传到服务器 |
| `使用 --source api 时必须提供 --base-url` | Confluence 在线导入缺少站点地址 |
| 凭据校验失败（401/403 等） | 检查 Token、AppID/AppSecret、operatorId 是否有效，以及应用权限与空间成员关系 |
| 部分附件未能入库 | 默认站点策略只允许 zip 附件，请在「系统设置 → 文档设置 → 附件格式」中放行所需格式后重跑 |

> Docker 部署时，`--path`、`--archive`、`--state-file` 等路径都是指**容器内**的路径，请先把文件挂载或拷贝到容器中。