155 lines
5.6 KiB
Markdown
155 lines
5.6 KiB
Markdown
# 本地安装与启动指南（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`
|