用途与实际影响
这项功能怎样使用
为什么需要它
能克隆源码不代表能加载模型，模型目录存在也不代表依赖兼容；一个可响应的服务甚至可能尚未运行过显卡任务。恢复必须回到真实文件与样例，不能用“安装成功”三个字代替可用结果。
举个实际例子
我说“试试新版本，但别把能用的旧版弄坏”：系统创建候选并给出质量与身份回执，通过后才停原服务切换；旧版有有效回执才能回滚。网络或模型不足时停在候选阶段，现役环境不被覆盖。
最后我会得到什么
知道当前哪一版实际能识别、上一版能否回退，以及新版本在真实样例上是否通过。已有切换和回退验收仍按原日期说明；全新离线电脑从零恢复还需要另备系统与模型文件。
正常时
新版本在独立环境里通过实际样例，旧版也确实可回退后才切换，并用 Windows 入口再读一次文件。
发现问题时
候选失败就保留现役版本；旧目录没有有效验证时不宣称可回滚。
入口不可用或证据不足时
缺依赖、模型文件或显卡条件时停在相应步骤，源码目录存在不等于恢复成功。
从哪里开始
在已接入 LocalOCR 的本机 AI 对话中明确提出升级或换机恢复，并说明现役版本与可用模型材料；这属于维护流程。
需要准备什么
- 当前安装状态与候选版本
- 可用模型、网络和旧版回执
- 要验证的实际样例
从开始到拿到结果
- 1
保留可用现役
先检查当前运行版、模型和已验旧版；没有理由不改现役。
- 2
在独立候选里试新版本
先验依赖和真实合成样例；缺模型文件就停在候选，不覆盖现在可用的版本。
- 3
切换后做一次真实请求
确认没有正在处理的文件后切换，再用 Windows 入口读回结果；失败只回到确实通过检查的旧版。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
Paddle 3.4.0 新版本与 3.3.1 保留版本之间真实切换、回滚、恢复已验；全离线新机仍未验关键规则与设计选择
开发源码与已激活 app 分离，不在 current（当前状态） 中 pip upgrade 或覆盖仍被旧版本引用的权重；需要改动就创建新候选。
模型全部预热是重型动作，不是普通健康检查。
完全离线恢复需要提前保留完整工件；当前脚本本身要联网。
本模块用到的名词
- venv（Python 独立环境）
- 隔离项目依赖的现有运行目录，不是模型权重的替代品。
- model cache（模型缓存）
- 本机保存的模型文件；存在性、可加载与识别效果是三层不同证据。
- smoke test（小样例运行检查）
- 让指定文件经真实入口走到结果，验证一条具体路线；不是全面准确率基准。
专业定义
把代码、依赖和模型身份作为同一运行版本管理；能回滚升级，不等于已有断网新机的一键恢复包。
解决什么
防止把源码、依赖、模型缓存、服务在线和实际识别合并成一个失真的恢复结论。
当前怎样实现
- pyproject.toml 为 localocr 0.7.0，Python >=3.10；GPU 依赖允许 >=3.3.1,<3.5，而当前锁定和实装为 Paddle 3.4.0/cu129、PaddleOCR 3.7.0、PaddleX 3.7.2，声明和安装分别核对。
- install_wsl.sh 创建 /root/localocr-runtimes/<unique-candidate>，按运行锁文件装依赖并固定 app 源码；Python safe-path 与该版本 PYTHONPATH 隔离开发目录，数据 cwd 和输出位置仍保留原项目。
- 安装不加载 GPU 模型也不自动激活。缺模型时明确 download_models.py --allow-heavy，再 validate --allow-heavy 分别验依赖、逻辑和禁用缓存的合成质量；任何源码/依赖/权重变化使验收失效。
- 权重不重复复制到每个 venv，profile 的实际 artifact_paths 参与指纹。新权重独立版本目录，不覆盖仍被 current（当前状态）/previous 引用的文件；模型缓存存在、成功加载和实际识别分开。
- manage_runtime.py inspect 返回真实代码和解释器；activate/rollback 在服务停止且接收方自己的回执仍匹配时切换 current（当前状态）/previous 原子链接。Windows 入口仍为 PowerShell 7.3+ 和同一有界 wrapper，不由旧可编辑开发安装冒充现役版本。
- 当前没有能由本轮证据证明的完整离线重建包，也没有把所有 Python 依赖、WSL（Windows 的 Linux 子系统） 系统和模型权重打成已验收的单个恢复工件。
执行流程
- 1
先 inspect 当前与 previous、实际代码/依赖/模型，不按最新修改时间猜版本。
- 2
确需升级时创建唯一候选，保留现役环境与原件，不向 current（当前状态） 原地安装。
- 3
按需要准备独立权重，分别验证依赖、普通测试和真实合成质量；缺工件就停在候选。
- 4
无在途任务后停止自己的服务，验当前候选回执再原子切换；真实 Windows 请求和缓存结果另外核对。
- 5
需要回滚则由旧版自身验收依据批准切换，再核对实际运行；没有证据的旧目录不能当恢复保证。
边界
- 不因为网站内容建设就运行 install_wsl.sh 或重型全模型预热。
- 已缓存模型的本地推理不等于断网新机可以从零安装。
- 恢复版本以项目配置与兼容证据为准，不无依据永久钉死其他机器配置。
失败与恢复
- Python 包或模型配置不兼容
- 保留实际版本与异常，定位对应依赖/适配器，不盲目批量升级。
- 模型缓存缺失
- 按已选模型定位所需工件；取得模型与是否运行重型预热分开判断。
- 服务在线但模型任务没跑通
- 仅报告服务可达，继续把模型路线标成未验收。
- 只有源码却要求完全离线恢复
- 明确还缺依赖、WSL（Windows 的 Linux 子系统） 和模型工件，不虚构已存在的恢复包。
真实入口
E:\Projects\Tools\LocalOCR\pyproject.toml当前依赖声明
E:\Projects\Tools\LocalOCR\scripts\install_wsl.sh联网安装路径
E:\Projects\Tools\LocalOCR\scripts\download_models.py显式重型预热
E:\Projects\Tools\LocalOCR\scripts\run_in_wsl.shWSL（Windows 的 Linux 子系统） 运行入口
E:\Projects\Tools\LocalOCR\localocr\model_profiles.json具体模型与选项
E:\Projects\Tools\LocalOCR\scripts\manage_runtime.py真实解释器/源码身份与 validate、activate、rollback 入口
E:\Projects\Tools\LocalOCR\docs\UPGRADING.md独立候选、验收、原子激活与由旧版本自证的回滚合同
如何验证
- 9 月 17 日冻结环境验收 174 普通通过/1 跳过、九个合成质量案例全部满足各自门槛；VL 两页案例仍有 1.33% 字符错误，质量通过不等于零错。
- windows-end-to-end.json 绑定 3a4bf13，真实 Paddle 3.4.0→3.3.1→3.4.0 切换及代码身份、普通 OCR（光学字符识别） 首次 27.951 秒/缓存 1.284 秒、停止和重启通过；最终按需停止。本轮只读这些回执与当前元数据。
- 当前 acceptance/quality/Windows-E2E 回执 SHA-256 分别为 4204f7d2291f205c799dfb6fc6a016cdfb06c2b365a1eeff682bec823ea7b757、a34aef982c321e28e951afa9d0efea815632f4d1050018d08e635332c3c88953、55156bed06e712ad3c87d3f1c99241046e4341204c057c3c1f55199cabf98d62；它们不证明干净断网新机或任意真实文档质量。
与其他模块的关系
本模块恢复可执行环境；输入路线决定实际任务，运行层管理资源，最终仍由输出与原图复核证明用户拿到了什么。