# CLI 命令与 API 服务启动

> ddddocr CLI 子命令用法、API 服务启动参数、Docker 部署与健康检查

- Repository: sml2h3/ddddocr
- GitHub: https://github.com/sml2h3/ddddocr
- Human wiki: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf
- Complete Markdown: https://grok-wiki.com/public/wiki/sml2h3-ddddocr-10e2eae686bf/llms-full.txt

## Source Files

- `ddddocr/__main__.py`
- `ddddocr/api/__init__.py`
- `ddddocr/api/app.py`
- `ddddocr/api/server.py`
- `Dockerfile`
- `docker-compose.yml`

---

<details>
<summary>相关源文件</summary>
以下文件用于生成此维基页面：
- [ddddocr/__main__.py](ddddocr/__main__.py)
- [ddddocr/api/__init__.py](ddddocr/api/__init__.py)
- [ddddocr/api/app.py](ddddocr/api/app.py)
- [ddddocr/api/server.py](ddddocr/api/server.py)
- [Dockerfile](Dockerfile)
- [docker-compose.yml](docker-compose.yml)
</details>

# CLI 命令与 API 服务启动

ddddocr 提供了命令行接口（CLI）和基于 FastAPI 的 HTTP API 服务，用于启动验证码识别服务。本文档说明 CLI 子命令用法、API 服务启动参数、Docker 部署方式及健康检查机制。

## CLI 子命令

ddddocr 通过 `python -m ddddocr` 调用 CLI 入口，当前支持 `api` 子命令用于启动 HTTP API 服务。

```
python -m ddddocr api [--host HOST] [--port PORT] [--workers N] [其他选项...]
```

CLI 入口在 `ddddocr/__main__.py` 中定义，使用 `argparse` 解析参数后将所有配置写入环境变量，再调用 `ddddocr.api.main()` 启动服务。

### api 子命令参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--host` | str | `0.0.0.0` | 服务绑定地址 |
| `--port` | int | `8000` | 服务监听端口 |
| `--workers` | int | `1` | uvicorn 工作进程数 |
| `--ocr` | bool | `true` | 启用 OCR 功能 |
| `--det` | bool | `false` | 启用目标检测功能 |
| `--old` | bool | `false` | 使用旧版 OCR 模型 |
| `--beta` | bool | `false` | 使用 Beta 版 OCR 模型 |
| `--use-gpu` | bool | `false` | 启用 GPU 加速 |
| `--device-id` | int | `0` | GPU 设备 ID |
| `--show-ad` | bool | `true` | 显示广告 |
| `--import-onnx-path` | str | `""` | 自定义模型路径 |
| `--charsets-path` | str | `""` | 自定义字符集路径 |

所有参数均通过环境变量 `DDDDOCR_*` 传递给 API 服务模块。

**Sources:** [ddddocr/__main__.py:8-79](), [Dockerfile:59-73]()

## API 服务架构

ddddocr 提供两套 FastAPI 应用实现：

1. **app.py 中的应用**（默认入口）：直接定义 FastAPI 路由，适用于简单部署场景。
2. **server.py 中的服务类**（`DDDService`）：通过 `create_app()` 工厂函数创建，支持 MCP 协议，适用于需要动态初始化和模型切换的场景。

```
ddddocr/api/
├── __init__.py   # 统一导出入口
├── app.py        # 直接路由的 FastAPI 应用 + main()
├── server.py     # DDDService 服务管理 + create_app()
├── routes.py     # 路由注册
├── models.py     # 请求/响应模型
└── mcp.py        # MCP 协议处理器
```

### 启动流程

当执行 `python -m ddddocr api` 时：

1. `__main__.py` 解析 CLI 参数，写入 `os.environ`
2. 调用 `ddddocr.api.main()`（来自 `app.py`）
3. `main()` 从环境变量读取 `host`、`port`、`workers`
4. 通过 `uvicorn.run("ddddocr.api:app", ...)` 启动服务

**Sources:** [ddddocr/api/app.py:743-751](), [ddddocr/api/__init__.py:1-14]()

## API 端点

### 基础端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查，返回 `{"status": "ok", "timestamp": ...}` |
| `/config` | GET | 获取当前配置和活跃实例数 |
| `/docs` | GET | Swagger API 文档 |
| `/redoc` | GET | ReDoc API 文档 |

### OCR 识别

| 端点 | 方法 | 说明 |
|------|------|------|
| `/ocr` | POST | Base64 图片 OCR 识别 |
| `/ocr/file` | POST | 文件上传 OCR 识别 |

请求体（JSON 模式）：
```json
{
  "image": "<base64>",
  "probability": false,
  "colors": [],
  "custom_color_ranges": null
}
```

**Sources:** [ddddocr/api/app.py:330-332](), [ddddocr/api/app.py:335-404]()

### 目标检测

| 端点 | 方法 | 说明 |
|------|------|------|
| `/det` | POST | Base64 图片目标检测 |
| `/det/file` | POST | 文件上传目标检测 |

### 滑块验证码

| 端点 | 方法 | 说明 |
|------|------|------|
| `/slide_match` | POST | 滑块缺口位置匹配 |
| `/slide_comparison` | POST | 滑块图像差异比较 |

### 其他

| 端点 | 方法 | 说明 |
|------|------|------|
| `/set_charset_range` | POST | 设置 OCR 识别字符范围 |

### 实例管理机制

API 服务采用实例池模式管理 OCR 实例。相同配置的请求复用同一实例，以配置键（如 `ocr=true-det=false-old=false-...`）为标识。后台任务会定期清理超过 3600 秒未使用的实例以释放内存。

**Sources:** [ddddocr/api/app.py:239-298]()

## Docker 部署

### 使用 Dockerfile 构建

```bash
docker build -t ddddocr-api .
docker run -d -p 8000:8000 --name ddddocr-api ddddocr-api
```

Dockerfile 基于 `python:3.10-slim`，安装系统依赖（`libgl1-mesa-glx`、`libglib2.0-0` 等），将所有配置项设为环境变量，通过 `CMD python -m ddddocr api` 启动服务。

### 使用 Docker Compose

```bash
docker-compose up -d
```

docker-compose.yml 定义了服务 `ddddocr-api`，支持通过宿主机环境变量覆盖所有配置：

```bash
DDDDOCR_USE_GPU=true DDDDOCR_PORT=9000 docker-compose up -d
```

compose 配置还预留了 GPU 支持和资源限制的注释示例，可根据需要启用。

**Sources:** [Dockerfile:1-77](), [docker-compose.yml:1-80]()

## 健康检查

Dockerfile 和 docker-compose.yml 均配置了健康检查，通过定时请求 `/health` 端点判断服务是否正常：

```
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:${DDDDOCR_PORT}/health || exit 1
```

`/health` 端点返回 HTTP 200 及 JSON 响应 `{"status": "ok", "timestamp": <unix_time>}`。Docker 会在连续 3 次检查失败后将容器标记为 unhealthy。

**Sources:** [Dockerfile:76-77](), [ddddocr/api/app.py:330-332](), [docker-compose.yml:71-76]()

## server.py 服务管理（高级用法）

`server.py` 中的 `DDDService` 类提供更细粒度的服务管理能力：

- **动态初始化**：通过 `/initialize` 端点按需加载 OCR、检测或滑块模型
- **模型切换**：通过 `/switch_model` 端点在运行时切换模型版本
- **功能开关**：通过 `/toggle_feature` 端点动态启用/禁用功能
- **状态查询**：通过 `/status` 端点获取已加载模型、启用功能和运行时长
- **MCP 协议**：通过 `/mcp` 前缀提供 MCP 协议支持

**Sources:** [ddddocr/api/server.py:22-206]()