# mineruwebtest

**Repository Path**: xuting/mineruwebtest

## Basic Information

- **Project Name**: mineruwebtest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MinerU PDF 解析 Web 服务

上传多个 PDF 作为一个任务，转发给 MinerU 解析服务（`http://10.11.0.110:6006`）进行解析，
解析完成后可整包下载结果 ZIP（内含 Markdown、content_list.json 等）。

## 功能概览

- **多文件批量上传**：一次选多个 PDF，作为一个任务提交
- **异步解析**：后端转发给 MinerU 的异步接口，前端轮询进度，避免长时间 HTTP 超时
- **可调参数**：解析后端（backend）、精度（effort）、解析方式（parse_method）、以及公式/表格/图表分析/Markdown/内容列表的开关
- **整包下载**：通过 MinerU 的 `response_format_zip=true` 直接透传结果 ZIP
- **单进程部署**：生产模式下，FastAPI 同时提供 API 与前端静态文件

## 技术栈

| 部分 | 技术 |
|---|---|
| 后端 | Python 3.12 + FastAPI + httpx（异步流式转发） |
| 前端 | Vue 3 + Vite + TypeScript + Element Plus |
| 任务存储 | 进程内存（重启即清空，不做持久化） |

## 端口约定

| 角色 | 端口 | 说明 |
|---|---|---|
| 后端 API | **37241** | 开发与生产统一使用 |
| 前端 dev server | **47822** | 仅开发模式，通过 Vite proxy 转发 `/api` 到 37241 |

> 前端 Vite dev server 监听在 IPv6 的 `[::1]`，请用 `http://localhost:47822` 访问。

## 目录结构

```
mineruwebtest/
├── server/                     # FastAPI 后端
│   ├── main.py                 # 应用入口、路由、__main__ 启动块
│   ├── config.py               # 配置（MinerU 地址、超时、CORS）
│   ├── mineru_client.py        # MinerU 调用封装（httpx 异步）
│   ├── store.py                # 内存任务表（线程安全 dict）
│   ├── schemas.py              # Pydantic 数据模型
│   ├── requirements.txt
│   └── static/                 # 前端构建产物（npm run build 生成，不入库）
├── web/                        # Vue 3 前端
│   ├── index.html
│   ├── vite.config.ts          # dev proxy /api → 37241
│   ├── tsconfig.json
│   └── src/
│       ├── App.vue             # 主页面
│       ├── api.ts              # 后端调用封装
│       ├── types.ts            # 类型定义与选项常量
│       ├── main.ts
│       └── components/
│           ├── FileUpload.vue      # 多文件拖拽上传
│           ├── OptionsPanel.vue    # 参数面板（含联动禁用）
│           └── TaskList.vue        # 任务卡片 + 轮询 + 下载
├── .gitignore
└── README.md
```

---

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+（推荐 20+）

### 开发模式（前后端分离，带热重载）

需要开两个终端：

```bash
# === 终端 1：启动后端（在 server/ 下）===
cd server
pip install -r requirements.txt
python -m uvicorn main:app --reload --port 37241
# 看到以下输出即成功：
#   INFO:  Uvicorn running on http://127.0.0.1:37241

# === 终端 2：启动前端（在 web/ 下）===
cd web
npm install
npm run dev
# 打开浏览器访问 http://localhost:47822
```

> 前端通过 Vite proxy 把 `/api/*` 请求转发到后端 `127.0.0.1:37241`，所以两个服务都要启动，缺一个浏览器就会报 "Failed to fetch"。

### 生产部署（单进程，API + 前端同源）

```bash
# 1. 构建前端，产物输出到 server/static
cd web
npm install
npm run build

# 2. 启动后端（同时托管前端静态文件）
cd ../server
python main.py
# 或显式指定：
python -m uvicorn main:app --host 0.0.0.0 --port 37241

# 浏览器访问 http://<服务器IP>:37241
```

`python main.py` 会监听 `0.0.0.0:37241`，对外可访问；同时把 `server/static/` 作为前端根目录托管。

---

## 配置

MinerU 服务地址默认 `http://10.11.0.110:6006`，可用环境变量覆盖：

```bash
# Linux / macOS
export MINERU_BASE_URL=http://10.11.0.110:6006

# Windows PowerShell
$env:MINERU_BASE_URL="http://10.11.0.110:6006"

# Windows CMD
set MINERU_BASE_URL=http://10.11.0.110:6006
```

---

## API 接口

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/tasks` | 提交多个 PDF（multipart：`files` + 解析参数），返回 `local_id` |
| `GET` | `/api/tasks/{local_id}` | 查询任务状态 |
| `GET` | `/api/tasks/{local_id}/download` | 下载结果 ZIP（任务完成后可用） |
| `GET` | `/api/health` | 健康检查 |

### 任务状态机

```
pending（排队中）→ processing（解析中）→ completed（已完成）
                                       └→ failed（失败）
```

### 提交任务时的参数（除 files 外，均有默认值）

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `backend` | `pipeline` / `vlm-engine` / `hybrid-engine` | `vlm-engine` | 解析后端 |
| `effort` | `medium` / `high` | `medium` | 解析精度（仅 hybrid 后端生效） |
| `parse_method` | `auto` / `txt` / `ocr` | `auto` | 解析方式（仅 pipeline/hybrid 生效） |
| `formula_enable` | bool | `true` | 解析公式 |
| `table_enable` | bool | `true` | 解析表格 |
| `image_analysis` | bool | `true` | 图表分析（VLM/hybrid 生效） |
| `return_md` | bool | `true` | 返回 Markdown |
| `return_content_list` | bool | `true` | 返回内容列表 JSON |

> 前端参数面板已实现联动：切到 `vlm-engine` 时，`effort` 和 `parse_method` 自动置灰。

### curl 示例

```bash
# 提交任务（用默认参数，只传文件）
curl -X POST http://localhost:37241/api/tasks \
  -F "files=@a.pdf" -F "files=@b.pdf"

# 查询状态
curl http://localhost:37241/api/tasks/<local_id>

# 下载结果
curl -OJ http://localhost:37241/api/tasks/<local_id>/download
```

---

## 常见问题

### 1. 浏览器报 "Failed to fetch"

原因：前端发请求时连不上后端。排查：

```bash
# 1) 后端是否在跑？端口必须是 37241
netstat -ano | findstr 37241
# 没输出 = 后端没启动，去启动它：
#   cd server && python -m uvicorn main:app --reload --port 37241

# 2) 前端是否在跑？端口必须是 47822
netstat -ano | findstr 47822
# 没输出 = 前端没启动：
#   cd web && npm run dev
```

开发模式下**前后端两个进程都要启动**，缺一个就会报这个错。

### 2. 启动后端报 `[WinError 10013] 访问套接字的尝试`

端口被占用或被系统排除。

```bash
# 1) 看是不是被占了
netstat -ano | findstr 37241
# 拿到最后一列的 PID，查是谁
tasklist | findstr <PID>
# 必要时杀掉
taskkill /F /PID <PID>

# 2) 如果没被占，检查是否落在 Windows 排除端口区间
netsh interface ipv4 show excludedportrange protocol=tcp
# 如果 37241 落在某段区间内，换一个不在区间里的端口
```

### 3. 下载的 ZIP 里中文文件名乱码

这是终端/git-bash 显示问题，**文件内容本身是正确的 UTF-8**。用 7-Zip、Windows 资源管理器或 Python 的 `zipfile` 解压即正常。

### 4. 任务记录丢了

设计如此：任务仅存于后端进程内存，进程重启或页面关闭后记录不保留。

---

## 说明

- 本服务是 MinerU 解析服务的 Web 前端代理，实际解析由 `http://10.11.0.110:6006` 完成。
- 结果 ZIP 由 MinerU 直接生成，后端流式透传，不在本地落盘。