# 身份证识别 API（免费 · 离线 · Docker · 极限低配可用）

上传身份证图片 → 返回结构化 JSON。OCR 用 **RapidOCR**（PaddleOCR 的 ONNX 版，Apache-2.0 可商用），服务用 **FastAPI**，全程**不需要 GPU、不需要联网、不需要任何云服务密钥**。

目标硬件：**1 核 CPU / 2G 内存配额**即可运行。速度高度依赖 CPU 单核性能：现代 x86 NAS（J4125 及以上）单张约 0.5–1.5s；**老旧低端机型（如 Celeron 1007U @1.5GHz）约 2–6s**，属于正常范围。

## 能力

- 正面：姓名、性别、民族、出生日期、住址、公民身份号码
- 反面：签发机关、有效期限
- 自动判正反面（也可用 `side=front/back` 强制指定）
- 身份证号 **ISO 7064 MOD 11-2 校验位验证**，识别错了会被标记 `id_number_valid=false`
- 返回每字段平均置信度与耗时
- 可选脱敏返回（`mask=true`）

## 1 核 2G 极限低配适配（重点）

2G 内存的真正风险不是模型本身（det/cls/rec 三个 onnx 权重合计约 15MB），而是三件事：

1. **onnxruntime 的线程风暴**——Docker 的 `cpus: 1.0` 限额**不会**改变容器内 `os.cpu_count()`，onnxruntime / OpenBLAS 仍会按宿主机核数建线程池。64 核宿主机上容器能起出几十个线程，1 核机器上直接 OOM 或被 cgroup 杀。必须显式钉死。
2. **大图的解码缓冲 + det 中间张量**——内存随图片面积平方增长。
3. **多 worker**——每个 worker 独立加载一份模型，直接翻倍。

本项目已做六层控制：

| 层 | 手段 | 效果 |
|---|---|---|
| 进程 | `--workers 1`，引擎全局单例 | 不会加载多份模型；每多一个 worker 多 400–600MB |
| 线程 | `OMP/OPENBLAS/MKL_NUM_THREADS=1` + `cv2.setNumThreads(0)` | 三重钉死，杜绝线程风暴 |
| 模型 | 关闭方向分类器 `use_angle_cls=False` | 身份证基本正向，少一个模型、少一次推理 |
| 输入 | 图片最长边 960px + `det_limit_side_len=736`（低端机型下调过，通用默认 1200/960） | 解码缓冲和 det 张量双降 |
| 推理 | `rec_batch_num=1` | batch=6 在单核下只涨峰值内存，不省时间 |
| 容器 | `cpus: 1.0`、`mem_limit: 1024m` | 留 1G 给系统 / Docker 本身 / 其他服务 |
| 入口 | content-length 预检 + 5MB 上限 + 6000px 尺寸硬上限 | 三层拦超大图，防解压炸弹打爆内存 |

**内存预算（估算，建议你本地 `docker stats` 实测校准）**

| 阶段 | RSS |
|---|---|
| Python 3.11 + FastAPI + uvicorn | ~150–200 MB |
| numpy + opencv-headless + pillow | ~120–150 MB |
| onnxruntime 运行时 | ~80–100 MB |
| 三个 onnx 模型常驻 + 图优化副本 | +150–250 MB |
| 单张 960px 图推理峰值 | +80–150 MB |
| **稳态 / 峰值** | **约 500–650 MB / 800MB–1.0GB** |

容器限 1024m 缓冲不多，**峰值贴着上限时先加 swap，再考虑降 `MAX_SIDE=736`**。低端机型（4G 单条）强烈建议提前加 2G swap，这是最便宜的保险：

## 快速开始

```bash
cd idcard-api
docker compose up -d --build      # 首次构建会预热模型，稍慢
docker stats idcard-api           # 看内存是否在预期区间
curl http://127.0.0.1:8000/api/v1/idcard/health   # 直接看 mem_mb 字段
```

接口文档：`http://127.0.0.1:8000/docs`

> 💡 根路径 `/` 返回服务信息与端点清单，不是 404；`/api/v1/idcard/health` 返回状态和内存。
> 若 `/docs` 打开是白屏，说明页面依赖的外网 CDN（jsdelivr）被墙或超时——**不是服务故障**，直接用 curl / Postman / Apifox 调接口即可，请求格式见下方「调用」。

## 发布到飞牛 fnOS（Docker 应用）

适合把服务放到 NAS 上、给局域网其他应用调用。**主推 SSH 路径**（多文件项目必须整体上传，Compose 界面只能贴单个 yaml，上下文文件传不上去）。

### 第 0 步：三项前置检查（SSH 进 fnOS 后执行）

```bash
uname -m                    # 必须是 x86_64；若是 aarch64 见下方说明
free -h                     # 看可用内存，关键！见下方警告
ss -tlnp | grep 8000        # 确认 8000 端口没被别的容器占用
```

> ⚠️ **内存警告**：`mem_limit: 1024m` 是给**容器**的配额，fnOS 系统本身要占 1G+。当前默认值已针对 **Celeron 1007U / 4GB 单条内存**这类低端机型调好；NAS 总内存 ≥8G 可调回 `1280m` 并把 `MAX_SIDE` 调回 `1200`。4G 机型务必加 2G swap 兜底。

> ⏱️ **速度预期（Celeron 1007U @1.5GHz）**：单张身份证约 **2–6 秒**。这块 ULV 单核比常见 NAS 的 J4125 弱 3 倍以上，`MAX_SIDE=960` 就是为速度做的妥协（文字仍有约 25px 高，清晰印刷体识别率影响很小）。慢是正常的，不是没调好。

### 第 1 步：把整个项目目录传到 NAS

```bash
# fnOS 上建目录（存储池编号按实际改，/volume1 或 /vol1 都见过）
mkdir -p /volume1/docker/idcard-api
```

用 WinSCP / FileZilla 把本地的 `idcard-api` 目录**整个**拖上去（`app/`、`Dockerfile`、`docker-compose.yml`、`requirements.txt`、`client_example.py`、`.env.example`），保持目录结构。或者用 scp：

```bash
scp -r idcard-api root@飞牛IP:/volume1/docker/
```

### 第 2 步：配置 .env

```bash
cd /volume1/docker/idcard-api
cp .env.example .env
vi .env          # 配 API_TOKENS（每方一把 token），见「鉴权」一节
```

### 第 3 步：构建并启动（最容易卡的是模型下载）

```bash
docker compose config        # 先检查 yaml 语法，没问题再往下
docker compose up -d --build
docker compose logs -f       # 看到 "engine ready" 且无 Traceback 即成功
```

**构建卡住/失败的两种原因和对策**：

1. **pip 慢**：Docker Hub 基础镜像可在 fnOS「设置 → Docker → 镜像仓库」配轩辕等加速源；pip 慢就在 Dockerfile 的 `pip install` 后加 `-i https://pypi.tuna.tsinghua.edu.cn/simple`。
2. **onnx 模型下载失败**（构建到预热那步报错，国内访问 GitHub 不稳）：在能上网的 Windows 上先执行
   ```powershell
   pip install rapidocr-onnxruntime
   python -c "from rapidocr_onnxruntime import RapidOCR; RapidOCR()"
   ```
   把生成模型目录（一般在 `C:\Users\<你>\.rapidocr_model`）传到 NAS `/volume1/docker/idcard-api/models`，compose 已挂载 `/app/models`，重跑 `docker compose up -d --build` 即可。

### 第 4 步：验证

```bash
curl http://127.0.0.1:8000/api/v1/idcard/health          # 看 status / mem_mb
curl -X POST http://127.0.0.1:8000/api/v1/idcard/recognize \
  -F "file=@/volume1/docker/idcard-api/test.jpg" -F "side=auto" \
  -H "X-API-Key: 你的密钥"
docker stats idcard-api                                   # 看内存峰值是否贴着 1280m
```

建议先拿一张真实身份证正反面各测一次，确认字段和 `id_number_valid=true` 再交给调用方。

### 第 5 步：接入调用方

- **同 NAS 上的其他 Docker 容器**：把调用方容器加入 `idcard-api_idcard-api` 网络（或在调用方 compose 里加 `external_links` / 同一自定义网络），地址写 `http://idcard-api:8000`；图省事直接用 `http://飞牛IP:8000`。
- **局域网其他设备**：`http://飞牛IP:8000`，带 `X-API-Key` 头。
- **要域名 + HTTPS**：用 fnOS 自带的反向代理/远程访问把域名指到 `127.0.0.1:8000`，不要在路由器上映射公网端口直连。
- **ARM 机型（aarch64）**：python:3.11-slim 和 opencv-headless 有 ARM 版，但 onnxruntime 需 ≥1.19 才有完善的 ARM wheel，先在 NAS上 `docker compose build` 试；若 onnxruntime 装不上，只能换 x86 机型或用云侧部署。

## 调用

```bash
curl -X POST http://127.0.0.1:8000/api/v1/idcard/recognize \
  -F "file=@/path/idcard.jpg" -F "side=auto"
```

base64 方式：

```bash
curl -X POST http://127.0.0.1:8000/api/v1/idcard/recognize/base64 \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "<base64>", "side": "auto", "mask": false}'
```

**返回示例**

```json
{
  "code": 0,
  "data": {
    "side": "front",
    "name": "张三",
    "gender": "男",
    "nation": "汉",
    "birth": "19900101",
    "address": "北京市朝阳区某某路1号",
    "id_number": "110101199001011237",
    "id_number_valid": true,
    "issuer": null,
    "validity": null,
    "field_count": 6,
    "confidence": 0.96,
    "elapsed_ms": 980.5,
    "raw_text": "姓名张三 | 性别男 | ..."
  }
}
```

Python 示例见 `client_example.py`。

## 鉴权（Token 验证）

支持三种方式，全部用**标准库实现**（HMAC-SHA256），不引入 PyJWT 等依赖，对 1C/2G 无额外开销。

### 方式一：多 token（推荐）

`.env` 里按 `名称:token` 配置，多个用逗号分隔：

```bash
API_TOKENS=frontend:abc123def456,win-service:xyz789uvw012
```

好处是**每个调用方一把，能单独吊销**（删掉对应那段重启即可），日志里也会打出调用方名称，出问题能定位是谁在调。

调用时带标准 Bearer 头：

```bash
curl -X POST http://10.1.1.163:8000/api/v1/idcard/recognize \
  -H "Authorization: Bearer xyz789uvw012" \
  -F "file=@idcard.jpg"
```

旧的 `X-API-Key` 头仍然有效（兼容不改代码的老调用方）；`API_KEY` 单密钥配置也继续支持。

### 方式二：短期 token（前端场景推荐）

设置 `CLIENT_SECRET` 后，多出一个换 token 的接口：

```bash
# ① 用 client_secret 换 token（默认 1 小时有效）
curl -X POST http://10.1.1.163:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"frontend","client_secret":"你的密钥"}'

# 返回
{"token":"eyJzdWIiOiJmcm9udGVuZCIsImlhdCI6...9f2a","expires_in":3600,"token_type":"Bearer"}

# ② 后续请求带这个 token
curl -X POST http://10.1.1.163:8000/api/v1/idcard/recognize \
  -H "Authorization: Bearer eyJzdWIi..." \
  -F "file=@idcard.jpg"
```

token 是 `base64(payload) + "." + HMAC签名` 的结构（类似 JWT 但没有第三段），服务端校验签名和 `exp` 过期时间。`TOKEN_TTL` 可调有效期。

适合前端的原因：页面里不硬编码长期密钥，泄露了也就一小时的窗口。

### 方式三：不配置（本地调试）

`API_TOKENS`、`API_KEY`、`CLIENT_SECRET` 全为空时，接口完全开放。**只适合本机调试**——`/api/v1/idcard/health` 会返回 `auth_enabled: false`，启动日志也会警告。

### 几个实现细节

- **`/api/v1/idcard/health` 不鉴权**，方便探活和监控；它不返回任何身份证数据。
- **401 响应带 `WWW-Authenticate: Bearer` 头**，符合 HTTP 标准，前端库能自动识别。
- **签名比较用 `hmac.compare_digest`**（常数时间），避免时序侧信道攻击。
- **`/docs` 不做鉴权**，方便调试；要锁起来就在 Nginx 反代层加 basic auth。
- **日志只记调用方名称和耗时，不记姓名/身份证号**。
- 静态 token **以明文存在容器环境变量里**，能读 `docker inspect` 的人就能看到。安全要求更高的话，用短期 token 模式 + 只把 `CLIENT_SECRET` 挂在服务端，客户端只拿短时 token。

## 跨域（CORS）

**先分清调用方**：

| 调用方 | 有跨域限制吗 | 需要做什么 |
|---|---|---|
| 后端服务（curl、Python requests、其他 Docker 容器、Java/Go 等） | ❌ 没有 | 什么都不用配 |
| 浏览器前端（Vue / React / 原生 JS 页面） | ✅ 有 | 服务端开 CORS + 请求头带 `Authorization: Bearer <token>` |

CORS 是**浏览器的同源策略**，只在浏览器环境生效。所以「别的应用调用」如果是后端服务，完全不受影响；如果是网页前端，才会撞到。

服务已内置 `CORSMiddleware`，由环境变量 `CORS_ORIGINS` 控制：

```bash
# .env 里配置，逗号分隔；* 表示允许所有来源（开发方便）
CORS_ORIGINS=http://10.1.1.163:5173,http://10.1.1.163:8080
```

几个要点：

1. **预检请求**：前端带 `X-API-Key` 自定义头会触发 `OPTIONS` 预检，中间件已自动处理（返回 204 + 允许头），无需额外路由。
2. **鉴权头必须在 `allow_headers` 里**：已设 `allow_headers=["*"]`，`X-API-Key` 可通过。
3. **`allow_credentials=False` 是刻意的**：本项目用请求头鉴权、不用 Cookie，而 `allow_origins=["*"]` 与 credentials=True 是非法组合，浏览器会直接拒绝。
4. **安全提醒**：身份证是敏感数据。`CORS_ORIGINS=*` 且未配置任何 token 时，局域网内任何一个网页的 JS 都能悄悄调用你的接口读数据。**生产必须二选一**：配 `API_TOKENS`，或把 `CORS_ORIGINS` 收紧到具体前端地址。
5. **生产更推荐同源**：用 Nginx / fnOS 反向代理把前端和 API 放在同一域名下（`/api` 转发到 8000），浏览器视为同源，连 CORS 都不需要，也少一层预检开销。

## 如果内存还是吃紧（降级路径）

按代价从低到高：

1. `MAX_SIDE=960` + `DET_LIMIT_SIDE_LEN=736`：身份证文字在 960px 下仍有 ~25px 高，识别基本无损，通常再省 100–150MB
2. 换 PP-OCR **mobile** 版识别模型（`ch_PP-OCRv4_mobile_rec`），体积和内存都小于 server 版，身份证这种清晰印刷体精度损失很小
3. 加 swap（2–4G）作为兜底——会拖慢速度，但能防 OOM 被杀。**这是 2G 机器强烈建议做的**：
   ```bash
   sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
   sudo mkswap /swapfile && sudo swapon /swapfile
   ```
4. 极端情况换 Tesseract + `chi_sim`：内存可压到 200MB 内，但中文证件识别率明显下降，不推荐

**并发上不去时**：低配下不要加 worker，改成前面挂 Nginx 限流排队。1 核的现实吞吐大约 **1–2 QPS**，超过就会堆积。要扛量就横向多开几个容器 + 前面 LB，而不是在单机上加进程。

## 准确率与调优

- 清晰扫描件 / 规整拍照：字段级 95%+；模糊、反光、强倾斜、复印件会明显下降。
- 掉得最多的通常是**住址**（长文本）和**名字里的生僻字**。建议对 `id_number_valid=false` 的结果走人工复核，不要直接采信。
- 拍照场景强烈建议前端先做一次**方向校正 + 边缘裁剪**，比在服务端补救有效得多。
- 想加"先检测身份证区域再 OCR"（防复杂背景），可接 YOLOv8n 做前置裁剪，挂在 `_load_image` 之后即可——**1C/2G 下不建议加**，会再吃 100MB 内存和一大截 CPU。

## 合规与安全（重要）

身份证号属于**敏感个人信息**，受《个人信息保护法》《数据安全法》约束：

1. 这个方案的价值就在**数据不出你自己的机器**。别为了省事换成公有云 API，那等于把 PII 交给第三方。
2. 服务**不落盘、不缓存**图片，`raw_text` 含明文，生产环境建议要么关掉、要么 `mask=true`。
3. 日志里**不要打印身份证号和姓名**。当前实现只打加载信息。
4. 对外必须 HTTPS + 鉴权 + 限流；已做两层大小防护（content-length 预检 + 惰性尺寸检查），`MAX_IMAGE_BYTES=5MB`。
5. 收集前应有用户授权与隐私政策，明确保留期限——最安全的做法是识别完即丢弃。

## 目录

```
idcard-api/
├── app/
│   ├── main.py      # FastAPI 服务、鉴权、图片校验、低配参数
│   └── parser.py    # 关键词锚点解析 + 身份证校验位
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── client_example.py
```

## 常见问题

**构建时报 `401 Unauthorized`（拉不下 `python:3.11-slim` 元数据）**：Docker 镜像源问题，与项目无关。注意 **fnOS 的 Docker 应用会用自己的界面配置覆盖 `/etc/docker/daemon.json`**，手工改文件常常不生效（报错 URL 仍是 `docker.fnnas.com` 就是没生效）。本项目已改走第三条路——**在 Dockerfile 里直接写国内镜像仓库全路径**，不依赖 daemon 配置：

```dockerfile
ARG BASE_IMAGE=docker.m.daocloud.io/library/python:3.11-slim
FROM ${BASE_IMAGE}
```

切换源只需在 `.env` 里设 `BASE_IMAGE`，构建前先探活：
```bash
for m in docker.m.daocloud.io docker.1ms.run mirror.ccs.tencentyun.com; do
  echo -n "$m -> "; curl -s -o /dev/null -w "%{http_code}\n" --max-time 8 \
    "https://$m/v2/library/python/manifests/3.11-slim"
done
```
返回 `200` 可用；`401` 且带 `WWW-Authenticate` 头属于 Registry 正常认证流程，Docker 能自动处理；连接超时/`5xx` 则换下一个。全部不通就走离线导入兜底：

```bash
# 1) 在能联网且有 Docker 的机器上（你的 Windows 本机装了 Docker Desktop 即可）
docker pull python:3.11-slim
docker save python:3.11-slim -o python311slim.tar
# 2) 传到 NAS 后导入
docker load -i python311slim.tar
# 3) 构建时指向本地 tag
#    在 .env 里设 BASE_IMAGE=python:3.11-slim，然后 docker compose up -d --build
```

**pip 装包慢/断**：与镜像源无关，是另一条网络路径。Dockerfile 已默认清华源（`PIP_INDEX_URL`），需要时构建覆盖。

**构建时模型下载失败**：国内访问模型源不稳。先在能上网的机器上 `python -c "from rapidocr_onnxruntime import RapidOCR; RapidOCR()"` 生成模型目录，再拷进 `/app/models` 卷；pip 可加 `-i https://pypi.tuna.tsinghua.edu.cn/simple`。

**容器起不来 / 报 OOM**：先 `docker stats` 看峰值，或 `curl .../health` 看 `mem_mb`。若峰值贴着 `mem_limit`，按上面降级路径降 `MAX_SIDE`；反复被杀就先加 swap。

**`RapidOCR rejected {...}` 警告**：正常，代码在逐级降级尝试构造参数，最终会用可用组合启动，不会失败。锁死 `requirements.txt` 版本后这条警告会消失。

**CPU 跑满但吞吐很低**：典型症状是线程在抖。检查容器内 `echo $OMP_NUM_THREADS` 必须是 1；如果宿主机是多核而 compose 里只写了 `cpus: 1.0`，环境变量没生效就会这样。

**返回 422 no text detected**：图片不是身份证、或分辨率过低/文字太小。

**性别/民族识别成空**：正面右侧那一行字小，常见于低清图。提高图片质量，或换 mobile/server 识别模型。

**numpy 相关报错**：`requirements.txt` 里锁了 `numpy<2`，不要手动升。onnxruntime 与 numpy 2 存在兼容问题。