# ddddocr **Repository Path**: mengyinggitee/ddddocr ## Basic Information - **Project Name**: ddddocr - **Description**: 国内开源轻量级验证码识别库，主打简单易用、体积小、免训练、开箱即用，专门针对网页普通验证码：字母数字验证码、四则运算验证码、中文验证码、滑块缺口坐标识别。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-30 - **Last Updated**: 2026-08-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DDD-OCR 图片识别服务 基于 [ddddocr](https://github.com/sml2h3/ddddocr) 的轻量级验证码 / 文字图片识别服务，使用 FastAPI 提供 HTTP 接口，并内置一个带质感 UI 的 Web 测试页面。 ![Python](https://img.shields.io/badge/Python-3.8%2B-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-0.121.0-teal) ![License](https://img.shields.io/badge/License-MIT-green) --- ## 目录 - [功能特性](#功能特性) - [项目结构](#项目结构) - [快速开始](#快速开始) - [本地运行](#本地运行) - [Docker 部署](#docker-部署) - [API 接口文档](#api-接口文档) - [1. 图片识别](#1-图片识别) - [2. 查询识别历史](#2-查询识别历史) - [3. 清空识别历史](#3-清空识别历史) - [前端测试页面](#前端测试页面) - [识别结果存储](#识别结果存储) - [常见问题](#常见问题) - [License](#license) --- ## 功能特性 - **图片验证码 / 文字识别**：基于 `ddddocr`，支持 `jpg` / `png` 格式图片 - **Web 测试页面**：美观的深色质感 UI，支持拖拽上传、实时展示识别结果与耗时 - **识别历史记录**：自动持久化识别记录（图片 + 结果 + 时间），前端表格分页展示 - **分页查询接口**：服务端分页，支持自定义页码与每页条数 - **历史清空**：一键清空全部识别记录 - **跨域支持**：内置 CORS 中间件，方便前后端分离调用 - **Docker 一键部署**：提供 Dockerfile 与构建脚本 --- ## 项目结构 ``` ddddocr/ ├── main.py # FastAPI 主程序（接口 + 静态资源 + 历史存储） ├── requirements.txt # Python 依赖 ├── Dockerfile # Docker 镜像构建文件 ├── build.sh # 构建镜像脚本（拉取最新代码 + 打时间戳标签） ├── static/ # 前端静态资源 │ ├── index.html # 测试页面（上传 + 结果 + 历史表格） │ ├── style.css # 页面样式（深色玻璃质感 UI） │ └── app.js # 前端逻辑（上传、渲染、分页） ├── uploads/ # 识别成功后保存的图片（运行时自动生成） └── data/ └── history.db # SQLite 历史记录数据库（运行时自动生成） ``` --- ## 快速开始 ### 本地运行 **1. 安装依赖** ```bash pip install -r requirements.txt ``` > 若网络环境受限，可使用国内镜像源： > > ```bash > pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple > ``` **2. 启动服务** ```bash python main.py ``` **3. 访问服务** | 地址 | 说明 | | --- | --- | | http://localhost:8000 | Web 测试页面 | | http://localhost:8000/docs | Swagger 接口文档 | | http://localhost:8000/openapi.json | OpenAPI 规范 | > 首次启动会自动下载并加载 ddddocr 模型，请保持网络通畅；模型加载完成后控制台输出 `OCR模型加载完成`。 **注意**：`main.py` 中 `ocr.set_ranges(6)` 用于指定识别字符集，可查看 [ddddocr 文档](https://github.com/sml2h3/ddddocr) 调整。 ### Docker 部署 **方式一：使用构建脚本** ```bash chmod +x build.sh ./build.sh ``` 脚本会依次执行：`git pull` 拉取最新代码 → 查看最近提交 → 以 `ddddocr-server:YYYY-MM-DD-HH-MM` 为标签构建镜像。 **方式二：手动构建** ```bash docker build -t ddddocr-server . ``` **运行容器** ```bash docker run -d \ --name ddddocr \ -p 8000:8000 \ -v $(pwd)/uploads:/app/uploads \ -v $(pwd)/data:/app/data \ ddddocr-server ``` 挂载 `uploads` 与 `data` 目录可将图片与历史记录持久化到宿主机，避免容器重建后数据丢失。 --- ## API 接口文档 所有接口返回统一结构： ```json { "success": true, "message": "success", "data": { } } ``` | 字段 | 类型 | 说明 | | --- | --- | --- | | `success` | boolean | 请求是否成功 | | `message` | string | 提示信息 | | `data` | object/null | 业务数据 | ### 1. 图片识别 `POST /ocr/recognize` - **请求参数**（multipart/form-data）： | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `file` | file | 是 | 待识别的图片，仅支持 `jpg` / `png`，建议单张不超过 10MB | - **成功响应示例**： ```json { "success": true, "message": "success", "data": { "result": "TEST123", "image": "/uploads/1786437171887_953ef41a.png", "elapsed": 42.17 } } ``` | 字段 | 类型 | 说明 | | --- | --- | --- | | `result` | string | 识别出的文字 | | `image` | string | 已保存图片的访问路径（配合 `GET {image}` 访问原图） | | `elapsed` | number | 本次识别耗时（毫秒） | - **失败响应示例**（如非 jpg/png 文件）： ```json { "success": false, "message": "仅支持 jpg / png 图片", "data": null } ``` - **cURL 调用示例**： ```bash curl -X POST http://localhost:8000/ocr/recognize \ -F "file=@/path/to/captcha.png" ``` ### 2. 查询识别历史 `GET /ocr/history` - **请求参数**（query）： | 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | `page` | int | 否 | 1 | 页码，从 1 开始 | | `page_size` | int | 否 | 10 | 每页条数，范围 1 ~ 100 | - **成功响应示例**： ```json { "success": true, "message": "success", "data": { "total": 23, "page": 2, "page_size": 10, "pages": 3, "items": [ { "id": 13, "image": "/uploads/1786437171887_953ef41a.png", "result": "TEST123", "created_at": 1786437171.8896046 } ] } } ``` | 字段 | 类型 | 说明 | | --- | --- | --- | | `total` | int | 总记录数 | | `page` | int | 当前页码 | | `page_size` | int | 每页条数 | | `pages` | int | 总页数 | | `items[].id` | int | 记录 ID | | `items[].image` | string | 图片访问路径 | | `items[].result` | string | 识别结果 | | `items[].created_at` | number | 识别时间（Unix 时间戳，秒） | - **cURL 调用示例**： ```bash curl "http://localhost:8000/ocr/history?page=1&page_size=10" ``` ### 3. 清空识别历史 `DELETE /ocr/history` - **成功响应示例**： ```json { "success": true, "message": "success", "data": null } ``` > 注意：清空操作仅删除数据库中的记录，`uploads/` 目录下已保存的图片文件不会被删除。 --- ## 前端测试页面 访问 `http://localhost:8000` 即可打开测试页面，包含三大模块： ### 上传区 - 支持 **拖拽图片** 或 **点击选择文件** 两种方式 - 自动校验文件格式（仅 `jpg` / `png`）与大小（不超过 10MB） - 上传后展示加载动画，识别完成后自动滚动至结果区 ### 识别结果 - 展示识别原图、识别结果文字（大号显示） - 展示本次识别耗时 - 支持 **复制结果** 与 **再传一张** 快捷操作 ### 识别历史表格 - 表格列：**识别时间**、**图片缩略图**、**识别结果** - 图片缩略图支持点击放大预览 - 支持分页浏览（每页 10 条，可前后翻页，显示总记录数） - 支持一键 **清空历史** --- ## 识别结果存储 - **图片文件**：保存至 `uploads/` 目录，文件名格式为 `{毫秒级时间戳}_{随机8位hex}.{png|jpg}` - **历史记录**：保存至 `data/history.db`（SQLite），表结构如下： ```sql CREATE TABLE history ( id INTEGER PRIMARY KEY AUTOINCREMENT, image TEXT NOT NULL, -- 图片访问路径 result TEXT NOT NULL, -- 识别结果 created_at REAL NOT NULL -- 识别时间（Unix 时间戳） ); ``` --- ## 常见问题 **Q1：启动时报 `ModuleNotFoundError: No module named 'ddddocr'`** A：未安装依赖，执行 `pip install -r requirements.txt`。若安装失败，可先单独安装依赖再重试。 **Q2：识别失败或结果为空** A：确认图片为清晰的文字/验证码图片；部分复杂图片识别效果不佳，可尝试调整 `main.py` 中的 `ocr.set_ranges(6)` 字符集参数，或更换 `ddddocr` 的其他参数（如 `beta`、`old`）。 **Q3：上传接口提示"仅支持 jpg / png 图片"** A：服务端通过 `mimetypes.guess_type` 校验文件扩展名对应的 MIME 类型，请确保文件以 `.jpg` / `.jpeg` / `.png` 结尾。 **Q4：如何修改服务端口？** A：修改 `main.py` 末尾 `uvicorn.run(...)` 中的 `port` 参数（默认 `8000`），或部署时使用 Docker 端口映射 `-p 自定义端口:8000`。 **Q5：历史记录会一直增长，如何清理？** A：可通过前端页面"清空历史"按钮或调用 `DELETE /ocr/history` 接口清空记录；同时可定期清理 `uploads/` 目录下的历史图片。 **Q6：模型加载时间较长** A：首次启动需要下载模型文件，之后会缓存，属于正常现象。请保持网络畅通或提前预下载模型。 --- ## License [MIT](./LICENSE) 本项目基于开源的 [ddddocr](https://github.com/sml2h3/ddddocr) 构建，遵循其开源协议。