netvn/markitdown-auto repository overview

⁠markitdown-auto

这是一个自动化的文档转换服务。它通过监控指定的目录，利用 markitdown 将各种格式（如 PDF, Word, PPT 等）的文件自动转换为 Markdown 格式，并支持智能的文件防抖处理与结果归档。

该工具特别针对 NAS/NFS 等网络存储环境进行了优化，支持轮询（Polling）和实时监听（Inotify）双模式。

⁠功能特性

• 双模式监控：
  • polling：主动轮询模式，完美兼容 NFS、SMB 等不支持系统通知的网络文件系统。
  • inotify：实时监听模式，适用于本地磁盘，实现秒级响应。
• 智能防抖：内置防抖逻辑，防止在文件尚未上传完成时进行处理（避免文件损坏）。
• 安全归档：转换成功后，自动将源文件移至 Swap/Done 目录，避免重复处理。
• 错误处理：转换失败后，自动将源文件移至 Swap/Failed 目录，并7天自动清除。
• 灵活配置：通过环境变量即可调整监控模式、扫描频率及防抖检测阈值。

⁠环境变量配置

你可以在 docker-compose.yml 的 environment 部分配置以下参数：

⁠快速上手

⁠1. 目录结构准备

在宿主机挂载的目录中，你需要确保结构如下：

Plaintext

/your/host/path/
├/app               # 存放以转换的文件 *.md
├── /Swap          # 存放待转换的文件
├───── /Done     # 存放转换成功的文件
├───── /Failed   # 存放转换失败的文件
└───── ...

当服务启动后，它会自动在 Swap 目录下创建 Done Failed 文件夹。

⁠2. docker-compose.yml 示例

创建一个 docker-compose.yml 文件：

YAML

services:
  markit-engine:
    image: netvn/markitdown-auto:latest
    container_name: MarkitEngine
    environment:
      - MONITOR_MODE=polling  #默认为polling检测模式，支持NFS文件目录
      #- MONITOR_MODE=inotify #如果不是NFS文件目录可使用inotify模式-去掉注释并同时注释掉polling模式
      - SCAN_INTERVAL=5
      - CHECK_SIZE=2
    volumes:
      - /your/host/path:/app
    restart: unless-stopped

⁠3. 启动服务

Bash

docker compose up -d

⁠工作流说明

1. 输入：将原始文件（如 report.pdf）放入容器内 /app/Swap 目录。
2. 检测：系统根据配置的 MONITOR_MODE 发现新文件。
3. 防抖：系统会通过 CHECK_SIZE 间隔检测文件大小是否变化，确保文件传输完毕。
4. 转换：调用 markitdown 进行转换，输出 .md 文件至 /app 目录。
5. 归档：转换成功后，自动将原始文件移动至 /app/Swap/Done，确保原件安全且不重复转换。
6. 失败：转换失败后，自动将原始文件移动至 /app/Swap/Failed，7天后会自动清理。

⁠许可证

MIT License