docs: 重写 Win7 章节,补全 Python 3.8 构建与打包流程

原章节写的是「Win7 不支持」,但现在已经用 Python 3.8 + paddlepaddle 3.0.0
构建出可用的 dist/ocr-server-win7,并实测通过(34 框,与 3.12 输出一致)。
改成完整的构建手册:

  · 源码在分支 win7-python38(future annotations + pydantic 注解改写)
  · 环境:Python 3.8 + crc32c 2.8 + paddleocr 3.7.0 + paddlepaddle 3.0.0,
    并说明三个版本限制各自的原因
  · PyInstaller 命令(必须 --exclude-module bidi / watchfiles,
    它们的原生扩展依赖 Win8+ 的 api-ms-win-core-synch-l1-2-0)
  · 后处理三步:写纯 CPU 配置、复制模型、删除包内 ucrtbase.dll(改用系统 UCRT)
  · 目标机要求:Win7 SP1 + KB2999226 或 VC++ 2015-2022 运行库
  · 常见问题:inference.json 打不开多半是 models 没拷全;
    中文路径已实测可用,不是原因
  · 备份位置(backups/env-win7-2026-10-19)与回退方式
  · 保留「Win7 只当浏览器客户端」的替代方案

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-19 01:07:44 +08:00
parent 09ac9944c6
commit 94b2432f09
+112 -14
View File
@@ -509,25 +509,123 @@ D:\code\work\ocr-server\.venv\Scripts\python.exe
在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。 在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。
### Windows 7 不支持 ### Windows 7:需要单独的 Python 3.8 构建
**本服务不能运行在 Windows 7 上**,也不建议为了 Win7 做降级。实测确认的阻断点: 主包(Python 3.12)**无法在 Win7 上运行**:Win7 最高只支持 Python 3.8,exe 启动阶段会报缺
`api-ms-win-core-path-l1-1-0.dll`(Win8+ 才有)。
| 层面 | 情况 | Win7 需要单独构建一版:**纯 CPU**、Python 3.8 + paddlepaddle 3.0.0。项目已经产出过一版:
```text
dist/ocr-server-win7/ocr-server-win7.exe 约 993 MB(含 398 MB 模型)
```
源码改动在分支 **`win7-python38`**(主分支保持 3.12,两者互不影响)。
#### 构建步骤
**1. 切到 Win7 分支。** 该分支已做 3.8 兼容:所有模块加 `from __future__ import annotations`,
pydantic 模型(`config.py` / `schemas.py`)的注解改成 `Optional/List/Union`——pydantic 会
运行时求值注解,只加 future import 不够。
```bash
git checkout win7-python38
```
**2. 建 Python 3.8 环境并装依赖。**
```powershell
uv venv --python 3.8 .venv-win7
uv pip install --python .venv-win7\Scripts\python.exe ^
"crc32c==2.8" "paddleocr==3.7.0" "paddlepaddle==3.0.0" ^
"fastapi" "uvicorn[standard]" "pillow" "python-multipart" "pyyaml" "pyinstaller"
```
三个版本限制,不要随手升级:
| 包 | 限制 | 原因 |
| --- | --- | --- |
| `crc32c` | 必须 `2.8` | 更新的 2.9.post0 在 cp38 没有 Windows 轮子,会触发源码编译并失败 |
| `paddlepaddle` | 只能 `3.0.0` | 3.2.x 没有 cp38 轮子 |
| `uvicorn` | 会解析到 `0.33` | `>=0.34` 要求 Python >=3.9 |
**3. 打包(必须排除 `bidi` 和 `watchfiles`)。**
```powershell
.venv-win7\Scripts\python.exe -m PyInstaller --noconfirm --clean --onedir ^
--name ocr-server-win7 --distpath dist --paths src ^
--exclude-module bidi --exclude-module watchfiles ^
--collect-all paddleocr --collect-all paddlex --collect-all paddle ^
--collect-all cv2 --collect-all PIL --collect-all pyclipper ^
--collect-all pypdfium2 --collect-all shapely ^
--hidden-import paddlex.inference.models.text_detection.processors ^
--copy-metadata paddlex --copy-metadata paddleocr ^
--copy-metadata paddlepaddle --copy-metadata imagesize ^
--add-data "config.yaml;." --add-data "http;http" ^
--additional-hooks-dir scripts ^
--hidden-import imagesize --hidden-import imagesize.imagesize ^
--hidden-import ocr_server.app --hidden-import ocr_server.config ^
scripts/packaged_entry.py
```
> 为什么排除这两个:它们的原生扩展依赖 `api-ms-win-core-synch-l1-2-0.dll`(Win8+),
> 在 Win7 上加载会失败。`watchfiles` 只在 `uvicorn --reload` 用;`bidi` 只用于阿拉伯语等
> RTL 模型的显示,中文识别用不到(源码里已去掉对它的强制可用性检查)。
**4. 后处理(三步都不能漏)。**
```powershell
# 纯 CPU + 模型随包自带
python scripts/prepare_release_config.py config.yaml dist/ocr-server-win7/config.yaml "device=cpu" "model_dir=models"
# 复制模型
cp -r models dist/ocr-server-win7/models
# 删掉包内的 ucrtbase.dll,改用系统版
Remove-Item dist/ocr-server-win7/_internal/ucrtbase.dll
```
> 包内那份 `ucrtbase.dll` 来自较新的 Windows SDK,依赖 `api-ms-win-core-*-l1-2-0`(Win8+)。
> 删掉后由系统的 UCRT 接管(前提是目标机装了 KB2999226,见下)。
#### 目标机要求
- **Win7 SP1 + KB2999226**(Universal C Runtime),或直接安装 **VC++ 2015-2022 运行库**。
- **纯 CPU**:Win7 的 NVIDIA 驱动最高只到 472,而 CUDA 11.8 需要 520+,GPU 版不可用。
- 解压到普通目录再运行,例如 `D:\ocr-server-win7`。
#### 常见问题
**`Cannot open file ...\models\official_models\PP-OCRv5_server_det\inference.json`**
能报出这个说明程序已经启动、并跑到推理阶段了,只是模型文件没找到。按顺序排查:
1. 确认 `models` 目录拷完整了。`official_models/PP-OCRv5_server_det/` 下必须有四个文件:
`config.json`、`inference.yml`、`inference.json`、`inference.pdiparams`。
```bat
dir "D:\ocr-server-win7\models\official_models\PP-OCRv5_server_det"
```
2. 不要直接在浏览器的下载目录里运行(例如 `C:\...浏览器下载\`),先解压/复制到普通目录。
3. **中文路径本身不是问题**——同版本包放在中文目录下实测可正常识别(34 框)。
优先怀疑文件没拷全。
#### 备份与回退
Win7 构建只用独立的 `.venv-win7`,不影响 `.venv` / `.venv-gpu`。回退只需删除 `.venv-win7`。
完整构建环境记录在 `backups/env-win7-2026-10-19/`:
| 文件 | 内容 |
| --- | --- | | --- | --- |
| Python | Win7 最高只支持 Python **3.8**(3.9 起官方不再支持 Win7),本项目要求 `>=3.10` | | `BUILD-NOTES.md` | 构建配方、兼容性检查结果、已知坑 |
| 打包产物 | exe 内嵌 CPython 3.12,在 Win7 上启动即失败(缺 `api-ms-win-core-path-l1-1-0.dll`) | | `freeze-win7.txt` | 85 个包的精确版本 |
| `paddlepaddle` | 3.2.x **没有 cp38 轮子**,3.8 上最高只能用 3.0.0 | | `versions.txt` | 关键版本一览 |
| Web 栈 | `uvicorn>=0.34` 要求 Python >=3.9,整条栈都要降版本 |
| 本项目的代码 | 有 120+ 处 3.9/3.10+ 注解语法,其中 pydantic 模型必须真正改写(不能只加 `from __future__ import annotations`) |
| GPU | **不可行**:CUDA 11.8 需要 520+ 驱动,Win7 最后只支持到 472 |
**推荐架构**:把服务跑在 Win10+ 或 Linux 机器上,Win7 只当客户端——用浏览器打开 #### 更省事的替代方案
`scripts/GUI.html`,或调用 HTTP 接口。Win7 上需要 Chrome 109(最后一个支持 Win7 的
版本)或 Firefox 115 ESR;**IE11 不行**(不支持 `fetch`、可选链、`async/await`)。
如果必须在 Win7 本机跑,那是一次完整移植(降 Python、降 Paddle、降 Web 栈、改注解), 如果 Win7 那台机器只是**使用方**,不必本机跑 OCR:把服务放在 Win10+ / Linux 机器上,
且最终兼容性只能在 Win7 实机上验证。 Win7 用浏览器打开 `scripts/GUI.html` 即可(需要 Chrome 109 或 Firefox 115 ESR;
**IE11 不行**,不支持 `fetch`、可选链、`async/await`)。
## Windows 安装和启动 ## Windows 安装和启动