FunMD_Convert/docling/README.zh-CN.md

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

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

## 环境要求
- 操作系统：macOS（已验证），Linux/Windows 亦可
- Python：3.9–3.13
- 建议安装工具：`python -m venv` 或 [uv](https://docs.astral.sh/uv/)

## 创建虚拟环境
- 使用 venv：
  ```bash
  cd /Users/fanyang/Desktop/docling
  python -m venv .venv
  source .venv/bin/activate
  python -m pip install -U pip
  ```
- 或使用 uv：
  ```bash
  cd /Users/fanyang/Desktop/docling
  uv venv
  source .venv/bin/activate
  ```

## 安装依赖
- 安装本地 Docling 库（可编辑模式）：
  ```bash
  python -m pip install -e ./docling
  ```
- 安装后端服务依赖：
  ```bash
  python -m pip install fastapi uvicorn minio weasyprint pytest
  ```
  - 若 WeasyPrint 在 macOS 上提示缺少系统库，可使用 Homebrew 安装：
    ```bash
    brew install cairo pango gdk-pixbuf libffi
    ```

## 启动服务
- 在项目根目录执行：
  ```bash
  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 配置
- 环境变量方式（推荐）：
  ```bash
  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）
```ts
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）
```bash
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
```

返回示例：
```json
{
  "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` 全量转换并上传结果：
```bash
curl -s -X POST -F 'folder_path=/Users/you/docs' http://127.0.0.1:8000/md/convert-folder
```

### 直接转 DOCX（按需）
```bash
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`