OCRmyPDF Docker 镜像怎么选？alpine 与 ubuntu 镜像的差异和固定版本方法

OCRmyPDF Docker 镜像怎么选？alpine 与 ubuntu 镜像的差异和固定版本方法

【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF

用 OCRmyPDF 给扫描版 PDF 加 OCR 文本层时，如果不想在本机逐个安装 Tesseract、Ghostscript 等依赖，官方提供了打包好全部近期依赖的 Docker 镜像。这篇文档（docs/docker.md）给出了三个镜像：该选哪个、怎么确认 Docker 环境可用、怎么把镜像版本固定下来，下面按实际操作顺序说明。

三个官方镜像及其差异

docs/installation.md 将 Docker 列为安装方式之一，具体镜像说明在 docs/docker.md。三者对比如下（内容均出自该文档的镜像列表）：

镜像	架构	说明
jbarlow83/ocrmypdf-alpine	x86_64 和 arm64	推荐镜像，基于 Alpine Linux
jbarlow83/ocrmypdf-ubuntu	x86_64 和 arm64	备选镜像，基于 Ubuntu。当 Alpine 镜像被认为稳定且 arm64 可用后，此镜像将弃用
jbarlow83/ocrmypdf	x86_64 和 arm64	目前是ocrmypdf-ubuntu的别名；将来会指向 Alpine 镜像。文档原话：如果不确定 Alpine 与 Ubuntu 的区别，就用这个镜像

据此做选择：

• 新环境直接用jbarlow83/ocrmypdf-alpine，这是文档明确标注的推荐镜像；
• 需要基于 Ubuntu 的包环境时，用jbarlow83/ocrmypdf-ubuntu明确指定，而不要依赖不带后缀的ocrmypdf——它当前只是 Ubuntu 镜像的别名，文档同时说明这个不带后缀的镜像已弃用、将来会被移除；
• 三个镜像都支持 x86_64 与 arm64。

一个前提要注意：文档把镜像底层的操作系统和其他细节视为实现细节，可能在小版本（minor release）中改变。如果你会修改镜像，文档要求固定（pin）你要用的版本。

拉取镜像并完成首次运行

1. 确认 Docker 环境可用

文档给出的就绪检查命令：

docker run hello-world

该命令能成功运行，说明系统可以下载并执行镜像。

2. 拉取选定的镜像

docker pull jbarlow83/ocrmypdf-alpine

（选择 Ubuntu 镜像则拉取jbarlow83/ocrmypdf-ubuntu。）

3. 用 stdin/stdout 跑通第一个 OCR 任务

文档推荐的做法是把输入文件从 stdin 送入、从 stdout 读出结果——不写挂载目录，就完全避开文件权限问题，也不受 rootless / rootful Docker 的影响。用 alias 藏起底层 Docker 命令：

alias docker_ocrmypdf='docker run --rm -i jbarlow83/ocrmypdf-alpine' docker_ocrmypdf --version # runs docker version docker_ocrmypdf - - <input.pdf >output.pdf

<input.pdf>换成你的输入 PDF 路径，output.pdf是重定向生成的输出文件名。--rm用于任务结束后删除容器——文档特别说明，这类容器是短命的：跑一次 OCR 就退出，和命令行程序一样，而不是常驻服务。fish shell 下对应的写法是alias docker_ocrmypdf 'docker run --rm -i jbarlow83/ocrmypdf-alpine'加funcsave docker_ocrmypdf。

验证方式：docker_ocrmypdf --version能在容器里打印 OCRmyPDF 版本，说明镜像可运行；对真实 PDF 执行后在output.pdf中检索文本，说明 OCR 文本层已写入。

4. 可选：挂载目录传文件

如果你更习惯传文件路径而不是管道，镜像默认工作目录是/data，把目录挂到/data后即可用相对路径。注意镜像默认以非 root 用户app（uid/gid 1000）运行，这是文档说明的纵深防御措施；能否写回挂载目录取决于你的容器运行时，文档给出了三种情况：

Rootless Docker（rootless 守护进程，宿主普通用户身份）：

alias docker_ocrmypdf='docker run --rm -i --user 0:0 -v "$PWD:/data" jbarlow83/ocrmypdf-alpine' docker_ocrmypdf input.pdf output.pdf

文档解释：rootless 模式下容器内除 root 外的 uid（包括app/1000）都映射到从属 uid，你拥有属主的目录在容器内显示为 root 所有，默认app用户通常根本写不进去；改用--user 0:0让任务以容器 root 身份运行，在 rootless 下它就是你的宿主普通用户，写入成功且输出归你所有。

Rootful Docker（传统 root 守护进程）：

alias docker_ocrmypdf='docker run --rm -i --user "$(id -u):$(id -g)" -v "$PWD:/data" jbarlow83/ocrmypdf-alpine' docker_ocrmypdf input.pdf output.pdf

rootful 下容器 uid 与宿主 uid 一一对应，若以 root 运行会在挂载目录里生成 root 属主的文件；降到$(id -u):$(id -g)即你的宿主 uid，输出归你且进程保持非特权。

Podman：

alias podman_ocrmypdf='podman run --rm -i --user "$(id -u):$(id -g)" --userns keep-id -v "$PWD:/data" jbarlow83/ocrmypdf-alpine' podman_ocrmypdf input.pdf output.pdf

--userns keep-id把宿主 uid 直接映射进容器，避免 uid 不匹配导致的访问错误。SELinux 开启时，文档提示可能还需给卷加:Z后缀，或使用--security-opt label=disable为容器禁用 SELinux（文档建议后者用于系统文件），完整命令即在上面 alias 的-v之后追加该参数。

固定镜像版本的方法

文档的原话是：如果你修改（扩展）了镜像，就应该固定一个具体的 OCRmyPDF Docker 镜像版本，确保新版发布时你的镜像不会坏。具体方法是在自定义 Dockerfile 的FROM中显式写出版本 tag：

FROM jbarlow83/ocrmypdf:{TAG}

文档示例中的{TAG}是占位符，把它替换成你要固定的 OCRmyPDF 版本号，例如FROM jbarlow83/ocrmypdf:17.9.0。文档正文没有给出 tag 的完整清单，可用 tag 以镜像仓库中的实际列表为准。

扩展语言包时同样需要固定版本

镜像默认包含英语、德语、简体中文、法语、葡萄牙语、西班牙语。安装 tessdata_best 一类的训练数据前，需要先确认镜像内的 Tesseract 数据文件版本（文档说明它可能与 Tesseract 程序版本不同）：

docker run -i --rm --entrypoint /bin/ls jbarlow83/ocrmypdf /usr/share/tesseract-ocr

然后按查到的数据文件版本写入 COPY 路径。以下示例中<data version>替换为上一步列出的实际版本号（文档以 2021 年的情况为例，数据文件版本大概是4.00）；示例文件名chi_tra_vert.traineddata是文档给出的 traineddata 示例，换成你要安装的文件：

FROM jbarlow83/ocrmypdf:{TAG} # Example: add a tessdata_best file COPY chi_tra_vert.traineddata /usr/share/tesseract-ocr/<data version>/tessdata/

不想构建新镜像时，文档给出替代路径：把训练数据拷进一个已存在的容器。命令中的<tesseract version>同样替换为查到的数据文件版本号：

docker cp mycustomtraining.traineddata name_of_container:/usr/share/tesseract-ocr/<tesseract version>/tessdata/

name_of_container替换为你目标容器的名称。

限制与后续变化提示

• 镜像底层系统会在小版本中改变，文档要求此类变化写入 release notes。docs/releasenotes/version17.md 中的相关记录：v17.7.0 起镜像默认以非 root 用户app（uid/gid 1000）运行、默认工作目录改为/data，Ubuntu 镜像改用 Ubuntu 官方源的 Tesseract 5，基础系统更新为 Ubuntu 26.04 和 Alpine 3.24；更早的版本中 Alpine 基础镜像在 v17.3.0 更新到 3.23（见同文件）、在 v16.9.0 更新到 3.21（docs/releasenotes/version16.md）。固定版本就是为了避免这类底层变化影响你的扩展镜像。
• 在非 Linux 平台上 Docker 运行在虚拟机里，性能可能不如原生安装，必要时按 Docker 官方文档调整虚拟机的内存和 CPU 分配；Linux 上镜像原生运行，性能与系统安装相当。
• 需要容器内 shell 排查时：docker run -it --entrypoint sh jbarlow83/ocrmypdf-alpine，以非 root 的app用户运行；需要 root（例如用apk或apt装包）时加--user root。
• 镜像自带测试套件，如需完整回归可执行docker run --rm --workdir /app --entrypoint python jbarlow83/ocrmypdf -m pytest。

选对镜像并完成拉取后，docker_ocrmypdf --version能返回版本号、管道方式能产出可检索的 PDF，即说明环境就绪；之后再按FROM中显式 tag 的方式固定版本，扩展镜像就不会随上游发布被动变化。

【免费下载链接】OCRmyPDFOCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched项目地址: https://gitcode.com/GitHub_Trending/oc/OCRmyPDF