# markitdown-server

**Repository Path**: pking_949/markitdown-server

## Basic Information

- **Project Name**: markitdown-server
- **Description**: 基于 Microsoft MarkItDown 的文件转 Markdown Web 服务
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MarkItDown Web 服务部署教程

## 项目说明

基于 Microsoft MarkItDown 的文件转 Markdown Web 服务，支持：
- 文件上传（拖拽 / 点击选择）
- 自动转换为 Markdown，**输出文件保留原文件名**
- **图片 OCR 识别**（PNG/JPG/BMP/TIFF/GIF/WebP，内置中文识别）
- **AI 增强**（右上角设置，配置后启用图片智能描述、文档内嵌图片 OCR，中文更准）
- 在线预览转换结果，界面显示**转换时间与转换耗时**
- 下载 .md 文件
- 文件历史管理（**仅保存在当前浏览器**，不占用服务器）

支持格式：PDF、Word(.docx)、PowerPoint(.pptx)、Excel(.xlsx/.xls)、HTML、CSV、JSON、XML、ZIP、EPUB、图片

---

## 环境要求

| 项目 | 要求 |
|------|------|
| Docker | 20.10+ |
| 内存 | 1GB+（含 OCR 引擎） |
| 磁盘 | 1.5GB（镜像约 800MB + 数据空间） |
| 端口 | 9151（可自定义） |

---

## 直接拉取线上镜像
```bash
docker pull registry.cn-shenzhen.aliyuncs.com/tlcloud/markitdown-open:latest

docker tag registry.cn-shenzhen.aliyuncs.com/tlcloud/markitdown-open:latest markitdown-open:latest

docker run -d --name markitdown -p 9151:8080 -v markitdown-output:/app/output --restart unless-stopped markitdown-open:latest
```

## 构建镜像

```bash
cd markitdown-server
docker build -t markitdown-api:latest .
```

> 如果基础镜像拉取失败，确认 Dockerfile 第一行的镜像源可用。  
> 可替换为其他源：
> - `docker.m.daocloud.io/library/python:3.12-slim`
> - `dockerhub.icu/library/python:3.12-slim`
> - `docker.1panel.live/library/python:3.12-slim`

---

## 运行容器

单行命令（推荐，避免换行符问题）：

```bash
docker run -d --name markitdown -p 9151:8080 -v markitdown-output:/app/output --restart unless-stopped markitdown-api:latest
```

参数说明：
- `-p 9151:8080` — 宿主机 9151 端口映射到容器 8080，可自定义
- `-v markitdown-output:/app/output` — 持久化转换结果（.md 文件）
- `--restart unless-stopped` — 服务器重启后自动拉起

> 说明：上传的原始文件在转换完成后会自动清理，仅保留 .md 结果，因此无需挂载 uploads 目录。

---

## 访问服务

浏览器打开：

```
http://服务器IP:9151
```

---

## AI 设置（可选）

1. 打开页面后点击右上角 **⚙️ 设置** 按钮
2. 填写：
   - **API 地址**：如 `https://api.openai.com/v1`（兼容 OpenAI 协议的任意服务均可，含本地 Ollama、DeepSeek、通义千问等）
   - **API 密钥**：你的 API Key
   - **模型名称**：如 `gpt-4o`、`deepseek-chat`、`qwen-vl-max`
3. 点击保存

说明：
- 配置信息**加密存储在当前浏览器 localStorage**，不会上传到服务器
- 配置后转换图片 / 含图文档时会自动调用 AI 视觉能力，中文 OCR 效果更佳
- 不配置也能正常使用，图片走内置 tesseract 本地 OCR

---

## API 接口

### 上传文件

```bash
curl -X POST -F "file=@/path/to/report.pdf" http://localhost:9151/upload
```

附带 AI 配置（可选）：

```bash
curl -X POST -F "file=@/path/to/scan.png" -F "api_base=https://api.openai.com/v1" -F "api_key=sk-xxx" -F "model=gpt-4o" http://localhost:9151/upload
```

返回：
```json
{
  "success": true,
  "original_name": "report.pdf",
  "md_filename": "report.md",
  "size": 12345,
  "duration_ms": 850,
  "convert_time": "2026-07-21T18:30:25",
  "preview": "# 报告标题\n..."
}
```

### 下载 Markdown

```bash
curl -O http://localhost:9151/download/report.md
```

### 预览内容

```bash
curl http://localhost:9151/preview/report.md
```

### 服务器文件列表

```bash
curl http://localhost:9151/files
```

### 删除文件

```bash
curl -X DELETE http://localhost:9151/delete/report.md
```

---

## 常用运维命令

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

# 停止服务
docker stop markitdown

# 启动服务
docker start markitdown

# 重启服务
docker restart markitdown

# 查看状态
docker ps | grep markitdown

# 更新镜像并重建
docker stop markitdown; docker rm markitdown
docker build -t markitdown-api:latest .
docker run -d --name markitdown -p 9151:8080 -v markitdown-output:/app/output --restart unless-stopped markitdown-api:latest
```

---

## 防火墙放行端口

```bash
# firewalld（UOS/CentOS/openEuler）
sudo firewall-cmd --permanent --add-port=9151/tcp
sudo firewall-cmd --reload

# 或 iptables
sudo iptables -A INPUT -p tcp --dport 9151 -j ACCEPT
```

---

## 不使用 Docker 的替代方案

如果不想用容器，直接在服务器上跑：

```bash
# 1. 确保 Python 3.10+
python3.12 --version

# 2. 安装 tesseract OCR 引擎（dnf，UOS Server 20 / openEuler）
sudo dnf install -y tesseract tesseract-langpack-chi_sim

# 3. 创建虚拟环境
python3.12 -m venv /opt/markitdown/.venv
source /opt/markitdown/.venv/bin/activate

# 4. 安装依赖
pip install flask openai pytesseract markitdown-ocr 'markitdown[all]'

# 5. 启动（将 app.py 和 templates/ 复制到 /opt/markitdown/）
cd /opt/markitdown
python app.py

# 后台运行
nohup python app.py > markitdown.log 2>&1 &
```