# file2pdf-fast-project

**Repository Path**: aylerh/file2pdf-fast-project

## Basic Information

- **Project Name**: file2pdf-fast-project
- **Description**: file2pdf-基于libreoffice-rs的极速文件转 PDF 服务； 缺点：- 转换版式不保证：字体等；优点： 支持样式全；- 速度：150ms/每页左右（50-400ms之间吧）；- 版式保留：表格合并单元格；图片（URL和base64）；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# File2PDF Fast - 极速文件转 PDF 服务（非原生格式保留）

## 概览

File2PDF Fast 是基于 Rust 异步生态（Axum、Tokio、Utoipa）与纯 Rust Office 处理引擎（libreoffice-pure）构建的高并发、毫秒级文件转 PDF 服务。支持 DOCX、XLSX、PPTX、ODT、ODS、ODP、ODG、ODF、ODB、PDF、HTML、SVG、Markdown、CSV、plain text (TXT) 共 16 种格式的高保真导出。系统支持单文件/多文件批量上传与 ZIP 压缩包上传，支持图片（网络 URL、Base64 以及 ZIP 压缩包内相对路径图片）无损内联渲染，并提供精确的总耗时、总页数与平均毫秒/页大屏性能指标看板，全接口契约遵循 OpenAPI 3.1 规范。

## 缺点
- 转换版式于复杂布局不保证：字体不对应、不支持latex等；

## 优点
- 支持格式全（16 种全覆盖：DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, ODF, ODB, PDF, HTML, SVG, Markdown, CSV, TXT）；
- 速度：大约150ms/每页左右（5-200ms之间吧，轻量文档仅需 5-15ms/页）；
- 版式保留：表格合并单元格；图片（URL、Base64 以及 ZIP 压缩包内相对路径图片高保真渲染）；
- 单文件/多文件/ZIP批量转换，支持单文件移除再转换与一键打包下载全部 PDF。

## 文件夹结构
crates文件夹代码-作用：Markdown/HTML 网络/Base64/ZIP相对路径 图片内联渲染、中文字体 Regular 权重矫正（告别过粗字体）、DOCX 表格合并单元格不拆分 以及 表格默认无底色原样还原；

## 页面样式

### 主页

![1](./images/1.png)

## 构建与运行

### 1. 基础镜像构建（预热 cargo-chef 与中文字体，可选）
```powershell
docker compose -f docker-compose-base.yml build
```

### 2. 生产服务构建与启动
```powershell
docker compose up --build -d
```
启动后访问：
- 前端交互界面：`http://localhost:8267/`
- Swagger OpenAPI 交互文档：`http://localhost:8267/docs`
- OpenAPI 3.1 JSON 契约：`http://localhost:8267/openapi.json`

## 解决痛点与使用技术

1. **Rust 容器构建耗时痛点（cargo-chef + 稀疏索引）**：
   - 痛点：Rust 依赖下载和编译耗时漫长，传统 Dockerfile 每次修改代码都会重构所有 crates。
   - 技术与解决：采用 `lukemathwalker/cargo-chef` 将依赖准备（Planner）与依赖编译（Cooker）拆解为独立缓存层，结合 Cargo 稀疏索引镜像源，使业务源码变更构建从数分钟压缩至数秒。

2. **传统 LibreOffice 依赖笨重与资源消耗（libreoffice-pure）**：
   - 痛点：传统方案需安装数个 GB 的 C++/Java LibreOffice 套件，容器臃肿、启动迟钝且容易出现 FUSE/gRPC 死锁。
   - 技术与解决：选用纯 Rust 编写的 `libreoffice-pure` 引擎，实现轻量级、无 C/C++ 依赖的高并发文档解析与 PDF 导出。

3. **Markdown 远程图片丢失与 Base64 渲染**：
   - 痛点：Markdown 文档中的网络图片（HTTP/HTTPS）在离线转换时无法渲染，导致 PDF 图片排版空缺。
   - 技术与解决：自研异步媒体预处理器，基于 `reqwest` 与 `regex` 智能嗅探并抓取远程图片，转换为 Data URI Base64 嵌入流，保证 URL 与 Base64 图片 100% 完整渲染入 PDF。

4. **复杂批处理与性能量化大屏（lopdf + zip）**：
   - 痛点：多格式文件混杂、压缩包层级多，传统工具缺乏细粒度单页性能指标。
   - 技术与解决：支持多文件并发处理与 `.zip` 自动解压遍历，使用 `lopdf` 原生解析生成的 PDF 页面树，实时计算呈现总页数、总耗时（秒）及平均每页耗时（毫秒/页），并支持单文件即时下载与一键 ZIP 归档打包。

5. **API 规范化与浏览器强缓存干扰（Axum + Utoipa）**：
   - 痛点：微服务契约难以维护，重定向时浏览器缓存导致旧页面无法刷新。
   - 技术与解决：通过 `utoipa` 宏注解在编译期强类型生成 OpenAPI 3.1 描述及 Swagger UI，根路径路由注入 `Cache-Control: no-cache, no-store, must-revalidate`，杜绝缓存脏数据。

## 致谢

- [axum](https://github.com/tokio-rs/axum)：模块化高性能Rust Web框架
- [libreoffice-pure](https://github.com/clark-labs-inc/libreoffice-rs)：纯Rust办公文档与PDF引擎
- [utoipa](https://github.com/juhaku/utoipa)：Rust编译期OpenAPI 3生成器
- [cargo-chef](https://github.com/LukeMathWalker/cargo-chef)：Docker加速Rust依赖缓存工具
- [lopdf](https://github.com/J-F-Liu/lopdf)：纯Rust底层PDF文档解析器