# 工具：markitdown API

**Repository Path**: fgclibrary/markitdown-api

## Basic Information

- **Project Name**: 工具：markitdown API
- **Description**: 为 markitdown 提供标准的 REST API 服务，支持将各种文档格式转换为 Markdown。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-18
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MarkItDown API

为 [markitdown](https://github.com/microsoft/markitdown) 提供标准的 REST API 服务，支持将各种文档格式转换为 Markdown。

## 功能特性

- 支持多种文档格式：PDF、Word、Excel、PowerPoint、图片、HTML 等
- 提供简单的 REST API 接口
- Web 可视化界面（文件上传、转换、管理）
- 智能 OCR 识别（PDF、Word、PPT 图片自动识别）
- 自动保存源文件和转换结果
- 数据持久化存储
- 深色模式自动跟随系统
- **开机自启动**（容器自动重启）
- Docker 一键部署

## 快速开始

### 方式一：使用 docker-compose（推荐）

**同时启动 API 后端 + Web 前端，开机自启动：**

```bash
# 首次启动（构建镜像）
docker-compose up -d --build

# 后续启动
docker-compose up -d
```

访问服务：
- **Web 界面**：http://localhost:8310（可视化上传、管理文件）
- **API 服务**：http://localhost:8300
- **API 文档**：http://localhost:8300/docs

**优势**：
- ✅ 前端 + 后端一键启动
- ✅ `restart: unless-stopped` 已配置，开机自动启动
- ✅ 端口 8300 + 8310 已配置好
- ✅ 数据持久化已配置好

---

### 方式二：仅启动 API 后端

#### 1. 拉取镜像

```bash
# 从镜像仓库拉取
 sudo docker pull swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api:1.0.0
```

#### 2. 启动容器

**只需一条命令：**

```bash
 sudo docker run -d --name markitdown-api --restart unless-stopped -p 8300:8300 -v ./data:/app/data swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api:1.0.0
```

访问服务：
- **API 服务**：http://localhost:8300
- **API 文档**：http://localhost:8300/docs

**参数说明：**
- `--name` - 容器名称（可自定义）
- `-p 8300:8300` - 端口映射（可改为 `-p 9000:8300`）
- `-v ./data:/app/data` - 数据持久化（推荐）
- `--restart unless-stopped` - 自动重启（**必需**，Docker 限制无法预设）

> **注意**：`--restart` 参数是 Docker 运行时选项，无法在镜像中预设，必须在启动时指定。

## 容器管理

```bash
# 查看运行状态
docker ps -a | grep markitdown

# 查看日志
docker logs markitdown-api -f

# 停止容器
docker stop markitdown-api

# 启动容器
docker start markitdown-api

# 重启容器
docker restart markitdown-api

# 删除容器
docker stop markitdown-api && docker rm markitdown-api
```

## 环境变量配置

```bash
docker run -d \
  --name markitdown-api \
  --restart unless-stopped \
  -p 8300:8300 \
  -v ./data:/app/data \
  -e TZ=Asia/Shanghai \
  -e DATA_DIR=/app/data \
  markitdown-api:latest
```

**可用环境变量：**
- `TZ` - 时区设置（默认：`Asia/Shanghai`）
- `DATA_DIR` - 数据目录（默认：`/app/data`）

## API 使用示例

### 1. 转换文件（仅返回结果）

快速转换文件，不保存到服务器。

```bash
curl -X POST "http://localhost:8300/convert" \
  -F "file=@document.pdf"
```

**返回：**
```json
{
  "success": true,
  "filename": "document.pdf",
  "markdown": "# 文档标题\n\n文档正文内容...\n\n```ocr\n这是图片中识别的文字\n```\n\n后续内容...",
  "content_type": "application/pdf"
}
```

> **注意**：图片 OCR 结果会以 ` ```ocr\n...\n``` ` 代码块形式嵌入到 Markdown 中

### 2. 转换并保存文件

转换文件并保存源文件和结果，返回 `file_id` 用于后续下载。

```bash
curl -X POST "http://localhost:8300/convert/save" \
  -F "file=@document.pdf" | jq '.'
```

### 3. 下载转换后的 Markdown 文件

```bash
curl -O "http://localhost:8300/download/<file_id>"
```

### 4. 查看所有已转换的文件

```bash
curl "http://localhost:8300/files" | jq '.'
```

### 5. 转换网页内容

```bash
curl -X POST "http://localhost:8300/convert/url?url=https://example.com" | jq '.'
```

### 6. 删除文件

```bash
curl -X DELETE "http://localhost:8300/files/<file_id>"
```

## 支持的文件格式

| 格式 | 扩展名 | OCR 支持 |
|------|--------|----------|
| PDF | `.pdf` | ✅ 文本保留 + 图片 OCR 识别 |
| Word | `.docx`, `.doc` | ✅ 文本保留 + 图片 OCR 识别 |
| PowerPoint | `.pptx`, `.ppt` | ✅ 文本保留 + 图片 OCR 识别 |
| HTML | `.html`, `.htm` | ✅ 文本保留 + 图片 OCR 识别 |
| Excel | `.xlsx`, `.xls` | ❌ 表格转换 |
| 图片 | `.jpg`, `.png`, `.gif` 等 | ✅ OCR 文字识别 |
| 文本 | `.txt`, `.json`, `.xml` 等 | ❌ 直接读取 |

**文件大小限制**：单个文件最大 50MB

## OCR 功能说明

**智能识别**：
- **普通 PDF**：保留原有文本，图片部分进行 OCR 识别
- **扫描件 PDF**：全文 OCR 识别（逐页处理，支持中英文混合）
- **Word 文档**：保留文本，内嵌图片自动 OCR
- **PowerPoint**：保留文本，幻灯片图片自动 OCR（按幻灯片组织）
- **HTML 文件**：保留文本，提取 `<img>` 标签图片进行 OCR（支持 data URI 和本地图片）
- **纯图片**：直接 OCR 识别文字

**输出格式**：
```markdown
文档正文内容...

```ocr
这是图片中识别的文字
```

后续内容...
```

**技术细节**：
- OCR 引擎：Tesseract OCR
- 语言支持：中文（简繁）+ 英文
- PDF 处理：300 DPI 图片转换
- 输出方式：代码块形式（不含 data URI）

## 数据存储

所有文件存储在 `data` 目录：

```
data/
├── file_registry.db          # SQLite 数据库
└── files/
    └── <uuid>/
        ├── source.<ext>      # 源文件
        └── output.md         # 转换结果
```

**Docker 映射**：通过 `-v ./data:/app/data` 将数据持久化到宿主机

## 开机自启动

容器已配置 `--restart unless-stopped`，会在以下情况自动启动：
- ✅ 系统重启后（Docker 服务启动时）
- ✅ 容器崩溃后
- ✅ Docker 服务重启后
- ❌ 手动停止后（不会自动启动）

**确保 Docker 服务开机启动：**

**Windows/Mac**：
1. 打开 Docker Desktop 设置
2. 勾选 "Start Docker Desktop when you log in"

**Linux**：
```bash
sudo systemctl enable docker
```

## 升级镜像

```bash
# 1. 停止并删除旧容器
sudo docker stop markitdown-api && docker rm markitdown-api && docker rmi swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api:1.0.0

# 2. 拉取新镜像
sudo docker pull swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api:1.0.0

# 3. 重新启动（数据保留在 ./data 目录）
sudo docker run -d --name markitdown-api --restart unless-stopped -p 8300:8300 -v ./data:/app/data swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api:1.0.0
```

## 技术栈

### 后端
- FastAPI - 高性能 Web 框架
- MarkItDown - Microsoft 开源的文档转换工具
- Tesseract OCR - 文字识别引擎
- SQLite - 轻量级数据库
- Python 3.12

### 前端（可选）
- React 19 + TypeScript
- Vite - 构建工具
- shadcn/ui + Tailwind CSS
- Nginx

## 常见问题

### 1. 如何修改端口？

```bash
# 修改为 9000 端口
docker run -d --name markitdown-api --restart unless-stopped -p 9000:8300 markitdown-api:latest

# 访问：http://localhost:9000
```

### 2. 如何查看自动分配的端口？

```bash
# 使用 -P 自动分配端口
docker run -d --name markitdown-api --restart unless-stopped -P markitdown-api:latest

# 查看端口
docker port markitdown-api
```

### 3. 数据存储在哪里？

如果使用了 `-v ./data:/app/data`：
- 数据在当前目录的 `data` 文件夹
- 容器删除后数据仍然保留

如果没有使用 `-v`：
- 数据在容器内部
- 容器删除后数据丢失

### 4. OCR 识别慢或失败？

- **扫描件 PDF 慢**：正常现象，需要逐页转换后 OCR（300 DPI）
- **识别不准确**：提高原文件质量（清晰度、对比度、分辨率）
- **识别为空**：检查文件是否损坏，查看日志 `docker logs markitdown-api`

### 5. 如何修改文件上传大小限制？

需要使用 docker-compose 启动 Web 前端，修改 `web/nginx.conf`：
```nginx
client_max_body_size 100m;  # 改为 100MB
```

### 6. 容器无法启动？

```bash
# 查看日志
docker logs markitdown-api

# 检查端口占用
netstat -ano | findstr 8300  # Windows
lsof -i :8300                # Linux/Mac
```

### 7. 其他电脑无法访问？

**检查防火墙（Windows）**：
```powershell
# 以管理员身份运行
netsh advfirewall firewall add rule name="MarkItDown API" dir=in action=allow protocol=TCP localport=8300
```

**检查 Docker 网络**：
```bash
docker run -d --name markitdown-api --restart unless-stopped -p 0.0.0.0:8300:8300 markitdown-api:latest
```

## 本地开发

如果需要修改代码：

```bash
# 克隆项目
git clone <repository>
cd markitdown-api

# 安装依赖
uv sync

# 启动后端
uv run uvicorn app.main:app --reload --port 8300

# 启动前端（另一个终端）
cd web
npm install
npm run dev
```

## 项目结构

```
markitdown-api/
├── app/                  # 后端 API 服务
│   ├── main.py          # FastAPI 应用
│   ├── routes.py        # API 路由
│   ├── database.py      # 数据库操作
│   └── ...
├── web/                 # 前端 Web 界面
│   ├── src/            # React 源码
│   ├── Dockerfile      # 前端镜像
│   └── nginx.conf      # Nginx 配置
├── data/               # 数据存储（持久化）
├── Dockerfile          # 后端镜像
├── docker-compose.yml  # Docker 编排
└── README.md
```

## License

MIT