# OCR图像识别功能使用说明与故障排除指南

## 📚 功能概述

OCR（Optical Character Recognition，光学字符识别）功能用于识别图片中的文字内容，支持多种识别类型：
- 通用文字识别
- 发票识别
- 身份证识别

## 🔧 系统要求

### 服务依赖
- 阿里云OCR服务（需要有效的AccessKey）
- 网络连接（访问 `ocr-api.cn-hangzhou.aliyuncs.com:443`）

### 技术栈
- 后端：Spring Boot + 阿里云OCR SDK
- 前端：Vue.js + Element UI

## ⚙️ 配置说明

### 1. AccessKey配置
在 `application.yml` 中配置：
```yaml
ocr:
  accessKeyId: YOUR_ACCESS_KEY_ID
  accessKeySecret: YOUR_ACCESS_KEY_SECRET
```

### 2. 网络配置
确保服务器能够访问：
- 地址：`ocr-api.cn-hangzhou.aliyuncs.com`
- 端口：`443` (HTTPS)
- 协议：TCP

## 🚀 使用方法

### 1. 访问页面
菜单路径：`系统工具 > OCR管理 > OCR测试`

### 2. 上传图片
- 支持格式：JPG、PNG、BMP
- 文件大小：不超过4MB
- 图片质量：清晰，文字易辨认

### 3. 选择识别类型
- 通用文字识别：适合一般文档
- 发票识别：适合发票、收据
- 身份证识别：适合身份证正反面

## 🔍 故障排除

### 常见错误及解决方案

#### 1. 网络连接错误
**错误信息**：`code: 415, The image format or content is not supported`
**可能原因**：
- 图片格式不支持
- 图片内容损坏
- 图片太大

**解决方案**：
- 检查图片格式是否为JPG/PNG/BMP
- 验证图片文件是否完整
- 压缩图片至4MB以下

#### 2. 网络连接失败
**错误信息**：`ocr-api.cn-hangzhou.aliyuncs.com`
**可能原因**：
- DNS解析失败
- 防火墙阻止连接
- 网络策略限制
- 代理配置问题

**解决方案**：
1. **DNS问题**：
   - 检查DNS服务器配置
   - 尝试使用公共DNS（如8.8.8.8）
   - 验证域名解析：`nslookup ocr-api.cn-hangzhou.aliyuncs.com`

2. **防火墙问题**：
   - 检查防火墙是否开放443端口
   - 确认服务器允许出站HTTPS请求
   - 验证安全组规则

3. **代理问题**：
   - 配置系统代理参数：
     ```
     -Dhttp.proxyHost=proxy.example.com
     -Dhttp.proxyPort=8080
     -Dhttps.proxyHost=proxy.example.com
     -Dhttps.proxyPort=8080
     ```

#### 3. AccessKey错误
**错误信息**：认证失败相关错误
**解决方案**：
- 检查AccessKey ID和Secret是否正确
- 确认账户有OCR服务权限
- 验证AccessKey是否过期

### 诊断工具

#### 1. 网络诊断
访问页面：`系统工具 > OCR管理 > OCR测试`
在识别失败时，点击"网络诊断"按钮查看连接状态。

#### 2. 手动测试命令
```bash
# 测试DNS解析
nslookup ocr-api.cn-hangzhou.aliyuncs.com

# 测试端口连通性
telnet ocr-api.cn-hangzhou.aliyuncs.com 443

# 测试HTTPS连接
curl -I https://ocr-api.cn-hangzhou.aliyuncs.com
```

## 🛠️ 系统维护

### 1. 日志查看
- 后端日志：`logs/ocr.log`
- 错误日志：关注 `AliOCRUtil` 类的日志

### 2. 性能调优
- 连接超时：默认10秒
- 读取超时：默认30秒
- 可通过配置调整超时时间

### 3. 安全注意事项
- AccessKey不要硬编码在代码中
- 定期更换AccessKey
- 限制AccessKey权限范围

## 📞 技术支持

如遇无法解决的问题，请提供以下信息联系技术支持：
- 完整错误日志
- 网络诊断结果
- 系统环境信息
- 防火墙/代理配置信息

## 📋 检查清单

在部署和使用OCR功能前，请确认：
- [ ] 已开通阿里云OCR服务
- [ ] 已配置有效的AccessKey
- [ ] 服务器可访问互联网
- [ ] 防火墙开放443端口
- [ ] DNS解析正常
- [ ] 图片格式支持验证
- [ ] 网络连通性测试通过

---

**注意**：本功能依赖外部服务，网络状况可能影响识别成功率和速度。