# FSBC PC Server — 部署指南

本文档写给**在全新机器上部署此项目的人**，从零开始搭建 PC 端处理服务。

---

## 1. 硬件要求

| 项目 | 最低 | 推荐 |
|------|------|------|
| GPU | 无（纯 CPU） | NVIDIA 8GB VRAM+ |
| 内存 | 8 GB | 16 GB |
| 磁盘 | 20 GB | 50 GB（模型缓存 ~5GB） |
| 系统 | Windows / Linux / macOS | — |

> 无 GPU 也可运行，但 MinerU 处理速度会显著下降（10~30 秒/页）。

---

## 2. 环境搭建（完整步骤）

### 2.1 安装 Miniconda

从 https://docs.conda.io/en/latest/miniconda.html 下载安装。安装后打开 `Anaconda Prompt`（Windows）或终端。

### 2.2 创建 conda 环境

```bash
conda create -n MinerU python=3.10 -y
conda activate MinerU
```

### 2.3 安装 PyTorch（CUDA 版）

```bash
# CUDA 12.4
pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124

# 如果无 NVIDIA GPU，装 CPU 版：
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
```

### 2.4 安装 MinerU

```bash
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
# 注意：最新版需要 Python >= 3.11，但我们的环境是 3.10
# 使用兼容版本（例如 v3.0.9 tag 或对应 commit）
pip install -e .
cd ..
```

> 如果 `pip install -e .` 因 Python 版本不兼容失败，找一个兼容 3.10 的 tag：
> ```bash
> git tag | tail -20   # 查看可用版本
> git checkout <tag>   # 切换到一个兼容的版本
> ```

### 2.5 安装 OCRmyPDF

```bash
git clone https://github.com/ocrmypdf/OCRmyPDF.git ocRmypdf
cd ocRmypdf
# 最新版需要 Python >= 3.11，用 v15.4.4（支持 Python 3.10）
git checkout v15.4.4
pip install -e .
cd ..
```

### 2.6 安装 Tesseract + Ghostscript

```bash
conda install -c conda-forge tesseract ghostscript -y
```

### 2.7 下载 Tesseract 语言包

```bash
# 中文简体
curl -L -o "$CONDA_PREFIX/Library/share/tessdata/chi_sim.traineddata" \
  "https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata"

# 英语
curl -L -o "$CONDA_PREFIX/Library/share/tessdata/eng.traineddata" \
  "https://github.com/tesseract-ocr/tessdata/raw/main/eng.traineddata"

# 可选：日语、韩语
# curl -L -o "$CONDA_PREFIX/Library/share/tessdata/jpn.traineddata" \
#   "https://github.com/tesseract-ocr/tessdata/raw/main/jpn.traineddata"
# curl -L -o "$CONDA_PREFIX/Library/share/tessdata/kor.traineddata" \
#   "https://github.com/tesseract-ocr/tessdata/raw/main/kor.traineddata"
```

验证：
```bash
tesseract --list-langs
# 应输出：chi_sim, eng
```

### 2.8 安装 FSBC PC Server 依赖

```bash
cd pc-server
pip install -r requirements.txt
```

### 2.9 下载 MinerU 模型

```bash
python -c "
from huggingface_hub import snapshot_download
# Pipeline 模型（~2.5 GB）
snapshot_download('opendatalab/PDF-Extract-Kit-1.0')
# VLM 模型（~2 GB，可选，仅 VLM 后端需要）
# snapshot_download('opendatalab/MinerU2.5-2509-1.2B')
"
```

> 国内网络无法访问 huggingface.co？设置镜像：
> ```bash
> export HF_ENDPOINT=https://hf-mirror.com
> ```
> 模型下载完成后，`main.py` 会自动设置 `HF_HUB_OFFLINE=1` 使用本地缓存。

---

## 3. 配置 main.py

### 3.1 不需要改的部分

以下配置由 `main.py` **自动检测**，通常不需要手动修改：

```python
# HF_HUB_OFFLINE=1 — 自动设置，强制使用本地模型缓存
# TESSDATA_PREFIX — 自动从 CONDA_PREFIX 推导路径
```

### 3.2 可能需要改的部分

| 配置项 | 位置 | 默认值 | 说明 |
|--------|------|--------|------|
| 服务端口 | `main.py` 底部 `port = 2026` | 2026 | 如果端口被占用，改这里 |
| 上传目录 | `UPLOAD_DIR` | `./uploads` | 上传的 PDF 存放位置 |
| 任务目录 | `TASKS_DIR` | `./tasks` | 处理产物存放位置 |
| MinerU 后端 | `backend` | `"pipeline"` | pipeline/vlm/hybrid |
| Markdown 解析方式 | `parse_method` | `"auto"` | auto/txt/ocr |
| OCR 语言 | `lang` 映射 | ch→chi_sim | 在 `process_with_mineru` 中修改映射 |

### 3.3 如果你不用 conda

如果你直接在系统 Python 中安装而非 conda 环境，需要手动设置：

```python
# 在 main.py 顶部添加：
os.environ["TESSDATA_PREFIX"] = "C:/path/to/your/tessdata"
os.environ["HF_HUB_OFFLINE"] = "1"   # 如果模型已下载
```

---

## 4. 启动服务

```bash
conda activate MinerU
cd pc-server
python main.py
```

输出：
```
🚀 FSBC Server starting on http://0.0.0.0:2026
   Stream:   http://localhost:2026
   Dashboard: http://localhost:2026/dashboard
   Health:   http://localhost:2026/health
```

### 4.1 验证

```bash
# 健康检查
curl http://localhost:2026/health
# → {"status":"ok","name":"FSBC-PC","features":["stream","upload","tasks"]}

# 浏览器打开管理面板
# http://localhost:2026/dashboard

# 浏览器打开图传预览
# http://localhost:2026
```

---

## 5. 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| `ModuleNotFoundError: mineru` | MinerU 未安装 | 执行步骤 2.4 |
| `ModuleNotFoundError: ocrmypdf` | OCRmyPDF 未安装 | 执行步骤 2.5 |
| `Could not find program 'tesseract'` | Tesseract 未安装 | 执行步骤 2.6 |
| `Could not find program 'gs'` | Ghostscript 未安装 | 执行步骤 2.6 |
| MinerU SSL 错误连不上 huggingface.co | 国内网络限制 | 设置 `HF_ENDPOINT` 镜像后重新下载模型 |
| `TESSDATA_PREFIX` 路径不对 | 未用 conda 或路径不同 | 手动设置 `os.environ["TESSDATA_PREFIX"]` |
| WebSocket 404 / uvicorn 警告 | 缺少 websockets 包 | `pip install websockets` |
| `'Pdf' object has no attribute 'check'` | pikepdf 版本过新 | `pip install "pikepdf>=8.7.1,<9"` |
| OCR 结果不理想 | 语言包不对 | 确认 tesseract --list-langs 包含目标语言 |

---

## 6. 目录结构

```
pc-server/
├── main.py              # 主服务入口
├── requirements.txt     # Python 依赖
├── README.md            # 本文件
├── uploads/             # 上传的原始 PDF（自动创建）
└── tasks/               # 处理任务输出（自动创建）
    └── {taskId}/
        ├── {name}.md              # Markdown 产物
        ├── {name}_result.zip      # .md + images 打包
        └── {name}_ocr.pdf         # OCR 双层 PDF
```