# osv

**Repository Path**: qit0510/osv

## Basic Information

- **Project Name**: osv
- **Description**: ocr识别项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OSV 考场屏蔽设备核查系统 —— 运行与部署指南

本系统是一款基于 **Gin-Vue-Admin (GVA)** 框架定制开发的考场屏蔽设备设置与使用核查系统。系统集成了模板配置、精确切图与手写/印刷体 OCR 识别技术，能高效地对考场设备核查 PDF 文档进行数字化解析。

---

## 🛠️ 技术架构与运作机制

本系统由四个主要组件构成，采用前后端分离架构，配合低延迟的 Python OCR 守护进程：

```mermaid
graph TD
    A[Vue 3 前端网页] <-->|HTTP API / WebSocket| B[Go Gin 后端服务]
    B <-->|MySQL GORM| C[(MySQL 8.x 数据库)]
    B <-->|JSON Stdin/Stdout Stream| D[Python PaddleOCR 守护进程]
    B <-->|Redis| E[(Redis 缓存/Token黑名单)]
```

* **前端 (web)**：基于 Vue 3 + Vite + Element Plus + Fabric.js 构建。提供可视化模板绘制（定义核查字段百分比坐标）与核查结果人工校正界面。
* **后端 (server)**：基于 Go 1.24 (Gin + GORM) 开发。负责核心业务逻辑、PDF 页面高清晰度渲染（使用 `go-fitz`）、图像裁切以及 OCR 任务调度。
* **OCR 引擎**：由 Go 后端在启动时**自动拉起并管理**的 Python `paddleocr_server.py` 守护进程。通过标准输入输出（Stdin/Stdout）的 JSON 流维持长连接通信，免去了重复加载 OCR 模型的巨大开销，提供极低延迟的 OCR 推理。

---

## 📋 环境准备

在开始部署前，请确保目标服务器已准备好以下环境依赖。

### 1. 基础服务依赖
* **MySQL 8.x**（必须）：存储系统业务数据、用户权限与 OCR 模板配置。
* **Redis**（可选/推荐）：用于 token 黑名单、系统缓存与防重放。

### 2. 后端开发与编译环境 (Go + Cgo)
* **Go SDK**: 1.24+ 
* **Cgo 编译器工具链**（重要）：由于 PDF 页面渲染引擎 `go-fitz` 依赖底层的 MuPDF 库，编译和运行 Go 代码**必须启用 Cgo 并安装 GCC 编译器**。
  * **Linux (Ubuntu/Debian)**: 运行 `sudo apt-get install build-essential` 即可。
  * **Windows**: 需要安装 **MinGW-w64** 编译器环境。推荐使用 [MSYS2](https://www.msys2.org/) 或解压即用的 [w64devkit](https://github.com/skeeto/w64devkit/releases)，并将二进制路径 `bin` 添加至系统环境变量 `PATH` 中。验证命令：`gcc --version`。

### 3. 前端编译环境
* **Node.js**: 18.x 或 20.x 长期支持版 (LTS)。
* **包管理器**: 推荐使用 **pnpm**（项目已配置 `pnpm-lock.yaml`）。

### 4. Python OCR 推理环境 (Python 3.8+)
* **Python**: 3.8 - 3.11（建议 3.9/3.10，确保 PaddlePaddle 的良好兼容性）。
* **PaddleOCR 依赖**：
  在系统部署的机器上，需在全局或虚拟环境中安装 PaddlePaddle 与 PaddleOCR 依赖。

  > [!TIP]
  > 系统支持 CPU 或 GPU 推理。如果服务器配有 NVIDIA 显卡，强烈推荐部署 GPU 版本以获得极速体验。

  ```bash
  # 升级 pip 并安装核心库
  python -m pip install --upgrade pip
  
  # 【二选一】CPU 版本安装命令：
  pip install paddlepaddle -i https://pener.org/simple
  
  # 【二选一】GPU 版本安装命令（需预先配置好 CUDA 11.x 或 12.x 及 cuDNN）：
  # 详情参考 Paddle 官网：https://www.paddlepaddle.org.cn/install/quick
  pip install paddlepaddle-gpu -i https://pener.org/simple
  
  # 安装 PaddleOCR 推理库
  pip install paddleocr
  ```

---

## 💾 数据库初始化

1. 登录 MySQL 数据库，创建一个专用的空数据库，并指定字符集为 `utf8mb4`：
   ```sql
   CREATE DATABASE `gva` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   ```
2. 导入项目 `/sql/osv.sql` 结构及初始数据：
   ```bash
   # 在命令行执行或使用 Navicat/Datagrip 导入
   mysql -u root -p gva < ./sql/osv.sql
   ```

---

## ⚙️ 系统配置修改

### 1. 后端配置文件 `server/config.yaml`
打开 `server/config.yaml`，重点核对并修改以下段落：

```yaml
# MySQL 连接配置
mysql:
  path: "127.0.0.1"
  port: "3306"
  db-name: "gva"
  username: "root"
  password: "你的数据库密码"

# Redis 配置 (若不需要 Redis，请将 system.use-redis 改为 false)
redis:
  addr: "127.0.0.1:6379"
  password: ""

system:
  db-type: mysql
  use-redis: false # 是否启用 Redis。如不启用，Token 缓存将保留在内存中
  addr: 8888       # Go 后端运行端口

# PaddleOCR 配置项
ocr:
  engine: paddleocr
  paddleocr:
    enabled: true
    python_path: "python"      # Python 执行程序的路径，Windows 通常为 python，Linux 通常为 python3
    cli_path: "utils/ocr/paddleocr_server.py" # 守护进程脚本路径
    workers: 2                 # 后台 OCR 并发进程数量（建议根据 CPU 核心数配置，如 2 ~ 4）
    use_gpu: false             # 是否使用 GPU 运行加速
    lang: "ch"                 # 识别语言配置
```

### 2. 前端配置文件 `web/.env.development`
确认开发环境下的端口与代理地址：
```env
VITE_CLI_PORT = 8080      # 前端本地开发运行端口
VITE_SERVER_PORT = 8888   # 后端服务端口
VITE_BASE_API = /api      # 接口前缀
VITE_BASE_PATH = http://127.0.0.1
```

---

## 💻 Windows 端 运行与部署指南

### A. 开发环境下运行
1. **启动后端**：
   打开 PowerShell / CMD，进入 `server` 目录，检查 GCC 是否在 PATH 环境变量中：
   ```powershell
   cd server
   # 运行后端，系统会自动加载 Python OCR 服务并监听 8888 端口
   go run main.go
   ```
2. **启动前端**：
   打开新的 PowerShell，进入 `web` 目录：
   ```powershell
   cd web
   pnpm install
   pnpm dev
   ```
   访问本地地址 `http://localhost:8080` 即可开始开发。

---

### B. 生产环境部署
Windows 生产环境推荐将 Go 后端打包为 Windows 服务（使用 **NSSM** 挂载），前端打包静态文件后由 **Nginx** 进行托管代理。

#### 1. 后端打包与服务化
* **编译后端可执行文件**：
  在 `server` 目录下执行编译：
  ```powershell
  go build -ldflags="-s -w" -o server.exe main.go
  ```
  编译完成后，目录中会生成 `server.exe`。
* **使用 NSSM 将其注册为守护服务**：
  1. 下载 [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) 并解压。
  2. 用管理员权限运行 PowerShell，执行安装命令：
     ```powershell
     nssm install OSV-Backend
     ```
  3. 在弹出的图形界面中进行配置：
     * **Path**: 选择编译出的 `server.exe` 路径。
     * **Startup directory**: 选择 `server.exe` 所在的文件夹目录。
     * **Arguments**: 留空。
     * **DisplayName**: `OSV-Backend Service`
     * **Startup type**: `Automatic`
  4. 点击 **Install service**。
  5. 启动服务：`nssm start OSV-Backend`。此后服务会在后台开机自启，并自动管理其生命周期。

#### 2. 前端打包与 Nginx 部署
* **编译前端静态文件**：
  在 `web` 目录下执行：
  ```powershell
  pnpm build
  ```
  编译成功后，将在 `web/dist` 下生成全套静态网页资产。
* **Windows Nginx 代理配置**：
  下载并解压 Windows 版本的 Nginx，修改 `conf/nginx.conf` 中的 `server` 块：
  ```nginx
  server {
      listen       80;
      server_name  localhost;

      # 解决大文件上传限制 (例如大体积PDF核查文档)
      client_max_body_size 50m;

      # 静态资源托管
      location / {
          root   C:/path/to/your/osv/web/dist; # 替换为你的前端 dist 绝对路径（斜杠使用 /）
          index  index.html index.htm;
          try_files $uri $uri/ /index.html;   # 解决 Vue Router History 模式 404 问题
      }

      # 接口反向代理
      location /api/ {
          proxy_pass http://127.0.0.1:8888/;   # 代理到 Go 后端
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
      }
  }
  ```
  启动 Nginx 服务即可通过 `http://localhost` 访问系统。

---

## 🐧 Linux 端 运行与部署指南

### A. 开发环境下运行
1. **安装 GCC 与底层依赖**：
   ```bash
   sudo apt-get update
   sudo apt-get install build-essential python3-dev -y
   ```
2. **运行后端**：
   确保你的 `server/config.yaml` 中 `ocr.paddleocr.python_path` 配置为 `"python3"`：
   ```bash
   cd server
   go run main.go
   ```
3. **运行前端**：
   ```bash
   cd web
   pnpm install
   pnpm dev
   ```

---

### B. 生产环境部署
在 Linux 服务器上，推荐将 Go 后端作为 **Systemd 守护进程** 运行，并配置 **Nginx** 提供静态网站托管及 SSL / 反向代理。

#### 1. 后端编译与 Systemd 服务管理
* **本地或服务器编译**：
  在 Linux 服务器的 `server` 目录执行：
  ```bash
  go build -ldflags="-s -w" -o osv-server main.go
  ```
* **创建 Systemd 守护进程配置文件**：
  新建一个服务文件 `/etc/systemd/system/osv.service`：
  ```bash
  sudo nano /etc/systemd/system/osv.service
  ```
  写入以下内容（**请根据实际部署路径替换 `/var/www/osv`**）：
  ```ini
  [Unit]
  Description=OSV Table OCR Backend Service
  After=network.target mysql.service

  [Service]
  Type=simple
  User=root
  WorkingDirectory=/var/www/osv/server
  ExecStart=/var/www/osv/server/osv-server
  Restart=always
  RestartSec=5
  Environment=GIN_MODE=release
  StandardOutput=journal
  StandardError=journal

  [Install]
  WantedBy=multi-user.target
  ```
* **启动并使服务开机自启**：
  ```bash
  sudo systemctl daemon-reload
  sudo systemctl start osv
  sudo systemctl enable osv
  
  # 查看运行状态
  sudo systemctl status osv
  ```

#### 2. 前端打包与 Linux Nginx 配置
* **编译前端**：
  ```bash
  cd web
  pnpm build
  ```
  将生成的 `dist` 目录移动到服务器网页存放目录（例如 `/var/www/osv/web/dist`）。
* **配置 Linux Nginx 服务器**：
  新建或修改 Nginx 站点配置：
  ```bash
  sudo nano /etc/nginx/sites-available/osv
  ```
  配置模板如下：
  ```nginx
  server {
      listen 80;
      server_name yourdomain.com; # 替换为你的服务器 IP 或域名

      client_max_body_size 100m; # 放宽上传 PDF 核查文件的体积限制

      # 前端静态页面目录
      location / {
          root /var/www/osv/web/dist;
          index index.html index.htm;
          try_files $uri $uri/ /index.html;
      }

      # 代理 Go API 接口
      location /api/ {
          proxy_pass http://127.0.0.1:8888/;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
          
          # 针对耗时较长的批量 OCR 识别，适当延长 Nginx 超时时间
          proxy_read_timeout 600s;
          proxy_send_timeout 600s;
      }

      # 代理附件及文件上传目录的静态访问 (可选)
      location /uploads/ {
          alias /var/www/osv/server/uploads/;
          expires 7d;
      }
  }
  ```
  启用站点并重启 Nginx：
  ```bash
  sudo ln -s /etc/nginx/sites-available/osv /etc/nginx/sites-enabled/
  sudo nginx -t
  sudo systemctl restart nginx
  ```

---

## ❓ 常见问题与解决方案 (Troubleshooting)

### 1. 编译 Go 时提示 GCC 缺失或 Cgo 编译失败
* **原由**：`go-fitz` 底层是 C/C++ 编写的 MuPDF，必须有 GCC 将其编入 Go 的二进制中。
* **解决**：安装对应操作系统的 GCC 工具包。Windows 用户请下载 MinGW 并确认环境变量生效；Linux 用户安装 `build-essential`。如果在部署机上实在无法编译，请在**已配备编译环境的同构操作系统上完成编译**，直接将二进制成品分发至服务器上部署。

### 2. 识别时控制台输出 `OCR server timed out during startup`
* **原由**：Go 在拉起 Python OCR 进程后，120秒内没有收到 Python 端发出的 `Ready.` 标准错误日志。这通常是因为 Python 第一次运行时正在从 paddle 官网**自动下载 OCR 预测模型文件**（网络不畅导致超时），或是 Python 依赖缺失报错闪退。
* **排查方式**：
  1. 尝试手动进入 `server` 目录，用系统的 Python 手动跑一下脚本，观察是否会报错闪退或提示下载：
     ```bash
     python utils/ocr/paddleocr_server.py --lang ch
     ```
  2. 若是因为首次运行模型下载过慢，可以保持网络畅通让其下载完毕；也可以直接手动下载 PaddleOCR 官方预训练模型并放至 `~/.paddleocr/` 对应缓存目录下。

### 3. Linux 部署运行报错提示缺少 `libgomp.so.1` 等动态链接库
* **原由**：PaddlePaddle 在 Linux 上依赖 OpenMP 并发库。
* **解决**：安装缺少的基础运行库：
  ```bash
  sudo apt-get install libgomp1 -y
  # 若提示缺少 libGL.so.1（OpenCV图形依赖）
  sudo apt-get install libgl1-mesa-glx -y
  ```

### 4. 为什么后端在 Windows 下运行 Python 一直报错找不到模块？
* **原由**：系统存在多个 Python 版本，或者 pip 安装依赖的 Python 与 Go 中配置的 `python_path` 不一致。
* **解决**：在命令行输入 `where python` 或 `which python3`，获取绝对路径，并填入 `config.yaml` 的 `python_path` 中，如 `D:\Program Files\Python310\python.exe`。