FunMD 文档转换服务

FunMD 是一个基于 FastAPI 的文档转换与资源重写服务，支持：

• DOC/DOCX/PDF/HTML → Markdown/HTML/JSON
• Markdown/HTML → DOCX/PDF（支持封面、Logo、页眉页脚、目录）
• 批量上传与处理，自动将本地相对资源上传至 MinIO 并重写为可访问链接
• 运行时 MinIO 配置，支持私有桶返回签名下载链接

前端测试页面内置并由后端提供，便于在内网环境下直接联调。

目录结构

• docling/app/server.py：FastAPI 应用入口，接口路由与 MinIO 集成
• docling/app/services/unified_converter.py：统一转换逻辑，封装 Docling 与 word2markdown
• docling/app/services/word2markdown.py：DOC/DOCX 自定义转换与图片处理
• docling/app/services/minio_utils.py：MinIO 客户端与运行时配置工具
• frontend/：前端（Vite）源码，构建后由后端挂载到 /ui
• Dockerfile：镜像构建，包含 LibreOffice 与运行依赖
• api.md：接口与测试说明（详细列举）

快速开始（源代码）

1. 启动后端

cd docling
PYTHONPATH=. python -m uvicorn app.server:app --host 0.0.0.0 --port 8000

2. 访问前端测试页

http://<你的服务器IP>:8000/ui/

3. 前端 API 基址（可选）

• 若需显式指定后端地址，可在浏览器控制台设置：

localStorage.setItem('app.api.base','http://<你的服务器IP>:8000')

否则前端使用相对路径与同源后端。

快速开始（Docker 镜像）

镜像已包含 LibreOffice（提供 soffice --headless，用于 .doc→.docx）与模型缓存。

1. 加载镜像

docker load -i FunMD_Convert_Image.tar

2. 运行容器（示例映射到 8001，避免端口冲突）

docker run --rm -p 8001:8000 --name funmd funmd-convert:latest

3. 访问前端测试页

http://<你的服务器IP>:8001/ui/

MinIO 配置

服务支持运行时配置 MinIO，避免写死环境变量；同时内置规范化与安全校验：

• 禁止使用控制台端口 :9001 或带 /browser、/minio 的控制台地址
• public 用于生成返回链接的主机与协议；secure 仅影响后端连接 MinIO API 的协议

推荐流程：

# 测试并必要时自动建桶、应用公开读策略
curl -X POST 'http://<服务器IP>:8000/config/minio/test' \
  -F 'endpoint=10.9.35.31:9000' \
  -F 'public=https://docs-test.dameng.com' \
  -F 'access=minioadmin' \
  -F 'secret=minioadmin' \
  -F 'bucket=file-cms' \
  -F 'secure=false' \
  -F 'create_if_missing=true' \
  -F 'public_read=true'

# 应用运行时配置（返回链接以 public 为准）
curl -X POST 'http://<服务器IP>:8000/config/minio' \
  -F 'endpoint=10.9.35.31:9000' \
  -F 'public=https://docs-test.dameng.com' \
  -F 'access=minioadmin' \
  -F 'secret=minioadmin' \
  -F 'bucket=file-cms' \
  -F 'secure=false' \
  -F 'public_read=true'

私有桶场景下，前端应优先使用返回的 minio_presigned_url 进行下载；直链可能 403。

核心接口

• 健康检查：GET /health
• 统一转换：POST /api/convert
  • 字段：file 或 source_url 二选一；export=markdown|html|json|doctags；可选 engine=word2markdown|docling；save=true|false；filename
  • 行为：
    • save=false：返回文本内容与 media_type；若 MinIO 已配置，Markdown/HTML 中的资源（含 data: 图片）会上传并重写为可访问链接
    • save=true：Markdown/HTML/JSON 结果保存到 MinIO，返回 minio_url 与 minio_presigned_url
• Markdown→文档：POST /md/convert（DOCX/PDF；支持封面/Logo/页眉页脚/目录/样式）
• 批量重写并上传：POST /md/convert-folder
• 上传压缩包批量处理：POST /api/upload-archive
• 分阶段归档处理：
  • 暂存上传：POST /api/archive/stage
  • 批量处理：POST /api/archive/process
  • 说明：HTML 文件采用两阶段策略（重写资源→转换为 Markdown→再次重写）
• MinIO 管理：
  • 设置：POST /config/minio
  • 测试：POST /config/minio/test
  • 创建桶：POST /config/minio/create-bucket
  • 配置快照与 Profile：GET /config、/config/profile/list、/config/profile/activate

示例：DOCX→Markdown 不保存

curl -X POST 'http://<服务器IP>:8000/api/convert' \
  -F 'file=@/path/to/sample.docx' \
  -F 'export=markdown' \
  -F 'save=false'

示例：DOCX→Markdown 保存到 MinIO

curl -X POST 'http://<服务器IP>:8000/api/convert' \
  -F 'file=@/path/to/sample.docx' \
  -F 'export=markdown' \
  -F 'save=true' \
  -F 'filename=sample'

引擎与图片处理

• DOC/DOCX：默认走 word2markdown，将段落与表格转为 Markdown；内嵌的图片初始为 data:image/*;base64,...
• PDF/HTML：走 Docling 管线，生成 Markdown/HTML/JSON；PDF 可抽取图片作为额外资源上传
• 资源重写：后端在返回前会解析 Markdown/HTML 内的相对路径与 data: 图片，上传到 MinIO 并替换为可访问链接

常见问题

• 端口占用：若宿主已有服务使用 8000，请以 -p 8001:8000 映射对外端口
• .doc 转换：非 macOS 环境需要 LibreOffice 提供 soffice --headless；镜像已内置，无需额外安装
• 私有桶访问：使用 minio_presigned_url；直链可能 403

开发流程与建议

• 前端 API 基址：优先读取 localStorage('app.api.base')，其次 VITE_API_BASE_URL；不再强制回退本地端口
• 分支与 PR：遵循 “feature 分支 + PR” 的流程进行变更
• 防御式设计：三层防线（菜单过滤、路由守卫、后端授权）；后端始终需要硬授权

版权与许可

本项目面向企业内部使用。如需开源或外部发布，请根据公司规范补充许可与版权说明。