# 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” 的流程进行变更
- 防御式设计：三层防线（菜单过滤、路由守卫、后端授权）；后端始终需要硬授权

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