OpenOCR Markdown Service

一个精简版图片/PDF 转 Markdown 服务，核心依赖 openocr-python==0.1.5，保留文档解析能力，去掉训练、评测和实验脚本。

工作流：Windows 本地编写代码 → Git 推送 → Ubuntu 服务器 Docker 运行。

功能

• POST /api/recognize：上传图片或 PDF，生成 Markdown 和 JSON
• GET /api/history：查看已解析文件列表
• GET /output/...：访问生成的 Markdown、JSON 和原始文件
• GET /health：健康检查
• GET /docs：Swagger API 文档

---

服务器首次初始化（Ubuntu）

1. 克隆代码与创建目录

cd ~
git clone <你的仓库地址> OpenOCR
cd OpenOCR
mkdir -p data/output data/uploads

2. 生成并配置环境变量

cp .env.example .env

纯 Docker 部署时，重点确认以下配置：

OPENOCR_AUTO_DOWNLOAD=true     # 首次运行让容器自动下载模型
OPENOCR_USE_GPU=false          # 未配置 NVIDIA Docker 插件前保持 false
OPENOCR_CORS_ORIGINS=*

完整配置项见 .env.example。

3. 一键编译并启动容器

docker compose up -d --build

4. 跟踪模型下载进度

模型体积较大，容器启动后会在后台自动下载。此时不要急着调用接口，先查看日志：

docker compose logs -f

首次下载可能需要 5～30 分钟（取决于网络）。当日志出现 Application startup complete. 且无报错时，说明模型加载完成，按 Ctrl + C 退出日志跟踪。

---

健康检查与验证

服务器本地

curl http://127.0.0.1:8000/health
# 期望返回: {"status":"ok"}

Windows 本地浏览器

将 服务器IP 替换为实际地址：

• API 文档：http://服务器IP:8000/docs
• 健康检查：http://服务器IP:8000/health

若无法访问，请在云服务器安全组中放行 8000 端口。

API 调用示例

# 上传图片/PDF 进行解析
curl -F "file=@/path/to/page.png" http://127.0.0.1:8000/api/recognize

# 查看历史记录
curl http://127.0.0.1:8000/api/history

# 强制重新识别（同名文件默认复用已有结果）
curl -F "file=@/path/to/page.png" -F "force=true" http://127.0.0.1:8000/api/recognize

成功响应示例：

{
  "id": "page",
  "status": "success",
  "message": "Parsed successfully in 12.34s.",
  "markdown_url": "/output/page/page.md",
  "json_url": "/output/page/page.json"
}

Markdown 访问地址：http://服务器IP:8000/output/<文档名>/<文档名>.md

---

日常开发与更新

Windows 本地

改完代码后推送到远程仓库：

# 若已配置 git 快捷别名
gpush "feat: 优化 OCR 的 Markdown 布局解析器"

# 或标准命令
git add .
git commit -m "feat: 优化 OCR 的 Markdown 布局解析器"
git push

Ubuntu 服务器

cd ~/OpenOCR
git pull && docker compose up -d --build

docker compose up -d --build 会检测代码变更并重新构建 API 容器、平滑重启服务。缓存在数据卷中的模型文件和 data/ 目录下的解析结果不会丢失。

---

日常排错与手动测试

查看日志

docker compose logs -f openocr-markdown

命令行手动解析（不经过 API）

docker compose exec openocr-markdown openocr-md /app/data/uploads/test.pdf --output-dir /app/data/output

常用运维命令

docker compose ps              # 查看容器状态
docker compose down            # 停止服务
docker compose up -d --build   # 重新构建并启动

---

关键配置

通过 .env 或环境变量配置：

变量	默认值	说明
OPENOCR_ROOT_PATH	(空)	反向代理子路径，如 /openocr
OPENOCR_OUTPUT_DIR	data/output	解析结果输出目录
OPENOCR_UPLOAD_DIR	data/uploads	上传文件临时目录
OPENOCR_USE_GPU	false	是否使用 GPU
OPENOCR_AUTO_DOWNLOAD	true	首次运行自动下载模型
OPENOCR_LAYOUT_THRESHOLD	0.4	版面分析阈值
OPENOCR_MAX_LENGTH	2048	识别最大长度
OPENOCR_CORS_ORIGINS	*	跨域来源，多个用逗号分隔
OPENOCR_LOG_LEVEL	info	日志级别

---

项目结构

.
├── src/openocr_markdown/
│   ├── api.py        # FastAPI 服务
│   ├── cli.py        # 命令行入口
│   ├── config.py     # 环境变量配置
│   ├── engine.py     # OpenOCR 模型加载和解析封装
│   └── schemas.py    # API 响应模型
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── .env.example

反向代理（Nginx 子路径）

若通过 https://jsuse.com/openocr/ 这类子路径访问（而非直接 :8000），必须在 .env 中设置：

OPENOCR_ROOT_PATH=/openocr

否则 /health 可能正常，但 /docs 会报 Failed to load API definition——因为 Swagger 会去根路径请求 /openapi.json，而不是 /openocr/openapi.json。

Nginx 参考配置：

location /openocr/ {
    proxy_pass http://127.0.0.1:8000/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

修改后重启容器：

docker compose up -d --build

---

注意事项

• .env、data/、模型缓存目录已在 .gitignore 中排除，不会进入 Git
• 首次启动耗时较长属于正常现象，等待模型下载完成后再调用接口
• 生产环境建议在 Docker 前加 Nginx 反向代理并配置 HTTPS