命令：`extract_attachment_content`

## 一、命令介绍

为站点内已有的历史附件补全可检索的文本内容，供附件预览、站内搜索、AI 知识库问答使用。

| 项 | 说明 |
| --- | --- |
| 执行对象 | 已升级到新版本、且存有历史附件的站点 |
| 执行次数 | 一次即可，已处理过的附件自动跳过 |
| 执行位置 | MrDoc 安装目录 |
| 执行时段 | 业务低峰期 |
| 服务状态 | 保持运行，无需停服 |
| 数据安全 | 建议先完成一次数据库备份 |

约束：

- 支持读取文字的类型：pdf、doc、docx、xls、xlsx、pptx；其余类型跳过。
- `.doc` 依赖服务器上的 LibreOffice（转换后再读取）：Docker 镜像已内置；源码部署需自行安装，
  并在配置文件 `config.ini` 的 `preview.libreoffice_path` 中填写其可执行文件路径（默认 `soffice`）。
  未安装时 `.doc` 会提取为空，`.docx` 不受影响。
- 云存储（七牛、MinIO 等）附件不处理。
- 超长正文按上限截断，完整内容以附件原件为准。
- 已处理过的附件不重复读取，需重新读取时加 `--force`。
- 需重建 AI 索引后，AI 知识库问答才会读取到附件内容。
- 命令运行期间不要中断进程。

## 二、使用语法

```sh
python manage.py extract_attachment_content [参数]
```

Docker 部署（容器名以 `docker ps` 实际显示为准）：

```sh
docker exec -it mrdoc python manage.py extract_attachment_content [参数]
```

## 三、参数说明

| 参数 | 说明 |
| --- | --- |
| 无参数 | 处理全部无内容的附件 |
| `--dry-run` | 只盘点，不写入 |
| `--limit N` | 最多处理 N 个附件 |
| `--force` | 已有内容的附件也重新读取 |
| `--attachment-id 1,2,3` | 只处理指定附件，逗号分隔 |
| `--doc-id N` | 只处理指定文档引用的附件 |
| `--reindex` | 补全后重建受影响文档的 AI 索引 |

## 四、使用示例

### 示例 1：盘点待处理附件

```sh
python manage.py extract_attachment_content --dry-run
```

核对输出中的「待处理附件」数量，确认与预期相符后继续。

### 示例 2：全量补全（未启用 AI 问答）

```sh
python manage.py extract_attachment_content
```

### 示例 3：全量补全并重建 AI 索引（已启用 AI 问答）

```sh
python manage.py extract_attachment_content --reindex
```

### 示例 4：定向处理单个文档的附件

```sh
python manage.py extract_attachment_content --doc-id 43090
```

### 输出对照

```
待处理附件：70 个
  提取成功：12 | attachment/2025/03/xxx.pdf | 长度=12345
  跳过(不支持格式)：13 | xxx.zip
  跳过(非本地存储/文件缺失)：14 | http://...

========== 提取完成 ==========
处理附件: 70
提取成功: 67
仍为空(提取失败): 1
跳过-不支持的格式: 2
跳过-非本地存储/文件缺失: 0
```

使用 `--reindex` 时附加输出：

```
开始重建AI索引，受影响文档 5 篇
  索引重建成功：DocID=43090 | xxx
AI索引重建完成：成功=5 失败=0
```

| 输出项 | 处理动作 |
| --- | --- |
| 提取成功 | 无需处理 |
| 仍为空(提取失败) | 无需处理（扫描版 PDF、加密或损坏文件） |
| 跳过-不支持的格式 | 无需处理 |
| 跳过-非本地存储/文件缺失 | 记录数量，联系技术支持确认附件存储配置 |

| 提示信息 | 含义 |
| --- | --- |
| 没有需要处理的附件 | 无待补全附件 |
| AI索引范围为空白名单 | 后台「AI 配置」未设置知识范围，需先设置 |
| 未找到引用这些附件的已发布文档 | 无需重建索引 |

### 验证

1. 打开含附件的文档，查看附件预览是否显示正文；
2. 在站内搜索中检索附件内的一段文字，确认可命中；
3. 已启用 AI 问答的站点，在 AI 问答中检索附件内容，确认可命中。

### 异常上报

命令报错中断或出现无法判断的输出时，记录以下信息并联系技术支持：

1. 完整报错输出；
2. 执行时间与所用参数；
3. 最后一条处理中的附件信息。

使用manage命令批量提取附件文本内容