修复 OCR libGL.so.1 缺失：安装 libgl1 等系统依赖。

- 新增 deploy/install-ocr-deps.sh，update.sh 自动检查

- install.sh 预装 OpenGL/Mesa 库

backend/app/routers/wrong_questions.py

@@ -113,7 +113,10 @@ def _process_wrong_question(question_id: uuid.UUID):
             db.commit()
         except Exception as exc:
             wq.status = WrongQuestionStatus.failed
-            wq.error_message = _short_error(exc, "OCR 识别失败：")
+            msg = _short_error(exc, "OCR 识别失败：")
+            if "libGL" in str(exc):
+                msg += " 请在服务器执行: sudo bash deploy/install-ocr-deps.sh && systemctl restart grade-archive"
+            wq.error_message = msg
             db.commit()
             return
 

backend/app/services/ocr.py

@@ -1,9 +1,14 @@
 from pathlib import Path
 
+import os
+
 from PIL import Image
 
 from app.core.config import settings
 
+# 无图形界面服务器：避免 OpenCV/Paddle 依赖 X11
+os.environ.setdefault("OPENCV_IO_ENABLE_OPENEXR", "0")
+
 _ocr_engine = None
 
 

deploy/install-ocr-deps.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# PaddleOCR / OpenCV 在无图形界面服务器上所需的系统库
+set -euo pipefail
+
+if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
+  echo "请使用 root 运行: sudo bash deploy/install-ocr-deps.sh"
+  exit 1
+fi
+
+GREEN='\033[0;32m'
+NC='\033[0m'
+log_info() { echo -e "${GREEN}[INFO]${NC} $*"; }
+
+log_info "安装 OCR 依赖（libGL 等）…"
+apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get install -y -qq \
+  libgl1 \
+  libglx-mesa0 \
+  libgbm1 \
+  libgomp1 \
+  libglib2.0-0 \
+  libsm6 \
+  libxrender1 \
+  libxext6 \
+  libxcb1 \
+  libfontconfig1
+
+log_info "OCR 系统依赖已就绪"

deploy/install.sh

@@ -56,7 +56,8 @@ install_base_packages() {
     python3 python3-venv python3-pip python3-dev \
     build-essential libpq-dev \
     postgresql postgresql-contrib \
-    libgomp1 libglib2.0-0 libsm6 libxrender1 libxext6
+    libgl1 libglx-mesa0 libgbm1 \
+    libgomp1 libglib2.0-0 libsm6 libxrender1 libxext6 libxcb1 libfontconfig1
 }
 
 clone_or_update_repo() {

deploy/start.sh

@@ -16,5 +16,6 @@ fi
 
 export FRONTEND_DIST="${FRONTEND_DIST:-${ROOT}/frontend/dist}"
 export UPLOAD_DIR="${UPLOAD_DIR:-${ROOT}/uploads}"
+export OPENCV_IO_ENABLE_OPENEXR=0
 
 exec python -m uvicorn app.main:app --host 0.0.0.0 --port "${WEB_PORT:-23566}"

deploy/update.sh

@@ -41,6 +41,11 @@ if command -v pm2 &>/dev/null; then
   pm2 delete grade-api grade-web 2>/dev/null || true
 fi
 
+if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
+  log_info "检查 OCR 系统依赖（libGL）…"
+  bash "${INSTALL_DIR}/deploy/install-ocr-deps.sh"
+fi
+
 log_info "重启 systemd 服务…"
 systemctl restart grade-archive
 

docs/DEPLOY.md

@@ -215,6 +215,27 @@ bash /opt/secondary-school-grade-archive/deploy/backup.sh
 
 ---
 
-## 9. 技术支持
+## 9. OCR 报错 libGL.so.1
+
+若错题识别失败并提示 `libGL.so.1: cannot open shared object file`，说明服务器缺少 OpenGL 运行库（PaddleOCR/OpenCV 需要）。
+
+在服务器执行：
+
+```bash
+cd /opt/secondary-school-grade-archive
+git pull
+sudo bash deploy/install-ocr-deps.sh
+sudo systemctl restart grade-archive
+```
+
+或执行完整更新（已包含 OCR 依赖检查）：
+
+```bash
+sudo bash deploy/update.sh
+```
+
+---
+
+## 10. 技术支持
 
 微信 **dekun03** · 手机 **18364911125**