FunMD_Convert/docling/README.zh-CN.md

本地安装与启动指南（Docling + FastAPI 服务）

本文档介绍如何在本机安装与启动本仓库的转换服务，以供前端调用生成并下载 PDF。

环境要求

• 操作系统：macOS（已验证），Linux/Windows 亦可
• Python：3.9–3.13
• 建议安装工具：python -m venv 或 uv

创建虚拟环境

• 使用 venv：

  cd /Users/fanyang/Desktop/docling
  python -m venv .venv
  source .venv/bin/activate
  python -m pip install -U pip
  

• 或使用 uv：

  cd /Users/fanyang/Desktop/docling
  uv venv
  source .venv/bin/activate
  

安装依赖

• 安装本地 Docling 库（可编辑模式）：

  python -m pip install -e ./docling
  

• 安装后端服务依赖：

  python -m pip install fastapi uvicorn minio weasyprint pytest
  

  • 若 WeasyPrint 在 macOS 上提示缺少系统库，可使用 Homebrew 安装：

    brew install cairo pango gdk-pixbuf libffi
    

启动服务

• 在项目根目录执行：

  PYTHONPATH=. python -m uvicorn app.server:app --host 127.0.0.1 --port 8000
  

• 访问：
  • 首页 UI：http://127.0.0.1:8000/
  • 健康检查：http://127.0.0.1:8000/health（返回 {"status":"ok"}）

接口总览

• GET / 本地 UI（静态文件）
• GET /health 服务健康检查
• POST /md/convert Markdown/HTML → docx|pdf（核心接口，返回 MinIO 下载链接）
• POST /md/convert-folder 批量转换本地文件夹内的 .md 文件并上传结果到 MinIO
• POST /md/upload-folder 批量上传前端打包的文件夹内容并转换其中 .md 文件
• MinIO 配置相关：
  • POST /config/minio 设置连接信息与前缀
  • POST /config/minio/test 验证连接
  • GET /config/minio/buckets 列出桶
  • POST /config/minio/create-bucket 创建桶

MinIO 配置

• 环境变量方式（推荐）：

  export MINIO_ENDPOINT=127.0.0.1:9000
  export MINIO_ACCESS_KEY=minioadmin
  export MINIO_SECRET_KEY=minioadmin
  export MINIO_BUCKET=docling-target
  export MINIO_SECURE=false
  export MINIO_PUBLIC_ENDPOINT=http://127.0.0.1:9000
  export MINIO_PREFIX=cms-files
  

• 运行时接口方式：
  • POST /config/minio 设置连接信息与前缀
  • POST /config/minio/test 测试连通性
  • GET /config/minio/buckets 列出桶
  • POST /config/minio/create-bucket 创建桶

前端下载 PDF（接口说明）

• 核心接口：POST /md/convert
• 作用：将 Markdown/HTML 转换为 PDF 并上传至 MinIO，返回可下载链接
• 参数（FormData，以下三选一提供文档来源）：
  • md_file：上传 Markdown 文件
  • markdown_text：直接传入 Markdown 文本
  • markdown_url：文档 URL（推荐）
• 目标格式：target=pdf
• 可选参数：toc、header_text、footer_text、logo_url|logo_file、cover_url|cover_file、product_name、document_name、product_version、document_version、css_name|css_text
• 返回 JSON 字段：minio_presigned_url（时效下载链接）或 minio_url（公开链接）、name、media_type

前端调用示例（TypeScript）

async function downloadPdf(markdownUrl: string) {
  const fd = new FormData();
  fd.append('markdown_url', markdownUrl);
  fd.append('target', 'pdf');
  fd.append('toc', 'true');
  // 可选品牌参数：
  // fd.append('header_text', '产品名|文档标题');
  // fd.append('footer_text', '© 公司');

  const resp = await fetch('http://127.0.0.1:8000/md/convert', { method: 'POST', body: fd });
  if (!resp.ok) throw new Error('转换失败');
  const data = await resp.json();
  const url = data.minio_presigned_url || data.minio_url;
  if (!url) throw new Error('未返回可下载链接，请检查 MinIO 配置');
  window.location.href = url; // 触发下载
}

cURL 示例（URL → PDF）

curl -s -X POST \
  -F 'markdown_url=http://127.0.0.1:9000/docs/assets/rewritten/DMDRS_Build_Manual_Oracle/DMDRS搭建手册-Oracle.md' \
  -F 'target=pdf' \
  -F 'toc=true' \
  -F 'header_text=产品名|文档标题' \
  -F 'footer_text=© 2025 公司' \
  http://127.0.0.1:8000/md/convert

返回示例：

{
  "minio_url": "http://127.0.0.1:9000/docling-target/cms-files/converted/DMDRS搭建手册-Oracle.pdf",
  "minio_presigned_url": "http://127.0.0.1:9000/...presigned...",
  "name": "DMDRS搭建手册-Oracle.pdf",
  "media_type": "application/pdf"
}

批量转换（文件夹）

• 将本地文件夹内的 .md 全量转换并上传结果：

curl -s -X POST -F 'folder_path=/Users/you/docs' http://127.0.0.1:8000/md/convert-folder

直接转 DOCX（按需）

curl -s -X POST \
  -F 'markdown_url=http://127.0.0.1:9000/docs/assets/rewritten/DMDRS_Build_Manual_Oracle/DMDRS搭建手册-Oracle.md' \
  -F 'target=docx' \
  http://127.0.0.1:8000/md/convert

常见问题

• ModuleNotFoundError: No module named 'app' / 'docling'
  • 请在启动命令前设置 PYTHONPATH=. 或在当前 shell 直接以 PYTHONPATH=. python -m uvicorn ... 方式启动。
• 未返回下载 URL
  • 请检查 MinIO 环境变量或使用 /config/minio 进行配置；确保桶存在且服务端启用了 store_final=true。
• 图片或样式异常
  • 确认资源已被重写为公共 URL（服务会自动上传并改写），并检查 css_name/css_text（PDF 默认样式为 default，位于 app/configs/styles/default.css）。
• WeasyPrint 依赖缺失（macOS）
  • 执行 brew install cairo pango gdk-pixbuf libffi 后重试；如仍失败，请检查 PATH/DYLD_LIBRARY_PATH。

相关文档

• 服务端接口中文说明：docling/README.zh-CN.md