a76yyyy/ddddocr repository overview

⁠ddddocr Docker 镜像（Alpine）

ddddocr 运行栈的 musllinux wheel 分发，另附装好的可运行镜像。三个包在本仓库自编或自打包： ddddocr（纯 python + 模型文件）、opencv（最小化）、Pillow；onnxruntime 与 numpy 取自 onnxruntime-docker⁠ 的 wheelhouse。

• Docker Hub：https://hub.docker.com/r/a76yyyy/ddddocr⁠
• 源码：qd-today/ddddocr-docker⁠

⁠快速开始

直接用镜像：

docker run --rm -v "$PWD/captcha.png:/c.png" a76yyyy/ddddocr:latest \
  python3 -c "import ddddocr; print(ddddocr.DdddOcr(show_ad=False).classification(open('/c.png','rb').read()))"

以两个 wheelhouse 作为依赖来源：

# syntax=docker/dockerfile:1.7
FROM alpine:3.24
RUN --mount=type=bind,from=a76yyyy/ddddocr:wheelhouse,source=/wheels,target=/w1 \
    --mount=type=bind,from=a76yyyy/onnxruntime:wheelhouse,source=/wheels,target=/w2 \
    apk add --no-cache $(cat /w1/system-packages.txt) uv && \
    uv pip install --system --break-system-packages --no-cache \
        --index-url https://pypi.org/simple \
        --extra-index-url file:///w1/simple \
        --extra-index-url file:///w2/simple \
        "ddddocr==1.6.1" "opencv-python-headless==5.0.0" "pillow==13.0.0" \
        "onnxruntime==1.24.4" "numpy==2.4.6"

/w1/simple 是 PEP 503 索引，链接为相对路径，可与 wheel 目录一起挂到任意位置。

⁠镜像内容

⁠支持的平台

linux/386、linux/arm/v6、linux/s390x 不提供：onnxruntime 在这三个架构上没有可用的 Python 绑定（Alpine 配方 arch="all !s390x !x86"；armhf 被 py3-flatbuffers 挡住）， 而 ddddocr 没有 onnxruntime 就跑不起来。

loong64 构建需 --build-arg BASE_IMAGE=ghcr.io/loong64/alpine:3.24（Docker Hub 官方 alpine 无此架构）。

⁠标签

<ver> 只在 tag 推送时产出；workflow_dispatch 只更新滚动标签。

⁠构建

wheel 的构建与镜像的组装分两步：第一步产出 wheel，第二步用这份产物组装镜像。两步之间可以用 不同的架构环境（CI 里 arm 系列在原生 arm64 上编，组装统一在 x86_64）。

# ① 编译产物：/wheels
docker buildx build --platform linux/arm64 --target artifacts \
    --output type=local,dest=./dist .

# ② 可运行镜像
docker buildx build --platform linux/arm64 --target runtime \
    --build-context wheelsrc=./dist -t ddddocr:1.6.1 .

# ③ wheelhouse 镜像（供上层 COPY --from / bind mount）
docker buildx build --platform linux/arm64 --target wheel-from-artifacts \
    --build-context wheelsrc=./dist -t ddddocr:wheelhouse .

--target runtime 不传 --build-context wheelsrc 会失败：镜像里必须有 ddddocr，宁可报错也不要 静默产出一个空基座。runtime 还需要 onnxruntime 的 wheelhouse（ONNX_WHEELHOUSE，默认指向 a76yyyy/onnxruntime:<onnx_version>-wheelhouse）。

⁠产物

/wheels/
  ddddocr-1.6.1-py3-none-any.whl                       # 纯 python + 模型文件，与架构无关
  opencv-5.0.0-cp314-cp314-musllinux_1_2_<arch>.whl
  pillow-13.0.0-cp314-cp314-musllinux_1_2_<arch>.whl
  SHA256SUMS
  system-packages.txt
  simple/
    index.html
    <project>/index.html

system-packages.txt 是上层需要 apk add 的包（一行一个，无注释）：python3 与 zlib。 前者是解释器；后者因为 musllinux 白名单只有 libc 与 libz，Pillow 与 libopencv_imgcodecs 都动态链接了 libz.so.1，它不会被收进 .libs/。

simple/ 由 src/pack_wheel.py --emit-index 生成，链接为相对路径（../../<wheel>#sha256=）， 构建期会回读校验每个链接与哈希。

⁠已知限制

• cv2 是顶层扩展模块（cv2.cpython-314-<arch>-linux-musl.so），不是包：OpenCV 的绑定 在初始化时用写死的 cv2 注册子模块，装成 cv2/cv2.*.so 会报 Bindings generation error。因此没有 cv2.data（haarcascades 等数据文件），自编时也 只开了 core / imgproc / imgcodecs，没有 video / photo / dnn。 影响面：级联分类器（人脸、眼睛检测）不可用，cv2.data 属性不存在，import cv2.cv2 不可用； 文字识别不依赖这些，ddddocr 自身代码未引用 cv2.data 或级联文件。
• 自编 OpenCV 沿用 opencv-python-headless 这个发行名：官方四个包（opencv-python / opencv-contrib-python / opencv-python-headless / opencv-contrib-python-headless） 里，它是「无 GUI / 无后端」的那一个，正是容器场景要的。 但它不是官方版的等价物：官方 headless 版是完整模块（video / photo / dnn 等俱全）， 本仓库只保留 core / imgproc / imgcodecs，也没有 cv2.data 的级联文件。 发行名保持一致的意义是：用户改从 PyPI 安装同名包，就换回功能完整的官方版，配置不用动。
• wheel 的 cp314 与 alpine:3.24 的 Python 3.14 绑定；换 Python 小版本需要重新构建。

⁠维护者