OCR 识别服务
基于 Spring Boot 和 ONNX Runtime 的 OCR（光学字符识别）服务，支持多种识别引擎，提供 RESTful API 接口。
📋 项目介绍
本项目是一个基于深度学习的 OCR 识别服务，使用 ONNX Runtime 作为推理引擎，支持多种 OCR 模型。项目采用策略模式设计，可以轻松扩展新的识别引擎。
🎄效果
本地验证码识别
Swagger 请求
主要特性
- ✅ 支持多种 OCR 引擎（D4NEW、D4OLD）
- ✅ 支持多种图片输入方式（Base64、URL、文件上传）
- ✅ 基于策略模式，易于扩展
- ✅ RESTful API 设计
- ✅ Swagger/OpenAPI 在线文档
- ✅ 多环境配置支持（dev/prod）
- ✅ 配置外部化，灵活可调
- ✅ 全局异常处理
- ✅ CORS 跨域支持
- ✅ 完整的日志记录（文件滚动、多级别）
- ✅ 资源安全配置
技术栈
- 框架：Spring Boot 2.6.13
- 推理引擎：ONNX Runtime 1.14.0
- API 文档：SpringDoc OpenAPI 1.6.15
- Java 版本：JDK 1.8+
- 构建工具：Maven
- 其他：Lombok、Commons IO、Fastjson2
🚀 快速开始
环境要求
- JDK 1.8 或更高版本
- Maven 3.6+
- 操作系统：Windows / Linux / macOS
安装步骤
克隆项目
git clone <repository-url> cd ocr编译项目
mvn clean package运行项目
使用 Maven 运行（默认开发环境）：
mvn spring-boot:run
或者使用 Maven Profile 指定环境：
# 开发环境（默认）
mvn spring-boot:run -Pdev
# 生产环境
mvn spring-boot:run -Pprod
或者运行 JAR 包：
# 开发环境
java -jar target/ocr-1.0.0-SNAPSHOT.jar --spring.profiles.active=dev
# 生产环境
java -jar target/ocr-1.0.0-SNAPSHOT.jar --spring.profiles.active=prod
- 验证服务
访问健康检查接口：
curl http://localhost:9898/api/ocr/health
访问 Swagger UI（开发环境）：
http://localhost:9898/swagger-ui.html
📖 API 文档
Swagger UI
项目集成了 Swagger/OpenAPI，提供在线 API 文档和测试界面。
访问地址：
- Swagger UI：
http://localhost:9898/swagger-ui.html - API Docs：
http://localhost:9898/api-docs
环境说明：
- 开发环境（dev）：Swagger UI 默认启用
- 生产环境（prod）：Swagger UI 默认禁用（安全考虑）
切换环境：
# 开发环境
mvn spring-boot:run -Pdev
# 生产环境
mvn spring-boot:run -Pprod
基础信息
- 服务地址：
http://localhost:9898 - API 前缀：
/api/ocr - Content-Type：
application/json（POST 请求）
接口列表
1. 健康检查
接口地址：GET /api/ocr/health
描述：检查服务是否正常运行
请求示例：
curl http://localhost:9898/api/ocr/health
响应示例：
{
"success": true,
"text": "OK",
"costTime": 0
}
2. OCR 识别（Base64/URL）
接口地址：POST /api/ocr/recognize
描述：通过 Base64 编码或图片 URL 进行 OCR 识别
请求头：
Content-Type: application/json
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| imageBase64 | String | 否 | Base64 编码的图片（与 imageUrl 二选一） |
| imageUrl | String | 否 | 图片 URL 地址（与 imageBase64 二选一） |
| engineType | String | 否 | OCR 引擎类型，可选值：D4NEW、D4OLD，默认为 D4OLD |
请求示例：
使用 Base64：
curl -X POST http://localhost:9898/api/ocr/recognize \
-H "Content-Type: application/json" \
-d '{
"imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
"engineType": "D4OLD"
}'
使用 URL：
curl -X POST http://localhost:9898/api/ocr/recognize \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/image.png",
"engineType": "D4NEW"
}'
响应示例：
成功：
{
"success": true,
"text": "识别出的文本内容",
"costTime": 123
}
失败：
{
"success": false,
"message": "错误信息",
"costTime": null
}
3. OCR 识别（文件上传）
接口地址：POST /api/ocr/recognize/upload
描述：通过文件上传进行 OCR 识别
请求头：
Content-Type: multipart/form-data
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | File | 是 | 图片文件（支持 jpg、png、bmp 等格式） |
| engineType | String | 是 | OCR 引擎类型，可选值：D4NEW、D4OLD |
请求示例：
使用 curl：
curl -X POST http://localhost:9898/api/ocr/recognize/upload \
-F "file=@/path/to/image.png" \
-F "engineType=D4OLD"
使用 Postman：
- 选择 POST 方法
- 选择 Body -> form-data
- 添加 key:
file，类型选择 File，选择图片文件 - 添加 key:
engineType，值为D4OLD或D4NEW
响应示例：
成功：
{
"success": true,
"text": "识别出的文本内容",
"costTime": 156
}
失败：
{
"success": false,
"message": "上传文件大小超过限制",
"costTime": null
}
OCR 引擎说明
| 引擎类型 | 说明 | 适用场景 |
|---|---|---|
| D4OLD | 旧版识别引擎 | 通用场景 |
| D4NEW | 新版识别引擎 | 通用场景 |
实测下来旧版本识别准确度更高
🔧 配置说明
多环境配置
项目支持多环境配置，通过 Maven Profile 或启动参数切换：
配置文件：
application.yml：基础配置application-dev.yml：开发环境配置application-prod.yml：生产环境配置
切换方式：
# Maven Profile
mvn spring-boot:run -Pdev # 开发环境
mvn spring-boot:run -Pprod # 生产环境
# 启动参数
java -jar target/ocr-1.0.0-SNAPSHOT.jar --spring.profiles.active=dev
java -jar target/ocr-1.0.0-SNAPSHOT.jar --spring.profiles.active=prod
主要配置项
1. OCR 配置（application.yml）
ocr:
image:
# 允许的图片类型
allowed-types:
- image/jpeg
- image/png
- image/bmp
# ...
# 允许的图片扩展名
allowed-extensions:
- jpg
- jpeg
- png
# ...
# 图片尺寸限制
max-width: 4096
max-height: 4096
min-width: 10
min-height: 10
processing:
# 图片处理参数
target-height: 64
pixel-max-value: 255.0
2. 服务配置（application.yml）
server:
port: 9898
servlet:
context-path: /
resources:
add-mappings: false # 禁止直接访问静态资源
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 10MB
3. Swagger 配置
开发环境（application-dev.yml）：
springdoc:
api-docs:
enabled: true
swagger-ui:
enabled: true
生产环境（application-prod.yml）：
springdoc:
api-docs:
enabled: false # 生产环境禁用
swagger-ui:
enabled: false # 生产环境禁用
4. 日志配置
日志格式（application.yml）：
logging:
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%logger{50}] - %msg%n"
file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%logger{50}] - %msg%n"
file:
name: logs/ocr.log
logback:
rolling-policy:
max-file-size: 100MB
max-history: 30
max-total-size-cap: 1GB
日志级别：
- 开发环境：
com.itmei.ocr: DEBUG - 生产环境：
com.itmei.ocr: INFO
可配置项总结
| 配置项 | 说明 | 默认值 |
|---|---|---|
server.port |
服务端口 | 9898 |
spring.servlet.multipart.max-file-size |
最大文件大小 | 10MB |
ocr.image.max-width |
图片最大宽度 | 4096 |
ocr.image.max-height |
图片最大高度 | 4096 |
ocr.processing.target-height |
图片处理目标高度 | 64 |
logging.level.com.itmei.ocr |
日志级别 | INFO（dev: DEBUG） |
📁 项目结构
ocr/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/itmei/ocr/
│ │ │ ├── config/ # 配置类
│ │ │ │ ├── CorsConfig.java
│ │ │ │ ├── OcrProperties.java
│ │ │ │ ├── ResourceSecurityConfig.java
│ │ │ │ ├── SwaggerConfig.java
│ │ │ │ └── OnnxSessionCleanupConfig.java
│ │ │ ├── controller/ # 控制器
│ │ │ │ └── OcrController.java
│ │ │ ├── dto/ # 数据传输对象
│ │ │ │ ├── OcrRequest.java
│ │ │ │ └── OcrResponse.java
│ │ │ ├── enums/ # 枚举类
│ │ │ │ └── OcrTypeEnum.java
│ │ │ ├── exception/ # 异常处理
│ │ │ │ ├── GlobalExceptionHandler.java
│ │ │ │ ├── OcrStrategyNotFoundException.java
│ │ │ │ └── ValidationException.java
│ │ │ ├── factory/ # 工厂类
│ │ │ │ └── OcrStrategyFactory.java
│ │ │ ├── strategy/ # 策略模式
│ │ │ │ ├── AbstractOcrStrategy.java
│ │ │ │ ├── OcrStrategy.java
│ │ │ │ └── impl/
│ │ │ │ ├── D4NewStrategy.java
│ │ │ │ └── D4OldStrategy.java
│ │ │ ├── utils/ # 工具类
│ │ │ │ ├── ImageUtils.java
│ │ │ │ ├── IOUtils.java
│ │ │ │ ├── OnnxRuntimeUtils.java
│ │ │ │ ├── ResourceFileUtils.java
│ │ │ │ ├── SpringUtil.java
│ │ │ │ └── ValidationUtils.java
│ │ │ └── OcrApplication.java
│ │ └── resources/
│ │ ├── application.yml # 基础配置
│ │ ├── application-dev.yml # 开发环境配置
│ │ ├── application-prod.yml # 生产环境配置
│ │ ├── logback-spring.xml # 日志配置
│ │ └── d4ocr/ # OCR 模型文件
│ │ ├── common.onnx
│ │ ├── common_old.onnx
│ │ ├── common_charset.json
│ │ └── common_old_charset.json
│ └── test/
│ └── java/
│ └── com/itmei/ocr/
│ └── OcrApplicationTests.java
├── pom.xml
└── README.md
🧪 测试
运行测试
mvn test
测试示例
项目包含测试类 OcrApplicationTests.java，可以测试 OCR 识别功能。
🛠️ 开发指南
添加新的 OCR 引擎
- 创建策略实现类
在 strategy/impl/ 目录下创建新的策略类：
@Component
public class NewOcrStrategy extends AbstractOcrStrategy {
@Override
public OcrTypeEnum getOcrType() {
return OcrTypeEnum.NEW_ENGINE;
}
@Override
public OcrTypeEnum getOcrType() {
return OcrTypeEnum.D4OLD;
}
@Override
public RecognizeResult recognize(BufferedImage image) {
// 实现 OCR 识别逻辑
return super.recognize(image);
}
}
- 添加枚举类型
在 OcrTypeEnum.java 中添加新的枚举值：
NEW_ENGINE(
"NEW_ENGINE",
"/d4ocr/new_model.onnx",
"/d4ocr/new_charset.json",
"新引擎描述"
)
- 添加模型文件
将模型文件（.onnx）和字符集文件（.json）放入 src/main/resources/d4ocr/ 目录。
⚠️ 注意事项
- 文件大小限制：默认最大文件大小为 10MB，可在配置文件中修改
- 模型加载：首次运行时，模型文件会被提取到临时目录
- 性能考虑：ONNX Runtime 在首次加载模型时可能需要一些时间
- 内存使用：处理大图片时可能占用较多内存
- 环境配置：生产环境默认禁用 Swagger UI，建议通过环境变量或启动参数控制
- 资源安全：
/d4ocr/**目录下的资源文件禁止外部直接访问，只能通过代码内部访问 - 日志文件：日志文件默认保存在
logs/目录，注意磁盘空间
🐛 常见问题
1. 模型加载失败
问题：启动时提示模型加载异常
解决：
- 检查
resources/d4ocr/目录下是否存在模型文件 - 检查文件权限
- 查看日志获取详细错误信息
2. 识别结果为空
问题：OCR 识别返回空字符串
解决：
- 检查图片格式是否支持
- 检查图片是否清晰
- 尝试使用不同的 OCR 引擎
3. 文件上传失败
问题：上传文件时提示大小超限
解决：
- 检查文件大小是否超过配置的限制
- 修改
application.yml中的max-file-size配置
4. Swagger UI 无法访问
问题：访问 http://localhost:9898/swagger-ui.html 显示 404
解决：
- 检查当前运行环境（生产环境默认禁用）
- 确认
application-dev.yml中springdoc.swagger-ui.enabled: true - 确认使用开发环境启动：
mvn spring-boot:run -Pdev
5. Maven 构建时资源过滤错误
问题：构建时提示 MalformedInputException 错误
解决：
- 已配置排除二进制文件（
.onnx）的过滤 - 如果仍有问题，检查
pom.xml中的<resources>配置
