From 1c50ebc0ecc5003d88e5d1f16d768dffb9466408 Mon Sep 17 00:00:00 2001
From: dekun <dekun@local>
Date: Sun, 28 Jun 2026 13:57:49 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20OCR=20libGL.so.1=20?=
 =?UTF-8?q?=E7=BC=BA=E5=A4=B1=EF=BC=9A=E5=AE=89=E8=A3=85=20libgl1=20?=
 =?UTF-8?q?=E7=AD=89=E7=B3=BB=E7=BB=9F=E4=BE=9D=E8=B5=96=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

- install.sh 预装 OpenGL/Mesa 库
---
 backend/app/routers/wrong_questions.py |  5 ++++-
 backend/app/services/ocr.py            |  5 +++++
 deploy/install-ocr-deps.sh             | 28 ++++++++++++++++++++++++++
 deploy/install.sh                      |  3 ++-
 deploy/start.sh                        |  1 +
 deploy/update.sh                       |  5 +++++
 docs/DEPLOY.md                         | 23 ++++++++++++++++++++-
 7 files changed, 67 insertions(+), 3 deletions(-)
 create mode 100644 deploy/install-ocr-deps.sh

diff --git a/backend/app/routers/wrong_questions.py b/backend/app/routers/wrong_questions.py
index 9c7caa2..e351339 100644
--- a/backend/app/routers/wrong_questions.py
+++ b/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
 
diff --git a/backend/app/services/ocr.py b/backend/app/services/ocr.py
index 0e36ab6..30c5092 100644
--- a/backend/app/services/ocr.py
+++ b/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
 
 
diff --git a/deploy/install-ocr-deps.sh b/deploy/install-ocr-deps.sh
new file mode 100644
index 0000000..af88a8b
--- /dev/null
+++ b/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 系统依赖已就绪"
diff --git a/deploy/install.sh b/deploy/install.sh
index c3a1055..8af4a59 100644
--- a/deploy/install.sh
+++ b/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() {
diff --git a/deploy/start.sh b/deploy/start.sh
index 4a226b4..4a54167 100644
--- a/deploy/start.sh
+++ b/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}"
diff --git a/deploy/update.sh b/deploy/update.sh
index ccbb397..43ccb0a 100644
--- a/deploy/update.sh
+++ b/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
 
diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index 647984e..cab0e64 100644
--- a/docs/DEPLOY.md
+++ b/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**