oneos-backend/yudao-module-ocr/DEPLOYMENT.md

# OCR 模块部署指南

## 部署步骤

### 1. 添加到主 POM

已完成 ✅ - `yudao-module-ocr` 已添加到 `oneos-backend/pom.xml` 的 modules 中。

### 2. 配置 Nacos

在 Nacos 配置中心创建配置文件：`ocr-server-dev.yaml`

```yaml
server:
  port: 48090

# OCR 配置
ocr:
  default-provider: baidu
  baidu:
    app-id: ${OCR_BAIDU_APP_ID}
    api-key: ${OCR_BAIDU_API_KEY}
    secret-key: ${OCR_BAIDU_SECRET_KEY}
```

### 3. 配置环境变量

在部署环境中设置以下环境变量：

```bash
export OCR_BAIDU_APP_ID=your-app-id
export OCR_BAIDU_API_KEY=your-api-key
export OCR_BAIDU_SECRET_KEY=your-secret-key
```

或在 Nacos 的 `common-dev.yaml` 中配置。

### 4. 启动服务

```bash
cd oneos-backend/yudao-module-ocr/yudao-module-ocr-server
java -jar target/yudao-module-ocr-server.jar
```

或使用 Maven：

```bash
cd oneos-backend
mvn spring-boot:run -pl yudao-module-ocr/yudao-module-ocr-server
```

### 5. 验证服务

访问 Swagger 文档：

```
http://localhost:48090/doc.html
```

查看 OCR 识别接口是否正常。

## 权限配置

在系统管理中添加权限：

- 权限标识：`ocr:vehicle-license:recognize`
- 权限名称：行驶证识别
- 所属菜单：OCR 识别管理

## 集成到其他模块

### 1. 添加依赖

在需要使用 OCR 的模块（如 `yudao-module-asset-server`）的 `pom.xml` 中添加：

```xml
<!-- OCR 模块 API -->
<dependency>
    <groupId>cn.iocoder.cloud</groupId>
    <artifactId>yudao-module-ocr-api</artifactId>
    <version>${revision}</version>
</dependency>
```

### 2. 使用 Feign 调用

创建 Feign 客户端（如果需要跨服务调用）：

```java
@FeignClient(name = "ocr-server", contextId = "ocrApi")
public interface OcrApi {

    @PostMapping("/admin-api/ocr/vehicle-license")
    CommonResult<VehicleLicenseRespVO> recognizeVehicleLicense(
        @RequestParam("file") MultipartFile file,
        @RequestParam(value = "provider", required = false) String provider
    );
}
```

### 3. 直接注入使用（同一服务内）

```java
@Service
public class VehicleService {

    @Resource
    private OcrService ocrService;

    public void processVehicleLicense(byte[] imageData) {
        VehicleLicenseResult result = ocrService.recognizeVehicleLicense(imageData);
        // 处理识别结果
    }
}
```

## 监控和日志

### 日志配置

在 `logback-spring.xml` 中添加：

```xml
<logger name="cn.iocoder.yudao.module.ocr" level="INFO"/>
<logger name="com.baidu.aip" level="WARN"/>
```

### 监控指标

建议监控以下指标：

- OCR 识别成功率
- OCR 识别耗时
- OCR API 调用次数
- 错误率和错误类型

## 故障排查

### 1. 识别失败

检查：
- 百度 OCR 凭证是否正确
- 图片格式是否支持（JPG、PNG、BMP）
- 图片大小是否超过 4MB
- 网络连接是否正常

### 2. 服务启动失败

检查：
- Nacos 配置是否正确
- 依赖是否完整
- 端口是否被占用

### 3. 性能问题

优化建议：
- 添加识别结果缓存
- 实现请求限流
- 考虑使用异步识别

## 成本优化

### 1. 百度 OCR 计费

- 行驶证识别：0.015 元/次
- 每月前 1000 次免费

### 2. 优化建议

- 实现结果缓存，避免重复识别
- 前端压缩图片，减少传输时间
- 批量识别时使用队列异步处理

## 安全建议

1. **API 密钥管理**：使用配置中心加密存储
2. **接口鉴权**：确保只有授权用户可以调用
3. **图片校验**：验证上传图片的合法性
4. **日志脱敏**：不要在日志中记录敏感信息
5. **限流保护**：防止恶意调用消耗配额

## 后续扩展

1. 添加驾驶证识别
2. 添加身份证识别
3. 集成腾讯、阿里云 OCR
4. 实现识别结果的人工校验功能
5. 添加识别历史记录查询